@medicine-wheel/storage-provider 0.5.9 → 0.6.0

package/dist/capture-records.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Capture Record semantics shared by every provider.
+ *
+ * The registry holds records and URIs — where a take lives — never the bytes
+ * themselves, which stay behind the capture service that made them. Capture is
+ * owned by @miadi/capture and the gmtermux edge; here we keep only the id
+ * convention, filter predicate, ordering, and upsert-merge rule so the jsonl
+ * and neon backends agree on what a capture means.
+ *
+ * Vocabulary law: capture-vocabulary.spec.md (§8, the registry noun ruling).
+ */
+import type { CaptureFilters, CaptureRecord } from './interface.js';
+/**
+ * Compose the upsert key for a capture, mirroring @miadi/inquiry-weave's
+ * weaveRecordId composition: `capture:<episode_path>:<filename>` when the
+ * capture is episode-bound, `capture:<filename>` otherwise.
+ *
+ * This convention applies only when no id is sent — it is a fallback for
+ * id-less registration, not the identity rule. The id assigned at first
+ * registration is permanent (capture-vocabulary.spec.md §6).
+ */
+export declare function captureRecordId(filename: string, episodePath?: string): string;
+/** True when a capture record satisfies every provided filter. */
+export declare function matchesCaptureFilters(record: CaptureRecord, filters: CaptureFilters): boolean;
+/**
+ * Filter a batch of capture rows, dropping anything that did not survive the
+ * read (a Postgres payload that fails to parse arrives here as null), then
+ * order newest registration first.
+ */
+export declare function filterAndOrderCaptures(records: readonly (CaptureRecord | null | undefined)[], filters?: CaptureFilters): CaptureRecord[];
+/**
+ * Upsert merge: the incoming record wins wherever it speaks, the existing
+ * record fills wherever it stays silent. Provenance is observed, not demanded
+ * — so a later registration that learned less (no device, no sha256) must not
+ * erase what an earlier one knew. The first registration timestamp survives,
+ * matching the plan-perspective merge contract.
+ */
+export declare function mergeCaptureRecords(existing: CaptureRecord, incoming: CaptureRecord): CaptureRecord;

package/dist/capture-records.js

@@ -0,0 +1,77 @@
+/**
+ * Capture Record semantics shared by every provider.
+ *
+ * The registry holds records and URIs — where a take lives — never the bytes
+ * themselves, which stay behind the capture service that made them. Capture is
+ * owned by @miadi/capture and the gmtermux edge; here we keep only the id
+ * convention, filter predicate, ordering, and upsert-merge rule so the jsonl
+ * and neon backends agree on what a capture means.
+ *
+ * Vocabulary law: capture-vocabulary.spec.md (§8, the registry noun ruling).
+ */
+/**
+ * Compose the upsert key for a capture, mirroring @miadi/inquiry-weave's
+ * weaveRecordId composition: `capture:<episode_path>:<filename>` when the
+ * capture is episode-bound, `capture:<filename>` otherwise.
+ *
+ * This convention applies only when no id is sent — it is a fallback for
+ * id-less registration, not the identity rule. The id assigned at first
+ * registration is permanent (capture-vocabulary.spec.md §6).
+ */
+export function captureRecordId(filename, episodePath) {
+    return episodePath ? `capture:${episodePath}:${filename}` : `capture:${filename}`;
+}
+/** True when a capture record satisfies every provided filter. */
+export function matchesCaptureFilters(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.composition !== undefined && record.composition !== filters.composition) {
+        return false;
+    }
+    if (filters.kind !== undefined && record.kind !== filters.kind) {
+        return false;
+    }
+    if (filters.origin !== undefined && record.origin !== filters.origin) {
+        return false;
+    }
+    if (filters.device !== undefined && record.device !== filters.device) {
+        return false;
+    }
+    if (filters.filename !== undefined && record.filename !== filters.filename) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Filter a batch of capture rows, dropping anything that did not survive the
+ * read (a Postgres payload that fails to parse arrives here as null), then
+ * order newest registration first.
+ */
+export function filterAndOrderCaptures(records, filters = {}) {
+    return records
+        .filter((record) => record !== null &&
+        record !== undefined &&
+        typeof record === 'object' &&
+        matchesCaptureFilters(record, filters))
+        .sort((left, right) => Date.parse(right.registered_at) - Date.parse(left.registered_at));
+}
+/**
+ * Upsert merge: the incoming record wins wherever it speaks, the existing
+ * record fills wherever it stays silent. Provenance is observed, not demanded
+ * — so a later registration that learned less (no device, no sha256) must not
+ * erase what an earlier one knew. The first registration timestamp survives,
+ * matching the plan-perspective merge contract.
+ */
+export function mergeCaptureRecords(existing, incoming) {
+    const merged = { ...existing };
+    for (const [key, value] of Object.entries(incoming)) {
+        if (value !== undefined)
+            merged[key] = value;
+    }
+    merged.registered_at = existing.registered_at;
+    return merged;
+}

