rust dsl and runtime algebra

root authored world artifact. it gathers all semantic nouns, shared defaults, and schema metadata for one world.

• Authored fields. id slug, optional name, schema_edition, thesis/principles, world-default authority and discharge defaults, plus collections of sources, ports, faces, rulesets, protos, proto bays, processes, routes, effects, and projections. ports carry nested PortBinding values; protos carry nested FieldBinding values.
• Compiler derives. normalized ids, reference tables, schema hashes, compiled lookup indices, and cross-object validation graphs.
• Invariants. every referenced slug must exist exactly once; authored slugs are stable semantic references; display names cannot be used as identifiers.
• Contracts. serializes to AuthoredWorld; compiles into CompiledWorld.

let world = WorldSpec::new("finexa_credit_world")
    .schema_edition("2026.q1")
    .name("finexa credit ops world")
    .source(Source::http_surface("qr_campaign_surface"))
    .proto(Proto::new("credit_request"))
    .route(Route::new("origination.request.submit"));

declares one outside system or material origin on the far side of the world boundary.

• Authored fields. id, optional name, kind, emitted material kinds, delivery mode, connection/auth hints, and trust classification.
• Compiler derives. source registry entries, capability tables, and admissible port-binding plus face compatibility validations.
• Invariants. a source is external topology, not business ontology; it may emit material but it does not define business truth by itself.
• Contracts. authored by world builders; referenced by port bindings, faces, field bindings, and effects.

Source::webhook("whatsapp_business_api")
    .emits(["chat_event", "flow_submission", "delivery_receipt"])
    .trust("signed_vendor_boundary");

declares one deployed contact point where source material is caught or outbound obligations are delivered.

• Authored fields. id, optional name, direction, transport family, deployment hints, nested PortBinding values, and allowed faces or effect faces.
• Compiler derives. concrete ingress/egress binding tables, capability maps, and compatibility checks against sources, faces, and effects.
• Invariants. port catch is not semantic admission; port direction and allowed face usage must be explicit; every real boundary crossing must name at least one PortBinding.
• Contracts. referenced by Face, outbound effect definitions, and compiled delivery policies.

Port::https("finexa_http_ingress")
    .binding(PortBinding::new("whatsapp_flow_in")
        .source("whatsapp_business_api")
        .parser("flow_submission")
        .matcher("request_ref_and_phone")
        .trust_posture("signed_vendor_boundary"))
    .routes_to_faces(["qr_entry", "whatsapp_chat", "whatsapp_flow", "trello_pipeline"]);

declares one concrete boundary composition on a port. this is where source composition becomes typed law instead of folklore.

• Authored fields. id, optional name, direction, source_ref, source_kind, credential/auth contract, protocol, parser, material contract, matcher, admit policy, bind rule, birth rule, effect policy, deployment, and trust posture.
• Compiler derives. executable ingress/egress adapter plans, boundary validation tables, typed material contracts, and source-to-face/effect compatibility indices.
• Invariants. PortBinding owns boundary composition only. it may normalize, authenticate, parse, match, and classify source material, but it does not maintain business fields and it does not decide local identity beyond the authored bind/birth hooks it exposes to ProtoBay.
• Source composition semantics. the canonical authored model is source_kind + credential + protocol + parser + matcher + admit_policy + bind_rule + birth_rule + effect_policy + deployment + trust_posture.
• Contracts. nested under Port; compiles into compiled_port_bindings and the boundary side of admission/discharge machinery.

PortBinding::new("trello_pipeline_watch")
    .direction("ingress")
    .source("trello")
    .source_kind("board_watch")
    .credential("oauth_workspace_token")
    .protocol("https_webhook")
    .parser("trello_card_event")
    .material_contract("trello.pipeline.event")
    .matcher("list_and_label_match")
    .admit_policy("mapped_operator_action_only")
    .bind_rule("credit_request_keys")
    .birth_rule("deny")
    .deployment("mx-prod-west")
    .trust_posture("operator_observation_only");

declares the semantic aperture where caught material becomes candidate datum under authored rules.

