> > > SpecProjectionMappingSpec

Projection Mapping Specification

Purpose

This specification defines how SOTER maps Logos semantic models into projection targets. It separates the notation-neutral mapping layer from target-specific projectors such as BPMN, PlantUML, Mermaid, D2, database materialization, auxiliary JSON, and UI/interaction formats.

Scope

This document covers:

the projection mapping pipeline;
target selection;
element classification;
generic mapping rules;
relation and flow inference;
target-specific mapping boundaries.

Non-Goals

This document does not define SVO semantics; see LogosSvoSemanticsSpec.md.
This document does not define BPMN-specific notation rules; see ProjectionBpmn.md.
This document does not define VGM geometry; see ProjectionVgmSpecification.md.
This document does not define layout strategies; see ProjectionLayoutStrategiesSpec.md.

Terminology

Term	Meaning
Projection target	Output family such as BPMN, UML, Mermaid, PlantUML, D2, database, JSON, or UI surface.
Mapping rule	Rule that maps semantic elements and relations to target concepts.
Projector	Adapter that renders a mapped projection into a concrete target format.
View profile	Configuration selecting scope, target, detail level, and rendering options.
Render plan	Intermediate target-aware plan consumed by a concrete projector.

Model or Contract

The mapping pipeline is:

Logos source
  -> semantic graph
  -> selected view profile
  -> target mapping
  -> render plan or materialization plan
  -> projector or materializer
  -> output artifact

Mapping produces target intent. Rendering produces concrete files or surfaces.

Rules

Semantic Source of Truth

The semantic graph remains the source of truth. A projection target may expose, hide, group, or annotate elements, but it must not create new domain meaning.

Generic Element Classification

Generic mappings start from semantic roles:

Semantic role	Generic projection role
Subject	Participant, owner, lane, actor, UI role, database owner dimension
Action	Task, transition, operation, command, interaction, service call
Object	Data object, state carrier, record, resource, UI entity, JSON node
Relationship	Association, dependency, message, containment, reference
Fact	Event, audit marker, observation, timeline item

Target-specific projectors refine these roles into target notation.

Relation and Flow Inference

Mapping may infer relations from semantic dependencies:

Action A -> Object/State -> Action B

The inferred relation is generic. BPMN may render it as sequence or message flow. UML may render it as dependency. A database materializer may render it as a foreign-key-like relation or graph edge. UI projection may render it as form flow or command availability.

Target Boundaries

Target-specific rules belong in the target specification:

BPMN gateways, lanes, pools, data associations, and event notation belong in ProjectionBpmn.md.
VGM geometry and visual node/edge payloads belong in ProjectionVgmSpecification.md.
Pipeline products and materialization outputs belong in ProjectionPipelineSpec.md.
Layout algorithms and text metrology belong in ProjectionLayoutStrategiesSpec.md.

Examples

Generic Action Mapping

Action RegisterInvoice
  performer: Accountant
  in: Invoice[received]
  out: Invoice[registered]

Generic mapping:

operation/task: RegisterInvoice
owner/participant: Accountant
input: Invoice[received]
output: Invoice[registered]

BPMN can render this as a task with data associations. A UI projector can render it as a command form. A JSON materializer can render it as a node with typed input/output references.

Validation

Projection mapping should validate:

unknown target;
missing target mapping rule;
ambiguous rule match;
view profile selecting elements outside scope;
target rule attempting to introduce semantic meaning;
renderer receiving incomplete render-plan data.

Compatibility

Older documents used BPMN as the main example of projection mapping. BPMN is now treated as one target-specific projection. General mapping rules belong here.

Open Questions

Should mapping rules be declared as JSON, Logos .view syntax, Python strategy objects, or a layered combination?
Which projection targets need first-class render plans rather than direct adapters?