package/dist/index.d.ts

@@ -15,12 +15,14 @@
  * const node = await store.getNode('elder-1');
  * ```
  */
-export type { StorageProvider, RelationalNode, RelationalEdge, CeremonyLog, WeaveRecord, WeaveSyncState, InquiryWeaveFilters, PlanPerspectiveRecord, PlanPerspectiveEpisode, PlanPerspectiveFilters, CeremonialPhase, DiaryEntryType, DiaryEntryLocation, DiaryEntryMetadata, DiaryEntryRecord, DiaryEntryFilters, CeremonyEventKind, CeremonyEventParticipant, CeremonyEventRecord, CeremonyEventFilters, ProviderType, NodePatch, EdgePatch, } from './interface.js';
+export type { StorageProvider, RelationalNode, RelationalEdge, CeremonyLog, WeaveRecord, WeaveSyncState, InquiryWeaveFilters, PlanPerspectiveRecord, PlanPerspectiveEpisode, PlanPerspectiveFilters, CeremonialPhase, DiaryEntryType, DiaryEntryLocation, DiaryEntryMetadata, DiaryEntryRecord, DiaryEntryFilters, CeremonyEventKind, CeremonyEventParticipant, CeremonyEventRecord, CeremonyEventFilters, CaptureKind, CaptureOrigin, CaptureRecord, CaptureFilters, ProviderType, NodePatch, EdgePatch, } from './interface.js';
+export { CAPTURE_KINDS, CAPTURE_ORIGINS } from './interface.js';
 export { NodeNotFoundError, EdgeNotFoundError, NodeHasRelationsError, } from './interface.js';
 export { mergePlanPerspectiveRecords, unionPlanPerspectiveEpisodes, matchesPlanPerspectiveFilters, } from './plan-perspectives.js';
 export { matchesInquiryWeaveFilters, filterInquiryWeaves, } from './inquiry-weaves.js';
 export { matchesDiaryEntryFilters, filterAndOrderDiaryEntries, } from './diary-records.js';
 export { matchesCeremonyEventFilters } from './ceremony-events.js';
+export { captureRecordId, matchesCaptureFilters, filterAndOrderCaptures, mergeCaptureRecords, } from './capture-records.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');
  * ```
  */
+// Capture vocabulary as values — checkable from plain JavaScript
+export { CAPTURE_KINDS, CAPTURE_ORIGINS } from './interface.js';
 // Typed errors (thrown by update/delete operations)
 export { NodeNotFoundError, EdgeNotFoundError, NodeHasRelationsError, } from './interface.js';
 // Plan Perspective merge/filter semantics (shared across providers)
@@ -25,6 +27,8 @@ export { matchesInquiryWeaveFilters, filterInquiryWeaves, } from './inquiry-weav
 export { matchesDiaryEntryFilters, filterAndOrderDiaryEntries, } from './diary-records.js';
 // Ceremony Event filter semantics (shared across providers)
 export { matchesCeremonyEventFilters } from './ceremony-events.js';
