compiler ir spec

the fully closed authored world after reference, completeness, and legality checking, but before precedence and handles are frozen.

ValidatedWorld {
  authored_world: AuthoredWorld,
  refs: map<SlugPath, ValidatedRef>,
  rulesets: map<RulesetSlug, ValidatedRuleset>,
  policy_declarations: ValidationPolicyTable,
  diagnostics: CompileDiagnostic[],
}

• invariants. every intake face, effect face, route fact kind, process transition, and set landmark ref must exist here or compilation stops.
• not yet done. no stable handles, no global positions, and no resolved precedence appear in this phase.
• first appearance. this is the first place where “the authored world is closed” becomes a machine-checkable claim.

specimen:
ValidatedWorld.refs["route.activation.credit.create"] = ValidatedRef {
  kind: "route",
  slug_path: "route.activation.credit.create",
  target_kind: "Route",
  origin_span: "fixtures/finexa/authored_world.pbjson#routes[0]"
}

the authored set after landmark closure and district-local geometry validation, but before global placement resolution.

ValidatedSet {
  authored_set: AuthoredSet,
  districts: map<DistrictSlug, DistrictFrame>,
  landmark_refs: map<SlugPath, ValidatedRef>,
  diagnostics: CompileDiagnostic[],
}

• invariants. set authoring may place only declared semantic landmarks; it may not create routes, bays, or process law.
• coordinate stance. all authored positions remain district-local here.

the world after stable handles, precedence, legality, and executable policy resolution. runtime never needs to recompute authorial precedence beyond this point.

ResolvedWorld {
  validated: ValidatedWorld,
  handles: map<SlugPath, ResolvedHandle>,
  bind_plans: map<ProtoBayHandle, ResolvedBindPlan>,
  birth_plans: map<ProtoBayHandle, ResolvedBirthPlan>,
  lane_plans: map<RouteHandle, ResolvedLanePlan>,
  authority_matrix: ResolvedAuthorityMatrix,
  authority_by_route: map<RouteHandle, ResolvedAuthorityPlan>,
  discharge_by_effect: map<EffectHandle, ResolvedDischargePlan>,
  diagnostics: CompileDiagnostic[],
}

• invariants. same-tier policy conflict, unresolved lane plan, illegal truth promotion, impossible bind/birth reuse, and route-side bind/birth redefinition are all errors here.
• identity stance. every public compiled handle is already frozen here and remains stable through lowering.
• runtime stance. runtime reads resolved authority and discharge plans; it does not redo authored precedence logic.

the set after stable handles, global positions, derived conduits/gates/bridges, and viewer-safe geometry handles are resolved.

ResolvedSet {
  validated: ValidatedSet,
  district_frames: map<DistrictHandle, DistrictFrame>,
  global_positions: map<LandmarkHandle, Vec3>,
  derived_edges: DerivedSceneEdges,
  diagnostics: CompileDiagnostic[],
}

• invariants. the compiler may derive conduits, gates, switches, chambers, bridges, labels, and overlay channels only from authored landmarks plus compiled world topology.
• geometry stance. district-local authored coordinates are lifted into global positions exactly once here.

the protobuf-ready world shape after resolved plans and lowered dag nodes are ordered into deterministic public artifact form.

LoweredWorld {
  resolved: ResolvedWorld,
  compiled_world: CompiledWorld,
  serialization_order: LoweringOrder,
}

• determinism. equal authored input plus equal schema edition yields equal handle sets, equal plan ordering, and byte-stable compiled output.
• public boundary. this is the last rust-only stop before the public compiled artifact.

the protobuf-ready set artifact with resolved global placement and derived scene machinery ordered deterministically.

LoweredSet {
  resolved: ResolvedSet,
  compiled_set: CompiledSet,
  serialization_order: LoweringOrder,
}

the root executable artifact for law, machinery, readout, and viewer adapters.

