@contractspec/lib.runtime-sandbox 2.7.5 → 2.7.9

package/README.md

@@ -1,40 +1,60 @@
 # @contractspec/lib.runtime-sandbox
 
-Website: https://contractspec.io/
+**Browser-compatible database abstraction built on PGLite for client-side SQL execution.**
 
-**Browser-friendly database abstraction with lazy-loaded PGLite.**
+## What It Provides
 
-Provides a `DatabasePort` interface and a PGLite adapter for running PostgreSQL-compatible queries in the browser. The adapter is lazy-loaded to avoid bundle bloat for consumers that don't need it.
+- **Layer**: lib.
+- **Consumers**: bundles, apps.
+- `src/adapters/` contains runtime, provider, or environment-specific adapters.
+- Related ContractSpec packages include `@contractspec/tool.bun`, `@contractspec/tool.typescript`.
+- `src/adapters/` contains runtime, provider, or environment-specific adapters.
 
 ## Installation
 
-```bash
-bun add @contractspec/lib.runtime-sandbox
-```
+`npm install @contractspec/lib.runtime-sandbox`
 
-## Exports
+or
 
-- `.` -- `DatabasePort`, `DatabaseAdapterFactory`, `createPGLiteAdapter()`, `web` namespace, and core types
+`bun add @contractspec/lib.runtime-sandbox`
 
 ## Usage
 
-```ts
-import { createPGLiteAdapter } from "@contractspec/lib.runtime-sandbox";
+Import the root entrypoint from `@contractspec/lib.runtime-sandbox`, or choose a documented subpath when you only need one part of the package surface.
 
-const db = await createPGLiteAdapter();
-await db.init();
+## Architecture
 
-await db.execute("CREATE TABLE users (id TEXT PRIMARY KEY, name TEXT)");
-await db.execute("INSERT INTO users VALUES ('1', 'Alice')");
+- `src/adapters/` contains runtime, provider, or environment-specific adapters.
+- `src/index.ts` is the root public barrel and package entrypoint.
+- `src/ports` is part of the package's public or composition surface.
+- `src/types` is part of the package's public or composition surface.
+- `src/web` is part of the package's public or composition surface.
 
-const result = await db.query("SELECT * FROM users");
-console.log(result.rows);
-```
+## Public Entry Points
 
-### Web namespace
+- Export `.` resolves through `./src/index.ts`.
 
-```ts
-import { web } from "@contractspec/lib.runtime-sandbox";
-```
+## Local Commands
 
