coaia-visualizer 1.6.0 → 1.6.2

package/lib/chart-editor.ts

@@ -1,6 +1,8 @@
 // lib/chart-editor.ts - Chart editing logic
 
 import type { EntityRecord, RelationRecord, ParsedData } from "./types"
+import { buildMetadataWarnings, buildRecordProjections, serializeParsedData } from "./jsonl-preservation"
+import { buildRiseSpecs } from "./jsonl-parser"
 
 export interface ChartUpdate {
   type:
@@ -20,11 +22,13 @@ export interface ChartUpdate {
 export class ChartEditor {
   private entities: Map<string, EntityRecord>
   private relations: RelationRecord[]
+  private rawRecords: NonNullable<ParsedData["rawRecords"]>
 
   constructor(parsedData: ParsedData) {
     // Clone data to avoid mutations
     this.entities = new Map(parsedData.entities)
     this.relations = [...parsedData.relations]
+    this.rawRecords = [...(parsedData.rawRecords || [])]
   }
 
   private resolveStructuralChart(chartRef: string): { entityName: string; chartId: string; entity: EntityRecord } | null {
@@ -520,19 +524,11 @@ export class ChartEditor {
   }
 
   exportToJSONL(): string {
-    const lines: string[] = []
-
-    // Export entities
-    for (const entity of this.entities.values()) {
-      lines.push(JSON.stringify(entity))
-    }
-
-    // Export relations
-    for (const relation of this.relations) {
-      lines.push(JSON.stringify(relation))
-    }
-
-    return lines.join("\n") + "\n"
+    return serializeParsedData({
+      entities: this.entities,
+      relations: this.relations,
+      rawRecords: this.rawRecords,
+    })
   }
 
   getUpdatedData(): ParsedData {
@@ -615,6 +611,10 @@ export class ChartEditor {
       relations: this.relations,
       charts: chartsArray,
       rootCharts: rootCharts,
+      rawRecords: this.rawRecords,
+      projections: buildRecordProjections(this.entities),
+      preservationWarnings: buildMetadataWarnings(this.rawRecords),
+      riseSpecs: buildRiseSpecs(chartsArray),
     }
   }
 }

package/lib/jsonl-parser.ts

@@ -1,8 +1,9 @@
-import type { EntityRecord, RelationRecord, JSONLRecord, Chart, ParsedData } from "./types"
+import type { Chart, EntityRecord, JSONLRecord, ParsedData, RawJSONLRecord, RelationRecord, RiseSpecProjection } from "./types"
+import { buildMetadataWarnings, buildRecordProjections, normalizeJsonlRecord } from "./jsonl-preservation"
 
-export function parseJSONL(content: string): JSONLRecord[] {
+export function parseJSONL(content: string): RawJSONLRecord[] {
   const lines = content.trim().split("\n")
-  const records: JSONLRecord[] = []
+  const records: RawJSONLRecord[] = []
 
   for (const line of lines) {
     if (!line.trim()) continue
@@ -17,7 +18,44 @@ export function parseJSONL(content: string): JSONLRecord[] {
   return records
 }
 
-export function organizeData(records: JSONLRecord[]): ParsedData {
+function firstObservation(entity?: EntityRecord): string {
+  return entity?.observations?.[0] || ""
+}
+
+function asStringList(value: unknown): string[] {
+  if (Array.isArray(value)) {
+    return value.map((item) => typeof item === "string" ? item : JSON.stringify(item))
+  }
+  if (typeof value === "string" && value.trim()) {
+    return [value]
+  }
+  return []
+}
+
+export function buildRiseSpecs(charts: Chart[]): RiseSpecProjection[] {
+  return charts.map((chart) => {
+    const metadata = chart.chartEntity.metadata || {}
+    const rise = metadata.rise || metadata.riseSpec || metadata.spec || {}
+    const incompleteActions = chart.actions.filter((action) => action.metadata?.completionStatus !== true)
+
+    return {
+      chartId: chart.id,
+      desiredOutcome: firstObservation(chart.desiredOutcome),
+      currentReality: chart.currentReality?.observations || [],
+      naturalProgression: [
+        ...asStringList(rise.naturalProgression || metadata.naturalProgression),
+        ...incompleteActions.slice(0, 3).map((action) => action.observations?.[0]).filter(Boolean),
+      ],
+      remainingBlockers: asStringList(rise.remainingBlockers || rise.blockers || metadata.remainingBlockers || metadata.blockers),
+      nextOperations: [
+        ...asStringList(rise.nextOperations || metadata.nextOperations),
+        ...incompleteActions.slice(0, 5).map((action) => action.observations?.[0]).filter(Boolean),
+      ],
+    }
+  })
+}
+
+export function organizeData(records: RawJSONLRecord[]): ParsedData {
   const entities = new Map<string, EntityRecord>()
   const relations: RelationRecord[] = []
   const charts = new Map<string, Chart>()
@@ -26,10 +64,15 @@ export function organizeData(records: JSONLRecord[]): ParsedData {
 
   // First pass: separate entities and relations
   for (const record of records) {
-    if (record.type === "entity") {
-      entities.set(record.name, record)
-    } else if (record.type === "relation") {
-      relations.push(record)
+    const normalized = normalizeJsonlRecord(record)
+    if (!normalized) {
+      continue
+    }
+
+    if (normalized.type === "entity") {
+      entities.set(normalized.name, normalized)
+    } else if (normalized.type === "relation") {
+      relations.push(normalized)
     }
   }
 
@@ -163,6 +206,10 @@ export function organizeData(records: JSONLRecord[]): ParsedData {
     entities,
     relations,
     rootCharts,
+    rawRecords: records,
+    projections: buildRecordProjections(entities),
+    preservationWarnings: buildMetadataWarnings(records),
+    riseSpecs: buildRiseSpecs(Array.from(charts.values())),
   }
 }
 

package/lib/jsonl-preservation.ts

@@ -0,0 +1,405 @@
+import type {
+  EntityRecord,
+  MetadataWarning,
+  ParsedData,
+  RawJSONLRecord,
+  RecordProjections,
+  RelationRecord,
+} from "./types"
+
+const UPSTREAM_ISSUE = "https://github.com/avadisabelle/coaia-narrative/issues/35"
+
+const ENTITY_TOP_LEVEL_KEYS = new Set(["type", "name", "entityType", "observations", "metadata"])
+const RELATION_TOP_LEVEL_KEYS = new Set(["type", "from", "to", "relationType", "metadata"])
+const NARRATIVE_BEAT_TOP_LEVEL_KEYS = new Set([
+  ...ENTITY_TOP_LEVEL_KEYS,
+  "narrative",
+  "relational_alignment",
+  "four_directions",
+])
+const MUTABLE_METADATA_KEYS = new Set([
+  "dueDate",
+  "chartId",
+  "phase",
+  "completionStatus",
+  "completedAt",
+  "parentChart",
+  "parentActionStep",
+  "level",
+  "createdAt",
+  "updatedAt",
+  "act",
+  "type_dramatic",
+  "universes",
+  "timestamp",
+  "elementsOfPerformance",
+  "mmotEvaluations",
+  "relationalAlignment",
+  "fourDirections",
+  "narrative",
+  "isTelescopedChart",
+  "telescopedChartId",
+])
+
+function isObject(value: unknown): value is Record<string, any> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+function cloneJson<T>(value: T): T {
+  return value === undefined ? value : JSON.parse(JSON.stringify(value))
+}
+
+function deepEqual(left: unknown, right: unknown): boolean {
+  return JSON.stringify(left) === JSON.stringify(right)
+}
+
+function removeUndefined<T extends Record<string, any>>(record: T): T {
+  for (const key of Object.keys(record)) {
+    if (record[key] === undefined) {
+      delete record[key]
+    }
+  }
+  return record
+}
+
+function relationKey(relation: Pick<RelationRecord, "from" | "to" | "relationType">): string {
+  return `${relation.from}\u0000${relation.to}\u0000${relation.relationType}`
+}
+
+export function isEntityLikeRecord(record: RawJSONLRecord): boolean {
+  return (record.type === "entity" || record.type === "narrative_beat") && typeof record.name === "string"
+}
+
+export function isRelationLikeRecord(record: RawJSONLRecord): boolean {
+  return (
+    record.type === "relation" &&
+    typeof record.from === "string" &&
+    typeof record.to === "string" &&
+    typeof record.relationType === "string"
+  )
+}
+
+export function normalizeJsonlRecord(record: RawJSONLRecord): EntityRecord | RelationRecord | null {
+  if (record.type === "entity" && typeof record.name === "string") {
+    return {
+      ...record,
+      type: "entity",
+      observations: Array.isArray(record.observations) ? record.observations : [],
+      metadata: isObject(record.metadata) ? record.metadata : {},
+    } as EntityRecord
+  }
+
+  if (record.type === "narrative_beat" && typeof record.name === "string") {
+    const metadata = {
+      ...(isObject(record.metadata) ? record.metadata : {}),
+      narrative: isObject(record.metadata) && record.metadata.narrative !== undefined
+        ? record.metadata.narrative
+        : record.narrative,
+      relationalAlignment: isObject(record.metadata) && record.metadata.relationalAlignment !== undefined
+        ? record.metadata.relationalAlignment
+        : record.relational_alignment,
+      fourDirections: isObject(record.metadata) && record.metadata.fourDirections !== undefined
+        ? record.metadata.fourDirections
+        : record.four_directions,
+    }
+
+    return removeUndefined({
+      ...record,
+      type: "entity",
+      name: record.name as string,
+      entityType: "narrative_beat",
+      observations: Array.isArray(record.observations) ? record.observations : [],
+      metadata: removeUndefined(metadata),
+    }) as EntityRecord
+  }
+
+  if (isRelationLikeRecord(record)) {
+    return {
+      ...record,
+      type: "relation",
+      metadata: isObject(record.metadata) ? record.metadata : {},
+    } as RelationRecord
+  }
+
+  return null
+}
+
+function mergePreservedMetadata(originalMetadata: unknown, currentMetadata: unknown): Record<string, any> {
+  const merged = {
+    ...(isObject(currentMetadata) ? currentMetadata : {}),
+  }
+
+  if (isObject(originalMetadata)) {
+    for (const [key, value] of Object.entries(originalMetadata)) {
+      if (!(key in merged) && (!MUTABLE_METADATA_KEYS.has(key) || key === "github")) {
+        merged[key] = cloneJson(value)
+      }
+    }
+  }
+
+  return merged
+}
+
+function serializeEntity(entity: EntityRecord, original?: RawJSONLRecord): RawJSONLRecord {
+  const metadata = mergePreservedMetadata(original?.metadata, entity.metadata)
+
+  if (original?.type === "narrative_beat") {
+    const record: RawJSONLRecord = {
+      ...original,
+      type: "narrative_beat",
+      name: entity.name,
+      observations: entity.observations,
+      metadata,
+    }
+
+    if ("entityType" in original) {
+      record.entityType = entity.entityType
+    }
+    if ("narrative" in original && entity.metadata?.narrative !== undefined) {
+      record.narrative = cloneJson(entity.metadata.narrative)
+    }
+    if ("relational_alignment" in original && entity.metadata?.relationalAlignment !== undefined) {
+      record.relational_alignment = cloneJson(entity.metadata.relationalAlignment)
+    }
+    if ("four_directions" in original && entity.metadata?.fourDirections !== undefined) {
+      record.four_directions = cloneJson(entity.metadata.fourDirections)
+    }
+
+    return removeUndefined(record)
+  }
+
+  return removeUndefined({
+    ...original,
+    ...entity,
+    type: "entity",
+    metadata,
+  })
+}
+
+function serializeRelation(relation: RelationRecord, original?: RawJSONLRecord): RawJSONLRecord {
+  return removeUndefined({
+    ...original,
+    ...relation,
+    type: "relation",
+    metadata: mergePreservedMetadata(original?.metadata, relation.metadata),
+  })
+}
+
+function findRecord(records: RawJSONLRecord[], key: string): RawJSONLRecord | undefined {
+  return records.find((record) => {
+    if (isEntityLikeRecord(record) && record.name === key) return true
+    if (isRelationLikeRecord(record)) return relationKey(record as RelationRecord) === key
+    return false
+  })
+}
+
+function validateMetadata(label: string, beforeMetadata: unknown, afterMetadata: unknown, failures: string[]): void {
+  if (!isObject(beforeMetadata)) return
+  if (!isObject(afterMetadata)) {
+    failures.push(`${label}: metadata object missing after write`)
+    return
+  }
+
+  for (const [key, value] of Object.entries(beforeMetadata)) {
+    if (!(key in afterMetadata)) {
+      failures.push(`${label}: metadata.${key} missing after write`)
+      continue
+    }
+
+    if ((key === "github" || !MUTABLE_METADATA_KEYS.has(key)) && !deepEqual(value, afterMetadata[key])) {
+      failures.push(`${label}: metadata.${key} changed unexpectedly`)
+    }
+  }
+}
+
+function validateRecordPreservation(
+  beforeRecords: RawJSONLRecord[],
+  afterRecords: RawJSONLRecord[],
+  entities: Map<string, EntityRecord>,
+  relations: RelationRecord[],
+): void {
+  const relationKeys = new Set(relations.map((relation) => relationKey(relation)))
+  const failures: string[] = []
+
+  for (const before of beforeRecords) {
+    if (isEntityLikeRecord(before)) {
+      const name = before.name as string
+      if (!entities.has(name)) continue
+
+      const after = findRecord(afterRecords, name)
+      if (!after) {
+        failures.push(`${name}: record missing after write`)
+        continue
+      }
+
+      if (before.type === "narrative_beat" && after.type !== "narrative_beat") {
+        failures.push(`${name}: legacy narrative_beat record type was flattened`)
+      }
+
+      const knownKeys = before.type === "narrative_beat" ? NARRATIVE_BEAT_TOP_LEVEL_KEYS : ENTITY_TOP_LEVEL_KEYS
+      for (const key of Object.keys(before)) {
+        if (!knownKeys.has(key) && !deepEqual(before[key], after[key])) {
+          failures.push(`${name}: top-level extension field "${key}" was not preserved`)
+        }
+      }
+      validateMetadata(name, before.metadata, after.metadata, failures)
+    }
+
+    if (isRelationLikeRecord(before)) {
+      const key = relationKey(before as RelationRecord)
+      if (!relationKeys.has(key)) continue
+
+      const after = findRecord(afterRecords, key)
+      if (!after) {
+        failures.push(`${key}: relation missing after write`)
+        continue
+      }
+
+      for (const topLevelKey of Object.keys(before)) {
+        if (!RELATION_TOP_LEVEL_KEYS.has(topLevelKey) && !deepEqual(before[topLevelKey], after[topLevelKey])) {
+          failures.push(`${key}: relation extension field "${topLevelKey}" was not preserved`)
+        }
+      }
+      validateMetadata(key, before.metadata, after.metadata, failures)
+    }
+  }
+
+  if (failures.length > 0) {
+    throw new Error(`COAIA JSONL metadata preservation failed:\n- ${failures.join("\n- ")}`)
+  }
+}
+
+export function buildRecordProjections(entities: Map<string, EntityRecord>): RecordProjections {
+  const allEntities = Array.from(entities.values())
+  return {
+    chartRecords: allEntities.filter((entity) => entity.entityType === "structural_tension_chart"),
+    actionStepRecords: allEntities.filter((entity) => entity.entityType === "action_step" || entity.metadata?.isTelescopedChart),
+    narrativeBeatRecords: allEntities.filter((entity) => entity.entityType === "narrative_beat"),
+  }
+}
+
+export function buildMetadataWarnings(records: RawJSONLRecord[]): MetadataWarning[] {
+  const warnings: MetadataWarning[] = []
+
+  for (const record of records) {
+    if (!isEntityLikeRecord(record) && !isRelationLikeRecord(record)) continue
+
+    const recordName = record.name || [record.from, record.to, record.relationType].filter(Boolean).join(" -> ")
+    const metadata = record.metadata
+
+    if (!isObject(metadata)) {
+      warnings.push({
+        severity: "warning",
+        recordName,
+        recordType: record.type,
+        message: "Record has no metadata object; provenance and extension fields may already be flattened.",
+        upstreamIssue: UPSTREAM_ISSUE,
+      })
+      continue
+    }
+
+    if (record.github && !metadata.github) {
+      warnings.push({
+        severity: "warning",
+        recordName,
+        recordType: record.type,
+        message: "GitHub provenance exists outside metadata.github; this shape is suspicious for preservation-aware tools.",
+        upstreamIssue: UPSTREAM_ISSUE,
+      })
+    }
+
+    const normalized = normalizeJsonlRecord(record)
+    if (normalized && "entityType" in normalized) {
+      if (
+        ["structural_tension_chart", "action_step", "desired_outcome", "current_reality", "narrative_beat"].includes(
+          normalized.entityType,
+        ) &&
+        !normalized.metadata?.chartId
+      ) {
+        warnings.push({
+          severity: "warning",
+          recordName: normalized.name,
+          recordType: normalized.entityType,
+          message: "COAIA entity is missing metadata.chartId, so chart/action projection may be incomplete.",
+          upstreamIssue: UPSTREAM_ISSUE,
+        })
+      }
+
+      if (
+        normalized.entityType === "narrative_beat" &&
+        !normalized.metadata?.narrative &&
+        !record.narrative &&
+        normalized.observations.length <= 1
+      ) {
+        warnings.push({
+          severity: "warning",
+          recordName: normalized.name,
+          recordType: normalized.entityType,
+          message: "Narrative beat appears flattened: no narrative metadata or rich beat payload is visible.",
+          upstreamIssue: UPSTREAM_ISSUE,
+        })
+      }
+    }
+
+    if (record.type === "narrative_beat") {
+      warnings.push({
+        severity: "warning",
+        recordName,
+        recordType: "narrative_beat",
+        message: "Legacy narrative_beat shape detected. It is rendered separately and preserved on save.",
+        upstreamIssue: UPSTREAM_ISSUE,
+      })
+    }
+  }
+
+  return warnings
+}
+
+export function serializeParsedData(data: Pick<ParsedData, "entities" | "relations" | "rawRecords">): string {
+  const rawRecords = data.rawRecords || []
+  const emittedEntities = new Set<string>()
+  const emittedRelations = new Set<string>()
+  const records: RawJSONLRecord[] = []
+
+  for (const original of rawRecords) {
+    if (isEntityLikeRecord(original)) {
+      const entity = data.entities.get(original.name)
+      if (entity) {
+        records.push(serializeEntity(entity, original))
+        emittedEntities.add(entity.name)
+      }
+      continue
+    }
+
+    if (isRelationLikeRecord(original)) {
+      const key = relationKey(original as RelationRecord)
+      const relation = data.relations.find((candidate) => relationKey(candidate) === key)
+      if (relation) {
+        records.push(serializeRelation(relation, original))
+        emittedRelations.add(key)
+      }
+      continue
+    }
+
+    records.push(original)
+  }
+
+  for (const entity of data.entities.values()) {
+    if (!emittedEntities.has(entity.name)) {
+      records.push(serializeEntity(entity))
+    }
+  }
+
+  for (const relation of data.relations) {
+    const key = relationKey(relation)
+    if (!emittedRelations.has(key)) {
+      records.push(serializeRelation(relation))
+    }
+  }
+
+  validateRecordPreservation(rawRecords, records, data.entities, data.relations)
+
+  return `${records.map((record) => JSON.stringify(record)).join("\n")}\n`
+}
+
+export { UPSTREAM_ISSUE }

package/lib/types.ts

@@ -3,33 +3,46 @@
 export interface EntityRecord {
   type: "entity"
   name: string
-  entityType:
-    | "structural_tension_chart"
-    | "desired_outcome"
-    | "current_reality"
-    | "action_step"
-    | "narrative_beat"
-    | "custom"
-    | (string & {})
+  entityType: "structural_tension_chart" | "desired_outcome" | "current_reality" | "action_step" | "narrative_beat"
   observations: string[]
   metadata: Record<string, any>
+  [key: string]: any
 }
 
 export interface RelationRecord {
   type: "relation"
   from: string
   to: string
-  relationType:
-    | "contains"
-    | "creates_tension_with"
-    | "advances_toward"
-    | "documents"
-    | "custom"
-    | (string & {})
+  relationType: "contains" | "creates_tension_with" | "advances_toward" | "documents"
   metadata: Record<string, any>
+  [key: string]: any
 }
 
 export type JSONLRecord = EntityRecord | RelationRecord
+export type RawJSONLRecord = Record<string, any>
+
+export interface MetadataWarning {
+  severity: "warning" | "error"
+  recordName?: string
+  recordType?: string
+  message: string
+  upstreamIssue?: string
+}
+
+export interface RecordProjections {
+  chartRecords: EntityRecord[]
+  actionStepRecords: EntityRecord[]
+  narrativeBeatRecords: EntityRecord[]
+}
+
+export interface RiseSpecProjection {
+  chartId: string
+  desiredOutcome: string
+  currentReality: string[]
+  naturalProgression: string[]
+  remainingBlockers: string[]
+  nextOperations: string[]
+}
 
 export interface Chart {
   id: string
@@ -49,4 +62,8 @@ export interface ParsedData {
   entities: Map<string, EntityRecord>
   relations: RelationRecord[]
   rootCharts: Chart[]
+  rawRecords?: RawJSONLRecord[]
+  projections?: RecordProjections
+  preservationWarnings?: MetadataWarning[]
+  riseSpecs?: RiseSpecProjection[]
 }