@medicine-wheel/storage-provider 0.4.11 → 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, 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

@@ -13,6 +13,94 @@ export interface RelationalEdge extends Omit<OntologyRelationalEdge, 'id'> {
     last_ceremony?: string;
 }
 export type CeremonyLog = OntologyCeremonyLog;
+export type WeaveSyncState = 'never-synced' | 'in-sync' | 'stale' | 'episode-copy-diverged';
+export interface WeaveRecord extends Record<string, unknown> {
+    id: string;
+    weave: 1;
+    artefact: {
+        id: string;
+        path?: string;
+        [key: string]: unknown;
+    };
+    issue: string;
+    issue_url?: string;
+    episode: {
+        path: string;
+        number: number;
+        [key: string]: unknown;
+    };
+    last_sync: {
+        state: WeaveSyncState;
+        at?: string;
+        tree_sha256?: string;
+        file_count?: number;
+        bytes_total?: number;
+        [key: string]: unknown;
+    };
+    source: {
+        package: string;
+        record_path?: string;
+        registered_at: string;
+        updated_at: string;
+        [key: string]: unknown;
+    };
+}
+export interface InquiryWeaveFilters {
+    episode_path?: string;
+    episode_number?: number;
+    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>;
@@ -33,5 +121,11 @@ export interface StorageProvider {
     getCeremoniesByDirection(direction: DirectionName): Promise<CeremonyLog[]>;
     getCeremoniesByType(type: CeremonyType): Promise<CeremonyLog[]>;
     getAllCeremonies(limit?: number): Promise<CeremonyLog[]>;
+    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,11 +1,13 @@
 import type { DirectionName, NodeType, CeremonyType } from '@medicine-wheel/ontology-core';
-import type { StorageProvider, RelationalNode, RelationalEdge, CeremonyLog } 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;
     private readonly nodesFile;
     private readonly edgesFile;
     private readonly ceremoniesFile;
+    private readonly inquiryWeavesFile;
+    private readonly planPerspectivesFile;
     constructor(dataDir?: string);
     connect(): Promise<void>;
     disconnect(): Promise<void>;
@@ -25,9 +27,17 @@ export declare class JsonlProvider implements StorageProvider {
     getCeremoniesByDirection(direction: DirectionName): Promise<CeremonyLog[]>;
     getCeremoniesByType(type: CeremonyType): Promise<CeremonyLog[]>;
     getAllCeremonies(limit?: number): Promise<CeremonyLog[]>;
+    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,17 +1,22 @@
 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;
     nodesFile;
     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);
@@ -118,6 +123,33 @@ export class JsonlProvider {
             .slice(0, limit)
             .map((ceremony) => this.parseCeremony(ceremony));
     }
+    async registerInquiryWeave(record) {
+        await this.upsertById(this.inquiryWeavesFile, record);
+    }
+    async getInquiryWeave(id) {
+        return this.readInquiryWeaves().find((record) => record.id === id) ?? null;
+    }
+    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);
     }
