@brightbeamai/chap-coordinator 0.2.9 → 0.2.12

package/dist/storage/sqlite.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/storage/sqlite.ts"],"sourcesContent":["/**\n * SQLite-backed store using better-sqlite3.\n *\n * Schema:\n *   CREATE TABLE chap_workspaces (\n *     id         TEXT PRIMARY KEY,\n *     data       TEXT NOT NULL,    -- JSON.stringify of snapshot\n *     version    INTEGER NOT NULL,\n *     updated_at TEXT NOT NULL     -- ISO-8601\n *   )\n *\n * Usage:\n *   import { Coordinator } from \"@brightbeamai/chap-coordinator\";\n *   import { SqliteStore } from \"@brightbeamai/chap-coordinator/storage/sqlite\";\n *\n *   const coord = new Coordinator({\n *     store: new SqliteStore(\"./chap.db\"),\n *   });\n *\n * Pass `\":memory:\"` for an in-memory SQLite instance (faster than the\n * MemoryStore for tests that need transactional semantics).\n *\n * better-sqlite3 is declared as an optionalDependency. If the binary\n * cannot be built (rare on Linux/macOS, common on locked-down CI), the\n * SqliteStore import will throw with a clear message and applications\n * can fall back to MemoryStore or another implementation.\n */\n\nimport type { Store, WorkspaceRecord } from \"./store.js\";\n\n// better-sqlite3 has no published types in its own package, but the\n// `@types/better-sqlite3` package provides them. We require a structural\n// subset so the file type-checks even if the typings are absent.\ninterface SqliteDatabase {\n  exec(sql: string): unknown;\n  prepare(sql: string): SqliteStatement;\n  pragma(name: string, options?: { simple?: boolean }): unknown;\n  close(): void;\n}\ninterface SqliteStatement {\n  run(...params: unknown[]): { changes: number; lastInsertRowid: number | bigint };\n  get(...params: unknown[]): unknown;\n  all(...params: unknown[]): unknown[];\n}\n\nexport interface SqliteStoreOptions {\n  /**\n   * Enable WAL journal mode for better concurrent-read performance.\n   * Default true. Set false for `:memory:` databases or when the\n   * filesystem does not support WAL (some network filesystems).\n   */\n  wal?: boolean;\n}\n\nexport class SqliteStore implements Store {\n  readonly db: SqliteDatabase;\n  private readonly stmtLoad: SqliteStatement;\n  private readonly stmtSave: SqliteStatement;\n  private readonly stmtDelete: SqliteStatement;\n\n  constructor(path: string, options: SqliteStoreOptions = {}) {\n    let Database: new (path: string) => SqliteDatabase;\n    try {\n      // require() is used so the dependency stays optional. ESM consumers\n      // can still load this file; the actual import is dynamic.\n      Database = require(\"better-sqlite3\");\n    } catch (err) {\n      throw new Error(\n        \"SqliteStore requires the `better-sqlite3` package. \" +\n        \"Install it with `npm install better-sqlite3` \" +\n        \"or use MemoryStore for non-persistent workloads.\",\n      );\n    }\n\n    this.db = new Database(path);\n    if (path !== \":memory:\" && options.wal !== false) {\n      this.db.pragma(\"journal_mode = WAL\");\n    }\n    this.db.exec(`\n      CREATE TABLE IF NOT EXISTS chap_workspaces (\n        id         TEXT PRIMARY KEY,\n        data       TEXT NOT NULL,\n        version    INTEGER NOT NULL,\n        updated_at TEXT NOT NULL\n      );\n      CREATE INDEX IF NOT EXISTS idx_chap_workspaces_updated_at\n        ON chap_workspaces (updated_at);\n    `);\n\n    this.stmtLoad = this.db.prepare(\n      \"SELECT id, data, version, updated_at FROM chap_workspaces\",\n    );\n    this.stmtSave = this.db.prepare(\n      \"INSERT INTO chap_workspaces (id, data, version, updated_at) \" +\n      \"VALUES (?, ?, ?, ?) \" +\n      \"ON CONFLICT(id) DO UPDATE SET \" +\n      \"data = excluded.data, \" +\n      \"version = excluded.version, \" +\n      \"updated_at = excluded.updated_at\",\n    );\n    this.stmtDelete = this.db.prepare(\n      \"DELETE FROM chap_workspaces WHERE id = ?\",\n    );\n  }\n\n  load(): WorkspaceRecord[] {\n    const rows = this.stmtLoad.all() as Array<{\n      id: string;\n      data: string;\n      version: number;\n      updated_at: string;\n    }>;\n    const out: WorkspaceRecord[] = [];\n    for (const r of rows) {\n      try {\n        out.push({ id: r.id, data: JSON.parse(r.data), version: r.version, updated_at: r.updated_at });\n      } catch {\n        // A single unreadable row must not discard every other workspace; skip it.\n      }\n    }\n    return out;\n  }\n\n  save(record: WorkspaceRecord): void {\n    this.stmtSave.run(\n      record.id,\n      JSON.stringify(record.data),\n      record.version,\n      record.updated_at,\n    );\n  }\n\n  delete(id: string): void {\n    this.stmtDelete.run(id);\n  }\n\n  close(): void {\n    this.db.close();\n  }\n}\n"],"mappings":";;;;;;;;AAsDO,IAAM,cAAN,MAAmC;AAAA,EAC/B;AAAA,EACQ;AAAA,EACA;AAAA,EACA;AAAA,EAEjB,YAAY,MAAc,UAA8B,CAAC,GAAG;AAC1D,QAAI;AACJ,QAAI;AAGF,iBAAW,UAAQ,gBAAgB;AAAA,IACrC,SAAS,KAAK;AACZ,YAAM,IAAI;AAAA,QACR;AAAA,MAGF;AAAA,IACF;AAEA,SAAK,KAAK,IAAI,SAAS,IAAI;AAC3B,QAAI,SAAS,cAAc,QAAQ,QAAQ,OAAO;AAChD,WAAK,GAAG,OAAO,oBAAoB;AAAA,IACrC;AACA,SAAK,GAAG,KAAK;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,KASZ;AAED,SAAK,WAAW,KAAK,GAAG;AAAA,MACtB;AAAA,IACF;AACA,SAAK,WAAW,KAAK,GAAG;AAAA,MACtB;AAAA,IAMF;AACA,SAAK,aAAa,KAAK,GAAG;AAAA,MACxB;AAAA,IACF;AAAA,EACF;AAAA,EAEA,OAA0B;AACxB,UAAM,OAAO,KAAK,SAAS,IAAI;AAM/B,UAAM,MAAyB,CAAC;AAChC,eAAW,KAAK,MAAM;AACpB,UAAI;AACF,YAAI,KAAK,EAAE,IAAI,EAAE,IAAI,MAAM,KAAK,MAAM,EAAE,IAAI,GAAG,SAAS,EAAE,SAAS,YAAY,EAAE,WAAW,CAAC;AAAA,MAC/F,QAAQ;AAAA,MAER;AAAA,IACF;AACA,WAAO;AAAA,EACT;AAAA,EAEA,KAAK,QAA+B;AAClC,SAAK,SAAS;AAAA,MACZ,OAAO;AAAA,MACP,KAAK,UAAU,OAAO,IAAI;AAAA,MAC1B,OAAO;AAAA,MACP,OAAO;AAAA,IACT;AAAA,EACF;AAAA,EAEA,OAAO,IAAkB;AACvB,SAAK,WAAW,IAAI,EAAE;AAAA,EACxB;AAAA,EAEA,QAAc;AACZ,SAAK,GAAG,MAAM;AAAA,EAChB;AACF;","names":[]}
+{"version":3,"sources":["../../src/storage/sqlite.ts"],"sourcesContent":["/**\n * SQLite-backed store using better-sqlite3.\n *\n * Schema:\n *   CREATE TABLE chap_workspaces (\n *     id         TEXT PRIMARY KEY,\n *     data       TEXT NOT NULL,    -- JSON.stringify of snapshot\n *     version    INTEGER NOT NULL,\n *     updated_at TEXT NOT NULL     -- ISO-8601\n *   )\n *\n * Usage:\n *   import { Coordinator } from \"@brightbeamai/chap-coordinator\";\n *   import { SqliteStore } from \"@brightbeamai/chap-coordinator/storage/sqlite\";\n *\n *   const coord = new Coordinator({\n *     store: new SqliteStore(\"./chap.db\"),\n *   });\n *\n * Pass `\":memory:\"` for an in-memory SQLite instance (faster than the\n * MemoryStore for tests that need transactional semantics).\n *\n * better-sqlite3 is declared as an optionalDependency. If the binary\n * cannot be built (rare on Linux/macOS, common on locked-down CI), the\n * SqliteStore import will throw with a clear message and applications\n * can fall back to MemoryStore or another implementation.\n */\n\nimport { createRequire } from \"node:module\";\nimport type { Store, WorkspaceRecord } from \"./store.js\";\n\n// better-sqlite3 has no published types in its own package, but the\n// `@types/better-sqlite3` package provides them. We require a structural\n// subset so the file type-checks even if the typings are absent.\ninterface SqliteDatabase {\n  exec(sql: string): unknown;\n  prepare(sql: string): SqliteStatement;\n  pragma(name: string, options?: { simple?: boolean }): unknown;\n  close(): void;\n}\ninterface SqliteStatement {\n  run(...params: unknown[]): { changes: number; lastInsertRowid: number | bigint };\n  get(...params: unknown[]): unknown;\n  all(...params: unknown[]): unknown[];\n}\n\nexport interface SqliteStoreOptions {\n  /**\n   * Enable WAL journal mode for better concurrent-read performance.\n   * Default true. Set false for `:memory:` databases or when the\n   * filesystem does not support WAL (some network filesystems).\n   */\n  wal?: boolean;\n}\n\nexport class SqliteStore implements Store {\n  readonly db: SqliteDatabase;\n  private readonly stmtLoad: SqliteStatement;\n  private readonly stmtSave: SqliteStatement;\n  private readonly stmtDelete: SqliteStatement;\n\n  constructor(path: string, options: SqliteStoreOptions = {}) {\n    let Database: new (path: string) => SqliteDatabase;\n    try {\n      // Resolved at construction so the dependency stays optional: importing\n      // this module costs nothing if you never build a SqliteStore.\n      //\n      // createRequire rather than a bare require(). A bare one is undefined in\n      // an ES module, so from source it threw ReferenceError and this catch\n      // reported the dependency as missing when it was installed. The bundled\n      // build masked it by shimming require, which is why it went unnoticed.\n      Database = createRequire(import.meta.url)(\"better-sqlite3\");\n    } catch (err) {\n      const detail = err instanceof Error ? `: ${err.message.split(\"\\n\")[0]}` : \"\";\n      throw new Error(\n        \"SqliteStore requires the `better-sqlite3` package. \" +\n        \"Install it with `npm install better-sqlite3` \" +\n        `or use MemoryStore for non-persistent workloads${detail}`,\n      );\n    }\n\n    this.db = new Database(path);\n    if (path !== \":memory:\" && options.wal !== false) {\n      this.db.pragma(\"journal_mode = WAL\");\n    }\n    this.db.exec(`\n      CREATE TABLE IF NOT EXISTS chap_workspaces (\n        id         TEXT PRIMARY KEY,\n        data       TEXT NOT NULL,\n        version    INTEGER NOT NULL,\n        updated_at TEXT NOT NULL\n      );\n      CREATE INDEX IF NOT EXISTS idx_chap_workspaces_updated_at\n        ON chap_workspaces (updated_at);\n    `);\n\n    this.stmtLoad = this.db.prepare(\n      \"SELECT id, data, version, updated_at FROM chap_workspaces\",\n    );\n    this.stmtSave = this.db.prepare(\n      \"INSERT INTO chap_workspaces (id, data, version, updated_at) \" +\n      \"VALUES (?, ?, ?, ?) \" +\n      \"ON CONFLICT(id) DO UPDATE SET \" +\n      \"data = excluded.data, \" +\n      \"version = excluded.version, \" +\n      \"updated_at = excluded.updated_at\",\n    );\n    this.stmtDelete = this.db.prepare(\n      \"DELETE FROM chap_workspaces WHERE id = ?\",\n    );\n  }\n\n  load(): WorkspaceRecord[] {\n    const rows = this.stmtLoad.all() as Array<{\n      id: string;\n      data: string;\n      version: number;\n      updated_at: string;\n    }>;\n    const out: WorkspaceRecord[] = [];\n    for (const r of rows) {\n      try {\n        out.push({ id: r.id, data: JSON.parse(r.data), version: r.version, updated_at: r.updated_at });\n      } catch {\n        // A single unreadable row must not discard every other workspace; skip it.\n      }\n    }\n    return out;\n  }\n\n  save(record: WorkspaceRecord): void {\n    this.stmtSave.run(\n      record.id,\n      JSON.stringify(record.data),\n      record.version,\n      record.updated_at,\n    );\n  }\n\n  delete(id: string): void {\n    this.stmtDelete.run(id);\n  }\n\n  close(): void {\n    this.db.close();\n  }\n}\n"],"mappings":";AA4BA,SAAS,qBAAqB;AA2BvB,IAAM,cAAN,MAAmC;AAAA,EAC/B;AAAA,EACQ;AAAA,EACA;AAAA,EACA;AAAA,EAEjB,YAAY,MAAc,UAA8B,CAAC,GAAG;AAC1D,QAAI;AACJ,QAAI;AAQF,iBAAW,cAAc,YAAY,GAAG,EAAE,gBAAgB;AAAA,IAC5D,SAAS,KAAK;AACZ,YAAM,SAAS,eAAe,QAAQ,KAAK,IAAI,QAAQ,MAAM,IAAI,EAAE,CAAC,CAAC,KAAK;AAC1E,YAAM,IAAI;AAAA,QACR,sJAEkD,MAAM;AAAA,MAC1D;AAAA,IACF;AAEA,SAAK,KAAK,IAAI,SAAS,IAAI;AAC3B,QAAI,SAAS,cAAc,QAAQ,QAAQ,OAAO;AAChD,WAAK,GAAG,OAAO,oBAAoB;AAAA,IACrC;AACA,SAAK,GAAG,KAAK;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,KASZ;AAED,SAAK,WAAW,KAAK,GAAG;AAAA,MACtB;AAAA,IACF;AACA,SAAK,WAAW,KAAK,GAAG;AAAA,MACtB;AAAA,IAMF;AACA,SAAK,aAAa,KAAK,GAAG;AAAA,MACxB;AAAA,IACF;AAAA,EACF;AAAA,EAEA,OAA0B;AACxB,UAAM,OAAO,KAAK,SAAS,IAAI;AAM/B,UAAM,MAAyB,CAAC;AAChC,eAAW,KAAK,MAAM;AACpB,UAAI;AACF,YAAI,KAAK,EAAE,IAAI,EAAE,IAAI,MAAM,KAAK,MAAM,EAAE,IAAI,GAAG,SAAS,EAAE,SAAS,YAAY,EAAE,WAAW,CAAC;AAAA,MAC/F,QAAQ;AAAA,MAER;AAAA,IACF;AACA,WAAO;AAAA,EACT;AAAA,EAEA,KAAK,QAA+B;AAClC,SAAK,SAAS;AAAA,MACZ,OAAO;AAAA,MACP,KAAK,UAAU,OAAO,IAAI;AAAA,MAC1B,OAAO;AAAA,MACP,OAAO;AAAA,IACT;AAAA,EACF;AAAA,EAEA,OAAO,IAAkB;AACvB,SAAK,WAAW,IAAI,EAAE;AAAA,EACxB;AAAA,EAEA,QAAc;AACZ,SAAK,GAAG,MAAM;AAAA,EAChB;AACF;","names":[]}

