@medicine-wheel/storage-provider 0.2.2

package/README.md

@@ -0,0 +1,18 @@
+# @medicine-wheel/storage-provider
+
+Abstract storage layer for Medicine Wheel data with JSONL and Neon backends, plus a future Redis path.
+
+## Install
+
+```bash
+npm install @medicine-wheel/storage-provider
+```
+
+## Usage
+
+```ts
+import { createProvider } from '@medicine-wheel/storage-provider';
+
+const store = await createProvider();
+```
+

package/dist/factory.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Storage Provider Factory
+ *
+ * Defaults to JSONL unless the backend is explicitly selected.
+ */
+import type { StorageProvider, ProviderType } from './interface.js';
+/**
+ * Create a storage provider instance.
+ *
+ * @param type - 'jsonl', 'neon', 'redis', or 'auto' (default)
+ * @returns Connected StorageProvider instance
+ */
+export declare function createProvider(type?: ProviderType): Promise<StorageProvider>;
+/**
+ * Detect which provider is available without connecting.
+ * Always returns a concrete non-null provider type; falls back to 'jsonl'.
+ */
+export declare function detectProvider(): ProviderType;

package/dist/factory.js

@@ -0,0 +1,64 @@
+/**
+ * Storage Provider Factory
+ *
+ * Defaults to JSONL unless the backend is explicitly selected.
+ */
+import { JsonlProvider } from './jsonl.js';
+import { NeonProvider } from './neon.js';
+function normalizeProviderType(value) {
+    switch (value.toLowerCase()) {
+        case 'jsonl':
+        case 'local':
+        case 'file':
+            return 'jsonl';
+        case 'neon':
+        case 'postgres':
+            return 'neon';
+        case 'redis':
+        case 'upstash':
+            return 'redis';
+        default:
+            return null;
+    }
+}
+function getConfiguredProvider() {
+    const raw = process.env.MW_STORAGE_PROVIDER;
+    if (!raw)
+        return null;
+    const normalized = normalizeProviderType(raw);
+    if (!normalized) {
+        // Truncate raw value to avoid leaking arbitrarily long env content into logs.
+        const displayValue = raw.length > 40 ? `${raw.slice(0, 40)}…` : raw;
+        throw new Error(`Unsupported MW_STORAGE_PROVIDER value: "${displayValue}". Expected jsonl, neon/postgres, or redis/upstash.`);
+    }
+    return normalized;
+}
+function instantiateProvider(type) {
+    switch (type) {
+        case 'jsonl':
+            return new JsonlProvider();
+        case 'neon':
+            return new NeonProvider();
+        case 'redis':
+            throw new Error('Redis provider not yet implemented. Use jsonl or neon.');
+    }
+}
+/**
+ * Create a storage provider instance.
+ *
+ * @param type - 'jsonl', 'neon', 'redis', or 'auto' (default)
+ * @returns Connected StorageProvider instance
+ */
+export async function createProvider(type = 'auto') {
+    const providerType = type === 'auto' ? getConfiguredProvider() ?? 'jsonl' : type;
+    const provider = instantiateProvider(providerType);
+    await provider.connect();
+    return provider;
+}
+/**
+ * Detect which provider is available without connecting.
+ * Always returns a concrete non-null provider type; falls back to 'jsonl'.
+ */
+export function detectProvider() {
+    return getConfiguredProvider() ?? 'jsonl';
+}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Medicine Wheel Storage Provider
+ *
+ * Abstract storage layer supporting multiple backends:
+ * - JSONL - Current default/local backend
+ * - Neon (Postgres) - First production backend path
+ * - Redis (Upstash) - Coming soon
+ *
+ * @example
+ * ```ts
+ * import { createProvider } from '@medicine-wheel/storage-provider';
+ *
+ * const store = await createProvider(); // Defaults to JSONL unless MW_STORAGE_PROVIDER explicitly selects another backend
+ * await store.createNode({ id: 'elder-1', type: 'human', ... });
+ * const node = await store.getNode('elder-1');
+ * ```
+ */
+export type { StorageProvider, RelationalNode, RelationalEdge, CeremonyLog, ProviderType, } from './interface.js';
+export { createProvider, detectProvider } from './factory.js';
+export { JsonlProvider } from './jsonl.js';
+export { NeonProvider } from './neon.js';

