Design Plans

Stable architecture and rationale for the published StoryTangl subsystems.

See also

• Code-Adjacent Design Docs for design notes that still live beside source modules and should eventually be folded into this section.

• Canonical Vocabulary
  • Core Graph Primitives
  • Narrative Architecture
  • Execution Model
  • Provisioning
  • Open Links and Projection
  • Dispatch and Behavior
  • Content and Presentation
  • Templates and Compilation
  • Cross-Cutting Concerns
  • Metaphor Families
• Conceptual Foundations
  • The Central Thesis
    • Why “Untangling”
  • Three Models, Three Layers
    • Fabula — the Possibility Space
    • Episodic Process — the Traversal
    • Syuzhet — the Realized Narrative
    • Why This Separation Matters
  • Concepts As Continuity Anchors
  • The Compiler Metaphor
  • Narrative Debt and Credit
  • Superposition of Possible Stories
    • Latent Hooks and Foreshadowing
  • Landmarks in Story Space
  • Parametric Story Space
  • The Observer Roles
  • Determinism and Replay
  • Theoretical Heritage
  • What This Document Does Not Cover
• Simplification Spec
  • Why This Exists
  • Core
  • VM
  • Story
  • Service
  • What Counts As Accidental Complexity
  • How To Use This
    • 1. Preserve Concepts, Not Incidental Shapes
    • 2. Prefer Direct Typed Paths
    • 3. Delete Dead Weight Before Generalizing
    • 4. Use It As A Porting Checklist
  • Non-Goals
• Content-Addressable Records
  • Overview
  • When to Use
  • Usage
    • Basic Usage (Default Hashing)
    • Custom Hashing
    • Accessing the Hash
  • How It Works
    • Automatic Computation
    • Default Behavior
    • Customization
  • Examples
    • Template Hashing
    • Media Resource Hashing
  • Integration with Registry
  • Provenance Tracking
  • Best Practices
    • DO:
    • DON’T:
  • Performance Notes
  • Troubleshooting
  • See Also
• Dereferencing GraphItems
• Hookable Dispatch Tasks
  • core/global hooks
  • vm/system hooks
  • story/app hooks
  • media/app hooks
  • discourse/app hooks
  • service/system hooks
• Mechanics Families
  • Core Idea
  • Internal Layers
    • 1. Kernel
    • 2. Domain
    • 3. Runtime
    • 4. Render
    • 5. Writeback
    • 6. Facade
  • Review Lens
    • Shape
    • Behavior
    • Attachment Points
    • Appearance
  • Support and Promotion Criteria
  • Current Family Matrix
    • games — Reference
    • progression — Foundation
    • assembly — Foundation
    • demographics — Foundation, first modernization spike
    • presence/wearable and presence/ornaments — Foundation
    • presence/look — Redesign
    • sandbox — Incubating
    • credentials — Incubating
    • scratch/mechanics — Archive
  • Mechanics Convergence
    • World-adopted mechanics and scenario layers
    • Demonstration worlds as conformance surfaces
  • CalvinCards as Exemplar
  • Current Implementation Priorities
• Episode-to-Syuzhet Rendering
  • Purpose
  • The rendering namespace
  • Content requests and adapters
  • Scaling authored content
  • Rejinja as a humane narrative default
  • Other valid adapters
  • Mechanics versus presentation
  • Credentials as a recursive-rendering proof
  • Static and dynamic materialization
  • Near-term implementation implication
  • Related contracts