-The `web` namespace provides browser-specific utilities for the sandbox runtime.
+- `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 run 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` — rm -rf dist
+- `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.
+
+## Notes
+
+- DatabasePort interface is the adapter boundary — consumers depend on the port, not the implementation.
+- PGLite adapter must stay browser-compatible (no Node-only APIs).
+- Migration schema must remain stable — breaking changes require a migration path.

package/dist/browser/index.js

@@ -228,16 +228,259 @@ async function seedWorkflowSystem(params) {
   const existing = await db.query(`SELECT COUNT(*) as count FROM workflow_definition WHERE "projectId" = $1`, [projectId]);
   if (existing.rows[0]?.count > 0)
     return;
-  await db.execute(`INSERT INTO workflow_definition (id, "projectId", "organizationId", name, description, type, status)
-     VALUES ($1, $2, $3, $4, $5, $6, $7)`, [
-    "wf_1",
-    projectId,
-    "org_demo",
-    "Approval Workflow",
-    "Demo approval workflow",
-    "APPROVAL",
-    "ACTIVE"
-  ]);
+  const definitions = [
+    {
+      id: "wf_expense",
+      name: "Expense Approval",
+      description: "Approve non-trivial spend before finance releases budget.",
+      type: "APPROVAL",
+      status: "ACTIVE",
+      createdAt: "2026-03-10T09:00:00.000Z",
+      updatedAt: "2026-03-20T08:15:00.000Z",
+      steps: [
+        {
+          id: "wfstep_expense_manager",
+          name: "Manager Review",
+          description: "Validate business value and team budget.",
+          stepOrder: 1,
+          type: "APPROVAL",
+          requiredRoles: ["manager"],
+          createdAt: "2026-03-10T09:00:00.000Z"
+        },
+        {
+          id: "wfstep_expense_finance",
+          name: "Finance Review",
+          description: "Confirm ledger coding and spending threshold.",
+          stepOrder: 2,
+          type: "APPROVAL",
+          requiredRoles: ["finance"],
+          createdAt: "2026-03-10T09:10:00.000Z"
+        }
+      ]
+    },
+    {
+      id: "wf_vendor",
+      name: "Vendor Onboarding",
+      description: "Sequence security, procurement, and legal before activation.",
+      type: "SEQUENTIAL",
+      status: "ACTIVE",
+      createdAt: "2026-03-08T11:00:00.000Z",
+      updatedAt: "2026-03-19T13:10:00.000Z",
+      steps: [
+        {
+          id: "wfstep_vendor_security",
+          name: "Security Check",
+          description: "Review data access and integration scope.",
+          stepOrder: 1,
+          type: "APPROVAL",
+          requiredRoles: ["security"],
+          createdAt: "2026-03-08T11:00:00.000Z"
+        },
+        {
+          id: "wfstep_vendor_procurement",
+          name: "Procurement Check",
+          description: "Validate pricing, procurement policy, and owner.",
+          stepOrder: 2,
+          type: "APPROVAL",
+          requiredRoles: ["procurement"],
+          createdAt: "2026-03-08T11:05:00.000Z"
+        },
+        {
+          id: "wfstep_vendor_legal",
+          name: "Legal Sign-off",
+          description: "Approve terms before the vendor goes live.",
+          stepOrder: 3,
+          type: "APPROVAL",
+          requiredRoles: ["legal"],
+          createdAt: "2026-03-08T11:10:00.000Z"
+        }
+      ]
+    },
+    {
+      id: "wf_policy_exception",
+      name: "Policy Exception",
+      description: "Escalate a temporary exception through team lead and compliance.",
+      type: "APPROVAL",
+      status: "DRAFT",
+      createdAt: "2026-03-15T07:30:00.000Z",
+      updatedAt: "2026-03-18T11:20:00.000Z",
+      steps: [
+        {
+          id: "wfstep_policy_lead",
+          name: "Team Lead Review",
+          description: "Check urgency and expected blast radius.",
+          stepOrder: 1,
+          type: "APPROVAL",
+          requiredRoles: ["team-lead"],
+          createdAt: "2026-03-15T07:30:00.000Z"
+        },
+        {
+          id: "wfstep_policy_compliance",
+          name: "Compliance Review",
+          description: "Accept or reject the exception request.",
+          stepOrder: 2,
+          type: "APPROVAL",
+          requiredRoles: ["compliance"],
+          createdAt: "2026-03-15T07:40:00.000Z"
+        }
+      ]
+    }
+  ];
+  const instances = [
+    {
+      id: "wfinst_expense_open",
+      definitionId: "wf_expense",
+      status: "IN_PROGRESS",
+      currentStepId: "wfstep_expense_finance",
+      data: { amount: 4200, currency: "EUR", vendor: "Nimbus AI" },
+      requestedBy: "sarah@contractspec.io",
+      startedAt: "2026-03-20T08:00:00.000Z",
+      completedAt: null,
+      approvals: [
+        {
+          id: "wfappr_expense_manager",
+          stepId: "wfstep_expense_manager",
+          status: "APPROVED",
+          actorId: "manager.demo",
+          comment: "Approved for the Q2 automation budget.",
+          decidedAt: "2026-03-20T08:15:00.000Z",
+          createdAt: "2026-03-20T08:05:00.000Z"
+        },
+        {
+          id: "wfappr_expense_finance",
+          stepId: "wfstep_expense_finance",
+          status: "PENDING",
+          actorId: null,
+          comment: null,
+          decidedAt: null,
+          createdAt: "2026-03-20T08:15:00.000Z"
+        }
+      ]
+    },
+    {
+      id: "wfinst_vendor_done",
+      definitionId: "wf_vendor",
+      status: "COMPLETED",
+      currentStepId: null,
+      data: { vendor: "Acme Cloud", riskTier: "medium" },
+      requestedBy: "leo@contractspec.io",
+      startedAt: "2026-03-19T09:30:00.000Z",
+      completedAt: "2026-03-19T13:10:00.000Z",
+      approvals: [
+        {
+          id: "wfappr_vendor_security",
+          stepId: "wfstep_vendor_security",
+          status: "APPROVED",
+          actorId: "security.demo",
+          comment: "SOC2 scope is acceptable.",
+          decidedAt: "2026-03-19T10:10:00.000Z",
+          createdAt: "2026-03-19T09:35:00.000Z"
+        },
+        {
+          id: "wfappr_vendor_procurement",
+          stepId: "wfstep_vendor_procurement",
+          status: "APPROVED",
+          actorId: "procurement.demo",
+          comment: "Commercial terms match the preferred vendor tier.",
+          decidedAt: "2026-03-19T11:25:00.000Z",
+          createdAt: "2026-03-19T10:15:00.000Z"
+        },
+        {
+          id: "wfappr_vendor_legal",
+          stepId: "wfstep_vendor_legal",
+          status: "APPROVED",
+          actorId: "legal.demo",
+          comment: "MSA redlines are complete.",
+          decidedAt: "2026-03-19T13:05:00.000Z",
+          createdAt: "2026-03-19T11:30:00.000Z"
+        }
+      ]
+    },
+    {
+      id: "wfinst_policy_rejected",
+      definitionId: "wf_policy_exception",
+      status: "REJECTED",
+      currentStepId: "wfstep_policy_compliance",
+      data: { policy: "Model rollout freeze", durationDays: 14 },
+      requestedBy: "maya@contractspec.io",
+      startedAt: "2026-03-18T10:00:00.000Z",
+      completedAt: "2026-03-18T11:20:00.000Z",
+      approvals: [
+        {
+          id: "wfappr_policy_lead",
+          stepId: "wfstep_policy_lead",
+          status: "APPROVED",
+          actorId: "lead.demo",
+          comment: "Escalation justified for the release train.",
+          decidedAt: "2026-03-18T10:30:00.000Z",
+          createdAt: "2026-03-18T10:05:00.000Z"
+        },
+        {
+          id: "wfappr_policy_compliance",
+          stepId: "wfstep_policy_compliance",
+          status: "REJECTED",
+          actorId: "compliance.demo",
+          comment: "Exception exceeds the allowed blast radius.",
+          decidedAt: "2026-03-18T11:15:00.000Z",
+          createdAt: "2026-03-18T10:35:00.000Z"
+        }
+      ]
+    }
+  ];
+  for (const definition of definitions) {
+    await db.execute(`INSERT INTO workflow_definition (id, "projectId", "organizationId", name, description, type, status, "createdAt", "updatedAt")
+     VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)`, [
+      definition.id,
+      projectId,
+      "org_demo",
+      definition.name,
+      definition.description,
+      definition.type,
+      definition.status,
+      definition.createdAt,
+      definition.updatedAt
+    ]);
+    for (const step of definition.steps) {
+      await db.execute(`INSERT INTO workflow_step (id, "definitionId", name, description, "stepOrder", type, "requiredRoles", "createdAt")
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`, [
+        step.id,
+        definition.id,
+        step.name,
+        step.description,
+        step.stepOrder,
+        step.type,
+        JSON.stringify(step.requiredRoles),
+        step.createdAt
+      ]);
+    }
+  }
+  for (const instance of instances) {
+    await db.execute(`INSERT INTO workflow_instance (id, "projectId", "definitionId", status, "currentStepId", data, "requestedBy", "startedAt", "completedAt")
+     VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)`, [
+      instance.id,
+      projectId,
+      instance.definitionId,
+      instance.status,
+      instance.currentStepId,
+      JSON.stringify(instance.data),
+      instance.requestedBy,
+      instance.startedAt,
+      instance.completedAt
+    ]);
+    for (const approval of instance.approvals) {
+      await db.execute(`INSERT INTO workflow_approval (id, "instanceId", "stepId", status, "actorId", comment, "decidedAt", "createdAt")
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`, [
+        approval.id,
+        instance.id,
+        approval.stepId,
+        approval.status,
+        approval.actorId,
+        approval.comment,
+        approval.decidedAt,
+        approval.createdAt
+      ]);
+    }
+  }
 }
 async function seedMarketplace(params) {
   const { projectId, db } = params;
@@ -1702,116 +1945,6 @@ var psaReviewTask = pgTable("psa_review_task", {
   decidedAt: text("decidedAt"),
   decidedBy: text("decidedBy")
 });
-// src/web/storage/indexeddb.ts
-var DEFAULT_DB_NAME = "contractspec-runtime";
-var DEFAULT_STORE = "kv";
-var FALLBACK_STORE = new Map;
-
-class LocalStorageService {
-  options;
-  dbPromise;
-  constructor(options = {}) {
-    this.options = options;
-  }
-  async init() {
-    await this.getDb();
-  }
-  async get(key, fallback) {
-    const db = await this.getDb();
-    if (!db) {
-      return FALLBACK_STORE.get(key) ?? fallback;
-    }
-    return new Promise((resolve, reject) => {
-      const tx = db.transaction(this.storeName, "readonly");
-      const store = tx.objectStore(this.storeName);
-      const request = store.get(key);
-      request.onsuccess = () => {
-        resolve(request.result ?? fallback);
-      };
-      request.onerror = () => reject(request.error);
-    });
-  }
-  async set(key, value) {
-    const db = await this.getDb();
-    if (!db) {
-      FALLBACK_STORE.set(key, value);
-      return;
-    }
-    await new Promise((resolve, reject) => {
-      const tx = db.transaction(this.storeName, "readwrite");
-      const store = tx.objectStore(this.storeName);
-      const request = store.put(value, key);
-      request.onsuccess = () => resolve();
-      request.onerror = () => reject(request.error);
-    });
-  }
-  async delete(key) {
-    const db = await this.getDb();
-    if (!db) {
-      FALLBACK_STORE.delete(key);
-      return;
-    }
-    await new Promise((resolve, reject) => {
-      const tx = db.transaction(this.storeName, "readwrite");
-      const store = tx.objectStore(this.storeName);
-      const request = store.delete(key);
-      request.onsuccess = () => resolve();
-      request.onerror = () => reject(request.error);
-    });
-  }
-  async clear() {
-    const db = await this.getDb();
-    if (!db) {
-      FALLBACK_STORE.clear();
-      return;
-    }
-    await new Promise((resolve, reject) => {
-      const tx = db.transaction(this.storeName, "readwrite");
-      const store = tx.objectStore(this.storeName);
-      const request = store.clear();
-      request.onsuccess = () => resolve();
-      request.onerror = () => reject(request.error);
-    });
-  }
-  get storeName() {
-    return this.options.storeName ?? DEFAULT_STORE;
-  }
-  async getDb() {
-    if (typeof indexedDB === "undefined") {
-      return null;
-    }
-    if (!this.dbPromise) {
-      this.dbPromise = this.openDb();
-    }
-    return this.dbPromise;
-  }
-  openDb() {
-    return new Promise((resolve, reject) => {
-      const request = indexedDB.open(this.options.dbName ?? DEFAULT_DB_NAME, this.options.version ?? 1);
-      request.onerror = () => reject(request.error);
-      request.onsuccess = () => {
-        resolve(request.result);
-      };
-      request.onupgradeneeded = () => {
-        const db = request.result;
-        if (!db.objectStoreNames.contains(this.storeName)) {
-          db.createObjectStore(this.storeName);
-        }
-      };
-    });
-  }
-}
-// src/web/utils/id.ts
-function generateId(prefix) {
-  const base = typeof crypto !== "undefined" && "randomUUID" in crypto ? crypto.randomUUID() : Math.random().toString(36).slice(2, 10);
-  return prefix ? `${prefix}_${base}` : base;
-}
-// src/web/graphql/local-client.ts
-import { ApolloClient, InMemoryCache } from "@apollo/client";
-import { SchemaLink } from "@apollo/client/link/schema";
-import { makeExecutableSchema } from "@graphql-tools/schema";
-import { GraphQLScalarType, Kind } from "graphql";
-
 // src/web/events/local-pubsub.ts
 class LocalEventBus {
   listeners = new Map;
@@ -1835,6 +1968,17 @@ class LocalEventBus {
     };
   }
 }
+// src/web/graphql/local-client.ts
+import { ApolloClient, InMemoryCache } from "@apollo/client";
+import { SchemaLink } from "@apollo/client/link/schema";
+import { makeExecutableSchema } from "@graphql-tools/schema";
+import { GraphQLScalarType, Kind } from "graphql";
+
+// src/web/utils/id.ts
+function generateId(prefix) {
+  const base = typeof crypto !== "undefined" && "randomUUID" in crypto ? crypto.randomUUID() : Math.random().toString(36).slice(2, 10);
+  return prefix ? `${prefix}_${base}` : base;
+}
 
 // src/web/graphql/local-client.ts
 var typeDefs = `
