coaiajs 0.4.2 → 0.5.0

package/dist/src/narrative/graph-manager.js

@@ -5,57 +5,82 @@
  * Implements structural tension charts, narrative beats, MMOT evaluation,
  * and general-purpose entity/relation CRUD over a JSONL file.
  */
-import { promises as fs } from 'fs';
+import { readJsonlMemoryFile, writeJsonlMemoryFile } from './jsonl-preservation.js';
+import { assertNoUnparsedCallSyntax } from './argument-hygiene.js';
+import { createGithubProjectFieldProjection, } from './github-bridge.js';
+/**
+ * Parse a GitHub issue reference written as `owner/repo#number`.
+ *
+ * The full path is required. A bare `#42` is rejected: charts travel between
+ * repositories, and a bare number silently resolves against whichever repo the
+ * reader happens to be in — which is how an issue from one project ends up
+ * cited as another project's.
+ */
+export function parseGithubIssueSpec(spec) {
+    const match = /^([A-Za-z0-9._-]+)\/([A-Za-z0-9._-]+)#(\d+)$/.exec(spec.trim());
+    if (!match) {
+        throw new Error(`Invalid GitHub issue reference: "${spec}". Use the full path 'owner/repo#number' (e.g. jgwill/coaiajs#1). A bare '#number' is not accepted — it resolves against the wrong repository as soon as the chart is read somewhere else.`);
+    }
+    const [, owner, repo, number] = match;
+    return {
+        owner: owner,
+        repo: repo,
+        number: Number(number),
+        url: `https://github.com/${owner}/${repo}/issues/${number}`,
+    };
+}
 export class KnowledgeGraphManager {
     memoryFilePath;
     constructor(memoryFilePath) {
+        /**
+         * Refuse a path that still carries an unexpanded shell variable.
+         *
+         * Paid for 2026-08-11 in the coaia-narrative lineage. A seat booted with its
+         * memory-path variable unset, so its `.mcp.json` handed the process the
+         * placeholder verbatim. The server started happily and wrote a live chart into
+         * a file literally NAMED `${VAR}` in whatever directory it was launched from.
+         * Nothing failed. The charts were simply somewhere nobody would look.
+         *
+         * The sibling failure is worse and is why this is fatal rather than a warning:
+         * had the variable been set to a path that does not exist, this would have
+         * started CLEAN and EMPTY, and the caller would have reported its whole store
+         * lost. A store is the one input where "start anyway" is never the kind answer.
+         *
+         * `${` cannot appear in a legitimate path here: `$` is legal in a filename, but
+         * a caller writing `${...}` is quoting a shell it expected to have run.
+         */
+        if (memoryFilePath.includes('${')) {
+            throw new Error(`Refusing to open memory store: the path contains an unexpanded shell variable.\n` +
+                `  got: ${memoryFilePath}\n` +
+                `  The variable was not set in the environment that launched this process, so this ` +
+                `would create a file with that literal name and write your charts into it where ` +
+                `nothing will find them.\n` +
+                `  Fix the environment (or pass a real path) and start again — no store was touched.`);
+        }
         this.memoryFilePath = memoryFilePath;
     }
     // ─── JSONL Storage ──────────────────────────────────────────────────
+    /**
+     * Read the store through the preserving parser, which keeps every line's raw
+     * record on the graph so a later write can round-trip fields this package does
+     * not model. See jsonl-preservation.ts.
+     */
     async loadGraph() {
-        try {
-            const data = await fs.readFile(this.memoryFilePath, 'utf-8');
-            const lines = data.split('\n').filter(line => line.trim() !== '');
-            return lines.reduce((graph, line) => {
-                const item = JSON.parse(line);
-                if (item.type === 'entity')
-                    graph.entities.push(item);
-                if (item.type === 'relation')
-                    graph.relations.push(item);
-                // Support narrative_beat entities stored in legacy format
-                if (item.type === 'narrative_beat') {
-                    const narrativeBeat = {
-                        name: item.name,
-                        entityType: 'narrative_beat',
-                        observations: item.observations || [],
-                        metadata: {
-                            ...item.metadata,
-                            narrative: item.narrative,
-                            relationalAlignment: item.relational_alignment,
-                            fourDirections: item.four_directions,
-                        },
-                    };
-                    graph.entities.push(narrativeBeat);
-                }
-                return graph;
-            }, { entities: [], relations: [] });
-        }
-        catch (error) {
-            if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
-                return { entities: [], relations: [] };
-            }
-            throw error;
-        }
+        return readJsonlMemoryFile(this.memoryFilePath);
     }