CompiledWorld {
  meta: ArtifactMeta,
  authored_world_ref: Handle,
  resolved_ids: ResolvedIds,
  compiled_sources: map<SourceSlug, CompiledSource>,
  compiled_ports: map<PortSlug, CompiledPort>,
  compiled_port_bindings: map<BindingSlug, CompiledPortBinding>,
  compiled_faces: map<FaceSlug, CompiledFace>,
  compiled_rulesets: map<RulesetSlug, CompiledRuleset>,
  compiled_protos: map<ProtoSlug, CompiledProto>,
  compiled_proto_bays: map<ProtoBaySlug, CompiledProtoBay>,
  compiled_processes: map<ProcessSlug, CompiledProcess>,
  compiled_routes: map<RouteSlug, CompiledRoute>,
  compiled_projections: map<ProjectionSlug, CompiledProjection>,
  bind_plans: map<ProtoBayHandle, ResolvedBindPlan>,
  birth_plans: map<ProtoBayHandle, ResolvedBirthPlan>,
  lane_plans: map<RouteHandle, ResolvedLanePlan>,
  authority_matrix: ResolvedAuthorityMatrix,
  authority_by_route: map<RouteHandle, ResolvedAuthorityPlan>,
  discharge_rules: map<EffectHandle, ResolvedDischargePlan>,
  viewer_handles: ViewerHandles,
  compile_diagnostics: CompileDiagnostic[],
}

• invariants. this artifact never invents missing authored law; every route fact kind, process move, effect face, and boundary surface must trace back to authored declarations.
• consequence. runtime, replay, and viewer can all read this artifact without re-running compile-time precedence.

specimen:
CompiledWorld.compiled_routes["activation.credit.create"].process_transition =
  { process: "activation", from: "approved", to: "active" }

the public atlas from authored slugs to compiled stable handles.

ResolvedIds {
  world: Handle,
  sources: map<SourceSlug, Handle>,
  ports: map<PortSlug, Handle>,
  faces: map<FaceSlug, Handle>,
  protos: map<ProtoSlug, Handle>,
  bindings: map<BindingSlug, Handle>,
  processes: map<ProcessSlug, Handle>,
  routes: map<RouteSlug, Handle>,
  projections: map<ProjectionSlug, Handle>,
  effects: map<EffectSlug, Handle>,
}

• invariants. one authored slug path yields one stable handle; missing or duplicate public handle allocation is an error.
• runtime consequence. every downstream public contract uses these handles as durable references.

specimen:
ResolvedIds.routes["activation.credit.create"] = "cw.finexa_credit_world.route.activation.credit.create"

compiled boundary capability summary for one authored source.

CompiledSource {
  handle: Handle,
  kind: SourceKind,
  trust: TrustPosture,
  material_contracts: ContractRef[],
}

• invariants. compiled source states capability only; it never injects new parsing, authority, or effect law.
• first appears. resolved in ResolvedWorld after source closure.
• consequence. boundary validation can reject impossible source/binding combinations before runtime.

specimen:
CompiledSource {
  handle: "cw.finexa_credit_world.source.trello",
  kind: SOURCE_KIND_TRELLO,
  trust: TRUST_POSTURE_OBSERVATIONAL,
  material_contracts: ["trello.card.action"]
}

the deployed transport surface after direction and deployment hints are normalized.

CompiledPort {
  handle: Handle,
  direction: Direction,
  transport_family: TransportFamily,
  deployment: PortDeployment,
}

• invariants. port deployment is transport posture only; semantic matching and truth movement still live on bindings, faces, and routes.
• first appears. resolved in ResolvedWorld after deployment closure.
• consequence. inbound admission and outbound delivery share one normalized transport surface without conflating it with law.

specimen:
CompiledPort {
  handle: "cw.finexa_credit_world.port.trello_webhook",
  direction: DIRECTION_INBOUND,
  transport_family: TRANSPORT_FAMILY_HTTP_WEBHOOK,
  deployment: PortDeployment { locality: LOCALITY_REMOTE, endpoint_ref: "deployment.trello.webhook" }
}

the compiled boundary object for one deployed source-composition path.

CompiledPortBinding {
  binding_id: Handle,
  port_ref: Handle,
  source_ref: Handle,
  direction: Direction,
  deployment_ref: Handle,
  credential_contract: ContractRef,
  protocol_adapter: Handle,
  parser_plan: Handle,
  material_contract: ContractRef,
  matcher_plan: Handle,
  admit_policy: Handle,
  bind_hook: Handle?,
  birth_hook: Handle?,
  effect_policy: Handle?,
  trust_posture: TrustPosture,
  diagnostics: CompileDiagnostic[],
}

• invariant. compiled port binding may authenticate, parse, classify, and match source material, but it never maintains proto truth by itself.
• first appears. resolved in ResolvedWorld once source, port, deployment, and policy refs are closed.
• runtime consequence. admitχ and outbound discharge both use this surface directly.