• Authored fields. id, kind, source refs, port refs, optional port-binding refs, ruleset ref, target proto bays, optional admitted datum kinds, and reject/quarantine outlets.
• Compiler derives. face dispatch tables, admissible route families, admission tracing handles, and face-to-boundary compatibility checks.
• Invariants. a face may admit many raw shapes, but it must have one explicit ruleset boundary and target proto bay set. if a face relies on a narrowed boundary composition, it must reference the relevant PortBinding explicitly.
• Contracts. produces Datum through machinery admit; referenced by routes as datum_face.

Face::write("whatsapp_flow")
    .sources(["whatsapp_business_api"])
    .ports(["finexa_http_ingress"])
    .port_bindings(["whatsapp_flow_in"])
    .ruleset("whatsapp_flow_rules")
    .targets(["party", "credit_request"]);

declares the executable boundary and transformation graph. rulesets are declarative operator DAGs, not opaque blobs.

• Authored fields. id, face or effect context, optional boundary contract refs, stage graph, input datum or payload contracts, output contracts, schema/version handling, and explicit operator nodes.
• Required operators. map, filter, join, window, aggregate, project, schema_map, quarantine, reject.
• Compiler derives. executable stage DAGs, contract validation, and compiled operator plans.
• Invariants. every ruleset path terminates in admit, reject, or quarantine; schema version handling cannot be implicit folklore.
• Contracts. referenced by faces for inbound admission and by field bindings/process transitions for internal maintenance logic.

Ruleset::new("whatsapp_flow_rules")
    .input("flow_submission")
    .stage("schema_map", "version_form_schema")
    .stage("map", "map_form_fields")
    .stage("filter", "require_pending_request_ref")
    .stage("quarantine", "schema_drift_or_missing_identity");

declares the semantic schema and the maintenance contract for one durable kind. proto is the field-level queryable meaning surface of the world.

• Authored fields. id, optional name, description, keys, lookups, relations, field set, optional field groups, and maintenance defaults.
• Compiler derives. compiled schema tables, field hydration plans, relation indices, field-group authority scopes, and validation contracts.
• Invariants. proto owns schema and field maintenance; it does not own identity crossing. every authored field must declare datatype semantics and one canonical maintenance path.
• Contracts. serializes into authored schema artifacts; compiles into executable field hydration and readout support.

Proto::new("credit")
    .key("credit_id")
    .lookup("fibo_credit_id")
    .lookup("croop_credit_id")
    .field(ProtoField::string("credit_id").required())
    .field(ProtoField::money("principal_balance").group("balance"))
    .field(ProtoField::enum_("status").group("lifecycle"));

declares one field inside a proto, including type and maintenance semantics.

• Authored fields. field slug, datatype, cardinality, nullability, default, field group, required-for-shape flag, and derive mode.
• Derive modes. direct source mapping, ruleset output, join, window, aggregate, projection-fed, or compiler-derived constant/default.
• Compiler derives. field-level validation, storage shape, hydration plans, and readout dependencies.
• Invariants. field hydration belongs here with FieldBinding, never inside BindStrategy.
• Contracts. nested under Proto; referenced by FieldBinding and field-group authority policies.

ProtoField::money("principal_balance")
    .nullable(false)
    .group("balance")
    .derive_mode("aggregate")
    .required_for_shape(true);

declares how one proto field is maintained from one or more upstream sources or ruleset outputs.

• Authored fields. target proto field, upstream source refs, face/ruleset outputs, join keys, optional window or aggregate clauses, projection refs, freshness policy, and missing-data behavior.
• Compiler derives. hydration query plans, execution DAG edges, and staleness guards.
• Invariants. field maintenance may mix and match multiple upstreams, but it must produce one canonical maintained value path per field.
• Contracts. nested under Proto; lowered into compiled field hydration/query plans.

FieldBinding::for_field("principal_balance")
    .from_face("croop_api")
    .via_ruleset("croop_api_rules")
    .join_on([("croop_credit_id", "croop_credit_id")])
    .fresh_for("4h")
    .on_missing("preserve_previous_and_raise_drift");

declares identity crossing for one proto: which faces may approach, how bind precedence works, when birth is allowed, and what lane/authority defaults apply.

