Canonical Vocabulary

The terms StoryTangl uses, what they mean, and where they live in the code.

This glossary maps between narratological concepts, engineering metaphors, and implementation names. When design docs, docstrings, or commit messages use these terms, they mean exactly what’s defined here.

---

Core Graph Primitives

Term	Metaphor	Definition	Implementation
Entity	managed object	Base data structure with identity, labels, tags, and comparison semantics	core.entity.Entity
Registry	collection	Indexed collection of entities with criteria-based search	core.registry.Registry
Node	vertex	Graph member; may carry state, children, and handler registrations	core.graph.Node
Edge	constraint	Directed link between nodes; carries predicate and effect semantics	core.graph.Edge
Subgraph	scope boundary	Named partition of related nodes with source/sink entry points	core.graph.Subgraph
Graph	program	Registry of nodes, edges, and subgraphs with membership and ancestry	core.graph.Graph

Narrative Architecture

Term	Metaphor	Definition	Implementation
Fabula	possibility space	The complete graph of events, characters, and relationships — all possible stories	StoryGraph after compilation
Episodic process	execution	Cursor-driven traversal that collapses fabula into a specific story	Frame.follow_edge() pipeline
Syuzhet	output trace	The linear journal of content fragments as experienced by the reader	Journal / OrderedRegistry
Block	instruction	Traversable structural node that generates content when visited	story.episode.Block
Scene	function	Structural subgraph containing blocks, with local roles and settings	story.episode.Scene
Action	branch	Traversable edge representing a player choice between blocks	story.episode.Action
Actor	resource	Non-traversable concept node representing a character	story.concepts.Actor
Location	resource	Non-traversable concept node representing a place	story.concepts.Location
Role	dependency slot	Named placeholder linking a structural node to a required actor	story.concepts.Role (dependency edge)
Setting	dependency slot	Named placeholder linking a structural node to a required location	story.concepts.Setting (dependency edge)

Execution Model

Term	Metaphor	Definition	Implementation
Frame	stack frame	Runtime context for a single traversal step: cursor, namespace, phase state	vm.Frame
Phase	compiler pass	One stage of the resolution pipeline; pure contract on inputs/outputs	ResolutionPhase enum
Cursor	program counter	Current position in the structural graph	Frame.cursor_id
Frontier	enabled set	Available outgoing edges from the current cursor position	Computed by do_validate
Namespace	symbol table	Scoped mapping of identifiers, layered local → ancestor → domain → global	PhaseCtx.get_ns(node) / do_gather_ns() → ChainMap
Ledger	event log	Append-only record of patches (state changes) per story instance	vm.Ledger
Patch	diff hunk	Single atomic state change: (step, target, op, before, after)	Ledger entries
Snapshot	checkpoint	Serialized graph state at a point in time; replayable with patch log	persistence.Snapshot

Provisioning

Term	Metaphor	Definition	Implementation
Requirement	package.json line	Declarative specification of what a dependency edge needs	ProvisionRequirement
Offer	candidate package	A proposed binding that could satisfy a requirement	ProvisionOffer
Resolver	package manager	Walks open dependencies, gathers offers, selects bindings by policy	vm.provision.Resolver
Provisioner	provider strategy	Concrete strategy for generating offers (find, create, template, clone)	FindProvisioner, TemplateProvisioner, etc.
Scope group	search radius	Set of registries to search for offer candidates, ordered by proximity	Resolver constructor args
Binding	lock-file entry	Committed assignment of a specific resource to a dependency edge	Resolved edge with destination
Narrative debt	technical debt	Provisioned concept not yet introduced to the reader via journal	Bound dependency with no journal coverage
Narrative credit	foreshadowing	Concept introduced in journal before any structural need requires it	Namespace-published, no dependency yet

Dispatch and Behavior

Term	Metaphor	Definition	Implementation
Behavior	plugin	Callable registered for a specific task at a specific priority	core.behavior.Behavior
Task	hook point	Named extension point in the pipeline (e.g., validate_edge, render_journal)	Task name string
Priority	ordering	Execution order within a task: EARLY → NORMAL → LATE	HandlerPriority enum
Layer	override scope	Dispatch tier: SYSTEM < APPLICATION < DOMAIN < INSTANCE	DispatchLayer enum
Aggregation mode	fold strategy	How multiple handler results combine: all_true, gather, merge, first, last	AggregationMode enum
Receipt	audit record	Record of what a handler did: blame_id, result, timing	JobReceipt
on_ / do_**	event / handler	Hook pair: on_* fires registered behaviors; do_* is the task implementation	dispatch.py in each layer

Content and Presentation

Term	Metaphor	Definition	Implementation
Fragment	log record	Atomic unit of journal output: content, type, source reference, metadata	core.fragment.BaseFragment
Content fragment	prose block	Text content rendered from a structural node	ContentFragment
Choice fragment	menu item	Available action with caption, availability status, and blocker diagnostics	ChoiceFragment
Media fragment	asset reference	Pointer to media content (image, audio) with staging hints	MediaFragment
Journal	narrative log	Ordered sequence of fragments constituting the syuzhet so far	OrderedRegistry
RIT	inventory tag	Resource Inventory Tag — content-addressed reference to a media asset	MediaRIT
Render profile	Accept header	Client capability declaration guiding fragment → presentation transformation	Service-layer configuration
Staging hints	CSS-like metadata	Rendering suggestions (orientation, placement, z-index) for media fragments	StagingHints

Templates and Compilation

Term	Metaphor	Definition	Implementation
World	source distribution	Singleton factory holding scripts, templates, and handlers for a story domain	story.World
Script	source code	YAML (or other format) defining structural and conceptual content	Authored .yaml files
Compiler	front-end	Transforms scripts into a world bundle (graph template + registries)	StoryCompiler
Materializer	linker	Instantiates a live story graph from a compiled world bundle	Materializer
Template	class definition	Prototype data for creating new node instances during provisioning	Template registries
Vocabulary bank	word list	Themed word/phrase collections for procedural prose generation	Namespace contributors

Cross-Cutting Concerns

Term	Metaphor	Definition	Implementation
Singleton	immutable constant	Named, immutable entity serializable by reference	core.singleton.Singleton
Token	wrapped constant	Graph-attachable wrapper adding mutable instance state to a singleton	core.singleton.Token
Domain	library / plugin	Named scope contributing variables, handlers, and templates	core.domain.Domain
Scope layer	stack frame	Local get_ns() maps plus gather-time overlays contributed by a domain or subgraph	Namespace assembly during do_gather_ns
Source / Sink	entry / exit	Dominator and post-dominator nodes of a subgraph scope	Subgraph structural properties

---

Metaphor Families

The vocabulary above draws on several metaphor families. When explaining the system, prefer the metaphor that fits the audience:

For software engineers: compiler pipeline, package resolution, event sourcing, stack frames. “The resolver is a dependency solver; the ledger is an event log; phases are compiler passes.”

For narratologists: fabula/syuzhet, kernels/satellites, focalization, morphological functions. “The graph is the fabula; the journal is the syuzhet; dependency edges are Chatman’s kernels.”

For game designers: possibility space, state collapse, choice consequences, character casting. “The story starts wide open and narrows through play; roles are cast at runtime; choices close off branches.”

For the philosophically inclined: Platonic forms casting shadows, Kantian noumenal/phenomenal distinction, quantum superposition collapsing through observation. Use sparingly. These are analogies, not implementations. The engine does not do quantum mechanics.