specimen:
CompiledPortBinding {
  binding_id: "cw.finexa_credit_world.binding.trello_card_action",
  port_ref: "cw.finexa_credit_world.port.trello_webhook",
  source_ref: "cw.finexa_credit_world.source.trello",
  material_contract: "trello.card.action",
  admit_policy: "cw.finexa_credit_world.policy.admit.trello_pipeline",
  matcher_plan: "cw.finexa_credit_world.matcher.card_list_activation"
}

the normalized semantic aperture that turns classified material into admitted datum families.

CompiledFace {
  handle: Handle,
  port_bindings: Handle[],
  ruleset: Handle,
  target_proto_bays: Handle[],
  admitted_datum_kinds: DatumKind[],
}

• invariants. face admission is semantic normalization only; it does not decide process movement or durable truth on its own.
• first appears. resolved after bindings and ruleset lowering are complete.
• consequence. runtime can map admitted material into route candidates without rediscovering boundary topology.

specimen:
CompiledFace {
  handle: "cw.finexa_credit_world.face.trello_pipeline",
  port_bindings: ["cw.finexa_credit_world.binding.trello_card_action"],
  ruleset: "cw.finexa_credit_world.ruleset.trello_pipeline_rules",
  target_proto_bays: ["cw.finexa_credit_world.proto_bay.credit_request"],
  admitted_datum_kinds: [DATUM_KIND_ACTIVATION_COMMAND]
}

the public executable dag for one face or effect ruleset. this doc treats it as typed dag, not operator strings.

CompiledRuleset {
  nodes: LoweredNode[],
  edges: LoweredEdge[],
  entry_nodes: Handle[],
  terminal_nodes: Handle[],
  input_contract: ContractRef,
  output_contract: ContractRef,
  event_time_policy: LoweredTimePolicy,
  lowering_diagnostics: CompileDiagnostic[],
}

• invariant. dag nodes and edges are typed and deterministic; runtime is never asked to infer operator intent from plain strings.
• phase. first fully appears in LoweredRulesetDag; exported publicly here.

specimen:
CompiledRuleset {
  entry_nodes: ["cw.finexa_credit_world.ruleset.trello_pipeline_rules.node.schema_map"],
  terminal_nodes: [
    "cw.finexa_credit_world.ruleset.trello_pipeline_rules.node.project_activation",
    "cw.finexa_credit_world.ruleset.trello_pipeline_rules.node.reject_unmapped"
  ],
  output_contract: "normalized_activation_command"
}

compiled field-maintenance and relation-index plan for one proto kind.

CompiledProto {
  handle: Handle,
  field_hydration_plans: map<Handle, FieldHydrationPlan>,
  relation_indices: map<Handle, Handle>,
  authority_groups: map<AuthorityGroupRef, Handle[]>,
}

• invariants. proto schema and hydration law are fixed here; runtime may execute maintenance but not reinterpret field meaning.
• first appears. resolved from authored proto plus field bindings, then exported publicly on CompiledWorld.
• consequence. replay and readout can maintain proto truth from durable envelopes without hidden schema knowledge.

specimen:
CompiledProto {
  handle: "cw.finexa_credit_world.proto.credit",
  authority_groups: { "credit.lifecycle": ["...field.status", "...field.opened_at"] }
}

the compiled plan for maintaining one proto field from upstream datums, records, observations, joins, windows, aggregates, or projections.

FieldHydrationPlan {
  mode: HydrationMode,
  upstream: Handle[],
  authority_group: AuthorityGroupRef,
  observations_allowed: bool,
  null_policy: NullPolicy,
  freshness_mode: FreshnessMode,
}

• mode examples. direct face mapping, ruleset output, join, window, aggregate, projection-fed, or constant/default.
• authority rule. observation-fed plans require both explicit observation consumption in authored bindings and allowance in the resolved authority matrix.
• first appears. shaped during resolution from FieldBinding and exported publicly on CompiledProto.
• consequence. proto maintenance becomes replayable and inspectable instead of hidden inside runtime handlers.

specimen:
FieldHydrationPlan {
  mode: HYDRATION_MODE_DIRECT_FACE_MAPPING,
  upstream: ["cw.finexa_credit_world.face.trello_pipeline"],
  authority_group: "credit_request.identity",
  observations_allowed: false
}

the public proto crossing plan for one kind boundary.

CompiledProtoBay {
  handle: Handle,
  bind_plan: ResolvedBindPlan,
  birth_plan: ResolvedBirthPlan,
  lane_default: ResolvedLanePlan,
}

