@GitHub review the data structure of a narrative beat into the npm package 'coaia-narrative' and explain its schema for advanced developper team (T8)#

In coaia-narrative, a narrative beat is not a dedicated top-level record type. It is modeled as a generic graph Entity whose beat-specific semantics live in EntityMetadata; the package’s canonical type source is src/types.ts.

Core shape#

interface Entity {
  type?: string;
  name: string;                 // stable beat identifier / title
  entityType: string;           // discriminates the node kind
  observations: string[];       // append-only factual notes
  metadata?: EntityMetadata;    // narrative-beat payload
  [key: string]: unknown;       // forward-compatible extension point
}

A beat is therefore a node in a KnowledgeGraph, alongside Relation edges and optional raw JsonlRecord entries. The graph is persisted as JSONL, which makes each entity/relation an independently addressable event-like record rather than a row in a rigid relational table.

Beat-specific metadata#

The narrative fields are under metadata:

Field	Type	Role
`act`	`number \| undefined`	Dramatic act or macro-sequence position
`type_dramatic`	`string \| undefined`	Beat classification, e.g. a dramatic-function label
`perspective_types`	`string[]`	Perspectives that read the beat: `engineer`, `ceremony`, `story_engine`
`universes`	`string[]`	Deprecated pre-0.17 predecessor of `perspective_types`; retained for old records
`timestamp`	`string \| undefined`	Beat time or occurrence marker
`narrative`	`{ description, prose, lessons[] }`	Human-readable narrative content and extracted lessons
`fourDirections`	`{ north_vision, east_intention, south_emotion, west_introspection }`	Four-direction reflection structure
`sessionContext`	`SessionContextMetadata`	Embodied/working context: voice vs terminal, land-based setting, capture quality, continuation kind, privacy
`sessionLineage`	`HermesSessionLineageMetadata`	Conversation branching, source beat, parent/branch session IDs, handoff state
`foundation`	`DeepResearchFoundationMetadata`	Research-packet provenance, expected/produced artifacts, evaluation and publication state
`wampumBelt`	`WampumBeltMetadata`	Non-linear mnemonic sequencing, bead positions/colors, ceremony links
`source`	`SourceProvenance`	Producing system, tool, session, version, creation time
`github`	`GithubBridgeMetadata`	Optional GitHub issue/project synchronization state

These fields are explicitly commented as “Narrative beat specific metadata” in EntityMetadata.

Structural-tension context#

A beat also inherits the package’s broader Structural Tension model:

metadata.phase is one of germination, assimilation, or completion.
metadata.chartId, parentChart, parentActionStep, and level place the beat within a chart/hierarchy.
metadata.dueDate, completionStatus, delayedResolution, and delayedResolutionHistory support actionable or time-bound beats.
elementsOfPerformance records DESIGN or EXECUTION performance elements.
mmotEvaluations records assessment cycles: acknowledge, analyze, update, recommit.

Relations and identity#

A beat connects to other entities through:

interface Relation {
  from: string;
  to: string;
  relationType: string;
  metadata?: {
    createdAt?: string;
    strength?: number;
    context?: string;
    description?: string;
    [key: string]: unknown;
  };
}

The from/to values are entity names, so Entity.name functions as the graph join key. Use relationType for the semantic edge—such as sequencing, causality, perspective, ceremony accountability, or chart membership—rather than embedding those relationships solely inside beat metadata.

Advanced-team implications#

Treat name as an identity key. Renaming a beat can break Relation.from/Relation.to references unless the graph layer migrates them.
Treat observations as append-oriented evidence, not a substitute for structured fields. Structured queryable state belongs in metadata; narrative prose belongs in metadata.narrative.
Use perspective_types, not universes, for new data. universes is deprecated and exists only for backward compatibility with pre-0.17 records.
Preserve unknown fields. Both Entity and EntityMetadata include index signatures, so consumers should not strip unrecognized properties during round-trips.
Keep ceremony data on the bead, not only the belt. WampumCeremonyLink can reference a chartId and beatName, while WampumBead.ceremonyLink carries the ceremony-specific accountability/witness relationship.
Validate JSONL strictly at ingestion. The open [key: string]: unknown signatures maximize compatibility but shift schema enforcement to the reader/writer boundary.

In short: beat = Entity + narrative EntityMetadata + graph Relations, with JSONL as the durable representation and optional bridges to research lineage, session context, GitHub, and Wampum sequencing.