package/dist/index.js

@@ -0,0 +1,22 @@
+/**
+ * Medicine Wheel Storage Provider
+ *
+ * Abstract storage layer supporting multiple backends:
+ * - JSONL - Current default/local backend
+ * - Neon (Postgres) - First production backend path
+ * - Redis (Upstash) - Coming soon
+ *
+ * @example
+ * ```ts
+ * import { createProvider } from '@medicine-wheel/storage-provider';
+ *
+ * const store = await createProvider(); // Defaults to JSONL unless MW_STORAGE_PROVIDER explicitly selects another backend
+ * await store.createNode({ id: 'elder-1', type: 'human', ... });
+ * const node = await store.getNode('elder-1');
+ * ```
+ */
+// Factory
+export { createProvider, detectProvider } from './factory.js';
+// Providers (for direct instantiation)
+export { JsonlProvider } from './jsonl.js';
+export { NeonProvider } from './neon.js';

package/dist/interface.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Storage Provider Interface
+ *
+ * Abstract interface for Medicine Wheel data persistence.
+ * Implementations: JsonlProvider (local/default), NeonProvider (Postgres), RedisProvider (future)
+ */
+import type { DirectionName, NodeType, CeremonyType, RelationalNode as OntologyRelationalNode, RelationalEdge as OntologyRelationalEdge, CeremonyLog as OntologyCeremonyLog } from '@medicine-wheel/ontology-core';
+export interface RelationalNode extends OntologyRelationalNode {
+    description?: string;
+}
+export interface RelationalEdge extends Omit<OntologyRelationalEdge, 'id'> {
+    id?: string;
+    last_ceremony?: string;
+}
+export type CeremonyLog = OntologyCeremonyLog;
+export interface StorageProvider {
+    readonly name: string;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    createNode(node: RelationalNode): Promise<void>;
+    getNode(id: string): Promise<RelationalNode | null>;
+    getNodesByType(type: NodeType): Promise<RelationalNode[]>;
+    getNodesByDirection(direction: DirectionName): Promise<RelationalNode[]>;
+    getAllNodes(limit?: number): Promise<RelationalNode[]>;
+    createEdge(edge: RelationalEdge): Promise<void>;
+    getEdge(fromId: string, toId: string): Promise<RelationalEdge | null>;
+    getRelatedNodes(nodeId: string, direction?: 'from' | 'to' | 'both'): Promise<string[]>;
+    updateEdgeCeremony(fromId: string, toId: string, ceremonyId: string): Promise<void>;
+    logCeremony(ceremony: CeremonyLog): Promise<void>;
+    getCeremony(id: string): Promise<CeremonyLog | null>;
+    getCeremoniesTimeline(limit?: number): Promise<CeremonyLog[]>;
+    getCeremoniesByDirection(direction: DirectionName): Promise<CeremonyLog[]>;
+    getCeremoniesByType(type: CeremonyType): Promise<CeremonyLog[]>;
+    getAllCeremonies(limit?: number): Promise<CeremonyLog[]>;
+}
+export type ProviderType = 'jsonl' | 'neon' | 'redis' | 'auto';

package/dist/interface.js

@@ -0,0 +1,7 @@
+/**
+ * Storage Provider Interface
+ *
+ * Abstract interface for Medicine Wheel data persistence.
+ * Implementations: JsonlProvider (local/default), NeonProvider (Postgres), RedisProvider (future)
+ */
+export {};

package/dist/jsonl.d.ts

