@medicine-wheel/storage-provider 0.4.12 → 0.4.13

package/dist/index.d.ts

@@ -15,7 +15,8 @@
  * 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, } 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,8 @@
  * const node = await store.getNode('elder-1');
  * ```
  */
+// 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

@@ -51,6 +51,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>;
@@ -74,5 +124,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/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 } 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>;
@@ -29,10 +30,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,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { randomUUID } from 'crypto';
+import { mergePlanPerspectiveRecords, matchesPlanPerspectiveFilters, } from './plan-perspectives.js';
 export class JsonlProvider {
     name = 'jsonl';
     dataDir;
@@ -8,12 +9,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);
@@ -129,6 +132,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 +162,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);

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 } from './interface.js';
 export declare class NeonProvider implements StorageProvider {
     readonly name = "neon";
     private sql;
@@ -33,4 +33,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,7 @@
 /**
  * Neon (Postgres) Storage Provider
  */
+import { mergePlanPerspectiveRecords, matchesPlanPerspectiveFilters, } from './plan-perspectives.js';
 export class NeonProvider {
     name = 'neon';
     sql = null;
@@ -11,6 +12,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;
@@ -228,6 +230,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.4.13",
   "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.4.13"
   },
   "devDependencies": {
     "typescript": "^5.7.0"