• invariants. field hydration never lives here; proto bay is identity, birth, and lane posture only.
• first appears. resolved in ResolvedWorld and then exported unchanged.
• consequence. runtime can execute place/birth decisions without consulting authored DSL structure.

specimen:
CompiledProtoBay {
  handle: "cw.finexa_credit_world.proto_bay.credit",
  bind_plan: ResolvedBindPlan { handle: "cw.finexa_credit_world.bind.credit" },
  birth_plan: ResolvedBirthPlan { handle: "cw.finexa_credit_world.birth.credit" }
}

the public lawful motion table for one process family.

CompiledProcess {
  handle: Handle,
  statuses: ProcessStatusSlug[],
  transitions: CompiledProcessTransition[],
}

• invariants. no compiled process may add statuses or transitions absent from authored law.
• first appears. validated as authored FSM law, then resolved and exported here.
• consequence. decide and commit can treat process legality as data, not code folklore.

specimen:
CompiledProcess {
  handle: "cw.finexa_credit_world.process.activation",
  statuses: ["approved", "active"],
  transitions: [{ from: "approved", to: "active", effects: ["cw.finexa_credit_world.effect.sync_to_fibo"] }]
}

one public lawful edge in a compiled process, including the effects it may emit when traversed.

CompiledProcessTransition {
  handle: Handle,
  from: StatusSlug,
  to: StatusSlug,
  effects: Handle[],
}

• invariants. effects listed here must trace to authored effect declarations and route permissions.
• first appears. validated as authored process law, then embedded into CompiledProcess and routes.
• consequence. viewer and runtime can both reason about lawful motion from one typed edge surface.

specimen:
CompiledProcessTransition {
  handle: "cw.finexa_credit_world.process.activation.transition.approved_to_active",
  from: "approved",
  to: "active",
  effects: ["cw.finexa_credit_world.effect.sync_to_fibo"]
}

the public execution plan for one legal path chosen from an admitted datum family.

CompiledRoute {
  datum_face: Handle,
  lane_plan: ResolvedLanePlan,
  birth_targets: Handle[],
  authority_plan: ResolvedAuthorityPlan,
  discharge_rules: Handle[],
  commit_fact_kinds: CommitFactSpec[],
  process_transition: CompiledProcessTransition,
}

• invariant. compiled route never invents process movement or fact kinds beyond authored law.
• runtime consequence. one admitted route yields one attempt and one local commit boundary.

specimen:
CompiledRoute { datum_face: "cw.finexa_credit_world.face.trello_pipeline", birth_targets: ["cw.finexa_credit_world.proto.credit"] }

the compiled readout/view handle for one authored projection.

CompiledProjection {
  handle: Handle,
  screen_handle: Handle,
  contract: ContractRef,
  projection_kind: ProjectionKind,
}

• invariants. compiled projection is readout only; it may not invent new world truth or set topology.
• first appears. resolved once screen refs and projection contracts are closed.
• consequence. viewer screens can boot directly from compiled contracts before live runtime overlays exist.

specimen:
CompiledProjection {
  handle: "cw.finexa_credit_world.projection.activation_queue",
  screen_handle: "cs.finexa_credit_world.screen.activation_queue",
  contract: "readout.activation.queue",
  projection_kind: PROJECTION_KIND_TABLE
}

the public effect closure rule as surfaced on the compiled artifact.

DischargeRule {
  effect: Handle,
  receipts: ReceiptKind[],
  timeout: DurationSpec?,
  escalation_target: EscalationTargetRef?,
  terminal_failure_mode: TerminalFailureMode,
}

• invariants. no obligation discharges on undeclared receipt families.
• first appears. resolved from effect policy and optional route override in ResolvedDischargePlan.
• consequence. replay can tell whether an obligation is still owed, discharged, escalated, or terminally failed without code-specific logic.

specimen:
DischargeRule {
  effect: "cw.finexa_credit_world.effect.sync_to_fibo",
  receipts: [RECEIPT_KIND_FIBO_ACCEPTED],
  timeout: DurationSpec { seconds: 86400 },
  escalation_target: "cw.finexa_credit_world.effect.raise_sync_alert"
}

the stable landmark handle set the viewer can use without re-discovering topology.

ViewerHandles {
  districts: Handle[],
  anchors: Handle[],
  tracks: Handle[],
  screens: Handle[],
  docks: Handle[],
}

• invariants. this is a handle atlas only; it does not duplicate topology or viewer state.
• first appears. resolved at set/world integration time, then exported on CompiledWorld.
• consequence. the viewer can bootstrap selection, highlighting, and overlay targeting without graph discovery.