+// Capture id/filter/merge semantics (shared across providers)
+export { captureRecordId, matchesCaptureFilters, filterAndOrderCaptures, mergeCaptureRecords, } from './capture-records.js';
 // Factory
 export { createProvider, detectProvider } from './factory.js';
 // Providers (for direct instantiation)

package/dist/interface.d.ts

@@ -218,6 +218,70 @@ export interface CeremonyEventFilters {
     direction?: DirectionName;
     repository?: string;
 }
+/**
+ * Kinds are published as a value, not only a type — a plain-JavaScript edge
+ * device cannot import a TypeScript union, so the array is the checkable
+ * contract and the type derives FROM it.
+ */
+export declare const CAPTURE_KINDS: readonly ["audio", "video", "midi", "other"];
+export type CaptureKind = (typeof CAPTURE_KINDS)[number];
+/**
+ * How a capture came to exist — the axis that says what must never be lost.
+ * `captured` is unrepeatable: a device, an instant, one chance. `derived` is
+ * regenerable from a source still held. `authored` was written rather than
+ * captured or generated. Flattening these loses the only property that
+ * distinguishes an irreplaceable take from a file rebuildable on demand.
+ */
+export declare const CAPTURE_ORIGINS: readonly ["captured", "derived", "authored"];
+export type CaptureOrigin = (typeof CAPTURE_ORIGINS)[number];
+export interface CaptureRecord extends Record<string, unknown> {
+    /**
+     * Stable upsert key. Convention: `capture:<episode_path>:<filename>` when
+     * episode-bound, `capture:<filename>` otherwise — see captureRecordId().
+     */
+    id: string;
+    /** The file's own name, as the capture service or author named it. */
+    filename: string;
+    kind: CaptureKind;
+    origin: CaptureOrigin;
+    /**
+     * Where the bytes live — a URI or path the capture service answers for.
+     * The registry stores this pointer and nothing behind it.
+     */
+    uri: string;
+    /** The device that made the capture, as it named itself. */
+    device?: string;
+    /** ISO 8601 instant the capture began. */
+    started_at?: string;
+    /** ISO 8601 instant the capture finished. */
+    stopped_at?: string;
+    /** Duration of the finished take, in seconds. */
+    duration_seconds?: number;
+    /** Size of the finished file in bytes — a count, never the bytes themselves. */
+    bytes?: number;
+    sha256?: string;
+    mimetype?: string;
+    /** Episode directory path relative to the chronicle root. */
+    episode_path?: string;
+    episode_number?: number;
+    /** Composition slug this capture belongs to, when known. */
+    composition?: string;
+    /** For derived captures: the filename or record id this one was made from. */
+    source_artifact?: string;
+    /** ISO 8601 registration timestamp; the first registration's stamp survives upserts. */
+    registered_at: string;
+    /** Free-form origin-of-registration, e.g. '@miadi/capture' or 'gmtermux'. */
+    source?: string;
+}
+export interface CaptureFilters {
+    episode_path?: string;
+    episode_number?: number;
+    composition?: string;
+    kind?: CaptureKind;
+    origin?: CaptureOrigin;
+    device?: string;
+    filename?: string;
+}
 export interface StorageProvider {
     readonly name: string;
     connect(): Promise<void>;
@@ -259,5 +323,8 @@ export interface StorageProvider {
     registerCeremonyEvent(record: CeremonyEventRecord): Promise<CeremonyEventRecord>;
     getCeremonyEvent(id: string): Promise<CeremonyEventRecord | null>;
     listCeremonyEvents(filters?: CeremonyEventFilters): Promise<CeremonyEventRecord[]>;
+    registerCapture(record: CaptureRecord): Promise<CaptureRecord>;
+    getCapture(id: string): Promise<CaptureRecord | null>;
+    listCaptures(filters?: CaptureFilters): Promise<CaptureRecord[]>;
 }
 export type ProviderType = 'jsonl' | 'neon' | 'redis' | 'auto';

package/dist/interface.js

@@ -41,3 +41,23 @@ export class NodeHasRelationsError extends Error {
         this.name = 'NodeHasRelationsError';
     }
 }
