tangl.story.fabula

Compilation and materialization APIs for turning authored scripts into runtime story graphs.

Related design docs

• Story Compilers

• Template Scope

• Story Entry Resolution

Related notes

• Code-Adjacent Design Docs

• VM38 Docstring Drift Audit

• ScriptManager query facade migration (v3.7)

Compilation

class StoryCompiler

Validate and normalize authored story script data into a StoryTemplateBundle.

Why

Authored story scripts are intentionally lightweight. The compiler turns that loose authoring shape into a typed, scoped template tree that runtime materialization and provisioning can trust.

Key Features

• Accepts raw dicts or validated StoryScript instances.

• Builds scene and block template hierarchy used by runtime scope matching.

• Canonicalizes action references so authored shorthand and qualified references resolve into a stable form.

• Attempts to resolve authored kind references during compilation when an override cannot be imported.

API

• compile() is the supported public entry point.

class StoryTemplateBundle

Canonical output of StoryCompiler.

Why

Separating compilation from materialization lets one validated script bundle produce many independent story graphs without reparsing authored input.

Key Features

• Carries the validated TemplateRegistry tree used by the materializer.

• Preserves metadata, story locals, source mapping, and codec state alongside the template hierarchy.

• Records entry_template_ids so materialization can resolve the graph’s initial cursor positions deterministically.

• Stores structured compiler diagnostics for cheap bundle-local integrity problems without forcing materialization first.

API

• metadata stores story-level metadata used by runtime setup.

• locals stores authored top-level namespace values.

• template_registry contains the validated template hierarchy.

• entry_template_ids lists the template ids used for initial cursor resolution.

• issues stores structured compile diagnostics for later inspection.

• source_map, codec_state, and codec_id preserve compile-time provenance and codec context.

class CompileIssue(code, severity, message, phase='compile', subject_label=None, source_ref=None, related_identifiers=<factory>, details=<factory>)

Structured compiler diagnostic stored on a compiled story bundle.

Notes

details is reserved for JSON-like payloads only. The compiler module documents allowed keys per issue code near its diagnostics helpers.

class CompileSeverity(*values)

Severity for compile diagnostics.

Notes

v1 of compiler diagnostics emits only error issues. warning exists so the surface can align with later authoring-integrity diagnostics work.

class AuthoredRef(path=None, story_key=None, authored_path=None, label=None, note=None)

Best-effort authored provenance for compile diagnostics.

Notes

This surface intentionally stays coarse in v1. File-level provenance plus compiler-known authored paths are sufficient for bundle preflight without blocking on line/column mapping.

Materialization

class StoryMaterializer

Story-policy helper for runtime graph wiring and compatibility delegation.

Why

World.create_story(...) now owns graph creation directly by layering over TraversableGraphFactory. StoryMaterializer remains as the focused helper that applies story-specific topology, eager prelink policy, and runtime materialization hooks on top of that lower-layer graph creation.

Key Features

• Wires story-specific topology onto an already-materialized graph.

• Supports eager prelink/report passes once generic graph creation completes.

• Preserves template-to-entity lineage for runtime scope lookup.

• Finalizes scene contracts and wires node destinations after instantiation.

• Uses vm resolver semantics instead of reimplementing provisioning logic.

API

• create_story() delegates to a bound world for compatibility.

• make_state() builds story wiring state from direct runtime authorities.

class World(label: str)

Unitary story authority over templates, runtime graph creation, and world adjunct providers.

Why

World is the canonical story-layer authority object. It owns the story template bundle, runtime behavior authorities, and compatible accessors for loader/service surfaces while delegating generic graph materialization to TraversableGraphFactory.

Key Features

• Acts as the singleton shape and behavior authority for StoryGraph.

• Preserves bundle-derived metadata, locals, entries, and compile provenance directly on the world.

• Keeps compatibility alias views for one phase of the world cutover.

API

• create_story() is the public story initialization entry point.

• get_authorities() exposes world-owned dispatch registries.

• get_story_info_projector() returns the world-owned projector when present.

• find_template() and find_templates() resolve directly against the world’s template registry.

class ScriptManager(template_registry, world_scope_provider=None)

Runtime template lookup and scope-group facade for story.

Init result types

class InitMode(*values)

Initialization depth for story graph materialization.

class InitReport(mode, materialized_counts=<factory>, prelinked_counts=<factory>, unresolved_hard=<factory>, unresolved_soft=<factory>, warnings=<factory>)

Structured diagnostics emitted during story graph initialization.

Tracks materialized entity counts, dependency prelink results, and any hard or soft unresolved requirements discovered during initialization.

class StoryInitResult(graph, report, entry_ids, source_map=<factory>, codec_state=<factory>, codec_id=None)

Final result of materializing a runtime story graph.

Packages the graph, initialization report, resolved entry ids, and optional source/codec metadata carried forward from compilation.

class GraphInitializationError(report)

Raised when eager initialization cannot satisfy hard requirements.

class ResolutionError(*, source_node_id, source_node_label, action_id, action_label, authored_ref, canonical_ref, reason, selector, world_id=None, bundle_id=None)

Raised when lazy destination wiring cannot resolve canonical targets.

Selected methods

StoryCompiler.compile(script_data, *, source_map=None, codec_state=None, codec_id=None)

Compile authored story data into a reusable template bundle.

Accepts raw script dictionaries or validated StoryScript objects.

Raw dicts are compiled directly. Use validate_ir() separately when authored near-native data should be linted against the IR schema.

StoryMaterializer.create_story(*, story_label, init_mode, freeze_shape=False, world=None)