@@ -0,0 +1,35 @@
+import type { DirectionName, NodeType, CeremonyType } from '@medicine-wheel/ontology-core';
+import type { StorageProvider, RelationalNode, RelationalEdge, CeremonyLog } from './interface.js';
+export declare class JsonlProvider implements StorageProvider {
+    readonly name = "jsonl";
+    readonly dataDir: string;
+    private readonly nodesFile;
+    private readonly edgesFile;
+    private readonly ceremoniesFile;
+    constructor(dataDir?: string);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    createNode(node: RelationalNode): Promise<void>;
+    getNode(id: string): Promise<RelationalNode | null>;
+    getNodesByType(type: NodeType): Promise<RelationalNode[]>;
+    getNodesByDirection(direction: DirectionName): Promise<RelationalNode[]>;
+    getAllNodes(limit?: number): Promise<RelationalNode[]>;
+    createEdge(edge: RelationalEdge): Promise<void>;
+    getEdge(fromId: string, toId: string): Promise<RelationalEdge | null>;
+    getRelatedNodes(nodeId: string, direction?: 'from' | 'to' | 'both'): Promise<string[]>;
+    updateEdgeCeremony(fromId: string, toId: string, ceremonyId: string): Promise<void>;
+    logCeremony(ceremony: CeremonyLog): Promise<void>;
+    getCeremony(id: string): Promise<CeremonyLog | null>;
+    getCeremoniesTimeline(limit?: number): Promise<CeremonyLog[]>;
+    getCeremoniesByDirection(direction: DirectionName): Promise<CeremonyLog[]>;
+    getCeremoniesByType(type: CeremonyType): Promise<CeremonyLog[]>;
+    getAllCeremonies(limit?: number): Promise<CeremonyLog[]>;
+    private readNodes;
+    private readEdges;
+    private readCeremonies;
+    private upsertById;
+    private upsertEdge;
+    private parseNode;
+    private parseEdge;
+    private parseCeremony;
+}

package/dist/jsonl.js