• StoryTangl Widget Vocabulary
  • 0 · Conventions and principles
    • 0.1 Tier tags
    • 0.2 The CLI Floor Rule
    • 0.3 Backend authority
    • 0.4 Records over tuples
    • 0.5 Naming changes from prior drafts
    • 0.6 Narrative authoring stance
    • 0.7 Three-layer architecture
    • 0.8 Journal as narrative
    • 0.9 Genre extensions index
  • 1 · Top-level contract — Tier S
    • 1.1 RuntimeEnvelope
    • 1.2 Fragment registry and UID stability
    • 1.3 ProjectedState
    • 1.4 Flow vs rail
    • 1.5 Cursors and journal channels — Tier P1
    • 1.6 Info channels — Tier S
  • 2 · Fragment widgets — Tier S
    • 2.1 content — Prose block
    • 2.2 attributed — Dialog line
    • 2.3 media — Media frame
    • 2.4 group — Container
    • 2.5 kv — Key/value rows (unified shape)
      • 2.5.1 Type narrowing via field population
      • 2.5.2 The kv fragment
    • 2.6 choice — Player commit point
    • 2.7 control — Silent fragment mutation
    • 2.8 Non-journal UX events
  • 3 · ProjectedState section values — Tier S
    • 3.1 The value_type discriminated union
    • 3.2 Shapes and renderings
    • 3.3 Section hints
  • 4 · Bundle customization — Tier S
    • 4.1 What is stable (not author-swappable)
    • 4.2 What a bundle MAY override
    • 4.3 Profiles — port conformance subsetting (Tier P2)
  • 5 · Conformance contracts
    • 5.1 Decision Legibility Contract
    • 5.2 Time Parity Rule
    • 5.3 Input Parity Rule
  • 6 · Tier P1 — typed contract surfaces
    • 6.1 Typed Accepts
      • 6.1.1 Commit payload shapes
      • 6.1.2 Validator authority
    • 6.2 Typed UIHints
      • 6.2.1 Genre-specific UIHints sub-shapes (Tier P3)
    • 6.3 Typed Blocker
    • 6.4 RuntimeEnvelope.ux_events
    • 6.5 Direct and exploratory edge resolution
    • 6.6 metadata.grammar
    • 6.7 HTTP API
  • 7 · Tier P2 — interactive surface vocabulary (proposed, larger)
    • 7.1 PieceFragment — Identified surface element with state and lifecycle
    • 7.2 zone — Group container with semantic constraints and geometry
    • 7.3 RollFragment — Structured-outcome ritual
    • 7.4 predicate_ref registration protocol
    • 7.5 Profile registry
  • 8 · Tier P3 — genre extensions (deferred)
  • 9 · Port parity reference (Tier S + Tier P1)
  • 10 · Conformance
    • 10.1 Fixture suite
    • 10.2 Conformance checks (Tier P1)
    • 10.3 CLI floor as gate
    • 10.4 Journal-as-story transcript test
  • Appendix A — Glossary
  • Appendix B — Open questions (working list)
  • Appendix C — Cross-references to genre extensions
• Widget Contract Reconciliation
  • How to read this doc
  • §A — Tier S surfaces (core contract)
  • §B — Tier P1 surfaces (target for next engine epoch)
  • §C — Tier P2 surfaces (interactive surface vocabulary)
  • §D — Tier P3 genre extension surfaces
  • §E — API transport (Layer 2)
  • §F — Conformance harness
  • §G — Recent reconciliation events
    • 2026-06 — spec v1.6 edge resolution and UX events
    • 2026-06 — backend fragment-contract audit (L2/L3 update)
    • 2026-05 — spec v1.5 (L1 update only)
    • 2026-05 — spec v1.3 (L1 update only)
    • 2026-05 — webapp v1.3 reference UI update
    • 2026-05 — webapp v1.5 reference UI reconciliation
    • 2026-05 — engine current (L3 baseline)
  • §H — How to use this doc
  • §I — Forward-looking sequence
• StoryTangl Widget Wireframes
• StoryTangl Brand References
  • v1.0
• StoryTan⅁l · brand usage
  • 1. The mark
  • 2. Where each asset goes
  • 3. SVGs are font-dependent — when to convert to paths
  • 4. The lockup is the wordmark or the wordmark + glyph — never the glyph alone with text
  • 5. The ⅁ character (U+2141) is the ASCII fallback
  • 6. Type stack rules
  • 7. Palette rules
  • 8. Voice and tone rules
  • 9. What an agent must never do
  • 10. Provenance
