@contractspec/module.context-storage 0.1.2

package/dist/node/index.js

@@ -0,0 +1,404 @@
+// src/entities/index.ts
+import { defineEntity, field, index } from "@contractspec/lib.schema";
+var ContextPackEntity = defineEntity({
+  name: "ContextPack",
+  description: "Context pack definition for snapshots.",
+  schema: "lssm_context",
+  map: "context_pack",
+  fields: {
+    id: field.id({ description: "Context pack record ID" }),
+    packKey: field.string({ description: "Context pack key" }),
+    version: field.string({ description: "Context pack version" }),
+    title: field.string({ description: "Pack title" }),
+    description: field.string({ isOptional: true }),
+    owners: field.json({ isOptional: true }),
+    tags: field.json({ isOptional: true }),
+    sources: field.json({ isOptional: true }),
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt()
+  },
+  indexes: [index.unique(["packKey", "version"])]
+});
+var ContextSnapshotEntity = defineEntity({
+  name: "ContextSnapshot",
+  description: "Immutable snapshot created from a context pack.",
+  schema: "lssm_context",
+  map: "context_snapshot",
+  fields: {
+    id: field.id({ description: "Snapshot ID" }),
+    packKey: field.string({ description: "Context pack key" }),
+    packVersion: field.string({ description: "Context pack version" }),
+    hash: field.string({ description: "Snapshot hash" }),
+    itemCount: field.int({ isOptional: true }),
+    createdBy: field.string({ isOptional: true }),
+    metadata: field.json({ isOptional: true }),
+    createdAt: field.createdAt()
+  },
+  indexes: [index.on(["packKey", "packVersion"]), index.on(["createdAt"])]
+});
+var ContextSnapshotItemEntity = defineEntity({
+  name: "ContextSnapshotItem",
+  description: "Item belonging to a context snapshot.",
+  schema: "lssm_context",
+  map: "context_snapshot_item",
+  fields: {
+    id: field.id({ description: "Snapshot item ID" }),
+    snapshotId: field.string({ description: "Context snapshot ID" }),
+    kind: field.string({ description: "Item kind" }),
+    sourceKey: field.string({ description: "Source key" }),
+    sourceVersion: field.string({ isOptional: true }),
+    content: field.json({ description: "Structured content" }),
+    textContent: field.string({ isOptional: true }),
+    metadata: field.json({ isOptional: true }),
+    createdAt: field.createdAt()
+  },
+  indexes: [index.on(["snapshotId"]), index.on(["kind"])]
+});
+var contextStorageEntities = [
+  ContextPackEntity,
+  ContextSnapshotEntity,
+  ContextSnapshotItemEntity
+];
+var contextStorageSchemaContribution = {
+  moduleId: "@contractspec/module.context-storage",
+  entities: contextStorageEntities
+};
+
+// src/storage/index.ts
+class PostgresContextStorage {
+  database;
+  schema;
+  createTablesIfMissing;
+  ensured = false;
+  constructor(options) {
+    this.database = options.database;
+    this.schema = options.schema ?? "lssm_context";
+    this.createTablesIfMissing = options.createTablesIfMissing ?? true;
+  }
+  async upsertPack(record) {
+    await this.ensureTables();
+    const packId = `${record.packKey}:${record.version}`;
+    await this.database.execute(`INSERT INTO ${this.table("context_pack")}
+        (id, pack_key, version, title, description, owners, tags, sources, created_at, updated_at)
+       VALUES ($1, $2, $3, $4, $5, $6::jsonb, $7::jsonb, $8::jsonb, $9, $10)
+       ON CONFLICT (pack_key, version)
+       DO UPDATE SET
+         title = EXCLUDED.title,
+         description = EXCLUDED.description,
+         owners = EXCLUDED.owners,
+         tags = EXCLUDED.tags,
+         sources = EXCLUDED.sources,
+         updated_at = EXCLUDED.updated_at;`, [
+      packId,
+      record.packKey,
+      record.version,
+      record.title,
+      record.description ?? null,
+      record.owners ? JSON.stringify(record.owners) : null,
+      record.tags ? JSON.stringify(record.tags) : null,
+      record.sources ? JSON.stringify(record.sources) : null,
+      record.createdAt,
+      record.updatedAt ?? record.createdAt
+    ]);
+    return record;
+  }
+  async getPack(packKey, version) {
+    await this.ensureTables();
+    const rows = await this.database.query(`SELECT * FROM ${this.table("context_pack")}
+       WHERE pack_key = $1
+       ${version ? "AND version = $2" : ""}
+       ORDER BY version DESC
+       LIMIT 1;`, version ? [packKey, version] : [packKey]);
+    return rows.rows[0] ? this.mapPack(rows.rows[0]) : null;
+  }
+  async listPacks(query = {}) {
+    await this.ensureTables();
+    const { query: q, tag, owner, limit = 50, offset = 0 } = query;
+    const filters = [];
+    const params = [];
+    params.push(limit, offset);
+    if (q) {
+      params.push(`%${q}%`);
+      filters.push(`(pack_key ILIKE $${params.length} OR title ILIKE $${params.length})`);
+    }
+    if (tag) {
+      params.push(tag);
+      filters.push(`tags @> to_jsonb(ARRAY[$${params.length}]::text[])`);
+    }
+    if (owner) {
+      params.push(owner);
+      filters.push(`owners @> to_jsonb(ARRAY[$${params.length}]::text[])`);
+    }
+    const where = filters.length ? `WHERE ${filters.join(" AND ")}` : "";
+    const rows = await this.database.query(`SELECT * FROM ${this.table("context_pack")}
+       ${where}
+       ORDER BY updated_at DESC
+       LIMIT $1 OFFSET $2;`, params);
+    const packs = rows.rows.map((row) => this.mapPack(row));
+    const total = rows.rowCount;
+    return {
+      packs,
+      total,
+      nextOffset: offset + packs.length < total ? offset + packs.length : undefined
+    };
+  }
+  async createSnapshot(record) {
+    await this.ensureTables();
+    await this.database.execute(`INSERT INTO ${this.table("context_snapshot")}
+        (id, pack_key, pack_version, hash, item_count, created_by, metadata, created_at)
+       VALUES ($1, $2, $3, $4, $5, $6, $7::jsonb, $8);`, [
+      record.snapshotId,
+      record.packKey,
+      record.packVersion,
+      record.hash,
+      record.itemCount ?? null,
+      record.createdBy ?? null,
+      record.metadata ? JSON.stringify(record.metadata) : null,
+      record.createdAt
+    ]);
+    return record;
+  }
+  async getSnapshot(snapshotId) {
+    await this.ensureTables();
+    const rows = await this.database.query(`SELECT * FROM ${this.table("context_snapshot")} WHERE id = $1;`, [snapshotId]);
+    return rows.rows[0] ? this.mapSnapshot(rows.rows[0]) : null;
+  }
+  async listSnapshots(query = {}) {
+    await this.ensureTables();
+    const { packKey, snapshotId, limit = 50, offset = 0 } = query;
+    const filters = [];
+    const params = [limit, offset];
+    if (packKey) {
+      params.push(packKey);
+      filters.push(`pack_key = $${params.length}`);
+    }
+    if (snapshotId) {
+      params.push(snapshotId);
+      filters.push(`id = $${params.length}`);
+    }
+    const where = filters.length ? `WHERE ${filters.join(" AND ")}` : "";
+    const rows = await this.database.query(`SELECT * FROM ${this.table("context_snapshot")}
+       ${where}
+       ORDER BY created_at DESC
+       LIMIT $1 OFFSET $2;`, params);
+    const snapshots = rows.rows.map((row) => this.mapSnapshot(row));
+    const total = rows.rowCount;
+    return {
+      snapshots,
+      total,
+      nextOffset: offset + snapshots.length < total ? offset + snapshots.length : undefined
+    };
+  }
+  async addSnapshotItems(snapshotId, items) {
+    await this.ensureTables();
+    const created = [];
+    for (const item of items) {
+      const createdAt = item.createdAt ?? new Date().toISOString();
+      await this.database.execute(`INSERT INTO ${this.table("context_snapshot_item")}
+          (id, snapshot_id, kind, source_key, source_version, content, text_content, metadata, created_at)
+         VALUES ($1, $2, $3, $4, $5, $6::jsonb, $7, $8::jsonb, $9);`, [
+        item.itemId,
+        snapshotId,
+        item.kind,
+        item.sourceKey,
+        item.sourceVersion ?? null,
+        JSON.stringify(item.content),
+        item.textContent ?? null,
+        item.metadata ? JSON.stringify(item.metadata) : null,
+        createdAt
+      ]);
+      created.push({ ...item, snapshotId, createdAt });
+    }
+    return created;
+  }
+  async listSnapshotItems(snapshotId, options = {}) {
+    await this.ensureTables();
+    const { limit = 100, offset = 0 } = options;
+    const rows = await this.database.query(`SELECT * FROM ${this.table("context_snapshot_item")}
+       WHERE snapshot_id = $1
+       ORDER BY created_at ASC
+       LIMIT $2 OFFSET $3;`, [snapshotId, limit, offset]);
+    return rows.rows.map((row) => this.mapItem(row));
+  }
+  async ensureTables() {
+    if (this.ensured || !this.createTablesIfMissing)
+      return;
+    await this.database.execute(`CREATE SCHEMA IF NOT EXISTS ${this.schema};`);
+    await this.database.execute(`CREATE TABLE IF NOT EXISTS ${this.table("context_pack")} (
+        id text PRIMARY KEY,
+        pack_key text NOT NULL,
+        version text NOT NULL,
+        title text NOT NULL,
+        description text,
+        owners jsonb,
+        tags jsonb,
+        sources jsonb,
+        created_at timestamptz NOT NULL,
+        updated_at timestamptz NOT NULL,
+        UNIQUE (pack_key, version)
+      );`);
+    await this.database.execute(`CREATE TABLE IF NOT EXISTS ${this.table("context_snapshot")} (
+        id text PRIMARY KEY,
+        pack_key text NOT NULL,
+        pack_version text NOT NULL,
+        hash text NOT NULL,
+        item_count int,
+        created_by text,
+        metadata jsonb,
+        created_at timestamptz NOT NULL
+      );`);
+    await this.database.execute(`CREATE TABLE IF NOT EXISTS ${this.table("context_snapshot_item")} (
+        id text PRIMARY KEY,
+        snapshot_id text NOT NULL,
+        kind text NOT NULL,
+        source_key text NOT NULL,
+        source_version text,
+        content jsonb NOT NULL,
+        text_content text,
+        metadata jsonb,
+        created_at timestamptz NOT NULL
+      );`);
+    await this.database.execute(`CREATE INDEX IF NOT EXISTS context_snapshot_item_snapshot_idx
+       ON ${this.table("context_snapshot_item")} (snapshot_id);`);
+    this.ensured = true;
+  }
+  table(name) {
+    return `${this.schema}.${name}`;
+  }
+  mapPack(row) {
+    return {
+      packKey: String(row.pack_key),
+      version: String(row.version),
+      title: String(row.title),
+      description: row.description ? String(row.description) : undefined,
+      owners: arrayFromJson(row.owners),
+      tags: arrayFromJson(row.tags),
+      sources: arrayFromJson(row.sources),
+      createdAt: String(row.created_at),
+      updatedAt: row.updated_at ? String(row.updated_at) : undefined
+    };
+  }
+  mapSnapshot(row) {
+    return {
+      snapshotId: String(row.id),
+      packKey: String(row.pack_key),
+      packVersion: String(row.pack_version),
+      hash: String(row.hash),
+      itemCount: row.item_count != null ? Number(row.item_count) : undefined,
+      createdBy: row.created_by ? String(row.created_by) : undefined,
+      metadata: recordFromJson(row.metadata),
+      createdAt: String(row.created_at)
+    };
+  }
+  mapItem(row) {
+    return {
+      itemId: String(row.id),
+      snapshotId: String(row.snapshot_id),
+      kind: String(row.kind),
+      sourceKey: String(row.source_key),
+      sourceVersion: row.source_version ? String(row.source_version) : undefined,
+      content: recordFromJson(row.content) ?? String(row.content ?? ""),
+      textContent: row.text_content ? String(row.text_content) : undefined,
+      metadata: recordFromJson(row.metadata),
+      createdAt: String(row.created_at)
+    };
+  }
+}
+function arrayFromJson(value) {
+  if (!value)
+    return;
+  if (Array.isArray(value))
+    return value.map(String);
+  if (typeof value === "string") {
+    try {
+      const parsed = JSON.parse(value);
+      return Array.isArray(parsed) ? parsed.map(String) : undefined;
+    } catch {
+      return;
+    }
+  }
+  return;
+}
+function recordFromJson(value) {
+  if (!value)
+    return;
+  if (typeof value === "object" && !Array.isArray(value)) {
+    return value;
+  }
+  if (typeof value === "string") {
+    try {
+      const parsed = JSON.parse(value);
+      return typeof parsed === "object" && parsed ? parsed : undefined;
+    } catch {
+      return;
+    }
+  }
+  return;
+}
+
+// src/pipeline/context-snapshot-pipeline.ts
+import { Buffer } from "node:buffer";
+import {
+  DocumentProcessor
+} from "@contractspec/lib.knowledge/ingestion";
+
+class ContextSnapshotPipeline {
+  store;
+  processor;
+  embeddingService;
+  vectorIndexer;
+  constructor(options) {
+    this.store = options.store;
+    this.processor = options.documentProcessor ?? new DocumentProcessor;
+    this.embeddingService = options.embeddingService;
+    this.vectorIndexer = options.vectorIndexer;
+  }
+  async buildSnapshot(input) {
+    await this.store.upsertPack(input.pack);
+    const snapshot = await this.store.createSnapshot({
+      ...input.snapshot,
+      itemCount: input.items.length
+    });
+    await this.store.addSnapshotItems(snapshot.snapshotId, input.items);
+    if (input.index !== false && this.embeddingService && this.vectorIndexer) {
+      const documents = input.items.map((item) => toRawDocument(item, snapshot.snapshotId));
+      const fragments = await this.collectFragments(documents);
+      const embeddings = await this.embeddingService.embedFragments(fragments);
+      await this.vectorIndexer.upsert(fragments, embeddings);
+    }
+    return { snapshot, itemCount: input.items.length };
+  }
+  async collectFragments(documents) {
+    const fragments = [];
+    for (const document of documents) {
+      const next = await this.processor.process(document);
+      fragments.push(...next);
+    }
+    return fragments;
+  }
+}
+function toRawDocument(item, snapshotId) {
+  const content = typeof item.content === "string" ? item.content : JSON.stringify(item.content);
+  const mimeType = typeof item.content === "string" ? "text/plain" : "application/json";
+  const metadata = {
+    snapshotId,
+    sourceKey: item.sourceKey,
+    sourceVersion: item.sourceVersion ?? "latest",
+    kind: item.kind
+  };
+  return {
+    id: item.itemId,
+    mimeType,
+    data: Buffer.from(content, "utf-8"),
+    metadata
+  };
+}
+export {
+  contextStorageSchemaContribution,
+  contextStorageEntities,
+  PostgresContextStorage,
+  ContextSnapshotPipeline,
+  ContextSnapshotItemEntity,
+  ContextSnapshotEntity,
+  ContextPackEntity
+};