+// ── Capture Records ──
+// A registry of captures: records and URIs only, never bytes. The bytes stay
+// behind the capture service that made them (@miadi/capture and the gmtermux
+// edge); this registry makes captures queryable for chronicle surfaces.
+// Vocabulary aligns with @miadi/episodic-memory-schema's artifact axes and is
+// ruled by capture-vocabulary.spec.md (§8, the registry noun ruling).
+/**
+ * Kinds are published as a value, not only a type — a plain-JavaScript edge
+ * device cannot import a TypeScript union, so the array is the checkable
+ * contract and the type derives FROM it.
+ */
+export const CAPTURE_KINDS = ['audio', 'video', 'midi', 'other'];
+/**
+ * How a capture came to exist — the axis that says what must never be lost.
+ * `captured` is unrepeatable: a device, an instant, one chance. `derived` is
+ * regenerable from a source still held. `authored` was written rather than
+ * captured or generated. Flattening these loses the only property that
+ * distinguishes an irreplaceable take from a file rebuildable on demand.
+ */
+export const CAPTURE_ORIGINS = ['captured', 'derived', 'authored'];

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, PlanPerspectiveRecord, PlanPerspectiveFilters, DiaryEntryRecord, DiaryEntryFilters, CeremonyEventRecord, CeremonyEventFilters, NodePatch, EdgePatch } from './interface.js';
+import type { StorageProvider, RelationalNode, RelationalEdge, CeremonyLog, WeaveRecord, InquiryWeaveFilters, PlanPerspectiveRecord, PlanPerspectiveFilters, DiaryEntryRecord, DiaryEntryFilters, CeremonyEventRecord, CeremonyEventFilters, CaptureRecord, CaptureFilters, NodePatch, EdgePatch } from './interface.js';
 export declare class JsonlProvider implements StorageProvider {
     readonly name = "jsonl";
     readonly dataDir: string;
@@ -10,6 +10,7 @@ export declare class JsonlProvider implements StorageProvider {
     private readonly planPerspectivesFile;
     private readonly diaryEntriesFile;
     private readonly ceremonyEventsFile;
+    private readonly capturesFile;
     constructor(dataDir?: string);
     connect(): Promise<void>;
     disconnect(): Promise<void>;
@@ -46,6 +47,9 @@ export declare class JsonlProvider implements StorageProvider {
     registerCeremonyEvent(record: CeremonyEventRecord): Promise<CeremonyEventRecord>;
     getCeremonyEvent(id: string): Promise<CeremonyEventRecord | null>;
     listCeremonyEvents(filters?: CeremonyEventFilters): Promise<CeremonyEventRecord[]>;
+    registerCapture(record: CaptureRecord): Promise<CaptureRecord>;
+    getCapture(id: string): Promise<CaptureRecord | null>;
+    listCaptures(filters?: CaptureFilters): Promise<CaptureRecord[]>;
     private readNodes;
     private readEdges;
     private readCeremonies;
@@ -53,6 +57,7 @@ export declare class JsonlProvider implements StorageProvider {
     private readPlanPerspectives;
     private readDiaryEntries;
     private readCeremonyEvents;
+    private readCaptures;
     private upsertById;
     private upsertEdge;
     private parseNode;

package/dist/jsonl.js

@@ -6,6 +6,7 @@ import { mergePlanPerspectiveRecords, matchesPlanPerspectiveFilters, } from './p
 import { filterInquiryWeaves } from './inquiry-weaves.js';
 import { filterAndOrderDiaryEntries } from './diary-records.js';
 import { matchesCeremonyEventFilters } from './ceremony-events.js';
+import { mergeCaptureRecords, filterAndOrderCaptures, } from './capture-records.js';
 export class JsonlProvider {
     name = 'jsonl';
     dataDir;
@@ -16,6 +17,7 @@ export class JsonlProvider {
     planPerspectivesFile;
     diaryEntriesFile;
     ceremonyEventsFile;
+    capturesFile;
     constructor(dataDir) {
         this.dataDir = path.resolve(dataDir ?? resolveProjectDataDir());
         this.nodesFile = path.join(this.dataDir, 'nodes.jsonl');
@@ -25,6 +27,7 @@ export class JsonlProvider {
         this.planPerspectivesFile = path.join(this.dataDir, 'plan-perspectives.jsonl');
         this.diaryEntriesFile = path.join(this.dataDir, 'diary-entries.jsonl');
         this.ceremonyEventsFile = path.join(this.dataDir, 'ceremony-events.jsonl');
+        this.capturesFile = path.join(this.dataDir, 'captures.jsonl');
     }
     async connect() {
         ensureDirectory(this.dataDir);
@@ -254,6 +257,24 @@ export class JsonlProvider {
             .filter((record) => matchesCeremonyEventFilters(record, filters))
             .sort(sortByNewest('timestamp'));
     }
+    async registerCapture(record) {
+        let merged = record;
+        await withWriteLock(this.capturesFile, () => {
+            const records = readJsonl(this.capturesFile);
+            const existing = records.find((candidate) => candidate.id === record.id);
+            merged = existing ? mergeCaptureRecords(existing, record) : record;
+            const nextRecords = records.filter((candidate) => candidate.id !== record.id);
+            nextRecords.push(merged);
+            writeJsonl(this.capturesFile, nextRecords);
+        });
+        return merged;
+    }
+    async getCapture(id) {
+        return this.readCaptures().find((record) => record.id === id) ?? null;
+    }
+    async listCaptures(filters = {}) {
+        return filterAndOrderCaptures(this.readCaptures(), filters);
+    }
     readNodes() {
         return readJsonl(this.nodesFile);
     }
@@ -275,6 +296,9 @@ export class JsonlProvider {
     readCeremonyEvents() {
         return readJsonl(this.ceremonyEventsFile);
     }
+    readCaptures() {
+        return readJsonl(this.capturesFile);
+    }
     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, PlanPerspectiveRecord, PlanPerspectiveFilters, DiaryEntryRecord, DiaryEntryFilters, CeremonyEventRecord, CeremonyEventFilters, NodePatch, EdgePatch } from './interface.js';
+import type { StorageProvider, RelationalNode, RelationalEdge, CeremonyLog, WeaveRecord, InquiryWeaveFilters, PlanPerspectiveRecord, PlanPerspectiveFilters, DiaryEntryRecord, DiaryEntryFilters, CeremonyEventRecord, CeremonyEventFilters, CaptureRecord, CaptureFilters, NodePatch, EdgePatch } from './interface.js';
 export declare class NeonProvider implements StorageProvider {
     readonly name = "neon";
     private sql;
@@ -50,4 +50,8 @@ export declare class NeonProvider implements StorageProvider {
     getCeremonyEvent(id: string): Promise<CeremonyEventRecord | null>;
     listCeremonyEvents(filters?: CeremonyEventFilters): Promise<CeremonyEventRecord[]>;
     private ensureCeremonyEventsTable;
+    registerCapture(record: CaptureRecord): Promise<CaptureRecord>;
+    getCapture(id: string): Promise<CaptureRecord | null>;
+    listCaptures(filters?: CaptureFilters): Promise<CaptureRecord[]>;
+    private ensureCapturesTable;
 }

package/dist/neon.js

@@ -6,6 +6,7 @@ import { mergePlanPerspectiveRecords, matchesPlanPerspectiveFilters, } from './p
 import { filterInquiryWeaves } from './inquiry-weaves.js';
 import { filterAndOrderDiaryEntries } from './diary-records.js';
 import { matchesCeremonyEventFilters } from './ceremony-events.js';
+import { mergeCaptureRecords, filterAndOrderCaptures, } from './capture-records.js';
 export class NeonProvider {
     name = 'neon';
     sql = null;
@@ -19,6 +20,7 @@ export class NeonProvider {
         await this.ensurePlanPerspectivesTable();
         await this.ensureDiaryEntriesTable();
         await this.ensureCeremonyEventsTable();
+        await this.ensureCapturesTable();
     }
     async disconnect() {
         this.sql = null;
@@ -489,6 +491,70 @@ export class NeonProvider {
         await this.db `CREATE INDEX IF NOT EXISTS idx_ceremony_events_phase ON ceremony_events(phase)`;
         await this.db `CREATE INDEX IF NOT EXISTS idx_ceremony_events_repository ON ceremony_events(repository)`;
     }
+    // ── Capture Operations (records + URIs, never bytes) ──
+    async registerCapture(record) {
+        const existing = await this.getCapture(record.id);
+        const merged = existing ? mergeCaptureRecords(existing, record) : record;
+        await this.db `
+      INSERT INTO captures (id, payload, filename, kind, origin, episode_path, episode_number, composition, device, registered_at, updated_at)
+      VALUES (
+        ${merged.id},
+        ${JSON.stringify(merged)},
+        ${merged.filename},
+        ${merged.kind},
+        ${merged.origin},
+        ${merged.episode_path ?? null},
+        ${merged.episode_number ?? null},
+        ${merged.composition ?? null},
+        ${merged.device ?? null},
+        ${merged.registered_at},
+        NOW()
+      )
+      ON CONFLICT (id) DO UPDATE SET
+        payload = EXCLUDED.payload,
+        filename = EXCLUDED.filename,
+        kind = EXCLUDED.kind,
+        origin = EXCLUDED.origin,
+        episode_path = EXCLUDED.episode_path,
+        episode_number = EXCLUDED.episode_number,
+        composition = EXCLUDED.composition,
+        device = EXCLUDED.device,
+        registered_at = EXCLUDED.registered_at,
+        updated_at = NOW()
+    `;
+        return merged;
+    }
+    async getCapture(id) {
+        const rows = await this.db `SELECT payload FROM captures WHERE id = ${id}`;
+        if (rows.length === 0)
+            return null;
+        return parseJsonValue(rows[0].payload, null);
+    }
+    async listCaptures(filters = {}) {
+        const rows = await this.db `SELECT payload FROM captures ORDER BY updated_at DESC`;
+        return filterAndOrderCaptures(rows.map((row) => parseJsonValue(row.payload, null)), filters);
+    }
+    async ensureCapturesTable() {
+        await this.db `
+      CREATE TABLE IF NOT EXISTS captures (
+        id TEXT PRIMARY KEY,
+        payload JSONB NOT NULL,
+        filename TEXT NOT NULL,
+        kind TEXT NOT NULL,
+        origin TEXT NOT NULL,
+        episode_path TEXT,
+        episode_number INTEGER,
+        composition TEXT,
+        device TEXT,
+        registered_at TIMESTAMPTZ,
+        updated_at TIMESTAMPTZ DEFAULT NOW()
+      )
+    `;
+        await this.db `CREATE INDEX IF NOT EXISTS idx_captures_episode_path ON captures(episode_path)`;
+        await this.db `CREATE INDEX IF NOT EXISTS idx_captures_episode_number ON captures(episode_number)`;
+        await this.db `CREATE INDEX IF NOT EXISTS idx_captures_composition ON captures(composition)`;
+        await this.db `CREATE INDEX IF NOT EXISTS idx_captures_kind ON captures(kind)`;
+    }
 }
 function getConnectionString() {
     return process.env.DATABASE_URL ?? process.env.POSTGRES_URL ?? process.env.NEON_DATABASE_URL;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@medicine-wheel/storage-provider",
-  "version": "0.5.9",
+  "version": "0.6.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.5.9"
+    "@medicine-wheel/ontology-core": "^0.6.0"
   },
   "devDependencies": {
     "typescript": "^5.7.0"