• Genre Audit Notes — v1.5
  • TL;DR
  • §A — Where the vocabulary works (per paradigm)
    • carwars
    • credentials
    • training (worlds/coronate_the_regent)
    • elefant_hunt
  • §B — Where the vocabulary is awkward but workable
    • Time pressure (credentials, optional)
    • Cell-as-zone for spatial games
    • Composite outcome rituals
    • Hot-seat as multi-cursor stand-in
    • cost_previews naming for gains
  • §C — Where the vocabulary genuinely doesn’t reach
    • §7.4 predicate_ref registration — confirmed highest-leverage open item
    • Multi-cursor projection (Tier P1 §1.5 elaboration)
    • Closed drafting / sealed-bid (re-confirmed out of scope)
  • §D — Cross-paradigm patterns
  • §E — Validation: the journal-as-story claim
  • §F — Recommended next steps
• Carwars Bundle — Widget Vocabulary Extensions
  • 0 · Genre summary
  • 1 · Slot-zone conventions
    • Conventional capacity kinds for carwars
    • Empty slots are visible
    • Inverse: removing a placed piece (unmount)
    • Swap as compose
  • 2 · Catalog conventions
    • Use-case patterns (same shape, different framing)
    • Race conditions on availability
    • Backend-issued realized UIDs
  • 3 · Pre-roll choice → RollFragment flow
    • ui_hints.stat_check typed sub-shape
    • RollFragment.inputs for kind: "dice" rolls
    • CLI floor rendering
  • 4 · ui_hints.drag typed sub-shape
    • Floor rule (mandatory)
    • Capacity preview during drag
    • Reduced motion
  • 5 · Worked example — Garage turn
    • Turn N — entering the Garage
    • Projected state — the ledger
    • Two paths through this turn
    • CLI port rendering of this turn
  • 6 · Combat-resolution patterns
    • Turn N — attack choice
    • Turn N+1 — the roll
    • Damage as a follow-on roll
    • Combat as multi-actor rounds
  • 7 · Edge cases — canonical responses
  • 8 · Testing patterns
    • Vue component tests (Vitest + @vue/test-utils)
    • Integration tests (Vitest + JSDOM)
    • E2E (Playwright)
    • Conformance smoke (CI)
  • 9 · Port parity addendum (carwars-specific widgets)
  • Appendix — BGG mechanism coverage
• Credentials Bundle — Widget Vocabulary Extensions
  • 0 · Genre summary
  • 1 · Domain vocabulary mapped to v1.5
  • 2 · Packet zone conventions
  • 3 · Findings as annotated KvRows
  • 4 · Mediation moves
    • ui_hints.validity_check optional preview
  • 5 · Disposition severity
  • 6 · Restriction map projection
  • 7 · Shift summary
  • 8 · Worked example — one candidate, three turns
    • Turn 1 — candidate arrives
    • Turn 2 — player inspects permit
    • Turn 3 — disposition
  • 9 · Time pressure
  • 10 · Port parity addendum
  • Appendix — Prior art
• Elefant Hunt Bundle — Widget Vocabulary Extensions
  • 0 · Genre summary
  • 1 · Domain vocabulary mapped to v1.5
  • 2 · Board topology
  • 3 · Movement
    • ui_hints.encounter_check optional preview
  • 4 · Hunters as mobs
  • 5 · The hunt — composite RollFragment
  • 6 · Hazard examples
    • River Crossing (probabilistic loss)
    • Albert Falls (mandatory next-turn junction)
    • Elefant Graveyard (special: cost + reward)
  • 7 · Port scoring
  • 8 · Solitaire mode — beat the blind
  • 9 · Multi-cursor framing (Tier P1 target)
  • 10 · The journal-as-story validation
  • 11 · Port parity addendum
  • Appendix — Prior art
• Training Bundle — Widget Vocabulary Extensions
  • 0 · Genre summary
  • 1 · Domain vocabulary mapped to v1.5
  • 2 · Mood as growth modulator
  • 3 · Scheduled events and skill checks
    • ui_hints.stat_check preview (carwars convention reused)
  • 4 · Inventory unlocks
  • 5 · Weekly study commit (richer compose form)
  • 6 · Worked example — Week 2 of coronate_the_regent
    • Envelope at start of week 2
    • CLI rendering
  • 7 · Forward direction (Tier P3 aspirational)
  • 8 · Port parity addendum
  • Appendix — Prior art