• Authored fields. target proto, intake faces, bind strategy, birth strategy, lane policy, authority default, and quarantine lane or rejection policy.
• Compiler derives. ordered executable lookup plans, bind tables, lane-key resolvers, and default crossing traces.
• Invariants. proto bay is identity-only; it does not hydrate arbitrary business fields. every intake face must be declared. bind precedence is ordered and explicit.
• Contracts. feeds machinery route, place, and commit; compiles into crossing policy.

ProtoBay::new("credit_request")
    .intake(["qr_entry", "whatsapp_chat", "whatsapp_flow", "trello_pipeline"])
    .bind(BindStrategy::by_precedence([
        KeyRef::field("request_id"),
        KeyRef::compound(["qr_context_id", "phone"]),
        KeyRef::field("trello_card_id"),
    ]))
    .birth(BirthStrategy::new().when("commit").requires(["phone"]).shape("minimal_shell").on_fail("quarantine"))
    .lane(LanePolicy::explicit("credit_request/request_id"));

declares one FSM of lawful motion over a durable kind or cross-kind operating track.

• Authored fields. id, tracked proto or family, statuses, transitions, and optional route attachments.
• Compiler derives. transition graph validation, status ordering helpers, and viewer track metadata.
• Invariants. process semantics include statuses, legal transitions, and side effects; process state is not inferred from tool UI drift.
• Contracts. referenced by routes, compiled track layouts, and runtime readout.

Process::new("risk_review")
    .status(ProcessStatus::new("pending_bureau"))
    .status(ProcessStatus::new("analyst_review"))
    .status(ProcessStatus::terminal("approved"))
    .transition(ProcessTransition::new("analyst_review", "approved"));

declares one named process state.

• Authored fields. status slug, terminal/intermediate kind, optional presentation label, and optional status-local effects or notes.
• Compiler derives. normalized ordering and track-stop metadata.
• Invariants. statuses are legal FSM states, not projections of vendor list names.
• Contracts. nested under Process; referenced by transitions and viewer track rendering.

ProcessStatus::terminal("approved").label("approved")

declares one legal edge in a process FSM, including any required side effects or guards.

• Authored fields. from status, to status, optional guard refs, optional route refs, and side-effect refs.
• Compiler derives. transition legality tables and route-to-process transition validations.
• Invariants. transitions are explicit; no route may silently move process state without a declared legal edge.
• Contracts. nested under Process; consumed by Route and compiled track logic.

ProcessTransition::new("analyst_review", "approved")
    .via_route("risk.review.decide")
    .effects(["notify_mattermost"]);

declares one legal interpretation path for one admitted datum family.

• Authored fields. id, datum face, eligible datum kind, touched proto bays, process transition, lane policy, commit fact kinds, birth permissions, effects/obligations, authority override, discharge override, and failure/quarantine policy.
• Compiler derives. dispatch entries, commit-domain plans, effect obligation templates, and validation against process and proto bay law.
• Invariants. route-level fact kinds are authored explicitly; birth must align with proto bay policy; one admitted route yields one local commit boundary.
• Contracts. authored route becomes RouteSelection at runtime and drives decide plus commit.

Route::new("activation.credit.create")
    .datum_face("trello_pipeline")
    .datum_kind("normalized_activation_command")
    .touches(["credit", "credit_request"])
    .process_transition("activation:approved->active")
    .lane(LanePolicy::explicit("credit_request/request_id"))
    .commit_facts(["credit.created", "credit_request.linked"])
    .births(["credit"])
    .effects(["create_or_move_trello_card", "sync_to_fibo"])
    .on_fail("quarantine");

declares one outbound obligation family owed to the outside world.

• Authored fields. id, effect face, destination source, payload contract, discharge policy, retry/escalation hints, and emitted receipt kinds.
• Compiler derives. obligation templates, delivery plans, and discharge matchers.
• Invariants. effects are not hidden side channels; if the world owes it, the effect must be declared and the discharge condition must be named.
• Contracts. emitted by routes as ObligationEnvelope values; closed by DischargeReceipt.

