00-review.perplexity.md#

@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:

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.

01-verified-against-0.25.0.md#

The Perplexity review checked against coaia-narrative 0.25.0#

Checked 2026-10-22 by the T8 seat (tmux iq-miadi-review-2610221150-coaia-narrative-followup-2610221322). The version read is the one npm publishes, 0.25.0 (2026-10-20), whose source is commit b6c8e76 on branch feat/delayed-resolution-261019 of avadisabelle/coaia-narrative (worktree /a/src/coaia-narrative--delayed-resolution-261019). Line numbers are in src/types.ts at that commit. The published dist/src/types.d.ts carries the same declarations without the // comments.

main of the checkout /a/src/coaia-narrative is at 0.23.0 (6d0ed15) and has none of the delayed-resolution types; its src/types.ts is 299 lines against 364.

Claims in 00-review.perplexity.md#

What the review leaves out#

• No version. Its statements are true of 0.25.0 and of 0.24.1; items 8 and 17 are false of main.
• relationalAlignment?: { assessed, score, principles[] } on every entity (L302 to 306).
• The 0.25.0 types that Episode 297 added: AgentSessionRef (L211 to 239, with trace and rehydrateWith at L229 and L234), DelayedResolutionOutcome (L241: rehydrated, released, resolved) and DelayedResolution (L250 to 265). The review names delayedResolution only as time-bound support.
• Direction (L19) and the deprecated sync_target (L329) and github_ref (L331), kept for old records.
• The JSON schema under schema/, which is where item 16's recommendation already has a home.

For T8#

The explanation to keep is: a beat is Entity with entityType: 'narrative_beat', its narrative payload under metadata from L281 on, joined to charts and other beats by Relation rows keyed on name, all of it one JSONL line per record. Any document T8 writes from this cites src/types.ts@b6c8e76 and says 0.25.0.

---

Inquiry artefact: /a/src/IAIP/prototypes/artefacts/miadi-review-2610221150-coaia-narrative-and-explain-its-schema-for-advanced-developper-team-T8-perplexityID-a73d7b8d-4dc0-4e97-a404-f8ced6cd40d9
Chronicle episode: 2026-07-24-episode-297-mino-bimaadizi-daa-stc-bot-ceremony
Woven into miadi-chronicle://297 (2026-07-24-episode-297-mino-bimaadizi-daa-stc-bot-ceremony)
Actions that follow from this inquiry: miadisabelle/Etuaptmumk-RSM#280