• Interaction Vocabulary
  • Design Split
  • Client Capability Floor
  • Core Terms
    • Surface
    • Entity
    • Zone
    • Affordance
    • Move
    • Procedure
    • Resource And Transaction
    • Payload Contract
    • Command Resolution
    • Outcome
    • Record
  • Interaction Classes
  • Visibility
  • Graceful Degradation
  • Mechanic Coverage Targets
  • Near-Term Implementation Targets
  • Non-Goals
• Journal Compose Contract
  • Current Runtime Contract
  • Reference Transform
  • Blessed Stanzas
  • Allowed Transformations
  • Forbidden Transformations
  • Metadata Preservation
  • Semantic Attribution And Derived History
  • Placement Rules
  • Examples
• Beat Composition
  • The pipeline
  • The override ladder
  • The blessed stanzas
  • Worked example
  • Boundaries
• Presence/Prose Contract Spike
  • Why This Spike Exists
  • Current v38 Baseline
  • Target Contract
    • 1. Presentable
    • 2. Narrative State Placement
    • 3. Speaker Profiles and Speech Acts
    • 4. Presence as an Adapter Seam
  • Compatibility with Current Runtime
  • Toy Spike Proof
  • Forward Integration
• Conditional Narratives in StoryTangl
  • State Variables
  • Effects
  • Conditions
  • Items and Flags
• Singleton Asset: Type/Token Pattern
  • The Pattern
  • Why This is Genius
    • Problem 1: Consistency
    • Problem 2: Memory
  • The Architecture
    • Layer 1: Singleton Registry (Type System)
    • Layer 2: Token Wrapper (Token System)
    • Layer 3: Usage in Story
  • Asset Manager Role
  • Resource Manager (Files/Media)
  • Script Format for Assets
    • YAML Definition
    • Story Script Reference
    • Programmatic Token Creation
  • Benefits Recap
    • 1. Consistency
    • 2. Memory Efficiency
    • 3. Centralized Logic
    • 4. Query Type Properties
  • Implementation Questions
    • Q1: Where do SingletonNodes live?
    • Q2: How to handle countable assets (potions)?
    • Q3: What about durability/condition?
  • World Architecture Update
  • Testing Strategy
  • Summary
• Concept Provisioning Design
  • Core Philosophy
  • Declaration Semantics
    • Named Individuals: Affordances
    • Generic Templates: Script Records in Registry
      • Template Structure
      • Declaration and Scope Inference
      • Storage: Single World Registry
      • Queries: Standard Registry API
      • Scope-Based Selection
      • Semantic Properties
  • Reference Semantics in Roles/Settings
    • 1. actor_ref: Named Reference
    • 2. actor_criteria: Pattern Matching
    • 3. actor_template: Inline Creation
    • 4. actor_template_ref: Registry Lookup
    • 5. Fallback Chains: Combined Syntax
  • Shorthand Syntax
    • Simple List → actor_ref
    • Null Value → actor_ref from label
    • String Value → actor_ref override
    • Dict without actor_ref → Infer from label
  • Cost Model & Selection
    • Offer Cost Components
    • Example
    • Deterministic Tie-Breaking
  • World Creation Modes
    • Axis 1: Concept Materialization
    • Axis 2: Dependency Linking
    • Preset Modes
    • FULL Mode Is Per-Story, Not Global Precomputation
  • Dependency Retargeting Policy
  • Provisioner Behavior
    • GraphProvisioner
    • TemplateProvisioner
    • Provisioner Ordering
  • Lifecycle and Persistence
    • Named Individuals (Affordances)
    • Generic Template Instances
    • Templates (Registry Records)
  • Common Patterns
    • Pattern 1: Global Characters with Fallback
    • Pattern 2: Scoped Templates for Variety
    • Pattern 3: Dynamic Casting with State
    • Pattern 4: Aliasing for Perspective
    • Pattern 5: Block-Local Specialists
  • Anti-Patterns
    • ❌ Named Individual in Templates
    • ❌ Generic Template as Affordance
    • ❌ Implicit Inference Collision
    • ❌ Expecting Template Reuse Without policy=ANY
    • ❌ Template Without Scope Override
  • Implementation Checklist
    • Phase 1: Template Registry ✓
    • Phase 2: TemplateProvisioner Registry Integration
    • Phase 3: World Creation Modes
    • Phase 4: Cost Model & Selection
    • Phase 5: Shorthand Expansion ✓ (Mostly exists)
    • Phase 6: Documentation & Polish
  • Future Enhancements
    • Template Overrides
    • Garbage Collection
    • Template Inheritance
    • Multi-Criteria Scope Selectors
  • Implementation Status
    • All Core Features: ✅ COMPLETE