@@ -0,0 +1,349 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { randomUUID } from 'crypto';
+export class JsonlProvider {
+    name = 'jsonl';
+    dataDir;
+    nodesFile;
+    edgesFile;
+    ceremoniesFile;
+    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');
+    }
+    async connect() {
+        ensureDirectory(this.dataDir);
+    }
+    async disconnect() {
+        // File-backed provider has no long-lived connection to tear down.
+    }
+    async createNode(node) {
+        await this.upsertById(this.nodesFile, node);
+    }
+    async getNode(id) {
+        const node = this.readNodes().find((candidate) => candidate.id === id);
+        return node ? this.parseNode(node) : null;
+    }
+    async getNodesByType(type) {
+        return this.readNodes()
+            .filter((node) => node.type === type)
+            .sort(sortByNewest('created_at'))
+            .map((node) => this.parseNode(node));
+    }
+    async getNodesByDirection(direction) {
+        return this.readNodes()
+            .filter((node) => node.direction === direction)
+            .sort(sortByNewest('created_at'))
+            .map((node) => this.parseNode(node));
+    }
+    async getAllNodes(limit = 100) {
+        return this.readNodes()
+            .sort(sortByNewest('created_at'))
+            .slice(0, limit)
+            .map((node) => this.parseNode(node));
+    }
+    async createEdge(edge) {
+        await this.upsertEdge({
+            ...edge,
+            ceremony_id: edge.last_ceremony,
+        });
+    }
+    async getEdge(fromId, toId) {
+        const edge = this.readEdges().find((candidate) => candidate.from_id === fromId && candidate.to_id === toId);
+        return edge ? this.parseEdge(edge) : null;
+    }
+    async getRelatedNodes(nodeId, direction = 'both') {
+        const related = new Set();
+        for (const edge of this.readEdges()) {
+            if ((direction === 'from' || direction === 'both') && edge.from_id === nodeId) {
+                related.add(edge.to_id);
+            }
+            if ((direction === 'to' || direction === 'both') && edge.to_id === nodeId) {
+                related.add(edge.from_id);
+            }
+        }
+        return Array.from(related);
+    }
+    async updateEdgeCeremony(fromId, toId, ceremonyId) {
+        await withWriteLock(this.edgesFile, () => {
+            const nextEdges = this.readEdges().map((edge) => {
+                if (edge.from_id !== fromId || edge.to_id !== toId)
+                    return edge;
+                return {
+                    ...edge,
+                    ceremony_honored: true,
+                    ceremony_id: ceremonyId,
+                    last_ceremony: ceremonyId,
+                };
+            });
+            writeJsonl(this.edgesFile, nextEdges);
+        });
+    }
+    async logCeremony(ceremony) {
+        await this.upsertById(this.ceremoniesFile, ceremony);
+    }
+    async getCeremony(id) {
+        const ceremony = this.readCeremonies().find((candidate) => candidate.id === id);
+        return ceremony ? this.parseCeremony(ceremony) : null;
+    }
+    async getCeremoniesTimeline(limit = 20) {
+        return this.readCeremonies()
+            .sort(sortByNewest('timestamp'))
+            .slice(0, limit)
+            .map((ceremony) => this.parseCeremony(ceremony));
+    }
+    async getCeremoniesByDirection(direction) {
+        return this.readCeremonies()
+            .filter((ceremony) => ceremony.direction === direction)
+            .sort(sortByNewest('timestamp'))
+            .map((ceremony) => this.parseCeremony(ceremony));
+    }
+    async getCeremoniesByType(type) {
+        return this.readCeremonies()
+            .filter((ceremony) => ceremony.type === type)
+            .sort(sortByNewest('timestamp'))
+            .map((ceremony) => this.parseCeremony(ceremony));
+    }
+    async getAllCeremonies(limit = 100) {
+        return this.readCeremonies()
+            .sort(sortByNewest('timestamp'))
+            .slice(0, limit)
+            .map((ceremony) => this.parseCeremony(ceremony));
+    }
+    readNodes() {
+        return readJsonl(this.nodesFile);
+    }
+    readEdges() {
+        return readJsonl(this.edgesFile);
+    }
+    readCeremonies() {
+        return readJsonl(this.ceremoniesFile);
+    }
+    async upsertById(filePath, item) {
+        await withWriteLock(filePath, () => {
+            const nextRecords = readJsonl(filePath).filter((candidate) => candidate.id !== item.id);
+            nextRecords.push(item);
+            writeJsonl(filePath, nextRecords);
+        });
+    }
+    async upsertEdge(edge) {
+        await withWriteLock(this.edgesFile, () => {
+            const nextEdges = this.readEdges().filter((candidate) => edgeKey(candidate) !== edgeKey(edge));
+            nextEdges.push(edge);
+            writeJsonl(this.edgesFile, nextEdges);
+        });
+    }
+    parseNode(node) {
+        return {
+            id: node.id,
+            type: node.type,
+            name: node.name,
+            description: node.description ?? '',
+            direction: node.direction,
+            metadata: node.metadata ?? {},
+            created_at: node.created_at,
+            updated_at: node.updated_at,
+        };
+    }
+    parseEdge(edge) {
+        return {
+            from_id: edge.from_id,
+            to_id: edge.to_id,
+            relationship_type: edge.relationship_type,
+            strength: Number(edge.strength),
+            ceremony_honored: Boolean(edge.ceremony_honored),
+            last_ceremony: edge.last_ceremony ?? edge.ceremony_id,
+            obligations: Array.isArray(edge.obligations) ? edge.obligations : [],
+            created_at: edge.created_at,
+        };
+    }
+    parseCeremony(ceremony) {
+        return {
+            id: ceremony.id,
+            type: ceremony.type,
+            direction: ceremony.direction,
+            participants: Array.isArray(ceremony.participants) ? ceremony.participants : [],
+            medicines_used: Array.isArray(ceremony.medicines_used) ? ceremony.medicines_used : [],
+            intentions: Array.isArray(ceremony.intentions) ? ceremony.intentions : [],
+            timestamp: ceremony.timestamp,
+            research_context: ceremony.research_context,
+        };
+    }
+}
+function ensureDirectory(dirPath) {
+    if (!fs.existsSync(dirPath)) {
+        fs.mkdirSync(dirPath, { recursive: true });
+    }
+}
+function readJsonl(filePath) {
+    if (!fs.existsSync(filePath))
+        return [];
+    const records = [];
+    const content = fs.readFileSync(filePath, 'utf-8');
+    for (const line of content.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            records.push(JSON.parse(trimmed));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.warn(`[storage-provider/jsonl] Skipping malformed line in ${filePath}: ${message}`);
+        }
+    }
+    return records;
+}
+function writeJsonl(filePath, records) {
+    ensureDirectory(path.dirname(filePath));
+    const tmpPath = `${filePath}.tmp.${process.pid}`;
+    const content = records.map((record) => JSON.stringify(record)).join('\n');
+    fs.writeFileSync(tmpPath, content.length > 0 ? `${content}\n` : '', 'utf-8');
+    fs.renameSync(tmpPath, filePath);
+}
+async function withWriteLock(filePath, fn) {
+    const lockPath = `${filePath}.lock`;
+    const ownerToken = await acquireWriteLock(lockPath);
+    try {
+        return await fn();
+    }
+    finally {
+        releaseWriteLock(lockPath, ownerToken);
+    }
+}
+function resolveProjectDataDir(currentDir) {
+    if (process.env.MW_DATA_DIR)
+        return process.env.MW_DATA_DIR;
+    const cwd = currentDir ?? process.cwd();
+    if (cwd.endsWith('/mcp') || cwd.endsWith('\\mcp')) {
+        return path.join(path.dirname(cwd), '.mw', 'store');
+    }
+    let dir = cwd;
+    for (let depth = 0; depth < 5; depth++) {
+        const packageJsonPath = path.join(dir, 'package.json');
+        if (fs.existsSync(packageJsonPath)) {
+            try {
+                const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+                if (pkg.name === 'medicine-wheel') {
+                    return path.join(dir, '.mw', 'store');
+                }
+            }
+            catch {
+                // Keep walking upward.
+            }
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return path.join(cwd, '.mw', 'store');
+}
+function edgeKey(edge) {
+    // JSON-array encoding avoids false collisions when IDs contain the delimiter.
+    return JSON.stringify([edge.from_id, edge.to_id]);
+}
+function sortByNewest(field) {
+    return (left, right) => Date.parse(right[field]) - Date.parse(left[field]);
+}
+function isProcessAlive(pid) {
+    try {
+        // Signal 0 checks process existence without sending a real signal.
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isLockStale(lockPath) {
+    try {
+        const content = fs.readFileSync(lockPath, 'utf-8').trim();
+        const parsed = JSON.parse(content);
+        const pid = typeof parsed.pid === 'number' ? parsed.pid : null;
+        const createdAt = typeof parsed.created_at === 'string' ? Date.parse(parsed.created_at) : NaN;
+        // A lock held by a live process is never stale.
+        if (pid !== null && isProcessAlive(pid)) {
+            return false;
+        }
+        // PID is dead or unreadable — treat as stale after a 30-second grace period.
+        const lockAgeMs = isNaN(createdAt) ? Infinity : Date.now() - createdAt;
+        return lockAgeMs > 30_000;
+    }
+    catch {
+        return false;
+    }
+}
+async function acquireWriteLock(lockPath) {
+    const ownerToken = `${process.pid}:${Date.now()}:${randomUUID()}`;
+    const payload = JSON.stringify({
+        token: ownerToken,
+        pid: process.pid,
+        created_at: new Date().toISOString(),
+    });
+    for (let attempt = 0; attempt < 20; attempt++) {
+        let fd;
+        try {
+            fd = fs.openSync(lockPath, 'wx');
+            fs.writeFileSync(fd, payload, 'utf-8');
+            return ownerToken;
+        }
+        catch (error) {
+            if (error?.code !== 'EEXIST') {
+                throw error;
+            }
+            // Only remove the lock file when we are certain its owner is gone.
+            if (isLockStale(lockPath)) {
+                try {
+                    fs.unlinkSync(lockPath);
+                    console.warn(`[storage-provider/jsonl] Removed stale lock: ${lockPath}`);
+                }
+                catch {
+                    // Another process may have removed it first — that is fine.
+                }
+            }
+            else {
+                await sleep(Math.min(25 * (attempt + 1), 250));
+            }
+        }
+        finally {
+            if (fd !== undefined) {
+                fs.closeSync(fd);
+            }
+        }
+    }
+    throw new Error(`[storage-provider/jsonl] Failed to acquire write lock: ${lockPath}`);
+}
+function releaseWriteLock(lockPath, ownerToken) {
+    try {
+        const currentOwner = readLockOwner(lockPath);
+        if (currentOwner !== ownerToken) {
+            return;
+        }
+        fs.unlinkSync(lockPath);
+    }
+    catch (error) {
+        if (error?.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+}
+function readLockOwner(lockPath) {
+    const content = fs.readFileSync(lockPath, 'utf-8').trim();
+    if (!content)
+        return null;
+    try {
+        const parsed = JSON.parse(content);
+        return typeof parsed.token === 'string' ? parsed.token : null;
+    }
+    catch {
+        return null;
+    }
+}
+function sleep(delayMs) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, delayMs);
+    });
+}

package/dist/neon.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Neon (Postgres) Storage Provider
+ */
+import type { DirectionName, NodeType, CeremonyType } from '@medicine-wheel/ontology-core';
+import type { StorageProvider, RelationalNode, RelationalEdge, CeremonyLog } from './interface.js';
+export declare class NeonProvider implements StorageProvider {
+    readonly name = "neon";
+    private sql;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    private get db();
+    createNode(node: RelationalNode): Promise<void>;
+    getNode(id: string): Promise<RelationalNode | null>;
+    getNodesByType(type: NodeType): Promise<RelationalNode[]>;
+    getNodesByDirection(direction: DirectionName): Promise<RelationalNode[]>;
+    getAllNodes(limit?: number): Promise<RelationalNode[]>;
+    private parseNode;
+    createEdge(edge: RelationalEdge): Promise<void>;
+    getEdge(fromId: string, toId: string): Promise<RelationalEdge | null>;
+    getRelatedNodes(nodeId: string, direction?: 'from' | 'to' | 'both'): Promise<string[]>;
+    updateEdgeCeremony(fromId: string, toId: string, ceremonyId: string): Promise<void>;
+    private parseEdge;
+    logCeremony(ceremony: CeremonyLog): Promise<void>;
+    getCeremony(id: string): Promise<CeremonyLog | null>;
+    getCeremoniesTimeline(limit?: number): Promise<CeremonyLog[]>;
+    getCeremoniesByDirection(direction: DirectionName): Promise<CeremonyLog[]>;
+    getCeremoniesByType(type: CeremonyType): Promise<CeremonyLog[]>;
+    getAllCeremonies(limit?: number): Promise<CeremonyLog[]>;
+    private parseCeremony;
+}

package/dist/neon.js

@@ -0,0 +1,196 @@
+/**
+ * Neon (Postgres) Storage Provider
+ */
+export class NeonProvider {
+    name = 'neon';
+    sql = null;
+    async connect() {
+        const url = getConnectionString();
+        if (!url)
+            throw new Error('DATABASE_URL, POSTGRES_URL, or NEON_DATABASE_URL must be set');
+        const { neon } = await import('@neondatabase/serverless');
+        this.sql = neon(url);
+    }
+    async disconnect() {
+        this.sql = null;
+    }
+    get db() {
+        if (!this.sql)
+            throw new Error('NeonProvider not connected');
+        return this.sql;
+    }
+    // ── Node Operations ──
+    async createNode(node) {
+        await this.db `
+      INSERT INTO nodes (id, type, name, description, direction, metadata, created_at, updated_at)
+      VALUES (${node.id}, ${node.type}, ${node.name}, ${node.description}, 
+              ${node.direction || null}, ${JSON.stringify(node.metadata)}, 
+              ${node.created_at}, ${node.updated_at})
+      ON CONFLICT (id) DO UPDATE SET
+        type = EXCLUDED.type,
+        name = EXCLUDED.name,
+        description = EXCLUDED.description,
+        direction = EXCLUDED.direction,
+        metadata = EXCLUDED.metadata,
+        updated_at = EXCLUDED.updated_at
+    `;
+    }
+    async getNode(id) {
+        const rows = await this.db `SELECT * FROM nodes WHERE id = ${id}`;
+        if (rows.length === 0)
+            return null;
+        return this.parseNode(rows[0]);
+    }
+    async getNodesByType(type) {
+        const rows = await this.db `SELECT * FROM nodes WHERE type = ${type} ORDER BY created_at DESC`;
+        return rows.map((row) => this.parseNode(row));
+    }
+    async getNodesByDirection(direction) {
+        const rows = await this.db `SELECT * FROM nodes WHERE direction = ${direction} ORDER BY created_at DESC`;
+        return rows.map((row) => this.parseNode(row));
+    }
+    async getAllNodes(limit = 100) {
+        const rows = await this.db `SELECT * FROM nodes ORDER BY created_at DESC LIMIT ${limit}`;
+        return rows.map((row) => this.parseNode(row));
+    }
+    parseNode(row) {
+        return {
+            id: row.id,
+            type: row.type,
+            name: row.name,
+            description: row.description || '',
+            direction: row.direction || undefined,
+            metadata: parseJsonValue(row.metadata, {}),
+            created_at: toIsoString(row.created_at),
+            updated_at: toIsoString(row.updated_at),
+        };
+    }
+    // ── Edge Operations ──
+    async createEdge(edge) {
+        await this.db `
+      INSERT INTO edges (from_id, to_id, relationship_type, strength, ceremony_honored, last_ceremony, obligations, created_at)
+      VALUES (${edge.from_id}, ${edge.to_id}, ${edge.relationship_type}, ${edge.strength},
+              ${edge.ceremony_honored}, ${edge.last_ceremony || null}, ${JSON.stringify(edge.obligations)}, ${edge.created_at})
+      ON CONFLICT (from_id, to_id) DO UPDATE SET
+        relationship_type = EXCLUDED.relationship_type,
+        strength = EXCLUDED.strength,
+        ceremony_honored = EXCLUDED.ceremony_honored,
+        last_ceremony = EXCLUDED.last_ceremony,
+        obligations = EXCLUDED.obligations
+    `;
+    }
+    async getEdge(fromId, toId) {
+        const rows = await this.db `SELECT * FROM edges WHERE from_id = ${fromId} AND to_id = ${toId}`;
+        if (rows.length === 0)
+            return null;
+        return this.parseEdge(rows[0]);
+    }
+    async getRelatedNodes(nodeId, direction = 'both') {
+        let rows;
+        if (direction === 'from') {
+            rows = await this.db `SELECT to_id as id FROM edges WHERE from_id = ${nodeId}`;
+        }
+        else if (direction === 'to') {
+            rows = await this.db `SELECT from_id as id FROM edges WHERE to_id = ${nodeId}`;
+        }
+        else {
+            rows = await this.db `
+        SELECT to_id as id FROM edges WHERE from_id = ${nodeId}
+        UNION
+        SELECT from_id as id FROM edges WHERE to_id = ${nodeId}
+      `;
+        }
+        return rows.map(r => r.id);
+    }
+    async updateEdgeCeremony(fromId, toId, ceremonyId) {
+        await this.db `
+      UPDATE edges SET ceremony_honored = true, last_ceremony = ${ceremonyId}
+      WHERE from_id = ${fromId} AND to_id = ${toId}
+    `;
+    }
+    parseEdge(row) {
+        return {
+            from_id: row.from_id,
+            to_id: row.to_id,
+            relationship_type: row.relationship_type,
+            strength: Number(row.strength),
+            ceremony_honored: row.ceremony_honored,
+            last_ceremony: row.last_ceremony || undefined,
+            obligations: parseJsonValue(row.obligations, []),
+            created_at: toIsoString(row.created_at),
+        };
+    }
+    // ── Ceremony Operations ──
+    async logCeremony(ceremony) {
+        await this.db `
+      INSERT INTO ceremonies (id, type, direction, participants, medicines_used, intentions, timestamp, research_context)
+      VALUES (${ceremony.id}, ${ceremony.type}, ${ceremony.direction},
+              ${JSON.stringify(ceremony.participants)}, ${JSON.stringify(ceremony.medicines_used)},
+              ${JSON.stringify(ceremony.intentions)}, ${ceremony.timestamp}, ${ceremony.research_context || null})
+      ON CONFLICT (id) DO UPDATE SET
+        type = EXCLUDED.type,
+        direction = EXCLUDED.direction,
+        participants = EXCLUDED.participants,
+        medicines_used = EXCLUDED.medicines_used,
+        intentions = EXCLUDED.intentions,
+        timestamp = EXCLUDED.timestamp,
+        research_context = EXCLUDED.research_context
+    `;
+    }
+    async getCeremony(id) {
+        const rows = await this.db `SELECT * FROM ceremonies WHERE id = ${id}`;
+        if (rows.length === 0)
+            return null;
+        return this.parseCeremony(rows[0]);
+    }
+    async getCeremoniesTimeline(limit = 20) {
+        const rows = await this.db `SELECT * FROM ceremonies ORDER BY timestamp DESC LIMIT ${limit}`;
+        return rows.map((row) => this.parseCeremony(row));
+    }
+    async getCeremoniesByDirection(direction) {
+        const rows = await this.db `SELECT * FROM ceremonies WHERE direction = ${direction} ORDER BY timestamp DESC`;
+        return rows.map((row) => this.parseCeremony(row));
+    }
+    async getCeremoniesByType(type) {
+        const rows = await this.db `SELECT * FROM ceremonies WHERE type = ${type} ORDER BY timestamp DESC`;
+        return rows.map((row) => this.parseCeremony(row));
+    }
+    async getAllCeremonies(limit = 100) {
+        return this.getCeremoniesTimeline(limit);
+    }
+    parseCeremony(row) {
+        return {
+            id: row.id,
+            type: row.type,
+            direction: row.direction,
+            participants: parseJsonValue(row.participants, []),
+            medicines_used: parseJsonValue(row.medicines_used, []),
+            intentions: parseJsonValue(row.intentions, []),
+            timestamp: toIsoString(row.timestamp),
+            research_context: row.research_context || undefined,
+        };
+    }
+}
+function getConnectionString() {
+    return process.env.DATABASE_URL ?? process.env.POSTGRES_URL ?? process.env.NEON_DATABASE_URL;
+}
+function toIsoString(value) {
+    if (value instanceof Date)
+        return value.toISOString();
+    if (typeof value === 'string')
+        return value;
+    return new Date(String(value)).toISOString();
+}
+function parseJsonValue(value, fallback) {
+    if (value === undefined || value === null)
+        return fallback;
+    if (typeof value === 'string') {
+        try {
+            return JSON.parse(value);
+        }
+        catch {
+            return fallback;
+        }
+    }
+    return value;
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@medicine-wheel/storage-provider",
+  "version": "0.2.2",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "dependencies": {
+    "@neondatabase/serverless": "^0.10.0",
+    "@upstash/redis": "^1.34.3",
+    "@medicine-wheel/ontology-core": "^0.2.2"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  }
+}