package/dist/node/pipeline/context-snapshot-pipeline.js

@@ -0,0 +1,60 @@
+// src/pipeline/context-snapshot-pipeline.ts
+import { Buffer } from "node:buffer";
+import {
+  DocumentProcessor
+} from "@contractspec/lib.knowledge/ingestion";
+
+class ContextSnapshotPipeline {
+  store;
+  processor;
+  embeddingService;
+  vectorIndexer;
+  constructor(options) {
+    this.store = options.store;
+    this.processor = options.documentProcessor ?? new DocumentProcessor;
+    this.embeddingService = options.embeddingService;
+    this.vectorIndexer = options.vectorIndexer;
+  }
+  async buildSnapshot(input) {
+    await this.store.upsertPack(input.pack);
+    const snapshot = await this.store.createSnapshot({
+      ...input.snapshot,
+      itemCount: input.items.length
+    });
+    await this.store.addSnapshotItems(snapshot.snapshotId, input.items);
+    if (input.index !== false && this.embeddingService && this.vectorIndexer) {
+      const documents = input.items.map((item) => toRawDocument(item, snapshot.snapshotId));
+      const fragments = await this.collectFragments(documents);
+      const embeddings = await this.embeddingService.embedFragments(fragments);
+      await this.vectorIndexer.upsert(fragments, embeddings);
+    }
+    return { snapshot, itemCount: input.items.length };
+  }
+  async collectFragments(documents) {
+    const fragments = [];
+    for (const document of documents) {
+      const next = await this.processor.process(document);
+      fragments.push(...next);
+    }
+    return fragments;
+  }
+}
+function toRawDocument(item, snapshotId) {
+  const content = typeof item.content === "string" ? item.content : JSON.stringify(item.content);
+  const mimeType = typeof item.content === "string" ? "text/plain" : "application/json";
+  const metadata = {
+    snapshotId,
+    sourceKey: item.sourceKey,
+    sourceVersion: item.sourceVersion ?? "latest",
+    kind: item.kind
+  };
+  return {
+    id: item.itemId,
+    mimeType,
+    data: Buffer.from(content, "utf-8"),
+    metadata
+  };
+}
+export {
+  ContextSnapshotPipeline
+};