• Hub Fanout and Sandbox Assembly
  • Problem Statement
  • Core Idea
  • Definitions
    • Hub
    • Provider
    • Fanout
    • Projection
  • Relationship to Existing Vocabulary
  • Compile-Time vs Runtime Responsibilities
    • Compiler
    • Materializer / VM
    • World / Domain Schedule
  • Scope Model
  • Refresh Policies
  • Projection Rules
  • Sandbox as a Fanout Consumer
  • Re-entrant Providers and Cycle Instances
  • Minimal Data Shape
  • Non-Goals
  • Implementation Direction
  • Current Implementation Status
  • Related
• MenuBlock: Dynamic Choice Hubs
  • Use Cases
  • Patterns
  • Scope Control
  • Action Labels
  • Scene Navigation
  • Implementation Notes
• Story Compilers
• How create world should work
• Open Links: Requirement-Bearing Edges and the Planning Matrix
  • Compact doctrine
  • Thesis
  • What an edge is here (read this before “fixing” anything)
  • Direction: same object, opposite fixed endpoints
    • Mapping to the current VM linkage (do not reverse the wiring)
  • The planning matrix
    • Origin (explicit/implicit ≈ static/dynamic)
  • Provider state is the architectural hinge: existing vs latent
  • Target kind and projection: concept vs episode
  • Availability is after binding
  • The source need not be the cursor
    • Worked example — the “start over” command
  • Planning as binding open links
    • Reference algorithm (illustrative, not a build target)
  • The conceptual base object (do NOT build yet)
  • Convergence debt (legible, not yet paid)
    • Near-term direction and the audit-first guard
    • The audit table (filled)
      • Cleanup ownership is a compound key (and where it bends)
      • Lifecycle metadata vs presentation hints in ui_hints (synthesis item D)
  • Future Extensions (seams, not commitments)
  • Naming note
  • Done-state for this model
• Cost Model & Offer Selection
  • Overview
  • Base Costs
  • Proximity Modifiers
  • Selection Algorithm
  • Debugging & Auditing
  • Troubleshooting
• Planning & Provisioning System Design (v3.7)
  • Executive Summary
  • Core Concepts
    • The Frontier
    • Structural vs Concept Layers
    • Requirements & Open Edges
    • Protocol / Constraint-Satisfaction View
      • Possible Future Extensions (Not Yet Implemented)
  • Architecture Overview
    • Component Layers
    • Key Classes
  • The Planning Cycle
    • Phase 1: PLANNING (Collect and Plan)
    • Phase 2: FINALIZE (Execute and Record)
  • Provisioning Mechanics
    • Cost-Based Selection
    • Deduplication
    • Hard vs Soft Requirements
  • What’s Implemented ✅
    • Core Infrastructure
    • Planning Pipeline
    • Quality Features
    • Related Systems
  • What’s Missing ⚠️
    • P1 - High Priority (Reduces Power)
      • 1. World Creation Doesn’t Wire Requirements
      • 2. TemplateProvisioner Not Connected to ScriptManager
      • 3. Availability Metadata Not Implemented
    • P2 - Medium Priority (Polish)
      • 4. No Tiered Lookahead Validation
      • 5. Affordance Lifecycle Management
    • P3 - Low Priority (Future)
      • 6. Resource Garbage Collection
      • 7. Structural Domain Abstraction
  • Integration Points
    • How to Use in Story Code
  • Usage Examples
    • Example 1: Simple Key-Door Scenario
    • Example 2: Soft vs Hard Requirements
    • Example 3: Prefer Existing Over Create
  • Testing Strategy
    • Unit Tests
    • Integration Tests
    • Recommended New Tests
  • References
    • Implementation Files
    • Test Files
  • Revision History
