Minimalist, modular narrative structure language for authors.

MuseFlows is a structured narrative data language aimed at supporting authors in designing, organizing, and managing narrative structures (StoryUnits) while remaining compatible with MuseTag annotations in text. MuseFlows focuses on composition through mixins, extensibility, and clear separation between author-visible fields and implementation mechanics.

The language defines StoryUnits and Entities as the core building blocks of a narrative, enriched with workflow guidance and meta-data to help authors plan and document their stories.

A StoryUnit is a narrative unit representing a change of state in one or more entities. It has multiple stages of maturation:

• new: only title filled
• juvenile: some fields partially filled
• ready: at least entity changes defined
• mature: all minimal relations and states defined

An Entity represents a character, place, event, or other narrative component. Entities can be extended via mixins to add attributes or constraints.

• Unit: id, title, description
• Maturation: lifecycle state and constraints on readiness
• WithContent: text or meta-text content
• EntityChange: list of entity state changes
• WithEntities: entities involved in this StoryUnit
• standard_writing_flow: previous/next StoryUnit in writing workflow
• standard_narrative_flow: previous/next StoryUnit in narrative sequence
• standard_hierarchy_flow: parent/child StoryUnit relationship
• StoryUnitMixin: central extension point, aggregates all core mixins and allows custom fields

• StoryUnit is composed entirely from mixins. No inheritance or derivation is used.
• StoryUnitMixin allows authors or designers to extend StoryUnit with custom fields or constraints.
• Mixins can themselves be composed, allowing modularity and reuse.

• All references to StoryUnit or Entity instances are typed as the class itself (e.g., StoryUnit, Entity).
• Each instance has a hidden UUID v7, used internally to maintain stable references.
• Authors only interact with human-readable ids and titles/names.

• Constraints are expressed using CEL or a simple validation language.
• Constraints can be applied at the mixin level (e.g., Maturation) or via StoryUnitMixin.
• Examples: a ready StoryUnit must have at least one entity change with actual state modification.

Three standard flows are defined:

1. Writing workflow: suggested sequence for the author
2. Narrative flow: chronological or narrative order
3. Hierarchy flow: structural nesting (e.g., parent/child StoryUnits)

Custom flows can be defined via additional mixins.

• Fields can be populated with text content visible in the narrative, or meta-text used for author guidance.
• MuseTag annotations can be used inside text content to describe entities or events inline.

Mixin Unit:
  fields:
    id: string
    title: string
    description: string

Mixin Maturation:
  fields:
    state: string
      allowed_values: ["new", "juvenile", "ready", "mature"]
      default: "new"
  constraints:
    - name: ready_requires_state_change
      applies_when: state in ["ready", "mature"]
      expression: "entity_changes != null && entity_changes.length > 0"
      message: "A ready StoryUnit must have at least one entity change"

Mixin WithContent:
  fields:
    content: Content

Mixin EntityChange:
  fields:
    entity_changes:
      type: list
      items:
        entity: Entity
        property: string
        value_before: any
        value_after: any

Mixin WithEntities:
  fields:
    entities:
      type: list

Mixin standard_writing_flow:
  fields:
    writing_flow:
      previous: StoryUnit | null
      next: StoryUnit | null

Mixin standard_narrative_flow:
  fields:
    narrative_flow:
      previous: StoryUnit | null
      next: StoryUnit | null

Mixin standard_hierarchy_flow:
  fields:
    hierarchy_flow:
      parent: StoryUnit | null
      child: StoryUnit | null

Mixin StoryUnitMixin:
  fields:
    custom_fields: map<string, any>
  mixins:
    - Unit
    - Maturation
    - WithContent
    - EntityChange
    - WithEntities
    - standard_writing_flow
    - standard_narrative_flow
    - standard_hierarchy_flow

StoryUnit:
  mixins:
    - StoryUnitMixin

Mixin EntityMixin:
  fields:
    id: string
    type: string
    name: string
    description: string

Entity:
  mixins:
    - EntityMixin

• UUID v7 is automatically generated for each instance for stable internal referencing.
• Fields typed as instances use the class type; UUID resolves the reference internally.
• Constraints use CEL (or equivalent simple validation language) to allow safe, deterministic validation.
• Editors are responsible for managing UUIDs and ensuring reference integrity.

• Define primitive types and extendable primitive mechanisms for field contents.
• Implement validation mechanism using simple language (CEL or safe alternative).
• Build sample Flows instances for StoryUnits and Entities.
• Integrate MuseTag annotations in WithContent fields.
• Develop example flows (writing, narrative, hierarchy) and demonstrate navigation.
• Explore custom flow mixins for branching or alternate narratives.
• Prepare example IDE integration with Rust-based editor.

This project is licensed under the MIT License.