+    /**
+     * Write the store atomically and without loss. The previous implementation
+     * re-serialised only the fields this package knows, so any consumer's metadata
+     * on a record was dropped the first time coaiajs touched it.
+     */
     async saveGraph(graph) {
-        const lines = [
-            ...graph.entities.map(e => JSON.stringify({ type: 'entity', ...e })),
-            ...graph.relations.map(r => JSON.stringify({ type: 'relation', ...r })),
-        ];
-        await fs.writeFile(this.memoryFilePath, lines.join('\n'));
+        await writeJsonlMemoryFile(this.memoryFilePath, graph);
     }
     // ─── Knowledge Graph CRUD ───────────────────────────────────────────
     async createEntities(entities) {
+        // Every chart body eventually lands here. Check before loading the graph, so a
+        // refusal leaves the store exactly as it was.
+        entities.forEach((entity, index) => assertNoUnparsedCallSyntax(entity.observations, `entities[${index}].observations`));
         const graph = await this.loadGraph();
         const newEntities = entities.filter(e => !graph.entities.some(existing => existing.name === e.name));
         graph.entities.push(...newEntities);
@@ -72,6 +97,9 @@ export class KnowledgeGraphManager {
         return newRelations;
     }
     async addObservations(observations) {
+        // All of them, before any of them — a batch where one body is malformed is a
+        // malformed call, and half of it must not land.
+        observations.forEach((o, index) => assertNoUnparsedCallSyntax(o.contents, `observations[${index}].contents`));
         const graph = await this.loadGraph();
         const results = observations.map(o => {
             const entity = graph.entities.find(e => e.name === o.entityName);
@@ -111,6 +139,20 @@ export class KnowledgeGraphManager {
     async readGraph() {
         return this.loadGraph();
     }
+    /**
+     * Project a chart (or any entity) into the GitHub Project field shape the
+     * coaia-github bridge writes. Returns null when nothing by that name or chartId
+     * is in the store.
+     */
+    async getGithubProjectFieldProjection(entityNameOrChartId) {
+        const graph = await this.loadGraph();
+        const entity = graph.entities.find(e => e.name === entityNameOrChartId) ??
+            graph.entities.find(e => e.entityType === 'structural_tension_chart' &&
+                e.metadata?.chartId === entityNameOrChartId);
+        if (!entity)
+            return null;
+        return createGithubProjectFieldProjection(entity, graph);
+    }
     async searchNodes(query) {
         const graph = await this.loadGraph();
         const q = query.toLowerCase();
@@ -155,10 +197,39 @@ export class KnowledgeGraphManager {
         return this.getChartDetails(telescopedOutcomeEntity.metadata.chartId);
     }
     // ─── Structural Tension Charts ──────────────────────────────────────
-    async createStructuralTensionChart(desiredOutcome, currentReality, dueDate, actionSteps, elementsOfPerformance) {
-        // Creative orientation validation
+    async createStructuralTensionChart(desiredOutcome, currentReality, dueDate, actionSteps, elementsOfPerformance, githubIssue) {
+        // A malformed call is diagnosed before its content is judged — there is no
+        // point coaching the creative orientation of a fragment of XML.
+        assertNoUnparsedCallSyntax(desiredOutcome, 'desiredOutcome');
+        assertNoUnparsedCallSyntax(currentReality, 'currentReality');
+        assertNoUnparsedCallSyntax(actionSteps, 'actionSteps');
+        // Creative orientation validation.
+        //
+        // MATCHED ON WORD BOUNDARIES, NOT SUBSTRINGS, and the difference is not
+        // cosmetic. This filter used `.includes()`, so it read the letters of these
+        // words wherever they fell inside a longer one:
+        //
+        //   "a fixed ladder of named rungs"          -> "fix"    -> refused
+        //   "carry one to completion or resolve it"  -> "solve"  -> refused
+        //   "unstoppable", "prevention", "removal", "avoidance", "dissolve",
+        //   "stopgap", "reducer", "solvent", "prefix", "suffix", "affix"…
+        //
+        // Both examples above are real refusals measured in the coaia-narrative
+        // lineage (2026-07-31 and 2026-08-01) on action steps already written in
+        // creative orientation. The author rephrased around the error both times
+        // without asking why, which is the quiet cost: a guard that fires on innocent
+        // text teaches the caller to edit for the checker rather than for the reader.
+        //
+        // Sharper still, the organisation's own guidance prescribes the very word this
+        // filter rejected: "GOOD EXAMPLE: Each action step resolve tension between
+        // current and desired states." So the check refused the phrasing its own
+        // doctrine recommends.
+        //
+        // The word list is unchanged — a chart whose desired outcome genuinely says
+        // "eliminate" or "reduce" should still be met with the teaching below. Only
+        // the matching is corrected.
         const problemSolvingWords = ['fix', 'solve', 'eliminate', 'prevent', 'stop', 'avoid', 'reduce', 'remove'];
-        const detectedProblemWords = problemSolvingWords.filter(word => desiredOutcome.toLowerCase().includes(word));
+        const detectedProblemWords = problemSolvingWords.filter(word => new RegExp(`\\b${word}\\b`, 'i').test(desiredOutcome));
         if (detectedProblemWords.length > 0) {
             throw new Error(`🌊 CREATIVE ORIENTATION REQUIRED\n\n` +
                 `Desired Outcome: "${desiredOutcome}"\n\n` +
@@ -193,6 +264,7 @@ export class KnowledgeGraphManager {
         }
         const chartId = `chart_${Date.now()}`;
         const timestamp = new Date().toISOString();
+        const issueRef = githubIssue ? parseGithubIssueSpec(githubIssue) : undefined;
         const entities = [
             {
                 name: `${chartId}_chart`,
@@ -207,6 +279,7 @@ export class KnowledgeGraphManager {
                     ...(elementsOfPerformance && elementsOfPerformance.length > 0
                         ? { elementsOfPerformance }
                         : {}),
+                    ...(issueRef ? { github: { issue: issueRef } } : {}),
                 },
             },
             {
@@ -358,15 +431,42 @@ export class KnowledgeGraphManager {
     async getChartProgress(chartId, preloadedGraph) {
         const graph = preloadedGraph ?? (await this.loadGraph());
         const actionSteps = graph.entities.filter(e => e.entityType === 'action_step' && e.metadata?.chartId === chartId);
-        const completedActions = actionSteps.filter(e => e.metadata?.completionStatus === true).length;
-        const totalActions = actionSteps.length;
+        // A chart holds its work in two shapes: action_step entities on the chart
+        // itself, and telescoped child charts. Counting only the first makes a chart
+        // whose steps were telescoped report 0/0 while holding real work.
+        const childCharts = graph.entities.filter(e => e.entityType === 'structural_tension_chart' &&
+            e.metadata?.parentChart === chartId);
+        // A child chart telescoped out of one of this chart's own steps is that same
+        // result seen closer up — it is counted through the step, not a second time.
+        const stepNames = new Set(actionSteps.map(e => e.name));
+        const telescopedChildren = childCharts.filter(c => !(c.metadata?.parentActionStep && stepNames.has(c.metadata.parentActionStep)));
+        const units = [
+            ...actionSteps.map(e => ({
+                name: e.name,
+                complete: e.metadata?.completionStatus === true,
+                dueDate: e.metadata?.dueDate,
+            })),
+            ...telescopedChildren.map(c => {
+                const childId = c.metadata?.chartId || c.name.replace('_chart', '');
+                // a child chart is completed through its desired outcome — that is the
+                // entity mark_action_complete writes to when a telescoped result is achieved
+                const outcome = graph.entities.find(e => e.name === `${childId}_desired_outcome` && e.entityType === 'desired_outcome');
+                return {
+                    name: `${childId}_desired_outcome`,
+                    complete: outcome?.metadata?.completionStatus === true,
+                    dueDate: c.metadata?.dueDate,
+                };
+            }),
+        ];
+        const completedActions = units.filter(u => u.complete).length;
+        const totalActions = units.length;
         const progress = totalActions > 0 ? completedActions / totalActions : 0;
-        // Next incomplete action step by earliest due date
-        const incompleteActions = actionSteps
-            .filter(e => e.metadata?.completionStatus !== true)
+        // Next incomplete unit by earliest due date
+        const incompleteActions = units
+            .filter(u => !u.complete)
             .sort((a, b) => {
-            const dateA = new Date(a.metadata?.dueDate || '').getTime();
-            const dateB = new Date(b.metadata?.dueDate || '').getTime();
+            const dateA = new Date(a.dueDate || '').getTime();
+            const dateB = new Date(b.dueDate || '').getTime();
             return dateA - dateB;
         });
         const chart = graph.entities.find(e => e.name === `${chartId}_chart`);
@@ -388,6 +488,18 @@ export class KnowledgeGraphManager {
             const progress = await this.getChartProgress(chartId, graph);
             const desiredOutcome = graph.entities.find(e => e.name === `${chartId}_desired_outcome` &&
                 e.entityType === 'desired_outcome');
+            // A chart holds its work in two shapes: action_step entities that live on
+            // the chart itself, and telescoped child charts. Callers rendering a
+            // hierarchy from parentChart alone see only the second and report the
+            // first as absent.
+            const actionSteps = graph.entities
+                .filter(e => e.entityType === 'action_step' && e.metadata?.chartId === chartId)
+                .map(e => ({
+                name: e.name,
+                title: e.observations[0] || 'Untitled action step',
+                complete: Boolean(e.metadata?.completionStatus),
+                dueDate: e.metadata?.dueDate,
+            }));
             return {
                 chartId,
                 desiredOutcome: desiredOutcome?.observations[0] || 'Unknown outcome',
@@ -397,6 +509,8 @@ export class KnowledgeGraphManager {
                 totalActions: progress.totalActions,
                 level: chart.metadata?.level || 0,
                 parentChart: chart.metadata?.parentChart,
+                parentActionStep: chart.metadata?.parentActionStep,
+                actionSteps,
             };
         }));
         return chartSummaries.sort((a, b) => {
@@ -409,6 +523,7 @@ export class KnowledgeGraphManager {
     }
     // ─── Update Action Progress ─────────────────────────────────────────
     async updateActionProgress(actionStepName, progressObservation, updateCurrentReality) {
+        assertNoUnparsedCallSyntax(progressObservation, 'progressObservation');
         const graph = await this.loadGraph();
         const actionStep = graph.entities.find(e => e.name === actionStepName &&
             (e.entityType === 'action_step' || e.entityType === 'desired_outcome'));
@@ -439,6 +554,7 @@ export class KnowledgeGraphManager {
     }
     // ─── Update Current Reality ─────────────────────────────────────────
     async updateCurrentReality(chartId, newObservations) {
+        assertNoUnparsedCallSyntax(newObservations, 'newObservations');
         const graph = await this.loadGraph();
         const currentReality = graph.entities.find(e => e.name === `${chartId}_current_reality` &&
             e.entityType === 'current_reality');
@@ -453,7 +569,27 @@ export class KnowledgeGraphManager {
         await this.saveGraph(graph);
     }
     // ─── Update Desired Outcome ─────────────────────────────────────────
+    /**
+     * Record on an existing chart the GitHub issue it was written from.
+     * Writes metadata.github.issue, which EntityMetadata already carried and no
+     * tool could reach.
+     */
+    async linkChartToGithubIssue(chartId, githubIssue) {
+        const graph = await this.loadGraph();
+        const chartEntity = graph.entities.find(e => e.name === `${chartId}_chart` && e.entityType === 'structural_tension_chart');
+        if (!chartEntity) {
+            throw new Error(`Chart ${chartId} not found`);
+        }
+        const issue = parseGithubIssueSpec(githubIssue);
+        const timestamp = new Date().toISOString();
+        chartEntity.metadata = chartEntity.metadata || {};
+        chartEntity.metadata.github = { ...(chartEntity.metadata.github || {}), issue };
+        chartEntity.metadata.updatedAt = timestamp;
+        await this.saveGraph(graph);
+        return { chartId, issue };
+    }
     async updateDesiredOutcome(chartId, newDesiredOutcome) {
+        assertNoUnparsedCallSyntax(newDesiredOutcome, 'newDesiredOutcome');
         const graph = await this.loadGraph();
         const desiredOutcomeEntity = graph.entities.find(e => e.name === `${chartId}_desired_outcome` &&
             e.entityType === 'desired_outcome');
@@ -466,8 +602,119 @@ export class KnowledgeGraphManager {
         }
         await this.saveGraph(graph);
     }
+    // ─── Chart Due Date ─────────────────────────────────────────────────
+    /**
+     * Move the date a chart is due.
+     *
+     * `updateDesiredOutcome` and `updateCurrentReality` could already reach both
+     * halves of the tension; the date the tension resolves by could only be changed
+     * by hand-editing the JSONL — on a store several MCP instances write with no
+     * lock, which is how a hand-edit becomes a lost write.
+     *
+     * The chart and its desired outcome were created carrying the same date and are
+     * moved together. Action step dates are left alone unless `redistributeActionSteps`
+     * is asked for; the count still standing past the new date is reported either way,
+     * so the caller sees what the move left behind.
+     */
+    async updateChartDueDate(chartId, newDueDate, redistributeActionSteps = false) {
+        const parsed = Date.parse(newDueDate);
+        if (Number.isNaN(parsed)) {
+            throw new Error(`Invalid due date: "${newDueDate}". Use an ISO date string, e.g. 2026-09-30T12:00:00Z`);
+        }
+        const normalizedDueDate = new Date(parsed).toISOString();
+        const graph = await this.loadGraph();
+        const chartEntity = graph.entities.find(e => e.name === `${chartId}_chart` && e.entityType === 'structural_tension_chart');
+        if (!chartEntity) {
+            throw new Error(`Chart ${chartId} not found`);
+        }
+        const timestamp = new Date().toISOString();
+        chartEntity.metadata = chartEntity.metadata || {};
+        const previousDueDate = typeof chartEntity.metadata.dueDate === 'string' ? chartEntity.metadata.dueDate : undefined;
+        chartEntity.metadata.dueDate = normalizedDueDate;
+        chartEntity.metadata.updatedAt = timestamp;
+        const desiredOutcomeEntity = graph.entities.find(e => e.name === `${chartId}_desired_outcome` && e.entityType === 'desired_outcome');
+        if (desiredOutcomeEntity) {
+            desiredOutcomeEntity.metadata = desiredOutcomeEntity.metadata || {};
+            desiredOutcomeEntity.metadata.dueDate = normalizedDueDate;
+            desiredOutcomeEntity.metadata.updatedAt = timestamp;
+        }
+        // The date a chart carried is part of its history. Recording the move on the
+        // chart itself keeps it readable later without touching current reality, which
+        // belongs to the work rather than to the schedule.
+        chartEntity.observations.push(`Due date changed from ${previousDueDate || 'unset'} to ${normalizedDueDate} on ${timestamp}`);
+        const units = this.collectChartWorkUnits(graph, chartId);
+        const openUnits = units.filter(u => !u.complete);
+        let actionStepsRescheduled = 0;
+        if (redistributeActionSteps && openUnits.length > 0) {
+            openUnits.sort((a, b) => {
+                const dateA = new Date(a.dueDate || normalizedDueDate).getTime();
+                const dateB = new Date(b.dueDate || normalizedDueDate).getTime();
+                return dateA - dateB;
+            });
+            const dates = this.distributeActionStepDates(new Date(timestamp), new Date(normalizedDueDate), openUnits.length);
+            openUnits.forEach((unit, index) => {
+                const moved = dates[index].toISOString();
+                unit.entities.forEach(entity => {
+                    entity.metadata = entity.metadata || {};
+                    entity.metadata.dueDate = moved;
+                    entity.metadata.updatedAt = timestamp;
+                });
+                unit.dueDate = moved;
+            });
+            actionStepsRescheduled = openUnits.length;
+        }
+        const actionStepsPastDueDate = openUnits.filter(u => u.dueDate ? new Date(u.dueDate).getTime() > parsed : false).length;
+        await this.saveGraph(graph);
+        return {
+            chartId,
+            previousDueDate,
+            newDueDate: normalizedDueDate,
+            actionStepsRescheduled,
+            actionStepsPastDueDate,
+        };
+    }
+    /**
+     * A chart's work in the two shapes it takes: action_step entities on the chart
+     * itself, and telescoped child charts. A child telescoped out of one of the
+     * chart's own steps is that same result seen closer up — it travels with the
+     * step rather than counting as a second unit.
+     */
+    collectChartWorkUnits(graph, chartId) {
+        const ownSteps = graph.entities.filter(e => e.entityType === 'action_step' && e.metadata?.chartId === chartId);
+        const childCharts = graph.entities.filter(e => e.entityType === 'structural_tension_chart' && e.metadata?.parentChart === chartId);
+        const outcomeOf = (chart) => {
+            const childId = chart.metadata?.chartId || chart.name.replace('_chart', '');
+            return graph.entities.find(e => e.name === `${childId}_desired_outcome` && e.entityType === 'desired_outcome');
+        };
+        const stepNames = new Set(ownSteps.map(e => e.name));
+        const units = ownSteps.map(step => {
+            const grown = childCharts.filter(c => c.metadata?.parentActionStep === step.name);
+            const entities = [
+                step,
+                ...grown.flatMap(c => [c, outcomeOf(c)].filter((e) => Boolean(e))),
+            ];
+            return {
+                entities,
+                complete: step.metadata?.completionStatus === true,
+                dueDate: typeof step.metadata?.dueDate === 'string' ? step.metadata.dueDate : undefined,
+            };
+        });
+        childCharts
+            .filter(c => !(c.metadata?.parentActionStep && stepNames.has(c.metadata.parentActionStep)))
+            .forEach(chart => {
+            const outcome = outcomeOf(chart);
+            units.push({
+                entities: [chart, outcome].filter((e) => Boolean(e)),
+                complete: outcome?.metadata?.completionStatus === true,
+                dueDate: typeof chart.metadata?.dueDate === 'string' ? chart.metadata.dueDate : undefined,
+            });
+        });
+        return units;
+    }
     // ─── MMOT Evaluation ────────────────────────────────────────────────
     async performMmotEvaluation(chartId, phase = 'full', assessment, direction, correctiveActions, updateReality = true) {
+        assertNoUnparsedCallSyntax(assessment, 'assessment');
+        assertNoUnparsedCallSyntax(correctiveActions, 'correctiveActions');
         const graph = await this.loadGraph();
         const chartEntity = graph.entities.find(e => e.entityType === 'structural_tension_chart' &&
             e.metadata?.chartId === chartId);
@@ -536,11 +783,17 @@ export class KnowledgeGraphManager {
         const guidance = phaseGuidance[phase] || phaseGuidance.full || phaseGuidance.acknowledge;
         let evaluationStored = false;
         let beatEmitted = false;
-        // Store evaluation observations
-        if (assessment && updateReality) {
-            const evalObservation = `[MMOT ${phase}${directionLabel}] ${assessment}`;
-            if (currentReality) {
-                currentReality.observations.push(evalObservation);
+        // Store evaluation observations.
+        //
+        // updateReality governs ONE record — the append into current reality — which is
+        // exactly what the tool declares it to mean ("whether to write evaluation
+        // observations into current reality"). The chart's own mmotEvaluations[] trail is
+        // a separate record and is written whenever an assessment was made. Gating both on
+        // one flag meant a caller who only asked to leave current reality alone lost the
+        // evaluation entirely, while still being handed a full phase response.
+        if (assessment) {
+            if (updateReality && currentReality) {
+                currentReality.observations.push(`[MMOT ${phase}${directionLabel}] ${assessment}`);
                 if (currentReality.metadata) {
                     currentReality.metadata.updatedAt = timestamp;
                 }
@@ -711,6 +964,143 @@ export class KnowledgeGraphManager {
         return beats;
     }
     // ─── Add Action Step (telescoped chart) ─────────────────────────────
+    // ─── Wampum Belt Sequencing ─────────────────────────────────────────
+    // Runs in parallel with linear narrative beats: a grid of beads, each holding a
+    // mnemonic and its readings, optionally tied to a chart or beat by ceremony.
+    async createWampumBelt(title, purpose, rows = 1, cols = 1) {
+        if (!Number.isInteger(rows) || rows <= 0 || !Number.isInteger(cols) || cols <= 0) {
+            throw new Error(`rows and cols must be positive integers (received rows=${rows}, cols=${cols})`);
+        }
+        const beltId = `belt_${Date.now()}`;
+        const timestamp = new Date().toISOString();
+        const beltMetadata = {
+            beltId,
+            title,
+            purpose,
+            rows,
+            cols,
+            beads: [],
+            createdAt: timestamp,
+            updatedAt: timestamp,
+        };
+        const entity = {
+            name: `${beltId}_belt`,
+            entityType: 'wampum_belt',
+            observations: [`Wampum Belt created: ${title}`, `Purpose: ${purpose}`],
+            metadata: {
+                beltId,
+                createdAt: timestamp,
+                updatedAt: timestamp,
+                wampumBelt: beltMetadata,
+            },
+        };
+        await this.createEntities([entity]);
+        return { beltId, entity };
+    }
+    async addWampumBead(beltId, mnemonic, color, position, reading, relationalReadings, ceremonyLink, observations = []) {
+        const graph = await this.loadGraph();
+        const beltEntity = graph.entities.find(e => e.entityType === 'wampum_belt' && e.metadata?.beltId === beltId);
+        if (!beltEntity?.metadata?.wampumBelt) {
+            throw new Error(`Wampum Belt not found: ${beltId}`);
+        }
+        const beltMeta = beltEntity.metadata.wampumBelt;
+        if (!Number.isInteger(position.row) ||
+            !Number.isInteger(position.col) ||
+            position.row < 0 ||
+            position.col < 0 ||
+            position.row >= beltMeta.rows ||
+            position.col >= beltMeta.cols) {
+            throw new Error(`Position (${position.row},${position.col}) out of bounds for belt ${beltId} (${beltMeta.rows}x${beltMeta.cols})`);
+        }
+        const conflict = beltMeta.beads.find(b => b.position.row === position.row && b.position.col === position.col);
+        if (conflict) {
+            throw new Error(`Position (${position.row},${position.col}) already occupied by bead "${conflict.mnemonic}"`);
+        }
+        const timestamp = new Date().toISOString();
+        const bead = {
+            id: `bead_${beltId}_${position.row}_${position.col}`,
+            mnemonic,
+            color,
+            position,
+            reading,
+            ...(relationalReadings ? { relationalReadings } : {}),
+            ...(ceremonyLink ? { ceremonyLink } : {}),
+            observations,
+            createdAt: timestamp,
+        };
+        beltMeta.beads.push(bead);
+        beltMeta.updatedAt = timestamp;
+        beltEntity.metadata.updatedAt = timestamp;
+        // Ceremony edges are subject to the BEAD, not the belt.
+        //
+        // A relation's identity in the store is (from, to, relationType) — see
+        // jsonl-preservation.ts. With the belt as subject, a second bead linking the
+        // same chart under a different ceremonyType collided on that triple: the
+        // existence check below matched, the push was skipped, and the bead kept a
+        // ceremonyType the graph had no edge for. Silent discard — the bead's own
+        // record disagreed with the graph, and nothing said so.
+        //
+        // bead.id is `bead_${beltId}_${row}_${col}` and a position can be written only
+        // once, so (bead, target, relationType) is unique by construction and every
+        // ceremony link survives with its own ceremonyType.
+        if (ceremonyLink?.chartId) {
+            const from = bead.id;
+            const to = `${ceremonyLink.chartId}_chart`;
+            const exists = graph.relations.some(r => r.from === from && r.to === to && r.relationType === 'wampum_holds_accountable');
+            if (!exists) {
+                graph.relations.push({
+                    from,
+                    to,
+                    relationType: 'wampum_holds_accountable',
+                    metadata: { createdAt: timestamp, context: ceremonyLink.ceremonyType, beltId },
+                });
+            }
+        }
+        if (ceremonyLink?.beatName) {
+            const from = bead.id;
+            const to = ceremonyLink.beatName;
+            const exists = graph.relations.some(r => r.from === from && r.to === to && r.relationType === 'wampum_witnesses');
+            if (!exists) {
+                graph.relations.push({
+                    from,
+                    to,
+                    relationType: 'wampum_witnesses',
+                    metadata: { createdAt: timestamp, beltId },
+                });
+            }
+        }
+        await this.saveGraph(graph);
+        return { bead };
+    }
+    async readWampumBelt(beltId, position) {
+        const graph = await this.loadGraph();
+        const beltEntity = graph.entities.find(e => e.entityType === 'wampum_belt' && e.metadata?.beltId === beltId);
+        if (!beltEntity?.metadata?.wampumBelt) {
+            throw new Error(`Wampum Belt not found: ${beltId}`);
+        }
+        const belt = beltEntity.metadata.wampumBelt;
+        if (!position) {
+            return { belt };
+        }
+        if (!Number.isInteger(position.row) ||
+            !Number.isInteger(position.col) ||
+            position.row < 0 ||
+            position.col < 0 ||
+            position.row >= belt.rows ||
+            position.col >= belt.cols) {
+            throw new Error(`Position (${position.row},${position.col}) out of bounds for belt ${beltId} (${belt.rows}x${belt.cols})`);
+        }
+        const bead = belt.beads.find(b => b.position.row === position.row && b.position.col === position.col);
+        if (!bead) {
+            return { belt };
+        }
+        const colLabel = position.col === 0 ? 'left' : position.col === belt.cols - 1 ? 'right' : 'center';
+        const positionalReading = bead.relationalReadings?.[`col:${position.col}`] ??
+            bead.relationalReadings?.[`row:${position.row}`] ??
+            bead.relationalReadings?.[colLabel] ??
+            bead.reading;
+        return { belt, bead, positionalReading };
+    }
     async addActionStep(parentChartId, actionStepTitle, dueDate, currentReality, performanceElements) {
         const graph = await this.loadGraph();
         const parentChart = graph.entities.find(e => e.entityType === 'structural_tension_chart' &&