• Provisioning Pipeline
  • Overview
  • Provisioner Sequence
  • TemplateProvisioner Flow
  • Scope Semantics
  • Debugging Provisioning
  • Cost Model & Auditing
• Provisioning Behavior for Authors
  • Why it Matters
  • Quick Rules
  • Author Controls
  • Debugging Example
  • Best Practices
• Template Scope
  • Overview
  • Scope Levels
    • Global (No Scope)
    • Scene-Scoped (parent_label)
    • Block-Scoped (source_label)
  • Scope Override
  • Scope Selectors
    • source_label
    • parent_label
    • ancestor_tags
    • ancestor_labels
  • Provisioning Behavior
  • Best Practices
  • Troubleshooting
• Template System
  • Overview
  • Declaration Levels
    • World Level (Global)
    • Scene Level (Parent Scope)
    • Block Level (Source Scope)
    • Explicit Scope Overrides
  • Querying Templates
  • Duplicate Labels
• Navigation vs Automatic Redirects
  • User Choices (Manual Navigation)
  • Automatic Redirects (Triggered Jumps)
    • Example: Single Choice Still Prompts
  • Navigation Assistant Pattern
• Story Entry Resolution
  • Problem Statement
  • Resolution Priority Chain
    • Stage 1 — Compile-time default (StoryCompiler)
    • Stage 2 — Init-time override (World.create_story)
  • Namespace Contract
  • World Implementation Sketch
  • Domain Registration Pattern
  • Ledger Role
  • Design Constraints
  • Current Implementation Status
  • Related
• Canonical Single-Source/Single-Sink Form
  • Why Canonical Form?
  • Implementation
  • Softlock Detection
  • Nested Domains
  • Performance
  • See Also
• Sinks, Softlocks, and Escape Hatches
  • Valid Sinks (Intentional Endpoints)
  • Softlocks (Unintentional Dead Ends)
  • Prevention Strategy
  • Escape Hatches: Reset Affordances
  • Design Philosophy
  • See Also
• Service Layer Architecture (v3.7)
  • Executive Summary
  • Core Concepts
    • Service Boundary
    • Controllers as Domain Logic
    • Orchestrator as Resource Manager
  • Architecture Overview
    • Layer Diagram
    • Key Classes
  • The Orchestration Cycle
    • Full Request Flow
    • Dependency Resolution Order
  • Dependency Injection
    • Type Hint Resolution
    • Ledger Resolution Rules
    • Frame Lifecycle
  • What’s Implemented
    • ✅ Core Infrastructure
    • ✅ Persistence Integration
    • ✅ RuntimeController Endpoints
    • ✅ Application Adapters
  • What’s Missing
    • ⚠️ Access Control Enforcement
    • ⚠️ Comprehensive Error Handling
    • ⚠️ Response Standardization
    • ⚠️ Endpoint Introspection
    • ⚠️ Preprocessor/Postprocessor Usage
    • ⚠️ Multi-Tenancy
    • ⚠️ Session Management
  • Integration Points
    • How Applications Use the Service Layer
    • Custom Controllers
    • REST API Integration
    • CLI Integration
  • Usage Examples
    • Example 1: Complete Story Playthrough
    • Example 2: Save/Load Session
    • Example 3: Multi-User Server
  • Testing Strategy
    • Unit Tests
    • Integration Tests
    • Application Tests
    • Recommended New Tests
  • References
    • Implementation Files
    • Test Files
    • Related Design Documents
  • Revision History
• Backend Fragment Contract Reconciliation
  • Target Shape
  • Responsibility Split
  • Current Status
  • Diagnostic Fixtures And Transcripts
• Response Type Decision Matrix
  • ResponseType.CONTENT
  • ResponseType.RUNTIME_ENVELOPE
  • ResponseType.INFO
  • ResponseType.RUNTIME
  • ResponseType.MEDIA
  • Decision Flowchart
