tangl.story.concepts

Story-domain concept entities that provide narrative vocabulary and namespace contributions.

Related design docs

Related notes

Core concept types

class Actor[source]

Named character provider published into the story namespace.

Why

Actor gives story templates a lightweight provider node for named characters. Role edges can resolve against these nodes without needing a story-specific provider protocol.

Key Features

  • Stores a human-friendly name alongside the graph label.

  • Carries narrator-facing epistemic annotations on the actor itself.

  • Publishes actor metadata into local namespace composition via provide_actor_symbols().

API

  • name stores the authored display name.

  • provide_actor_symbols() returns the namespace payload contributed by this actor.

class Location[source]

Named place provider with local namespace publication.

Why

Location gives story templates a lightweight provider node for places. Settings and runtime namespace gathering can reference these nodes without making places part of the cursor-traversal fabric.

Key Features

  • Carries a human-friendly name alongside the graph label.

  • Carries narrator-facing epistemic annotations on the location itself.

  • Publishes location metadata as a local namespace contribution through provide_location_symbols().

API

  • name stores the authored display name.

  • provide_location_symbols() returns the local namespace payload later gathered into scoped runtime views.

class Role[source]

Story-specific dependency edge that binds an actor provider into gathered scope.

Why

Role turns generic dependency resolution into a narrative concept with a stable namespace contract, making resolved actors available under both the role label and derived metadata keys.

Key Features

  • Extends Dependency so role edges participate in standard provisioning and frontier resolution.

  • Publishes the resolved actor under the role label plus derived metadata keys such as guide_name.

  • Publishes additive aliases such as guide_role and role_edges so templates and filters can address role-level epistemic state separately from provider-level knowledge.

  • Contributes a merged roles mapping during namespace gathering.

API

  • provide_role_symbols() returns the local symbol payload reused by gather-time assembly.

See also

Actor

Default provider type bound by role dependencies.

Dependency

Base provisioning edge contract used by story roles.

class Setting[source]

Story-specific dependency edge that binds a location provider into gathered scope.

Why

Setting specializes generic dependency resolution for location-like providers so story blocks and scenes can expose a stable place contract without hard-coding provider lookup rules.

Key Features

  • Extends Dependency so settings use the same provisioning mechanics as other frontier edges.

  • Publishes the resolved provider under the setting label plus derived metadata keys during namespace gathering.

  • Publishes additive aliases such as place_setting and setting_edges so setting-level epistemic state remains distinct from provider-level knowledge.

  • Contributes a merged settings mapping for render/provision helpers.

API

  • provide_setting_symbols() returns the local symbol payload reused by gather-time assembly.