@contractspec/module.context-storage 0.7.5 → 0.7.7

package/README.md

@@ -1,39 +1,66 @@
 # @contractspec/module.context-storage
 
-Website: https://contractspec.io/
+Website: https://contractspec.io
 
-**Context storage module with persistence adapters**
+**Context storage module with persistence adapters.**
 
-Context storage module for packs, snapshots, and items. Re-exports entities, storage adapters, and the context-snapshot pipeline.
+## What It Provides
+
+- **Layer**: module.
+- **Consumers**: bundles (library), apps (registry-server).
+- `src/pipeline/` contains pipeline stages and orchestration helpers.
+- Related ContractSpec packages include `@contractspec/lib.context-storage`, `@contractspec/lib.contracts-integrations`, `@contractspec/lib.knowledge`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`.
+- `src/pipeline/` contains pipeline stages and orchestration helpers.
 
 ## Installation
 
-```bash
-bun add @contractspec/module.context-storage
-```
+`npm install @contractspec/module.context-storage`
 
-## Exports
+or
 
-- `.` — Main entry: entities, storage, and pipeline
-- `./entities` — Schema entities (ContextPack, ContextSnapshot, ContextSnapshotItem)
-- `./storage` — Postgres storage adapter (PostgresContextStorage)
-- `./pipeline` — ContextSnapshotPipeline for building snapshots from packs
+`bun add @contractspec/module.context-storage`
 
 ## Usage
 
-```typescript
-import {
-  PostgresContextStorage,
-  ContextSnapshotPipeline,
-} from "@contractspec/module.context-storage";
-
-const store = new PostgresContextStorage({ database });
-const pipeline = new ContextSnapshotPipeline({ store });
-
-const result = await pipeline.buildSnapshot({
-  pack,
-  snapshot,
-  items,
-  index: true,
-});
-```
+Import the root entrypoint from `@contractspec/module.context-storage`, or choose a documented subpath when you only need one part of the package surface.
+
+## Architecture
+
+- `src/entities/` contains domain entities and value objects.
+- `src/index.ts` is the root public barrel and package entrypoint.
+- `src/pipeline/` contains pipeline stages and orchestration helpers.
+- `src/storage/` contains persistence adapters and storage implementations.
+
+## Public Entry Points
+
+- Export `.` resolves through `./src/index.ts`.
+- Export `./entities` resolves through `./src/entities/index.ts`.
+- Export `./pipeline/context-snapshot-pipeline` resolves through `./src/pipeline/context-snapshot-pipeline.ts`.
+- Export `./storage` resolves through `./src/storage/index.ts`.
+
+## Local Commands
+
+- `bun run dev` — contractspec-bun-build dev
+- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
+- `bun run lint` — bun lint:fix
+- `bun run lint:check` — biome check .
+- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
+- `bun run typecheck` — tsc --noEmit
+- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
+- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
+- `bun run clean` — rimraf dist .turbo
+- `bun run build:bundle` — contractspec-bun-build transpile
+- `bun run build:types` — contractspec-bun-build types
+- `bun run prebuild` — contractspec-bun-build prebuild
+
+## Recent Updates
+
+- Replace eslint+prettier by biomejs to optimize speed.
+- Resolve lint, build, and type errors across nine packages.
+- Add AI provider ranking system with ranking-driven model selection.
+
+## Notes
+
+- Depends on `lib.context-storage`, `lib.knowledge`, `lib.contracts-integrations`.
+- Pipeline stages must be idempotent; re-running a snapshot should not duplicate data.
+- Storage adapters are swappable -- always code against the interface, not the implementation.

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export * from './entities';
-export * from './storage';
 export * from './pipeline/context-snapshot-pipeline';
+export * from './storage';

package/dist/index.js

@@ -65,6 +65,64 @@ var contextStorageSchemaContribution = {
   entities: contextStorageEntities
 };
 
+// src/pipeline/context-snapshot-pipeline.ts
+import { Buffer } from "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
+  };
+}
+
 // src/storage/index.ts
 class PostgresContextStorage {
   database;
@@ -336,64 +394,6 @@ function recordFromJson(value) {
   }
   return;
 }
-
-// src/pipeline/context-snapshot-pipeline.ts
-import { Buffer } from "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,

package/dist/node/index.js

@@ -64,6 +64,64 @@ var contextStorageSchemaContribution = {
   entities: contextStorageEntities
 };
 
+// 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
+  };
+}
+
 // src/storage/index.ts
 class PostgresContextStorage {
   database;
@@ -335,64 +393,6 @@ function recordFromJson(value) {
   }
   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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractspec/module.context-storage",
-  "version": "0.7.5",
+  "version": "0.7.7",
   "description": "Context storage module with persistence adapters",
   "keywords": [
     "contractspec",
@@ -19,20 +19,20 @@
     "dev": "contractspec-bun-build dev",
     "clean": "rimraf dist .turbo",
     "lint": "bun lint:fix",
-    "lint:fix": "eslint src --fix",
-    "lint:check": "eslint src",
+    "lint:fix": "biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .",
+    "lint:check": "biome check .",
     "prebuild": "contractspec-bun-build prebuild",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@contractspec/lib.context-storage": "0.7.5",
-    "@contractspec/lib.schema": "3.7.5",
-    "@contractspec/lib.contracts-integrations": "3.7.5",
-    "@contractspec/lib.knowledge": "3.7.5"
+    "@contractspec/lib.context-storage": "0.7.6",
+    "@contractspec/lib.schema": "3.7.6",
+    "@contractspec/lib.contracts-integrations": "3.7.7",
+    "@contractspec/lib.knowledge": "3.7.7"
   },
   "devDependencies": {
-    "@contractspec/tool.typescript": "3.7.5",
-    "@contractspec/tool.bun": "3.7.5",
+    "@contractspec/tool.typescript": "3.7.6",
+    "@contractspec/tool.bun": "3.7.6",
     "typescript": "^5.9.3"
   },
   "exports": {