Effect::new("sync_to_fibo")
    .through_face("fibo_outbound")
    .payload("credit_sync_payload")
    .discharge(DischargePolicy::new().receipt("fibo.accepted").timeout("30m"));

declares one read surface or derived operational view over durable record.

• Authored fields. id, source protos or processes, readout intent, refresh mode, and screen affinity.
• Compiler derives. projection dependencies, readout plans, and viewer screen handles.
• Invariants. projections are derived readout, not canonical ontology or hidden process law.
• Contracts. referenced by screens and readout compilation.

Projection::new("active_credits_lens")
    .from_protos(["credit"])
    .from_process("servicing")
    .kind("readout_lens");

declares how one admitted route resolves to its local serial commit domain.

• Authored fields. typed lane-key ref (or DSL alias recipe), referenced fields or relation keys, optional fallback lane, and collision behavior.
• Compiler derives. executable lane-key resolvers and lane conflict detectors.
• Invariants. lane policy is explicit, not inferred from runtime convenience. equal bind results must yield equal lane keys.
• Contracts. lowered into compiled lane-key plans; consumed by machinery place.

LanePolicy::explicit("credit_request/request_id")

declares identity-only matching precedence for entering a proto bay.

• Authored fields. ordered precedence list, compound key groups, optional confidence gates, and match outcome rules.
• Compiler derives. executable lookup chains and ambiguous-match detection plans.
• Invariants. bind strategy never owns field hydration; it only answers whether this datum matches an existing epi and in what order references are attempted.
• Contracts. nested under ProtoBay; compiled into crossing policy.

BindStrategy::by_precedence([
    KeyRef::field("request_id"),
    KeyRef::compound(["qr_context_id", "phone"]),
    KeyRef::field("trello_card_id"),
])

declares composable birth law. mental model: when + requires + shape + on_fail.

• Authored fields. trigger point, required identities or relations, allowed resulting shape, and failure outcome.
• Compiler derives. birth guards, partial-shape validators, and crossing failure plans.
• Invariants. birth is never implicit from bind miss alone. the strategy must say when birth is legal, what minimum shape is sufficient, and what happens if the minimum is not met.
• Contracts. nested under ProtoBay; consulted during commit.

BirthStrategy::new()
    .when("commit")
    .requires(["phone"])
    .shape("minimal_shell")
    .on_fail("quarantine")

declares who is canonical for maintained truth. granularity is world default, proto field-group policy, and route override.

• Authored fields. canonical owner, field-group scopes, allowed observation faces, allowed writeback effects, and optional route-local override mode.
• Compiler derives. authority matrix and illegal truth-promotion guards.
• Invariants. not every field is authored independently, but field groups such as balance, lifecycle, and external_refs must be nameable and governable.
• Contracts. compiled into authority_matrix; checked during commit and sync discharge.

AuthorityPolicy::world_canonical()
    .field_group("balance", "compiled_world")
    .observe_from_faces(["croop_api"])
    .writeback_effects(["sync_to_fibo"]);

declares what closes an obligation. mental model: satisfying receipt kinds plus timeout, escalation, and terminal failure behavior.

• Authored fields. accepted receipt-kind refs, timeout, escalation target or effect, and terminal failure rule.
• Compiler derives. receipt matchers, expiry watchers, and obligation state transitions.
• Invariants. no obligation may be considered discharged by vendor side effects alone; a declared receipt is required unless the policy explicitly says otherwise.
• Contracts. nested under Effect or route override; compiled into discharge rules and emitted DischargeReceipt matching logic.

DischargePolicy::new()
    .receipt("fibo.accepted")
    .timeout("30m")
    .escalate("notify_mattermost")
    .on_terminal_failure("raise_fault");

root authored set artifact. it places semantic landmarks in district-local 3d space without redefining world law.

• Authored fields. set id, world ref, district placements, face placements, anchor placements, track placements, dock placements, screen placements, camera hints, and lens hints.
• Compiler derives. resolved global positions, derived scene edges, default labels, camera fallbacks, and overlay channels.
• Invariants. coordinates are local to a district frame, not global world absolutes. set authoring may place landmarks and hints only; conduits, gates, switches, chambers, relation bridges, overlay channels, and default labels remain compiler-only.
• Contracts. serializes to AuthoredSet; compiles into CompiledSet.

