tangl.story.runtime

Runtime graph and handler surfaces used during namespace gathering, choice preview, and journaling.

Related design docs

Related notes

Runtime graph

class StoryGraph[source]

Runtime graph specialization for story-layer execution state.

Why

Story execution needs more than generic graph topology. StoryGraph adds story locals, runtime lineage state, and a compatibility world alias over the bound graph factory so story handlers can resolve scoped data without reaching back into compile-time structures directly.

Key Features

  • Tracks one or more initial cursor ids for entry into the runtime graph.

  • Carries story locals plus runtime lineage state outside serialized graph payloads.

  • Records template lineage for each materialized entity so provisioning can recover template scope.

API

  • get_story_locals() returns the story-level namespace payload.

  • get_authorities() returns dispatch registries available to runtime handlers.

  • get_template_scope_groups() returns template groups ordered from the closest scope outward.

Runtime context

Story runtime helpers use the VM’s canonical phase context directly.

class PhaseCtx(graph, cursor_id, step=0, current_phase=ResolutionPhase.INIT, correlation_id=None, logger=None, meta=<factory>, causality_mode=CausalityMode.CLEAN, mark_soft_dirty_callback=None, escalate_to_hard_dirty_callback=None, random=<factory>, inline_behaviors=<factory>, local_authorities=<factory>, incoming_edge=None, incoming_payload=None, _ns_cache=<factory>, _ns_inflight=<factory>, _result_pipe_stack=<factory>)[source]

Dispatch context for one follow_edge call.

Why

Every do_* call in the pipeline requires a context that satisfies the BehaviorRegistry.chain_execute_all protocol: get_authorities() and get_inline_behaviors(). PhaseCtx provides these, plus VM-specific accessors for the cursor, graph, namespace, and random state.

Lifecycle

One PhaseCtx per follow_edge invocation. The cursor is fixed for the duration (it was just updated at the top of follow_edge). The current_phase field is updated as the pipeline progresses — this lets handlers know which phase they’re executing in.

Namespace

get_ns(node) delegates to do_gather_ns which assembles a scoped namespace in two phases: caller/ancestor entity-local get_ns() maps, then immediate-caller dispatch contributors. Results are cached per node UID for the lifetime of this context — the assembled view is stable within a single pipeline pass.

The cache is keyed by node UID, so different nodes (cursor vs. frontier nodes during PLANNING, different ancestors during condition evaluation) each get their own cached namespace. The cache dies with the context (one follow_edge call), so mutations in UPDATE are reflected in the next pipeline pass.

API

  • get_authorities() — authority registries for dispatch expansion.

  • get_inline_behaviors() — inline behaviors (empty for now).

  • get_ns(node) — cached assembled scoped namespace for a node.

  • get_random() — deterministic RNG for this frame.

  • cursor — the current node (resolved from cursor_id).

Implements

tangl.vm.ctx.VmPhaseCtx

Protocol consumed by vm phase handlers and resolver helpers.

Journal handlers

Default story dispatch handlers for namespace gathering and journaling.

This module registers the story-layer handlers that:

  • contribute story and world locals during gathered namespace assembly,

  • contribute template scopes and token catalogs for runtime provisioning, and

  • turn a Block cursor into journal fragments during the JOURNAL phase.

These handlers define story-specific policy on top of the generic dispatch and resolver mechanisms in tangl.vm.