@@ -2381,6 +2525,106 @@ function mapRecipeInstruction(row, locale) {
     ordering: row.ordering ?? 0
   };
 }
+// src/web/storage/indexeddb.ts
+var DEFAULT_DB_NAME = "contractspec-runtime";
+var DEFAULT_STORE = "kv";
+var FALLBACK_STORE = new Map;
+
+class LocalStorageService {
+  options;
+  dbPromise;
+  constructor(options = {}) {
+    this.options = options;
+  }
+  async init() {
+    await this.getDb();
+  }
+  async get(key, fallback) {
+    const db = await this.getDb();
+    if (!db) {
+      return FALLBACK_STORE.get(key) ?? fallback;
+    }
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(this.storeName, "readonly");
+      const store = tx.objectStore(this.storeName);
+      const request = store.get(key);
+      request.onsuccess = () => {
+        resolve(request.result ?? fallback);
+      };
+      request.onerror = () => reject(request.error);
+    });
+  }
+  async set(key, value) {
+    const db = await this.getDb();
+    if (!db) {
+      FALLBACK_STORE.set(key, value);
+      return;
+    }
+    await new Promise((resolve, reject) => {
+      const tx = db.transaction(this.storeName, "readwrite");
+      const store = tx.objectStore(this.storeName);
+      const request = store.put(value, key);
+      request.onsuccess = () => resolve();
+      request.onerror = () => reject(request.error);
+    });
+  }
+  async delete(key) {
+    const db = await this.getDb();
+    if (!db) {
+      FALLBACK_STORE.delete(key);
+      return;
+    }
+    await new Promise((resolve, reject) => {
+      const tx = db.transaction(this.storeName, "readwrite");
+      const store = tx.objectStore(this.storeName);
+      const request = store.delete(key);
+      request.onsuccess = () => resolve();
+      request.onerror = () => reject(request.error);
+    });
+  }
+  async clear() {
+    const db = await this.getDb();
+    if (!db) {
+      FALLBACK_STORE.clear();
+      return;
+    }
+    await new Promise((resolve, reject) => {
+      const tx = db.transaction(this.storeName, "readwrite");
+      const store = tx.objectStore(this.storeName);
+      const request = store.clear();
+      request.onsuccess = () => resolve();
+      request.onerror = () => reject(request.error);
+    });
+  }
+  get storeName() {
+    return this.options.storeName ?? DEFAULT_STORE;
+  }
+  async getDb() {
+    if (typeof indexedDB === "undefined") {
+      return null;
+    }
+    if (!this.dbPromise) {
+      this.dbPromise = this.openDb();
+    }
+    return this.dbPromise;
+  }
+  openDb() {
+    return new Promise((resolve, reject) => {
+      const request = indexedDB.open(this.options.dbName ?? DEFAULT_DB_NAME, this.options.version ?? 1);
+      request.onerror = () => reject(request.error);
+      request.onsuccess = () => {
+        resolve(request.result);
+      };
+      request.onupgradeneeded = () => {
+        const db = request.result;
+        if (!db.objectStoreNames.contains(this.storeName)) {
+          db.createObjectStore(this.storeName);
+        }
+      };
+    });
+  }
+}
+
 // src/web/runtime/services.ts
 var DEFAULT_PROJECT_ID = "local-project";