let set = SetSpec::new("finexa_credit_world")
    .world("finexa_credit_world")
    .district(DistrictPlacement::new("center").origin([0.0, 0.0, 0.0]))
    .anchor(AnchorPlacement::new("credit_request").district("center").at([0.0, 0.0, 0.0]));

declares one local spatial frame for a semantic district such as west, center, north, east, or south.

• Authored fields. district id, local origin, extents, optional orientation, and membership defaults.
• Compiler derives. global transforms and default placement bounds.
• Invariants. all contained landmark coordinates are local to this district frame.
• Contracts. nested under SetSpec; used when resolving placements.

DistrictPlacement::new("center")
    .origin([0.0, 0.0, 0.0])
    .extent([14.0, 8.0, 6.0]);

places one semantic face landmark in district-local space.

• Authored fields. face id ref, district, local position, optional rotation, and optional size/style hint.
• Compiler derives. shell alignment, default conduit anchors, and viewer handles.
• Invariants. face placement references an existing semantic face and does not create one.
• Contracts. nested under SetSpec; compiled into a face landmark in CompiledSet.

FacePlacement::new("whatsapp_flow")
    .district("west")
    .at([1.5, 3.0, 0.5]);

places one proto anchor orb in district-local space.

• Authored fields. proto id ref, district, local position, optional scale, and optional bay emphasis hints.
• Compiler derives. bridge sockets, bay visual handles, and occupancy overlay channels.
• Invariants. anchors correspond to compiled protos only; anchor position does not change identity law.
• Contracts. nested under SetSpec; compiled into anchor nodes.

AnchorPlacement::new("credit")
    .district("center")
    .at([4.0, 0.5, 0.0]);

places one process track using semantic connection points plus optional control points.

• Authored fields. process id ref, district, semantic endpoints or stop refs, optional local control points, and optional stop spacing hints.
• Compiler derives. final curves, stop interpolation, and route overlay attachment points.
• Invariants. track placement is authored as semantic connection points, not arbitrary freehand mesh geometry.
• Contracts. nested under SetSpec; compiled into track geometry and stop metadata.

TrackPlacement::new("activation")
    .district("north")
    .connect("credit_request", "credit")
    .control_points([[1.5, 1.0, 0.0], [2.5, 1.2, 0.0]]);

places one outbound effect dock in district-local space.

• Authored fields. effect id ref, district, local position, and optional orientation or capacity hint.
• Compiler derives. default obligation lanes and effect-edge routing sockets.
• Invariants. docks correspond to declared effects only.
• Contracts. nested under SetSpec; compiled into dock landmarks.

DockPlacement::new("sync_to_fibo")
    .district("south")
    .at([3.0, -2.0, 0.0]);

places one projection screen or readout slab in district-local space.

• Authored fields. projection id ref, district, local position, optional orientation, optional size, and optional default lens ref.
• Compiler derives. screen framing, projection handles, and default label anchors.
• Invariants. screens reference projections; they do not define readout logic themselves.
• Contracts. nested under SetSpec; compiled into screen landmarks.

ScreenPlacement::new("active_credits_lens")
    .district("east")
    .at([2.0, 1.0, 0.0]);

authors basic camera intent for default world framing, focus zones, or entry views.

• Authored fields. hint id, target district or landmark refs, offset, framing mode, and optional zoom/angle preference.
• Compiler derives. camera fallback stack and transition-friendly framing metadata.
• Invariants. camera hints guide staging, but they are not interaction scripts or imperative camera choreography.
• Contracts. nested under SetSpec; exposed to viewer defaults.

CameraHint::new("default_finexa_view")
    .target_districts(["west", "center", "north"])
    .offset([0.0, 0.0, 18.0]);

authors basic readout and overlay emphasis intent for a screen or viewport lens.

• Authored fields. hint id, target projection or landmark refs, overlay channel preferences, selection scope, and filter defaults.
• Compiler derives. viewer-ready lens presets and overlay binding handles.
• Invariants. lens hints guide readout emphasis only; they are not imperative interaction scripting.
• Contracts. nested under SetSpec; consumed by viewer/frame defaults.

