Implementation Architecture

This page maps the source-to-runtime implementation for contributors. It is not required for writing simple Strata programs.

Crate Layout

Source Path

flowchart LR
    Source["source text"]
    Lexer["lexer"]
    Parser["parser"]
    Ast["AST"]
    Checker["semantic checker"]
    Checked["checked IR"]
    Lowering["lowering"]
    Artifact["Mantle Target Artifact"]

    Source --> Lexer --> Parser --> Ast --> Checker --> Checked --> Lowering --> Artifact

The parser accepts source shape. The checker assigns source-visible meaning, resolves names, validates process/message/state rules, and produces checked IR. It resolves process reference names and source type references into checked IDs, including checked type identities for value and process-reference payloads. Lowering converts checked IR into Mantle artifact tables by mapping checked process, message, state, output, and type IDs to artifact IDs.

Runtime Path

flowchart LR
    Artifact["artifact text"]
    Decode["decode"]
    Validate["validate"]
    Load["load typed runtime tables"]
    Plan["build executable plan"]
    Spawn["spawn Main"]
    Deliver["deliver entry message"]
    Dispatch["dispatch by message ID"]
    Execute["execute typed actions"]
    Host["explicit runtime host"]
    Trace["JSONL trace sink"]
    Output["program output sink"]

    Artifact --> Decode --> Validate --> Load --> Plan --> Spawn --> Deliver --> Dispatch --> Execute --> Host
    Host --> Trace
    Host --> Output

Mantle must validate artifacts before execution. Runtime dispatch uses loaded typed IDs, not source strings. Payload and state type identity is admitted through Mantle type-table IDs; source type labels are metadata only. The executable plan is an internal Mantle structure built from the admitted LoadedProgram; it pre-resolves typed dispatch, action, and executable value template references but is not serialized bytecode and is not emitted by Strata lowering. Strata still emits typed .mta value templates at the boundary; Mantle owns only the internal executable template program derived from admitted artifact data. Runtime execution emits events, program output, monotonic time queries, and final flushes through an explicit RuntimeHost; the CLI is a filesystem/stdout host adapter over that admitted core, while in-memory callers use the same runtime path with in-memory sinks.

Important Boundaries

Strata owns:

• source syntax;
• diagnostics;
• AST;
• semantic checking;
• checked IR;
• source-visible meaning.

Lowering owns:

• conversion from checked Strata IR into Mantle artifact records;
• mapping checked process, message, state, type, and output IDs to artifact IDs.

Mantle owns:

• artifact decoding and validation;
• admitted runtime tables;
• process instances and mailboxes;
• action execution;
• host-mediated runtime events, output, clocks, and traces.

Workspace source-to-runtime acceptance gates own the cross-boundary proof that a Strata program can be checked, lowered, admitted by Mantle, executed, and traced.

flowchart LR
    subgraph Strata["Strata frontend"]
        Syntax["source syntax"]
        Check["semantic checking"]
        Ir["checked IR"]
    end

    subgraph Lower["Lowering boundary"]
        Map["typed ID mapping"]
        Mta["Mantle Target Artifact"]
    end

    subgraph Mantle["Mantle runtime"]
        Admit["artifact admission"]
        Tables["loaded typed tables"]
        Plan["internal executable plan"]
        Exec["runtime execution"]
        Obs["observability"]
    end

    Syntax --> Check --> Ir --> Map --> Mta --> Admit --> Tables --> Plan --> Exec --> Obs

Do not move source-only assumptions into Mantle as trusted runtime behavior. Do not make Mantle dispatch through labels that exist only for diagnostics or trace readability. Do not move Strata source constants, default output paths, examples, or source-to-runtime gates into Mantle-owned crates.

Adding A Language Feature

A source-facing feature usually needs changes across several layers:

• parser;
• AST;
• checker;
• checked IR;
• lowering;
• artifact schema or validation, when runtime representation changes;
• runtime execution, when behavior changes;
• diagnostics;
• examples;
• docs;
• positive tests;
• negative tests;
• source-to-runtime gates, when user-visible execution changes.

Parser acceptance alone is not enough. If another layer can construct or admit the same invalid state, that layer needs its own validation.

Existing Source-To-Runtime Gates

The runnable examples are:

• examples/hello.str;
• examples/actor_ping.str;
• examples/actor_sequence.str;
• examples/actor_match.str;
• examples/init_match.str;
• examples/init_return_match.str;
• examples/function_match.str;
• examples/function_payload_match.str;
• examples/function_if_else.str;
• examples/function_collection_match.str;
• examples/function_return_match.str;
• examples/process_return_match.str;
• examples/process_return_match_arm_prefix.str;
• examples/process_return_match_arm_runtime_if_prefix.str;
• examples/process_return_match_arm_for_prefix.str;
• examples/process_return_match_arm_for_if_prefix.str;
• examples/process_return_match_arm_if_for_prefix.str;
• examples/function_record_pattern.str;
• examples/function_record_return_match.str;
• examples/function_record_body_match.str;
• examples/state_payload_enum.str;
• examples/collection_state.str;
• examples/state_payload_match.str;
• examples/actor_instances.str;
• examples/actor_payloads.str;
• examples/runtime_if_else.str;
• examples/runtime_payload_projection_if.str;
• examples/runtime_payload_projection_next_state.str;
• examples/runtime_state_payload_projection_if.str;
• examples/runtime_state_payload_projection_next_state.str;
• examples/runtime_nested_if_actions.str;
• examples/runtime_final_if_guarded_loop.str;
• examples/runtime_final_if_nested_if_actions.str;
• examples/runtime_final_if_nested_terminal_if.str;
• examples/runtime_guard_noop.str;
• examples/runtime_for_each.str;
• examples/runtime_for_each_empty.str;
• examples/runtime_for_each_if.str;
• examples/runtime_for_each_nested_if_actions.str;
• examples/runtime_guarded_for_each.str;
• examples/runtime_guarded_ref_loop.str;
• examples/runtime_guarded_ref_loop_jobs.str;
• examples/runtime_loop_element_projection.str;
• examples/actor_payload_match.str;
• examples/actor_payload_split_match.str;
• examples/actor_payload_split_signature.str;
• examples/actor_payload_split_signature_wildcard.str;
• examples/actor_payload_state_match_split.str;
• examples/actor_payload_state_match_wildcard.str;
• examples/nested_patterns.str;
• examples/actor_reply.str;
• examples/actor_emit_spawn_send.str;
• examples/effect_outcome_spawn_denied.str;
• examples/actor_panic_no_replay.str.

The integration tests rooted at crates/strata-mantle-acceptance/tests/source_to_runtime_gates.rs, with focused gate families under crates/strata-mantle-acceptance/tests/source_to_runtime_gates/, mirror the same source check, artifact build, and runtime execution sequence:

just run-example hello

The same pattern applies to the actor examples. Fail-closed examples check and build, but their runtime gate expects mantle run to return non-zero after emitting trace evidence.

Closure Rule

A change that affects source syntax, artifact schema, runtime behavior, diagnostics, examples, or gates should update this book and pass:

just quality

Docs explain the contract; runnable gates prove the behavior.