• Fragment Stream Contract
  • Layer Placement
  • RuntimeEnvelope
  • Fragment Registry Model
  • Current Fragment Vocabulary
  • Choice Fragments
  • Media Fragments
  • Groups And Scene Shells
  • Command Resolution
  • UX Events
  • Decision Legibility
  • Compatibility Policy
  • Test Contract
• Media Subsystem Design
  • See also
  • Executive Summary
  • Core Concepts
    • MediaResourceInventoryTag (MediaRIT)
    • Media Layers
    • Media Roles
  • Architecture Overview
    • Component Diagram
  • The Media Lifecycle
    • 1. Script Declaration
    • 2. Provisioning (PLANNING Phase)
    • 3. Fragment Emission (JOURNAL Phase)
    • 4. Service Layer Dereferencing
  • Provisioning Integration
    • MediaRequirement Specification
    • MediaDependency Edge
    • Provisioning Priority
  • Fragment Rendering & Dereferencing
    • Fragment Emission Pattern
    • Service Layer Resolution
  • Creator Pipeline
    • MediaSpec Abstraction
    • Example Spec: Stable Diffusion
    • Forge Extensibility
  • Integration Points
    • With VM Provisioning
    • With Block Rendering
    • With Service Layer
  • Usage Examples
    • Example 1: Simple Image Attachment
    • Example 2: Generated Character Portrait
    • Example 3: SVG Paperdoll
    • Example 4: Multi-Media Scene
  • Testing Strategy
    • Unit Tests
    • Integration Tests
  • Glossary
  • References
    • Implementation Files
    • Test Files
    • Design Documents
  • Implementation Status (March 2026)
    • Landed
    • Active Next Steps
    • Residual Gaps
• Generative Media Design
  • Implementation Status
  • Context and Motivation
  • Design Summary
  • Part 1: Pending-RIT Lifecycle
    • 1.1 RIT Identity Is Simpler Than It Looks
    • 1.2 RIT Lifecycle State
    • 1.3 Persistence Policy
    • 1.4 Three-Phase RIT Identity
    • 1.5 Provenance Fields on MediaRIT
    • 1.6 Seed Assignment During Adaptation — Determinism Contract
    • 1.7 Spec Hash as EXISTING Search Key
    • 1.8 render_ready Property on MediaDep
  • Part 2: Media Authority Chain — Dispatch, Not Hierarchy
    • 2.1 The Authoritative Question
    • 2.2 Story Scope: Graph Is the Registry
    • 2.3 World/Sys Scope: ResourceManager Registries
    • 2.4 Style Registries and Swappable Sets
    • 2.5 Typed Result Objects and Resolve Media Data
  • Part 3: Media Registries and Spec Templates
    • 3.1 Summary
    • 3.2 Static Catalog = MediaResourceRegistry (Already Exists)
    • 3.3 Spec Templates = MediaSpecRegistry (New)
    • 3.4 Per-Story Generated RITs
    • 3.5 materialize_rit_from_spec
    • 3.6 MediaSpecProvisioner
  • Part 4: Phase-Bus Reconciliation Hooks
    • 4.1 Pre-PLANNING: Reconcile Completed Jobs
    • 4.2 Post-PLANNING: Dispatch Accepted Async Offers
    • 4.3 No New Phases Required
  • Part 5: Anticipatory Media Affordances
  • Part 6: Service Layer — MediaRenderProfile
    • 6.1 Pending Policy
    • 6.2 Content Profile
    • 6.3 Combined Profile Object
    • 6.4 Updated media_fragment_to_payload
  • Part 7: WorkerDispatcher Interface
  • Part 8: Scope of Changes (Implementation Checklist)
    • tangl/media/media_resource/media_resource_inv_tag.py
    • tangl/media/media_creators/media_spec.py
    • tangl/media/media_resource/media_dependency.py
    • tangl/media/media_resource/media_provisioning.py
    • tangl/media/media_resource/media_spec_registry.py (future)
    • tangl/media/worker_dispatcher.py (new)
    • tangl/media/phase_hooks.py (new)
    • tangl/service/media.py
    • tangl/service/ (REST adapter / runtime controller)
    • Deferred
  • Invariants
  • Open Questions (Deferred)
  • Future: Generative Prose as a Sibling System
  • Relationship to Existing Design Documents