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
  • 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
  • The Compiler Metaphor
  • Narrative Debt and Credit
  • 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
  • CalvinCards as Exemplar
  • Current Implementation Priorities
• Journal Compose Contract
  • Current Runtime Contract
  • Reference Transform
  • Allowed Transformations
  • Forbidden Transformations
  • Metadata Preservation
  • Placement Rules
  • Examples
• 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
• 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
• Response Type Decision Matrix
  • ResponseType.CONTENT
  • ResponseType.INFO
  • ResponseType.RUNTIME
  • ResponseType.MEDIA
  • Decision Flowchart
• 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