LensHint::new("risk_queue_focus")
    .projection("risk_queue")
    .show_channels(["attempts", "obligations", "faults"]);

deterministic world IR for law, machinery, replay, and viewer adapters.

• Compiled fields. meta, authored_world_ref, resolved_ids, compiled_sources, compiled_ports, compiled_port_bindings, compiled_faces, compiled_rulesets, compiled_protos, compiled_proto_bays, compiled_processes, compiled_routes, compiled_projections, bind_plans, birth_plans, lane_key_plans, authority_matrix, discharge_rules, viewer_handles, and compile_diagnostics.
• Resolved ownership. compiled sources and ports keep boundary capabilities; compiled port bindings own parser/matcher/admit composition; compiled protos own field hydration plans; compiled proto bays own bind/birth/lane defaults; compiled routes own commit-domain, fact-kind, and effect emission plans.
• Precedence resolution. lane resolves as route.lane_policy_override > proto_bay.lane_policy; authority resolves as route.authority_override > proto.field_group_policy > world.default_authority; discharge resolves as route.discharge_override > effect.discharge_policy; bind/birth strategy resolves only from ProtoBay.
• Compiler derives. stable dotted resolved handles, executable lookup chains, birth guards, authority guards, discharge matchers, route dispatch tables, relation indices, and viewer-safe handles for districts, landmarks, tracks, and projections.
• Ambiguity errors. same-tier conflicting declarations, missing required resolution, impossible source-to-face contracts, or route-local attempts to redefine proto-bay bind/birth law are compile errors, not runtime fallbacks.
• Contracts. durable deterministic protobuf artifact consumed by Law, Machinery, Readout, and static/dynamic viewer loaders.

high-level summary only here.
full typed catalog:
compiler_ir_spec.html#compiled-world
compiler_ir_spec.html#resolved-ids-public
compiler_ir_spec.html#compiled-route

the lowered boundary object for one deployed source composition path.

• Compiled fields. resolved binding id, port ref, source ref, direction, deployment handle, credential contract, protocol adapter, parser plan, material contract id, matcher plan, admit policy, bind hook, birth hook, effect policy, trust posture, and boundary diagnostics.
• Compiler derives. executable adapter chain, parsed payload contract, matcher bytecode/graph, and compatibility mapping to allowed faces or effect faces.
• Invariants. a compiled port binding may shape and classify source material, but it may not maintain proto truth directly. its output must cross a face/ruleset boundary before it can become a Datum.
• Contracts. nested inside CompiledWorld; consumed by admit and outbound delivery/discharge machinery.

CompiledPortBinding {
  binding_id: "pb_whatsapp_flow_in_01...",
  port_id: "prt_finexa_http_ingress_01...",
  source_id: "src_whatsapp_business_api_01...",
  protocol_adapter: "https_webhook",
  parser_plan: "flow_submission.v3",
  matcher_plan: "request_ref_and_phone",
  trust_posture: "signed_vendor_boundary",
}

deterministic scene IR resolved against compiled world ids.

• Compiled fields. meta, authored_set_ref, compiled_world_ref, districts, face_placements, anchors, tracks, docks, screens, semantic_connection_points, optional control_points, resolved_global_positions, derived_conduits, derived_gates, derived_switches, derived_chambers, relation_bridges, overlay_channels, default_labels, default_camera_state, default_lens_state, and compile_diagnostics.
• Compiler derives. global coordinates from district-local positions, semantic edge routing, default district/layout hints, bridge geometry, overlay lanes, label fallbacks, and camera/lens defaults.
• Invariants. compilation may derive scene machinery only from authored landmarks and compiled world topology. it may not create new routes, proto bays, authority policy, or process law.
• Viewer boundary. every node, edge, position, label, and handle needed for a static render lives here or in CompiledWorld; ViewerFrame never duplicates them.
• Contracts. durable deterministic protobuf artifact loaded directly by the first static viewer.

high-level summary only here.
full typed catalog:
compiler_ir_spec.html#compiled-set
compiler_ir_spec.html#resolved-district
compiler_ir_spec.html#resolved-track