@medicine-wheel/storage-provider 0.4.12 → 0.5.0

package/dist/index.d.ts

@@ -15,7 +15,9 @@
  * const node = await store.getNode('elder-1');
  * ```
  */
-export type { StorageProvider, RelationalNode, RelationalEdge, CeremonyLog, WeaveRecord, WeaveSyncState, InquiryWeaveFilters, ProviderType, } from './interface.js';
+export type { StorageProvider, RelationalNode, RelationalEdge, CeremonyLog, WeaveRecord, WeaveSyncState, InquiryWeaveFilters, PlanPerspectiveRecord, PlanPerspectiveEpisode, PlanPerspectiveFilters, ProviderType, NodePatch, EdgePatch, } from './interface.js';
+export { NodeNotFoundError, EdgeNotFoundError, NodeHasRelationsError, } from './interface.js';
+export { mergePlanPerspectiveRecords, unionPlanPerspectiveEpisodes, matchesPlanPerspectiveFilters, } from './plan-perspectives.js';
 export { createProvider, detectProvider } from './factory.js';
 export { JsonlProvider } from './jsonl.js';
 export { NeonProvider } from './neon.js';

package/dist/index.js

@@ -15,6 +15,10 @@
  * const node = await store.getNode('elder-1');
  * ```
  */
+// Typed errors (thrown by update/delete operations)
+export { NodeNotFoundError, EdgeNotFoundError, NodeHasRelationsError, } from './interface.js';
+// Plan Perspective merge/filter semantics (shared across providers)
+export { mergePlanPerspectiveRecords, unionPlanPerspectiveEpisodes, matchesPlanPerspectiveFilters, } from './plan-perspectives.js';
 // Factory
 export { createProvider, detectProvider } from './factory.js';
 // Providers (for direct instantiation)

package/dist/interface.d.ts

@@ -13,6 +13,42 @@ export interface RelationalEdge extends Omit<OntologyRelationalEdge, 'id'> {
     last_ceremony?: string;
 }
 export type CeremonyLog = OntologyCeremonyLog;