@@ -127,6 +159,12 @@ export class JsonlProvider {
     readCeremonies() {
         return readJsonl(this.ceremoniesFile);
     }
+    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);
@@ -254,6 +292,21 @@ function edgeKey(edge) {
 function sortByNewest(field) {
     return (left, right) => Date.parse(right[field]) - Date.parse(left[field]);
 }
+function matchesInquiryWeaveFilters(record, filters) {
+    if (filters.episode_path !== undefined && record.episode?.path !== filters.episode_path) {
+        return false;
+    }
+    if (filters.episode_number !== undefined && record.episode?.number !== filters.episode_number) {
+        return false;
+    }
+    if (filters.issue !== undefined && record.issue !== filters.issue) {
+        return false;
+    }
+    if (filters.artefact !== undefined && record.artefact?.id !== filters.artefact) {
+        return false;
+    }
+    return true;
+}
 function isProcessAlive(pid) {
     try {
         // Signal 0 checks process existence without sending a real signal.

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 } 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;
@@ -28,4 +28,13 @@ export declare class NeonProvider implements StorageProvider {
     getCeremoniesByType(type: CeremonyType): Promise<CeremonyLog[]>;
     getAllCeremonies(limit?: number): Promise<CeremonyLog[]>;
     private parseCeremony;
+    registerInquiryWeave(record: WeaveRecord): Promise<void>;
+    getInquiryWeave(id: string): Promise<WeaveRecord | null>;
+    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;
@@ -10,6 +11,8 @@ export class NeonProvider {
             throw new Error('DATABASE_URL, POSTGRES_URL, or NEON_DATABASE_URL must be set');
         const { neon } = await import('@neondatabase/serverless');
         this.sql = neon(url);
+        await this.ensureInquiryWeavesTable();
+        await this.ensurePlanPerspectivesTable();
     }
     async disconnect() {
         this.sql = null;
@@ -174,6 +177,126 @@ export class NeonProvider {
             research_context: row.research_context || undefined,
         };
     }
+    // ── Inquiry Weave Operations ──
+    async registerInquiryWeave(record) {
+        await this.db `
+      INSERT INTO inquiry_weaves (id, payload, episode_path, episode_number, issue, artefact_id, updated_at)
+      VALUES (
+        ${record.id},
+        ${JSON.stringify(record)},
+        ${record.episode.path},
+        ${record.episode.number},
+        ${record.issue},
+        ${record.artefact.id},
+        NOW()
+      )
+      ON CONFLICT (id) DO UPDATE SET
+        payload = EXCLUDED.payload,
+        episode_path = EXCLUDED.episode_path,
+        episode_number = EXCLUDED.episode_number,
+        issue = EXCLUDED.issue,
+        artefact_id = EXCLUDED.artefact_id,
+        updated_at = NOW()
+    `;
+    }
+    async getInquiryWeave(id) {
+        const rows = await this.db `SELECT payload FROM inquiry_weaves WHERE id = ${id}`;
+        if (rows.length === 0)
+            return null;
+        return parseJsonValue(rows[0].payload, null);
+    }
+    async listInquiryWeaves(filters = {}) {
+        const records = await this.getAllInquiryWeaves();
+        return records.filter((record) => matchesInquiryWeaveFilters(record, filters));
+    }
+    async getAllInquiryWeaves() {
+        const rows = await this.db `SELECT payload FROM inquiry_weaves ORDER BY updated_at DESC`;
+        return rows.map((row) => parseJsonValue(row.payload, null));
+    }
+    async ensureInquiryWeavesTable() {
+        await this.db `
+      CREATE TABLE IF NOT EXISTS inquiry_weaves (
+        id TEXT PRIMARY KEY,
+        payload JSONB NOT NULL,
+        episode_path TEXT NOT NULL,
+        episode_number INTEGER NOT NULL,
+        issue TEXT NOT NULL,
+        artefact_id TEXT NOT NULL,
+        updated_at TIMESTAMPTZ DEFAULT NOW()
+      )
+    `;
+        await this.db `CREATE INDEX IF NOT EXISTS idx_inquiry_weaves_episode_path ON inquiry_weaves(episode_path)`;
+        await this.db `CREATE INDEX IF NOT EXISTS idx_inquiry_weaves_episode_number ON inquiry_weaves(episode_number)`;
+        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;
@@ -198,3 +321,18 @@ function parseJsonValue(value, fallback) {
     }
     return value;
 }
+function matchesInquiryWeaveFilters(record, filters) {
+    if (filters.episode_path !== undefined && record.episode?.path !== filters.episode_path) {
+        return false;
+    }
+    if (filters.episode_number !== undefined && record.episode?.number !== filters.episode_number) {
+        return false;
+    }
+    if (filters.issue !== undefined && record.issue !== filters.issue) {
+        return false;
+    }
+    if (filters.artefact !== undefined && record.artefact?.id !== filters.artefact) {
+        return false;
+    }
+    return true;
+}

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.11",
+  "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.11"
+    "@medicine-wheel/ontology-core": "^0.4.13"
   },
   "devDependencies": {
     "typescript": "^5.7.0"