package/dist/storage/store.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/storage/store.ts"],"sourcesContent":["/**\n * Pluggable persistence for the Coordinator.\n *\n * A Store persists workspace state between process restarts. Coordinators\n * call `store.save(workspaceId, snapshot)` after every mutation that\n * appends to the audit chain, and `store.load()` on startup to restore.\n *\n * Two implementations ship in-tree:\n *   - MemoryStore  (default, no persistence; existing behaviour)\n *   - SqliteStore  (real SQLite via better-sqlite3, opt-in)\n *\n * Third-party stores (Postgres, Redis, etc.) implement this interface.\n *\n * Stores hold per-workspace JSON snapshots, not a decomposed relational\n * model. The Coordinator's snapshot/restore methods produce JSON-safe\n * payloads; this is fast for workspaces in the low-thousands of audit\n * entries and trades query flexibility for simplicity. Production\n * deployments needing rich query semantics should project the audit log\n * into their own analytics store via the `onAudit` listener.\n */\n\nexport interface WorkspaceRecord {\n  /** Workspace identifier. */\n  id: string;\n  /** JSON-serialisable payload produced by `Coordinator.snapshot()`. */\n  data: unknown;\n  /** Monotonically increasing version for optimistic concurrency. */\n  version: number;\n  /** Wall-clock timestamp of the last write, ISO-8601. */\n  updated_at: string;\n}\n\nexport interface Store {\n  /** Load all workspace records into memory. Called once on coordinator start. */\n  load(): Promise<WorkspaceRecord[]> | WorkspaceRecord[];\n\n  /** Persist one workspace record. Called after every mutation. */\n  save(record: WorkspaceRecord): Promise<void> | void;\n\n  /** Remove one workspace. Used by `workspace.delete` semantics (not in v0.2). */\n  delete(id: string): Promise<void> | void;\n\n  /** Release resources. Idempotent. */\n  close?(): Promise<void> | void;\n}\n\n/**\n * In-memory store. Default behaviour: no persistence, fast tests.\n * State lives in a Map; closing it discards everything.\n */\nexport class MemoryStore implements Store {\n  private records = new Map<string, WorkspaceRecord>();\n\n  load(): WorkspaceRecord[] {\n    return Array.from(this.records.values());\n  }\n\n  save(record: WorkspaceRecord): void {\n    this.records.set(record.id, record);\n  }\n\n  delete(id: string): void {\n    this.records.delete(id);\n  }\n\n  close(): void {\n    this.records.clear();\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAkDO,IAAM,cAAN,MAAmC;AAAA,EAChC,UAAU,oBAAI,IAA6B;AAAA,EAEnD,OAA0B;AACxB,WAAO,MAAM,KAAK,KAAK,QAAQ,OAAO,CAAC;AAAA,EACzC;AAAA,EAEA,KAAK,QAA+B;AAClC,SAAK,QAAQ,IAAI,OAAO,IAAI,MAAM;AAAA,EACpC;AAAA,EAEA,OAAO,IAAkB;AACvB,SAAK,QAAQ,OAAO,EAAE;AAAA,EACxB;AAAA,EAEA,QAAc;AACZ,SAAK,QAAQ,MAAM;AAAA,EACrB;AACF;","names":[]}
+{"version":3,"sources":["../../src/storage/store.ts"],"sourcesContent":["/**\n * Pluggable persistence for the Coordinator.\n *\n * A Store persists workspace state between process restarts. Coordinators\n * call `store.save(workspaceId, snapshot)` after every mutation that\n * appends to the audit chain, and `store.load()` on startup to restore.\n *\n * Two implementations ship in-tree:\n *   - MemoryStore  (default, no persistence; existing behaviour)\n *   - SqliteStore  (real SQLite via better-sqlite3, opt-in)\n *\n * Third-party stores (Postgres, Redis, etc.) implement this interface.\n *\n * Concurrency model\n * -----------------\n *\n * A Coordinator is a **single-writer** component: dispatch is serial, workspace\n * state is held in memory, and each chain link is computed from the head the\n * instance holds. This interface is a persistence mechanism, not a\n * concurrency-control one. `save` is an unconditional write and no\n * implementation rejects a stale record.\n *\n * Running two or more Coordinator instances against one shared store is\n * therefore not supported. A stale instance's write replaces a newer one\n * wholesale: entries written by the other instance are lost, the chain is\n * re-linked from the surviving head, and `audit.verify_chain` still reports\n * `ok`, because the surviving chain is internally consistent. The loss is\n * silent and CHAP's own verification will not reveal it.\n *\n * If you need more than one instance, serialise writes above the Coordinator by\n * partitioning workspaces so no workspace is ever written by two, or by holding\n * an external lock. See SPECIFICATION.md section 10.3.\n *\n * Stores hold per-workspace JSON snapshots, not a decomposed relational\n * model. The Coordinator's snapshot/restore methods produce JSON-safe\n * payloads; this is fast for workspaces in the low-thousands of audit\n * entries and trades query flexibility for simplicity. Production\n * deployments needing rich query semantics should project the audit log\n * into their own analytics store via the `onAudit` listener.\n */\n\nexport interface WorkspaceRecord {\n  /** Workspace identifier. */\n  id: string;\n  /** JSON-serialisable payload produced by `Coordinator.snapshot()`. */\n  data: unknown;\n  /**\n   * Incremented on each save. Recorded for diagnostics and for stores that\n   * want it; it is NOT enforced. Nothing here performs a compare-and-swap,\n   * so this field does not give you optimistic concurrency. See the\n   * concurrency model in this module's header.\n   */\n  version: number;\n  /** Wall-clock timestamp of the last write, ISO-8601. */\n  updated_at: string;\n}\n\nexport interface Store {\n  /** Load all workspace records into memory. Called once on coordinator start. */\n  load(): Promise<WorkspaceRecord[]> | WorkspaceRecord[];\n\n  /** Persist one workspace record. Called after every mutation. */\n  save(record: WorkspaceRecord): Promise<void> | void;\n\n  /** Remove one workspace. Used by `workspace.delete` semantics (not in v0.2). */\n  delete(id: string): Promise<void> | void;\n\n  /** Release resources. Idempotent. */\n  close?(): Promise<void> | void;\n}\n\n/**\n * In-memory store. Default behaviour: no persistence, fast tests.\n * State lives in a Map; closing it discards everything.\n */\nexport class MemoryStore implements Store {\n  private records = new Map<string, WorkspaceRecord>();\n\n  load(): WorkspaceRecord[] {\n    return Array.from(this.records.values());\n  }\n\n  save(record: WorkspaceRecord): void {\n    this.records.set(record.id, record);\n  }\n\n  delete(id: string): void {\n    this.records.delete(id);\n  }\n\n  close(): void {\n    this.records.clear();\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AA2EO,IAAM,cAAN,MAAmC;AAAA,EAChC,UAAU,oBAAI,IAA6B;AAAA,EAEnD,OAA0B;AACxB,WAAO,MAAM,KAAK,KAAK,QAAQ,OAAO,CAAC;AAAA,EACzC;AAAA,EAEA,KAAK,QAA+B;AAClC,SAAK,QAAQ,IAAI,OAAO,IAAI,MAAM;AAAA,EACpC;AAAA,EAEA,OAAO,IAAkB;AACvB,SAAK,QAAQ,OAAO,EAAE;AAAA,EACxB;AAAA,EAEA,QAAc;AACZ,SAAK,QAAQ,MAAM;AAAA,EACrB;AACF;","names":[]}

package/dist/storage/store.d.cts

@@ -11,6 +11,26 @@
  *
  * Third-party stores (Postgres, Redis, etc.) implement this interface.
  *
+ * Concurrency model
+ * -----------------
+ *
+ * A Coordinator is a **single-writer** component: dispatch is serial, workspace
+ * state is held in memory, and each chain link is computed from the head the
+ * instance holds. This interface is a persistence mechanism, not a
+ * concurrency-control one. `save` is an unconditional write and no
+ * implementation rejects a stale record.
+ *
+ * Running two or more Coordinator instances against one shared store is
+ * therefore not supported. A stale instance's write replaces a newer one
+ * wholesale: entries written by the other instance are lost, the chain is
+ * re-linked from the surviving head, and `audit.verify_chain` still reports
+ * `ok`, because the surviving chain is internally consistent. The loss is
+ * silent and CHAP's own verification will not reveal it.
+ *
+ * If you need more than one instance, serialise writes above the Coordinator by
+ * partitioning workspaces so no workspace is ever written by two, or by holding
+ * an external lock. See SPECIFICATION.md section 10.3.
+ *
  * Stores hold per-workspace JSON snapshots, not a decomposed relational
  * model. The Coordinator's snapshot/restore methods produce JSON-safe
  * payloads; this is fast for workspaces in the low-thousands of audit
@@ -23,7 +43,12 @@ interface WorkspaceRecord {
     id: string;
     /** JSON-serialisable payload produced by `Coordinator.snapshot()`. */
     data: unknown;
-    /** Monotonically increasing version for optimistic concurrency. */
+    /**
+     * Incremented on each save. Recorded for diagnostics and for stores that
+     * want it; it is NOT enforced. Nothing here performs a compare-and-swap,
+     * so this field does not give you optimistic concurrency. See the
+     * concurrency model in this module's header.
+     */
     version: number;
     /** Wall-clock timestamp of the last write, ISO-8601. */
     updated_at: string;

package/dist/storage/store.d.ts

@@ -11,6 +11,26 @@
  *
  * Third-party stores (Postgres, Redis, etc.) implement this interface.
  *
+ * Concurrency model
+ * -----------------
+ *
+ * A Coordinator is a **single-writer** component: dispatch is serial, workspace
+ * state is held in memory, and each chain link is computed from the head the
+ * instance holds. This interface is a persistence mechanism, not a
+ * concurrency-control one. `save` is an unconditional write and no
+ * implementation rejects a stale record.
+ *
+ * Running two or more Coordinator instances against one shared store is
+ * therefore not supported. A stale instance's write replaces a newer one
+ * wholesale: entries written by the other instance are lost, the chain is
+ * re-linked from the surviving head, and `audit.verify_chain` still reports
+ * `ok`, because the surviving chain is internally consistent. The loss is
+ * silent and CHAP's own verification will not reveal it.
+ *
+ * If you need more than one instance, serialise writes above the Coordinator by
+ * partitioning workspaces so no workspace is ever written by two, or by holding
+ * an external lock. See SPECIFICATION.md section 10.3.
+ *
  * Stores hold per-workspace JSON snapshots, not a decomposed relational
  * model. The Coordinator's snapshot/restore methods produce JSON-safe
  * payloads; this is fast for workspaces in the low-thousands of audit
@@ -23,7 +43,12 @@ interface WorkspaceRecord {
     id: string;
     /** JSON-serialisable payload produced by `Coordinator.snapshot()`. */
     data: unknown;
-    /** Monotonically increasing version for optimistic concurrency. */
+    /**
+     * Incremented on each save. Recorded for diagnostics and for stores that
+     * want it; it is NOT enforced. Nothing here performs a compare-and-swap,
+     * so this field does not give you optimistic concurrency. See the
+     * concurrency model in this module's header.
+     */
     version: number;
     /** Wall-clock timestamp of the last write, ISO-8601. */
     updated_at: string;

package/dist/storage/store.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/storage/store.ts"],"sourcesContent":["/**\n * Pluggable persistence for the Coordinator.\n *\n * A Store persists workspace state between process restarts. Coordinators\n * call `store.save(workspaceId, snapshot)` after every mutation that\n * appends to the audit chain, and `store.load()` on startup to restore.\n *\n * Two implementations ship in-tree:\n *   - MemoryStore  (default, no persistence; existing behaviour)\n *   - SqliteStore  (real SQLite via better-sqlite3, opt-in)\n *\n * Third-party stores (Postgres, Redis, etc.) implement this interface.\n *\n * Stores hold per-workspace JSON snapshots, not a decomposed relational\n * model. The Coordinator's snapshot/restore methods produce JSON-safe\n * payloads; this is fast for workspaces in the low-thousands of audit\n * entries and trades query flexibility for simplicity. Production\n * deployments needing rich query semantics should project the audit log\n * into their own analytics store via the `onAudit` listener.\n */\n\nexport interface WorkspaceRecord {\n  /** Workspace identifier. */\n  id: string;\n  /** JSON-serialisable payload produced by `Coordinator.snapshot()`. */\n  data: unknown;\n  /** Monotonically increasing version for optimistic concurrency. */\n  version: number;\n  /** Wall-clock timestamp of the last write, ISO-8601. */\n  updated_at: string;\n}\n\nexport interface Store {\n  /** Load all workspace records into memory. Called once on coordinator start. */\n  load(): Promise<WorkspaceRecord[]> | WorkspaceRecord[];\n\n  /** Persist one workspace record. Called after every mutation. */\n  save(record: WorkspaceRecord): Promise<void> | void;\n\n  /** Remove one workspace. Used by `workspace.delete` semantics (not in v0.2). */\n  delete(id: string): Promise<void> | void;\n\n  /** Release resources. Idempotent. */\n  close?(): Promise<void> | void;\n}\n\n/**\n * In-memory store. Default behaviour: no persistence, fast tests.\n * State lives in a Map; closing it discards everything.\n */\nexport class MemoryStore implements Store {\n  private records = new Map<string, WorkspaceRecord>();\n\n  load(): WorkspaceRecord[] {\n    return Array.from(this.records.values());\n  }\n\n  save(record: WorkspaceRecord): void {\n    this.records.set(record.id, record);\n  }\n\n  delete(id: string): void {\n    this.records.delete(id);\n  }\n\n  close(): void {\n    this.records.clear();\n  }\n}\n"],"mappings":";AAkDO,IAAM,cAAN,MAAmC;AAAA,EAChC,UAAU,oBAAI,IAA6B;AAAA,EAEnD,OAA0B;AACxB,WAAO,MAAM,KAAK,KAAK,QAAQ,OAAO,CAAC;AAAA,EACzC;AAAA,EAEA,KAAK,QAA+B;AAClC,SAAK,QAAQ,IAAI,OAAO,IAAI,MAAM;AAAA,EACpC;AAAA,EAEA,OAAO,IAAkB;AACvB,SAAK,QAAQ,OAAO,EAAE;AAAA,EACxB;AAAA,EAEA,QAAc;AACZ,SAAK,QAAQ,MAAM;AAAA,EACrB;AACF;","names":[]}
+{"version":3,"sources":["../../src/storage/store.ts"],"sourcesContent":["/**\n * Pluggable persistence for the Coordinator.\n *\n * A Store persists workspace state between process restarts. Coordinators\n * call `store.save(workspaceId, snapshot)` after every mutation that\n * appends to the audit chain, and `store.load()` on startup to restore.\n *\n * Two implementations ship in-tree:\n *   - MemoryStore  (default, no persistence; existing behaviour)\n *   - SqliteStore  (real SQLite via better-sqlite3, opt-in)\n *\n * Third-party stores (Postgres, Redis, etc.) implement this interface.\n *\n * Concurrency model\n * -----------------\n *\n * A Coordinator is a **single-writer** component: dispatch is serial, workspace\n * state is held in memory, and each chain link is computed from the head the\n * instance holds. This interface is a persistence mechanism, not a\n * concurrency-control one. `save` is an unconditional write and no\n * implementation rejects a stale record.\n *\n * Running two or more Coordinator instances against one shared store is\n * therefore not supported. A stale instance's write replaces a newer one\n * wholesale: entries written by the other instance are lost, the chain is\n * re-linked from the surviving head, and `audit.verify_chain` still reports\n * `ok`, because the surviving chain is internally consistent. The loss is\n * silent and CHAP's own verification will not reveal it.\n *\n * If you need more than one instance, serialise writes above the Coordinator by\n * partitioning workspaces so no workspace is ever written by two, or by holding\n * an external lock. See SPECIFICATION.md section 10.3.\n *\n * Stores hold per-workspace JSON snapshots, not a decomposed relational\n * model. The Coordinator's snapshot/restore methods produce JSON-safe\n * payloads; this is fast for workspaces in the low-thousands of audit\n * entries and trades query flexibility for simplicity. Production\n * deployments needing rich query semantics should project the audit log\n * into their own analytics store via the `onAudit` listener.\n */\n\nexport interface WorkspaceRecord {\n  /** Workspace identifier. */\n  id: string;\n  /** JSON-serialisable payload produced by `Coordinator.snapshot()`. */\n  data: unknown;\n  /**\n   * Incremented on each save. Recorded for diagnostics and for stores that\n   * want it; it is NOT enforced. Nothing here performs a compare-and-swap,\n   * so this field does not give you optimistic concurrency. See the\n   * concurrency model in this module's header.\n   */\n  version: number;\n  /** Wall-clock timestamp of the last write, ISO-8601. */\n  updated_at: string;\n}\n\nexport interface Store {\n  /** Load all workspace records into memory. Called once on coordinator start. */\n  load(): Promise<WorkspaceRecord[]> | WorkspaceRecord[];\n\n  /** Persist one workspace record. Called after every mutation. */\n  save(record: WorkspaceRecord): Promise<void> | void;\n\n  /** Remove one workspace. Used by `workspace.delete` semantics (not in v0.2). */\n  delete(id: string): Promise<void> | void;\n\n  /** Release resources. Idempotent. */\n  close?(): Promise<void> | void;\n}\n\n/**\n * In-memory store. Default behaviour: no persistence, fast tests.\n * State lives in a Map; closing it discards everything.\n */\nexport class MemoryStore implements Store {\n  private records = new Map<string, WorkspaceRecord>();\n\n  load(): WorkspaceRecord[] {\n    return Array.from(this.records.values());\n  }\n\n  save(record: WorkspaceRecord): void {\n    this.records.set(record.id, record);\n  }\n\n  delete(id: string): void {\n    this.records.delete(id);\n  }\n\n  close(): void {\n    this.records.clear();\n  }\n}\n"],"mappings":";AA2EO,IAAM,cAAN,MAAmC;AAAA,EAChC,UAAU,oBAAI,IAA6B;AAAA,EAEnD,OAA0B;AACxB,WAAO,MAAM,KAAK,KAAK,QAAQ,OAAO,CAAC;AAAA,EACzC;AAAA,EAEA,KAAK,QAA+B;AAClC,SAAK,QAAQ,IAAI,OAAO,IAAI,MAAM;AAAA,EACpC;AAAA,EAEA,OAAO,IAAkB;AACvB,SAAK,QAAQ,OAAO,EAAE;AAAA,EACxB;AAAA,EAEA,QAAc;AACZ,SAAK,QAAQ,MAAM;AAAA,EACrB;AACF;","names":[]}

package/package.json

@@ -1,52 +1,104 @@
 {
   "name": "@brightbeamai/chap-coordinator",
-  "version": "0.2.9",
+  "version": "0.2.12",
   "description": "Collaborative Human-Agent Protocol (CHAP): reference TypeScript implementation. Coordinator with Core + every shipped profile, plus pluggable storage and typed method facade.",
   "license": "Apache-2.0",
   "author": "Brightbeam AI <oss@brightbeam.com>",
   "homepage": "https://github.com/BrightbeamAI/chap",
   "repository": {
     "type": "git",
-    "url": "https://github.com/BrightbeamAI/chap.git",
+    "url": "git+https://github.com/BrightbeamAI/chap.git",
     "directory": "packages/coordinator"
   },
   "bugs": {
     "url": "https://github.com/BrightbeamAI/chap/issues"
   },
   "keywords": [
-    "chap", "agent", "protocol", "audit", "json-rpc",
-    "human-ai", "human-agent", "review", "override", "scitt", "mcp", "a2a"
+    "chap",
+    "agent",
+    "protocol",
+    "audit",
+    "json-rpc",
+    "human-ai",
+    "human-agent",
+    "review",
+    "override",
+    "scitt",
+    "mcp",
+    "a2a"
   ],
   "type": "module",
-  "engines": { "node": ">=20" },
-  "files": ["dist", "README.md", "LICENSE"],
-  "main":   "./dist/index.cjs",
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.cjs",
   "module": "./dist/index.js",
-  "types":  "./dist/index.d.ts",
+  "types": "./dist/index.d.ts",
   "exports": {
-    ".":                 { "types": "./dist/index.d.ts",            "import": "./dist/index.js",            "require": "./dist/index.cjs" },
-    "./jsonrpc":         { "types": "./dist/jsonrpc.d.ts",          "import": "./dist/jsonrpc.js",          "require": "./dist/jsonrpc.cjs" },
-    "./patch":           { "types": "./dist/patch.d.ts",            "import": "./dist/patch.js",            "require": "./dist/patch.cjs" },
-    "./types":           { "types": "./dist/types.d.ts",            "import": "./dist/types.js",            "require": "./dist/types.cjs" },
-    "./methods":         { "types": "./dist/methods.d.ts",          "import": "./dist/methods.js",          "require": "./dist/methods.cjs" },
-    "./api":             { "types": "./dist/api.d.ts",              "import": "./dist/api.js",              "require": "./dist/api.cjs" },
-    "./storage/store":   { "types": "./dist/storage/store.d.ts",    "import": "./dist/storage/store.js",    "require": "./dist/storage/store.cjs" },
-    "./storage/sqlite":  { "types": "./dist/storage/sqlite.d.ts",   "import": "./dist/storage/sqlite.js",   "require": "./dist/storage/sqlite.cjs" }
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./jsonrpc": {
+      "types": "./dist/jsonrpc.d.ts",
+      "import": "./dist/jsonrpc.js",
+      "require": "./dist/jsonrpc.cjs"
+    },
+    "./patch": {
+      "types": "./dist/patch.d.ts",
+      "import": "./dist/patch.js",
+      "require": "./dist/patch.cjs"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js",
+      "require": "./dist/types.cjs"
+    },
+    "./methods": {
+      "types": "./dist/methods.d.ts",
+      "import": "./dist/methods.js",
+      "require": "./dist/methods.cjs"
+    },
+    "./api": {
+      "types": "./dist/api.d.ts",
+      "import": "./dist/api.js",
+      "require": "./dist/api.cjs"
+    },
+    "./storage/store": {
+      "types": "./dist/storage/store.d.ts",
+      "import": "./dist/storage/store.js",
+      "require": "./dist/storage/store.cjs"
+    },
+    "./storage/sqlite": {
+      "types": "./dist/storage/sqlite.d.ts",
+      "import": "./dist/storage/sqlite.js",
+      "require": "./dist/storage/sqlite.cjs"
+    }
   },
   "scripts": {
-    "build":          "tsup",
-    "test":           "tsx --test tests/*.test.ts",
-    "typecheck":      "tsc",
-    "check:schemas":  "tsx scripts/check-method-coverage.ts",
+    "build": "tsup",
+    "test": "tsx --test tests/*.test.ts",
+    "typecheck": "tsc",
+    "check:schemas": "tsx scripts/check-method-coverage.ts",
     "prepublishOnly": "npm run check:schemas && npm run typecheck && npm run test && npm run build"
   },
-  "optionalDependencies": { "better-sqlite3": "^12.11.1" },
+  "optionalDependencies": {
+    "better-sqlite3": "^12.11.1"
+  },
   "devDependencies": {
-    "@types/node":     "^20.11.0",
-    "better-sqlite3":  "^12.11.1",
-    "tsup":            "^8.0.0",
-    "tsx":             "^4.7.0",
-    "typescript":      "^5.3.0"
+    "@types/node": "^20.11.0",
+    "better-sqlite3": "^12.11.1",
+    "tsup": "^8.0.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.0"
   },
-  "publishConfig": { "access": "public" }
+  "publishConfig": {
+    "access": "public"
+  }
 }