specimen:
ViewerHandles {
  districts: ["cs.finexa_credit_world.district.intake", "cs.finexa_credit_world.district.activation"],
  tracks: ["cs.finexa_credit_world.track.activation"]
}

the public compile finding surface shared across validation, resolution, lowering, and layout derivation.

CompileDiagnostic {
  stage: CompileStage,
  code: DiagnosticCode,
  severity: DiagnosticSeverity,
  subject_ref: Handle,
  related_refs: Handle[],
  authored_span: DiagnosticSpan,
  message: string,
  fix_hint: string?,
}

• severity set. error, warning, note.
• emission rule. warnings and notes may still emit artifacts; any error prevents artifact emission.

specimen:
CompileDiagnostic { stage: COMPILE_STAGE_RESOLVE, code: "resolve.authority.conflict", severity: DIAGNOSTIC_SEVERITY_ERROR }

the root compiled set artifact for static topology, placement, derived scene machinery, and viewer defaults.

CompiledSet {
  meta: ArtifactMeta,
  authored_set_ref: Handle,
  compiled_world_ref: Handle,
  districts: map<DistrictSlug, ResolvedDistrict>,
  face_placements: map<FaceSlug, ResolvedPlacement>,
  anchors: map<ProtoSlug, ResolvedPlacement>,
  tracks: map<TrackSlug, ResolvedTrack>,
  docks: map<EffectSlug, ResolvedPlacement>,
  screens: map<ProjectionSlug, ResolvedPlacement>,
  semantic_connection_points: map<TrackSlug, ConnectionPoints>,
  control_points: map<TrackSlug, Vec3[]>,
  resolved_global_positions: map<Handle, Vec3>,
  derived_conduits: Handle[],
  derived_gates: Handle[],
  derived_switches: Handle[],
  derived_chambers: Handle[],
  relation_bridges: Handle[],
  overlay_channels: Handle[],
  default_labels: map<Handle, string>,
  default_camera_state: CameraState,
  default_lens_state: LensState,
  compile_diagnostics: CompileDiagnostic[],
}

• invariant. this artifact may derive scene machinery only from authored landmarks plus compiled world topology.
• first appears. built in LoweredSet from ResolvedSet and CompiledWorld.
• viewer boundary. static viewer reads topology, placement, and defaults from here; ViewerFrame stays thin.

specimen:
CompiledSet.tracks["activation"] =
  ResolvedTrack { from: "cs.finexa_credit_world.anchor.credit_request", to: "cs.finexa_credit_world.anchor.credit" }

one district frame after placement resolution.

ResolvedDistrict { id: Handle, origin: Vec3, extent: Vec3, members: Handle[] }

• first appears. resolved in ResolvedSet when district-local coordinates are lifted.
• consequence. camera fitting, culling, and layout diagnostics all anchor on this frame.

specimen:
ResolvedDistrict { id: "cs.finexa_credit_world.district.activation", origin: (20,0,0), extent: (12,6,10) }

one landmark after district-local coordinates are lifted into world-space coordinates.

ResolvedPlacement { handle: Handle, district: Handle, global_position: Vec3 }

• first appears. emitted during set resolution from district-local authored positions.
• consequence. viewer startup never has to recompute placement math.

specimen:
ResolvedPlacement { handle: "cs.finexa_credit_world.anchor.credit_request", district: "cs.finexa_credit_world.district.intake", global_position: (4,1,0) }

one process track after semantic connection points and control points are lifted into resolved world geometry.

ResolvedTrack {
  district: Handle,
  from: Handle,
  to: Handle,
  semantic_connection_points: ConnectionPoints,
  control_points: Vec3[],
}

• first appears. resolved in ResolvedSet after anchor placement closure.
• consequence. motion, breadcrumb animation, and lane highlighting all share the same compiled geometry.

specimen:
ResolvedTrack { district: "cs.finexa_credit_world.district.activation", from: "cs.finexa_credit_world.anchor.credit_request", to: "cs.finexa_credit_world.anchor.credit" }

the semantic endpoints of one authored or compiled track.

ConnectionPoints { from_point: Vec3, to_point: Vec3 }

• first appears. derived during track resolution from authored endpoints and district frames.
• consequence. viewer routing stays semantically anchored even if spline geometry changes later.

specimen:
ConnectionPoints { from_point: (4,1,0), to_point: (9,1,0) }