+/** Partial update for a node. `direction: null` releases the node from its direction. */
+export interface NodePatch {
+    name?: string;
+    type?: NodeType;
+    description?: string;
+    direction?: DirectionName | null;
+    metadata?: Record<string, unknown>;
+}
+/** Partial update for an edge (identified by from_id + to_id). */
+export interface EdgePatch {
+    relationship_type?: string;
+    strength?: number;
+    ceremony_honored?: boolean;
+    obligations?: string[];
+}
+export declare class NodeNotFoundError extends Error {
+    readonly nodeId: string;
+    readonly code = "NODE_NOT_FOUND";
+    constructor(nodeId: string);
+}
+export declare class EdgeNotFoundError extends Error {
+    readonly fromId: string;
+    readonly toId: string;
+    readonly code = "EDGE_NOT_FOUND";
+    constructor(fromId: string, toId: string);
+}
+/**
+ * Deleting a node with living relations is refused: relational accountability
+ * means severing each relation consciously before releasing the node.
+ */
+export declare class NodeHasRelationsError extends Error {
+    readonly nodeId: string;
+    readonly relationCount: number;
+    readonly code = "NODE_HAS_RELATIONS";
+    constructor(nodeId: string, relationCount: number);
+}
 export type WeaveSyncState = 'never-synced' | 'in-sync' | 'stale' | 'episode-copy-diverged';
 export interface WeaveRecord extends Record<string, unknown> {
     id: string;
@@ -51,6 +87,56 @@ export interface InquiryWeaveFilters {
     issue?: string;
     artefact?: string;
 }
+export interface PlanPerspectiveEpisode {
+    path: string;
+    number?: number;
+    [key: string]: unknown;
+}
+export interface PlanPerspectiveRecord extends Record<string, unknown> {
+    id: string;
+    perspective: 1;
+    plan: {
+        session_id: string;
+        plan_path?: string;
+        plan_filename: string;
+        plan_sha256: string;
+        captured_at?: string;
+        [key: string]: unknown;
+    };
+    narrative: {
+        title: string;
+        body_markdown: string;
+        mia_context?: string;
+        [key: string]: unknown;
+    };
+    lineage?: {
+        user_inputs_path?: string;
+        input_count?: number;
+        first_input_at?: string;
+        last_input_at?: string;
+        excerpts?: string[];
+        [key: string]: unknown;
+    };
+    episodes: PlanPerspectiveEpisode[];
+    source: {
+        package?: string;
+        generator?: {
+            system?: string;
+            agent?: string;
+            model?: string;
+            producer_session_id?: string;
+            [key: string]: unknown;
+        };
+        registered_at: string;
+        updated_at: string;
+        [key: string]: unknown;
+    };
+}
+export interface PlanPerspectiveFilters {
+    episode_path?: string;
+    session_id?: string;
+    id?: string;
+}
 export interface StorageProvider {
     readonly name: string;
     connect(): Promise<void>;
@@ -60,11 +146,19 @@ export interface StorageProvider {
     getNodesByType(type: NodeType): Promise<RelationalNode[]>;
     getNodesByDirection(direction: DirectionName): Promise<RelationalNode[]>;
     getAllNodes(limit?: number): Promise<RelationalNode[]>;
+    /** Throws NodeNotFoundError when the node does not exist. */
+    updateNode(id: string, patch: NodePatch): Promise<RelationalNode>;
+    /** Throws NodeNotFoundError or NodeHasRelationsError (refusal, never cascade). */
+    deleteNode(id: string): Promise<void>;
     createEdge(edge: RelationalEdge): Promise<void>;
     getEdge(fromId: string, toId: string): Promise<RelationalEdge | null>;
     getAllEdges(limit?: number): Promise<RelationalEdge[]>;
     getRelatedNodes(nodeId: string, direction?: 'from' | 'to' | 'both'): Promise<string[]>;
     updateEdgeCeremony(fromId: string, toId: string, ceremonyId: string): Promise<void>;
+    /** Throws EdgeNotFoundError when no relation exists between the pair. */
+    updateEdge(fromId: string, toId: string, patch: EdgePatch): Promise<RelationalEdge>;
+    /** Throws EdgeNotFoundError when no relation exists between the pair. */
+    deleteEdge(fromId: string, toId: string): Promise<void>;
     logCeremony(ceremony: CeremonyLog): Promise<void>;
     getCeremony(id: string): Promise<CeremonyLog | null>;
     getCeremoniesTimeline(limit?: number): Promise<CeremonyLog[]>;
@@ -74,5 +168,8 @@ export interface StorageProvider {
     registerInquiryWeave(record: WeaveRecord): Promise<void>;
     getInquiryWeave(id: string): Promise<WeaveRecord | null>;
     listInquiryWeaves(filters?: InquiryWeaveFilters): Promise<WeaveRecord[]>;
+    registerPlanPerspective(record: PlanPerspectiveRecord): Promise<PlanPerspectiveRecord>;
+    getPlanPerspective(id: string): Promise<PlanPerspectiveRecord | null>;
+    listPlanPerspectives(filters?: PlanPerspectiveFilters): Promise<PlanPerspectiveRecord[]>;
 }
 export type ProviderType = 'jsonl' | 'neon' | 'redis' | 'auto';

package/dist/interface.js

@@ -4,4 +4,40 @@
  * Abstract interface for Medicine Wheel data persistence.
  * Implementations: JsonlProvider (local/default), NeonProvider (Postgres), RedisProvider (future)
  */
-export {};
+// ── Typed Errors ──
+// Providers throw these so API layers can answer with honest status codes.
+export class NodeNotFoundError extends Error {
+    nodeId;
+    code = 'NODE_NOT_FOUND';
+    constructor(nodeId) {
+        super(`Node not found: ${nodeId}`);
+        this.nodeId = nodeId;
+        this.name = 'NodeNotFoundError';
+    }
+}
+export class EdgeNotFoundError extends Error {
+    fromId;
+    toId;
+    code = 'EDGE_NOT_FOUND';
+    constructor(fromId, toId) {
+        super(`Relation not found between ${fromId} and ${toId}`);
+        this.fromId = fromId;
+        this.toId = toId;
+        this.name = 'EdgeNotFoundError';
+    }
+}
+/**
+ * Deleting a node with living relations is refused: relational accountability
+ * means severing each relation consciously before releasing the node.
+ */
+export class NodeHasRelationsError extends Error {
+    nodeId;
+    relationCount;
+    code = 'NODE_HAS_RELATIONS';
+    constructor(nodeId, relationCount) {
+        super(`This node holds ${relationCount} relation${relationCount === 1 ? '' : 's'} — release them first`);
+        this.nodeId = nodeId;
+        this.relationCount = relationCount;
+        this.name = 'NodeHasRelationsError';
+    }
+}

package/dist/jsonl.d.ts

@@ -1,5 +1,5 @@
 import type { DirectionName, NodeType, CeremonyType } from '@medicine-wheel/ontology-core';
-import type { StorageProvider, RelationalNode, RelationalEdge, CeremonyLog, WeaveRecord, InquiryWeaveFilters } from './interface.js';
+import type { StorageProvider, RelationalNode, RelationalEdge, CeremonyLog, WeaveRecord, InquiryWeaveFilters, PlanPerspectiveRecord, PlanPerspectiveFilters, NodePatch, EdgePatch } from './interface.js';
 export declare class JsonlProvider implements StorageProvider {
     readonly name = "jsonl";
     readonly dataDir: string;
@@ -7,6 +7,7 @@ export declare class JsonlProvider implements StorageProvider {
     private readonly edgesFile;
     private readonly ceremoniesFile;
     private readonly inquiryWeavesFile;
+    private readonly planPerspectivesFile;
     constructor(dataDir?: string);
     connect(): Promise<void>;
     disconnect(): Promise<void>;
@@ -15,11 +16,15 @@ export declare class JsonlProvider implements StorageProvider {
     getNodesByType(type: NodeType): Promise<RelationalNode[]>;
     getNodesByDirection(direction: DirectionName): Promise<RelationalNode[]>;
     getAllNodes(limit?: number): Promise<RelationalNode[]>;
+    updateNode(id: string, patch: NodePatch): Promise<RelationalNode>;
+    deleteNode(id: string): Promise<void>;
     createEdge(edge: RelationalEdge): Promise<void>;
     getEdge(fromId: string, toId: string): Promise<RelationalEdge | null>;
     getRelatedNodes(nodeId: string, direction?: 'from' | 'to' | 'both'): Promise<string[]>;
     getAllEdges(limit?: number): Promise<RelationalEdge[]>;
     updateEdgeCeremony(fromId: string, toId: string, ceremonyId: string): Promise<void>;
+    updateEdge(fromId: string, toId: string, patch: EdgePatch): Promise<RelationalEdge>;
+    deleteEdge(fromId: string, toId: string): Promise<void>;
     logCeremony(ceremony: CeremonyLog): Promise<void>;
     getCeremony(id: string): Promise<CeremonyLog | null>;
     getCeremoniesTimeline(limit?: number): Promise<CeremonyLog[]>;
@@ -29,10 +34,14 @@ export declare class JsonlProvider implements StorageProvider {
     registerInquiryWeave(record: WeaveRecord): Promise<void>;
     getInquiryWeave(id: string): Promise<WeaveRecord | null>;
     listInquiryWeaves(filters?: InquiryWeaveFilters): Promise<WeaveRecord[]>;
+    registerPlanPerspective(record: PlanPerspectiveRecord): Promise<PlanPerspectiveRecord>;
+    getPlanPerspective(id: string): Promise<PlanPerspectiveRecord | null>;
+    listPlanPerspectives(filters?: PlanPerspectiveFilters): Promise<PlanPerspectiveRecord[]>;
     private readNodes;
     private readEdges;
     private readCeremonies;
     private readInquiryWeaves;
+    private readPlanPerspectives;
     private upsertById;
     private upsertEdge;
     private parseNode;

package/dist/jsonl.js

@@ -1,6 +1,8 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { randomUUID } from 'crypto';
+import { NodeNotFoundError, EdgeNotFoundError, NodeHasRelationsError, } from './interface.js';
+import { mergePlanPerspectiveRecords, matchesPlanPerspectiveFilters, } from './plan-perspectives.js';
 export class JsonlProvider {
     name = 'jsonl';
     dataDir;
@@ -8,12 +10,14 @@ export class JsonlProvider {
     edgesFile;
     ceremoniesFile;
     inquiryWeavesFile;
+    planPerspectivesFile;
     constructor(dataDir) {
         this.dataDir = path.resolve(dataDir ?? resolveProjectDataDir());
         this.nodesFile = path.join(this.dataDir, 'nodes.jsonl');
         this.edgesFile = path.join(this.dataDir, 'edges.jsonl');
         this.ceremoniesFile = path.join(this.dataDir, 'ceremonies.jsonl');
         this.inquiryWeavesFile = path.join(this.dataDir, 'inquiry-weaves.jsonl');
+        this.planPerspectivesFile = path.join(this.dataDir, 'plan-perspectives.jsonl');
     }
     async connect() {
         ensureDirectory(this.dataDir);
@@ -46,6 +50,42 @@ export class JsonlProvider {
             .slice(0, limit)
             .map((node) => this.parseNode(node));
     }
+    async updateNode(id, patch) {
+        return withWriteLock(this.nodesFile, () => {
+            const nodes = this.readNodes();
+            const index = nodes.findIndex((candidate) => candidate.id === id);
+            if (index === -1)
+                throw new NodeNotFoundError(id);
+            const current = nodes[index];
+            const next = {
+                ...current,
+                ...(patch.name !== undefined ? { name: patch.name } : {}),
+                ...(patch.type !== undefined ? { type: patch.type } : {}),
+                ...(patch.description !== undefined ? { description: patch.description } : {}),
+                ...(patch.metadata !== undefined ? { metadata: patch.metadata } : {}),
+                updated_at: new Date().toISOString(),
+            };
+            if (patch.direction !== undefined) {
+                next.direction = patch.direction === null ? undefined : patch.direction;
+            }
+            nodes[index] = next;
+            writeJsonl(this.nodesFile, nodes);
+            return this.parseNode(next);
+        });
+    }
+    async deleteNode(id) {
+        await withWriteLock(this.nodesFile, () => {
+            const nodes = this.readNodes();
+            if (!nodes.some((candidate) => candidate.id === id)) {
+                throw new NodeNotFoundError(id);
+            }
+            const relationCount = this.readEdges().filter((edge) => edge.from_id === id || edge.to_id === id).length;
+            if (relationCount > 0) {
+                throw new NodeHasRelationsError(id, relationCount);
+            }
+            writeJsonl(this.nodesFile, nodes.filter((candidate) => candidate.id !== id));
+        });
+    }
     async createEdge(edge) {
         await this.upsertEdge({
             ...edge,
@@ -89,6 +129,38 @@ export class JsonlProvider {
             writeJsonl(this.edgesFile, nextEdges);
         });
     }
+    async updateEdge(fromId, toId, patch) {
+        return withWriteLock(this.edgesFile, () => {
+            const edges = this.readEdges();
+            const index = edges.findIndex((candidate) => candidate.from_id === fromId && candidate.to_id === toId);
+            if (index === -1)
+                throw new EdgeNotFoundError(fromId, toId);
+            const next = {
+                ...edges[index],
+                ...(patch.relationship_type !== undefined
+                    ? { relationship_type: patch.relationship_type }
+                    : {}),
+                ...(patch.strength !== undefined ? { strength: patch.strength } : {}),
+                ...(patch.ceremony_honored !== undefined
+                    ? { ceremony_honored: patch.ceremony_honored }
+                    : {}),
+                ...(patch.obligations !== undefined ? { obligations: patch.obligations } : {}),
+            };
+            edges[index] = next;
+            writeJsonl(this.edgesFile, edges);
+            return this.parseEdge(next);
+        });
+    }
+    async deleteEdge(fromId, toId) {
+        await withWriteLock(this.edgesFile, () => {
+            const edges = this.readEdges();
+            const remaining = edges.filter((candidate) => !(candidate.from_id === fromId && candidate.to_id === toId));
+            if (remaining.length === edges.length) {
+                throw new EdgeNotFoundError(fromId, toId);
+            }
+            writeJsonl(this.edgesFile, remaining);
+        });
+    }
     async logCeremony(ceremony) {
         await this.upsertById(this.ceremoniesFile, ceremony);
     }
@@ -129,6 +201,24 @@ export class JsonlProvider {
     async listInquiryWeaves(filters = {}) {
         return this.readInquiryWeaves().filter((record) => matchesInquiryWeaveFilters(record, filters));
     }
+    async registerPlanPerspective(record) {
+        let merged = record;
+        await withWriteLock(this.planPerspectivesFile, () => {
+            const records = readJsonl(this.planPerspectivesFile);
+            const existing = records.find((candidate) => candidate.id === record.id);
+            merged = existing ? mergePlanPerspectiveRecords(existing, record) : record;
+            const nextRecords = records.filter((candidate) => candidate.id !== record.id);
+            nextRecords.push(merged);
+            writeJsonl(this.planPerspectivesFile, nextRecords);
+        });
+        return merged;
+    }
+    async getPlanPerspective(id) {
+        return this.readPlanPerspectives().find((record) => record.id === id) ?? null;
+    }
+    async listPlanPerspectives(filters = {}) {
+        return this.readPlanPerspectives().filter((record) => matchesPlanPerspectiveFilters(record, filters));
+    }
     readNodes() {
         return readJsonl(this.nodesFile);
     }
@@ -141,6 +231,9 @@ export class JsonlProvider {
     readInquiryWeaves() {
         return readJsonl(this.inquiryWeavesFile);
     }
+    readPlanPerspectives() {
+        return readJsonl(this.planPerspectivesFile);
+    }
     async upsertById(filePath, item) {
         await withWriteLock(filePath, () => {
             const nextRecords = readJsonl(filePath).filter((candidate) => candidate.id !== item.id);
@@ -169,6 +262,7 @@ export class JsonlProvider {
     }
     parseEdge(edge) {
         return {
+            id: edge.id ?? `${edge.from_id}:${edge.to_id}`,
             from_id: edge.from_id,
             to_id: edge.to_id,
             relationship_type: edge.relationship_type,

package/dist/neon.d.ts

@@ -2,7 +2,7 @@
  * Neon (Postgres) Storage Provider
  */
 import type { DirectionName, NodeType, CeremonyType } from '@medicine-wheel/ontology-core';
-import type { StorageProvider, RelationalNode, RelationalEdge, CeremonyLog, WeaveRecord, InquiryWeaveFilters } from './interface.js';
+import type { StorageProvider, RelationalNode, RelationalEdge, CeremonyLog, WeaveRecord, InquiryWeaveFilters, PlanPerspectiveRecord, PlanPerspectiveFilters, NodePatch, EdgePatch } from './interface.js';
 export declare class NeonProvider implements StorageProvider {
     readonly name = "neon";
     private sql;
@@ -14,12 +14,16 @@ export declare class NeonProvider implements StorageProvider {
     getNodesByType(type: NodeType): Promise<RelationalNode[]>;
     getNodesByDirection(direction: DirectionName): Promise<RelationalNode[]>;
     getAllNodes(limit?: number): Promise<RelationalNode[]>;
+    updateNode(id: string, patch: NodePatch): Promise<RelationalNode>;
+    deleteNode(id: string): Promise<void>;
     private parseNode;
     createEdge(edge: RelationalEdge): Promise<void>;
     getEdge(fromId: string, toId: string): Promise<RelationalEdge | null>;
     getRelatedNodes(nodeId: string, direction?: 'from' | 'to' | 'both'): Promise<string[]>;
     getAllEdges(limit?: number): Promise<RelationalEdge[]>;
     updateEdgeCeremony(fromId: string, toId: string, ceremonyId: string): Promise<void>;
+    updateEdge(fromId: string, toId: string, patch: EdgePatch): Promise<RelationalEdge>;
+    deleteEdge(fromId: string, toId: string): Promise<void>;
     private parseEdge;
     logCeremony(ceremony: CeremonyLog): Promise<void>;
     getCeremony(id: string): Promise<CeremonyLog | null>;
@@ -33,4 +37,8 @@ export declare class NeonProvider implements StorageProvider {
     listInquiryWeaves(filters?: InquiryWeaveFilters): Promise<WeaveRecord[]>;
     private getAllInquiryWeaves;
     private ensureInquiryWeavesTable;
+    registerPlanPerspective(record: PlanPerspectiveRecord): Promise<PlanPerspectiveRecord>;
+    getPlanPerspective(id: string): Promise<PlanPerspectiveRecord | null>;
+    listPlanPerspectives(filters?: PlanPerspectiveFilters): Promise<PlanPerspectiveRecord[]>;
+    private ensurePlanPerspectivesTable;
 }

package/dist/neon.js

@@ -1,6 +1,8 @@
 /**
  * Neon (Postgres) Storage Provider
  */
+import { NodeNotFoundError, EdgeNotFoundError, NodeHasRelationsError, } from './interface.js';
+import { mergePlanPerspectiveRecords, matchesPlanPerspectiveFilters, } from './plan-perspectives.js';
 export class NeonProvider {
     name = 'neon';
     sql = null;
@@ -11,6 +13,7 @@ export class NeonProvider {
         const { neon } = await import('@neondatabase/serverless');
         this.sql = neon(url);
         await this.ensureInquiryWeavesTable();
+        await this.ensurePlanPerspectivesTable();
     }
     async disconnect() {
         this.sql = null;
@@ -54,6 +57,45 @@ export class NeonProvider {
         const rows = await this.db `SELECT * FROM nodes ORDER BY created_at DESC LIMIT ${limit}`;
         return rows.map((row) => this.parseNode(row));
     }
+    async updateNode(id, patch) {
+        const existing = await this.getNode(id);
+        if (!existing)
+            throw new NodeNotFoundError(id);
+        const next = {
+            ...existing,
+            ...(patch.name !== undefined ? { name: patch.name } : {}),
+            ...(patch.type !== undefined ? { type: patch.type } : {}),
+            ...(patch.description !== undefined ? { description: patch.description } : {}),
+            ...(patch.metadata !== undefined ? { metadata: patch.metadata } : {}),
+            updated_at: new Date().toISOString(),
+        };
+        if (patch.direction !== undefined) {
+            next.direction = patch.direction === null ? undefined : patch.direction;
+        }
+        await this.db `
+      UPDATE nodes SET
+        name = ${next.name},
+        type = ${next.type},
+        description = ${next.description ?? ''},
+        direction = ${next.direction || null},
+        metadata = ${JSON.stringify(next.metadata)},
+        updated_at = ${next.updated_at}
+      WHERE id = ${id}
+    `;
+        return next;
+    }
+    async deleteNode(id) {
+        const existing = await this.db `SELECT id FROM nodes WHERE id = ${id}`;
+        if (existing.length === 0)
+            throw new NodeNotFoundError(id);
+        const counts = await this.db `
+      SELECT COUNT(*)::int AS count FROM edges WHERE from_id = ${id} OR to_id = ${id}
+    `;
+        const relationCount = Number(counts[0]?.count ?? 0);
+        if (relationCount > 0)
+            throw new NodeHasRelationsError(id, relationCount);
+        await this.db `DELETE FROM nodes WHERE id = ${id}`;
+    }
     parseNode(row) {
         return {
             id: row.id,
@@ -113,8 +155,41 @@ export class NeonProvider {
       WHERE from_id = ${fromId} AND to_id = ${toId}
     `;
     }
+    async updateEdge(fromId, toId, patch) {
+        const existing = await this.getEdge(fromId, toId);
+        if (!existing)
+            throw new EdgeNotFoundError(fromId, toId);
+        const next = {
+            ...existing,
+            ...(patch.relationship_type !== undefined
+                ? { relationship_type: patch.relationship_type }
+                : {}),
+            ...(patch.strength !== undefined ? { strength: patch.strength } : {}),
+            ...(patch.ceremony_honored !== undefined
+                ? { ceremony_honored: patch.ceremony_honored }
+                : {}),
+            ...(patch.obligations !== undefined ? { obligations: patch.obligations } : {}),
+        };
+        await this.db `
+      UPDATE edges SET
+        relationship_type = ${next.relationship_type},
+        strength = ${next.strength},
+        ceremony_honored = ${next.ceremony_honored},
+        obligations = ${JSON.stringify(next.obligations)}
+      WHERE from_id = ${fromId} AND to_id = ${toId}
+    `;
+        return next;
+    }
+    async deleteEdge(fromId, toId) {
+        const deleted = await this.db `
+      DELETE FROM edges WHERE from_id = ${fromId} AND to_id = ${toId} RETURNING from_id
+    `;
+        if (deleted.length === 0)
+            throw new EdgeNotFoundError(fromId, toId);
+    }
     parseEdge(row) {
         return {
+            id: `${row.from_id}:${row.to_id}`,
             from_id: row.from_id,
             to_id: row.to_id,
             relationship_type: row.relationship_type,
@@ -228,6 +303,73 @@ export class NeonProvider {
         await this.db `CREATE INDEX IF NOT EXISTS idx_inquiry_weaves_issue ON inquiry_weaves(issue)`;
         await this.db `CREATE INDEX IF NOT EXISTS idx_inquiry_weaves_artefact_id ON inquiry_weaves(artefact_id)`;
     }
+    // ── Plan Perspective Operations ──
+    async registerPlanPerspective(record) {
+        const existing = await this.getPlanPerspective(record.id);
+        const merged = existing ? mergePlanPerspectiveRecords(existing, record) : record;
+        const episodePaths = merged.episodes.map((episode) => episode.path);
+        await this.db `
+      INSERT INTO plan_perspectives (id, payload, session_id, episode_paths, updated_at)
+      VALUES (
+        ${merged.id},
+        ${JSON.stringify(merged)},
+        ${merged.plan.session_id},
+        ${episodePaths},
+        NOW()
+      )
+      ON CONFLICT (id) DO UPDATE SET
+        payload = EXCLUDED.payload,
+        session_id = EXCLUDED.session_id,
+        episode_paths = EXCLUDED.episode_paths,
+        updated_at = NOW()
+    `;
+        return merged;
+    }
+    async getPlanPerspective(id) {
+        const rows = await this.db `SELECT payload FROM plan_perspectives WHERE id = ${id}`;
+        if (rows.length === 0)
+            return null;
+        return parseJsonValue(rows[0].payload, null);
+    }
+    async listPlanPerspectives(filters = {}) {
+        let rows;
+        if (filters.id !== undefined) {
+            rows = await this.db `SELECT payload FROM plan_perspectives WHERE id = ${filters.id}`;
+        }
+        else if (filters.session_id !== undefined) {
+            rows = await this.db `
+        SELECT payload FROM plan_perspectives
+        WHERE session_id = ${filters.session_id}
+        ORDER BY updated_at DESC
+      `;
+        }
+        else if (filters.episode_path !== undefined) {
+            rows = await this.db `
+        SELECT payload FROM plan_perspectives
+        WHERE episode_paths @> ARRAY[${filters.episode_path}]
+        ORDER BY updated_at DESC
+      `;
+        }
+        else {
+            rows = await this.db `SELECT payload FROM plan_perspectives ORDER BY updated_at DESC`;
+        }
+        return rows
+            .map((row) => parseJsonValue(row.payload, null))
+            .filter((record) => record !== null && matchesPlanPerspectiveFilters(record, filters));
+    }
+    async ensurePlanPerspectivesTable() {
+        await this.db `
+      CREATE TABLE IF NOT EXISTS plan_perspectives (
+        id TEXT PRIMARY KEY,
+        payload JSONB NOT NULL,
+        session_id TEXT NOT NULL,
+        episode_paths TEXT[] NOT NULL DEFAULT '{}',
+        updated_at TIMESTAMPTZ DEFAULT NOW()
+      )
+    `;
+        await this.db `CREATE INDEX IF NOT EXISTS idx_plan_perspectives_session_id ON plan_perspectives(session_id)`;
+        await this.db `CREATE INDEX IF NOT EXISTS idx_plan_perspectives_episode_paths ON plan_perspectives USING GIN(episode_paths)`;
+    }
 }
 function getConnectionString() {
     return process.env.DATABASE_URL ?? process.env.POSTGRES_URL ?? process.env.NEON_DATABASE_URL;

package/dist/plan-perspectives.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Plan Perspective merge and filter semantics shared by every provider.
+ *
+ * Medicine-wheel stores relational projections of Miette perspectives; the
+ * session file remains authoritative. Nothing here generates or rewrites
+ * narrative prose — records pass through untouched apart from the episode
+ * union and source timestamps pinned by @miadi/plan-insight's
+ * mergePerspectiveRecords contract.
+ */
+import type { PlanPerspectiveEpisode, PlanPerspectiveFilters, PlanPerspectiveRecord } from './interface.js';
+/** Union episode relations by exact path; a known number backfills an entry missing one. */
+export declare function unionPlanPerspectiveEpisodes(episodes: readonly PlanPerspectiveEpisode[]): PlanPerspectiveEpisode[];
+/**
+ * Upsert merge: the incoming projection wins, episodes union by path, and the
+ * original registration timestamp survives while updated_at refreshes.
+ */
+export declare function mergePlanPerspectiveRecords(existing: PlanPerspectiveRecord, incoming: PlanPerspectiveRecord): PlanPerspectiveRecord;
+export declare function matchesPlanPerspectiveFilters(record: PlanPerspectiveRecord, filters: PlanPerspectiveFilters): boolean;

package/dist/plan-perspectives.js

@@ -0,0 +1,53 @@
+/**
+ * Plan Perspective merge and filter semantics shared by every provider.
+ *
+ * Medicine-wheel stores relational projections of Miette perspectives; the
+ * session file remains authoritative. Nothing here generates or rewrites
+ * narrative prose — records pass through untouched apart from the episode
+ * union and source timestamps pinned by @miadi/plan-insight's
+ * mergePerspectiveRecords contract.
+ */
+/** Union episode relations by exact path; a known number backfills an entry missing one. */
+export function unionPlanPerspectiveEpisodes(episodes) {
+    const byPath = new Map();
+    for (const episode of episodes) {
+        if (typeof episode?.path !== 'string' || episode.path.length === 0)
+            continue;
+        const existing = byPath.get(episode.path);
+        if (!existing) {
+            byPath.set(episode.path, { ...episode });
+        }
+        else if (existing.number === undefined && typeof episode.number === 'number') {
+            existing.number = episode.number;
+        }
+    }
+    return [...byPath.values()];
+}
+/**
+ * Upsert merge: the incoming projection wins, episodes union by path, and the
+ * original registration timestamp survives while updated_at refreshes.
+ */
+export function mergePlanPerspectiveRecords(existing, incoming) {
+    return {
+        ...incoming,
+        episodes: unionPlanPerspectiveEpisodes([...existing.episodes, ...incoming.episodes]),
+        source: {
+            ...incoming.source,
+            registered_at: existing.source.registered_at,
+            updated_at: incoming.source.updated_at,
+        },
+    };
+}
+export function matchesPlanPerspectiveFilters(record, filters) {
+    if (filters.id !== undefined && record.id !== filters.id) {
+        return false;
+    }
+    if (filters.session_id !== undefined && record.plan?.session_id !== filters.session_id) {
+        return false;
+    }
+    if (filters.episode_path !== undefined &&
+        !record.episodes?.some((episode) => episode?.path === filters.episode_path)) {
+        return false;
+    }
+    return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@medicine-wheel/storage-provider",
-  "version": "0.4.12",
+  "version": "0.5.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -16,7 +16,7 @@
   "dependencies": {
     "@neondatabase/serverless": "^0.10.0",
     "@upstash/redis": "^1.34.3",
-    "@medicine-wheel/ontology-core": "^0.4.12"
+    "@medicine-wheel/ontology-core": "^0.5.0"
   },
   "devDependencies": {
     "typescript": "^5.7.0"