@brightbeamai/chap-coordinator 0.2.12 → 0.3.0

package/README.md

@@ -13,8 +13,9 @@ surface, so the two interoperate on the same JSON-RPC 2.0 wire.
 npm install @brightbeamai/chap-coordinator
 ```
 
-Node 20+ required. Zero external runtime dependencies; uses Node's
-built-in `crypto` for Ed25519 and JCS.
+Node 20+ required. No required runtime dependencies; uses Node's built-in
+`crypto` for Ed25519 and JCS. `better-sqlite3` is an optional dependency,
+needed only for `SqliteStore`.
 
 ## Companion packages
 
@@ -85,7 +86,7 @@ console.log(resp.result);  // { task_id: "tsk_...", state: "created" }
 
 | Profile               | Methods (per profile spec)                                                                |
 |-----------------------|-------------------------------------------------------------------------------------------|
-| `core/1.0`            | `workspace.create`, `workspace.describe`, `workspace.set_profiles`, `participant.join`, `participant.leave`, `task.create`, `task.update`, `task.complete`, `audit.read` |
+| `core/1.0`            | `workspace.create`, `workspace.describe`, `workspace.set_profiles`, `participant.join`, `participant.leave`, `task.create`, `task.update`, `task.complete`, `audit.read`; a task created with `review_required` completes only on a reviewer decision |
 | `review/1.0`          | `review.request`, `decide.approve`, `decide.reject`, `decide.override`, `abstain.declare`, `escalate.raise` |
 | `whisper/1.0`         | `whisper.ask`, `whisper.answer`; lapse hook via `coord.checkWhisperLapses(workspaceId, now?)` |
 | `deliberation/1.0`    | `deliberate.open`, `deliberate.comment`, `deliberate.vote`, `deliberate.close` |
@@ -100,6 +101,15 @@ console.log(resp.result);  // { task_id: "tsk_...", state: "created" }
 
 **39 method handlers in total**, matching the Python reference exactly.
 
+**The review gate.** A task carrying `review_required` does not complete on
+`task.complete`. The call opens a review, holding the submitted output as the
+artefact under review, and only a `decide.*` reaches `completed`. `task.update`
+cannot complete such a task either, and answers `-32602` naming the route
+through. Where no reviewer was named, the set is the human members other than
+the completer and the assignee; a workspace with no eligible human refuses the
+completion rather than opening a review nobody can decide. Under `modes/1.0` a
+trial-mode task has `review_required` set for it.
+
 ## Architecture
 
 The coordinator is transport-agnostic, persistence-agnostic, and
@@ -171,7 +181,7 @@ Key lifecycle:
 - `participant.revoke_key` is an admin operation; envelopes signed
   with the revoked key after revocation are rejected.
 
-Helpers exported from `@brightbeamai/chap-coordinator/crypto`:
+Helpers exported from `@brightbeamai/chap-coordinator`:
 
 ```typescript
 import {
@@ -210,7 +220,10 @@ const coord = new Coordinator({
 
 Every call to `task.route`, `review.depth`, and `escalate.auto`
 emits a `route_decision` artefact. `task.route` also updates the
-task's `assignee`.
+task's `assignee`. The caller must be a workspace member. The default
+policy takes the first candidate that is a member and is not paused; a
+`routingPolicy` selection that is not a member is refused with
+`-32510`, and one that is paused with `-32063`.
 
 ## Audit and SCITT (audit-scitt/1.0)
 
@@ -259,9 +272,9 @@ and response shapes. The full audit notes are in the parent repo's
 the original TypeScript expansion and 0.2.3 / 0.2.4 covering the MCP
 and A2A transport additions.
 
-## License
+## Licence
 
-Apache 2.0. See the parent repository's [LICENSE](./LICENSE).
+Apache 2.0. This package ships the licence in its own [LICENSE](./LICENSE) file.
 
 ## Specification
 

package/dist/{api-DiiL0sil.d.cts → api-BkvwN42r.d.cts}

@@ -79,6 +79,10 @@ interface CoordinatorOptions {
     maxEnvelopeBytes?: number;
     onAudit?: AuditListener;
     onAutoEscalate?: (task: Task, to: ParticipantUri) => void;
+    onStoreError?: (err: unknown, record: {
+        id: string;
+        version: number;
+    }) => void;
     verifyOidcToken?: TokenVerifier;
     verifyVc?: CredentialVerifier;
     scittSubmitter?: ScittSubmitter;
@@ -110,8 +114,16 @@ declare class Coordinator {
     readonly ids: IdFactory;
     readonly store: Store;
     private wsVersions;
+    private saveChains;
     private clockMs?;
+    private frozenNow?;
     private auditListeners;
+    /**
+     * The signed calls on each workspace's log, by what their senders signed:
+     * recorded refusals with their seq and code, and accepted calls. Rebuilt
+     * from the log when missing, so a snapshot never carries it.
+     */
+    private signedIndexes;
     /** Method handler registry; profiles plug into this. */
     readonly handlers: Map<string, Handler>;
     /** Custom lapse-check function (whisper/1.0). Set by the whisper profile. */
@@ -129,6 +141,10 @@ declare class Coordinator {
     private applyRecords;
     /** Persist the current snapshot of one workspace to the store. */
     private persist;
+    private trackSave;
+    private reportStoreError;
+    drainSaves(): Promise<void>;
+    private advanceClock;
     now(): string;
     onAudit(listener: AuditListener): () => void;
     /** Convenience: get a workspace by id, or undefined. */
@@ -160,10 +176,34 @@ declare class Coordinator {
      *  any existing in-memory workspaces. */
     restore(data: unknown): void;
     dispatch(envelope: Envelope): Envelope;
+    private _dispatch;
     recordAudit(ws: Workspace, envelope: Envelope): void;
+    /**
+     * SPECIFICATION 10.1: record a refused call when it is a governed attempt.
+     * The caller must be a member of an existing workspace, the call must be a
+     * JSON-RPC call for a method that is not a read, and the refusal must be one
+     * `refusalIsRecorded` names. The request is kept as it arrived, so a
+     * signature on it still verifies. Every call that reaches a recorded refusal
+     * has passed the canonical check, so it can be hashed into the chain.
+     */
+    private recordRefusal;
+    /** The signed calls on this workspace's log, built from the log when missing. */
+    private signedIndex;
+    private appendEntry;
     private verifySignature;
     /** Lookup the key valid for a given participant at a given time. */
     lookupKey(member: Member, kid: string, ts: string): KeyRecord | null;
+    /**
+     * The SPECIFICATION 15.4 check, per method rather than per namespace.
+     *
+     * Core is always present, so a core method is never gated. The reads in
+     * ALWAYS_AVAILABLE are never gated either: a workspace must be able to ask
+     * what it is and to check its own chain, and `audit.verify_chain` belongs to
+     * `audit-scitt/1.0` while chaining also turns on through an option, so
+     * gating it would let a workspace write a hash-linked chain it is refused
+     * permission to verify.
+     */
+    private profileGate;
     private checkStepUp;
     private registerCoreHandlers;
     private registerProfileHandlers;

package/dist/{api-BOGEBNmX.d.ts → api-Ddy9fqkY.d.ts}

@@ -79,6 +79,10 @@ interface CoordinatorOptions {
     maxEnvelopeBytes?: number;
     onAudit?: AuditListener;
     onAutoEscalate?: (task: Task, to: ParticipantUri) => void;
+    onStoreError?: (err: unknown, record: {
+        id: string;
+        version: number;
+    }) => void;
     verifyOidcToken?: TokenVerifier;
     verifyVc?: CredentialVerifier;
     scittSubmitter?: ScittSubmitter;
@@ -110,8 +114,16 @@ declare class Coordinator {
     readonly ids: IdFactory;
     readonly store: Store;
     private wsVersions;
+    private saveChains;
     private clockMs?;
+    private frozenNow?;
     private auditListeners;
+    /**
+     * The signed calls on each workspace's log, by what their senders signed:
+     * recorded refusals with their seq and code, and accepted calls. Rebuilt
+     * from the log when missing, so a snapshot never carries it.
+     */
+    private signedIndexes;
     /** Method handler registry; profiles plug into this. */
     readonly handlers: Map<string, Handler>;
     /** Custom lapse-check function (whisper/1.0). Set by the whisper profile. */
@@ -129,6 +141,10 @@ declare class Coordinator {
     private applyRecords;
     /** Persist the current snapshot of one workspace to the store. */
     private persist;
+    private trackSave;
+    private reportStoreError;
+    drainSaves(): Promise<void>;
+    private advanceClock;
     now(): string;
     onAudit(listener: AuditListener): () => void;
     /** Convenience: get a workspace by id, or undefined. */
@@ -160,10 +176,34 @@ declare class Coordinator {
      *  any existing in-memory workspaces. */
     restore(data: unknown): void;
     dispatch(envelope: Envelope): Envelope;
+    private _dispatch;
     recordAudit(ws: Workspace, envelope: Envelope): void;
+    /**
+     * SPECIFICATION 10.1: record a refused call when it is a governed attempt.
+     * The caller must be a member of an existing workspace, the call must be a
+     * JSON-RPC call for a method that is not a read, and the refusal must be one
+     * `refusalIsRecorded` names. The request is kept as it arrived, so a
+     * signature on it still verifies. Every call that reaches a recorded refusal
+     * has passed the canonical check, so it can be hashed into the chain.
+     */
+    private recordRefusal;
+    /** The signed calls on this workspace's log, built from the log when missing. */
+    private signedIndex;
+    private appendEntry;
     private verifySignature;
     /** Lookup the key valid for a given participant at a given time. */
     lookupKey(member: Member, kid: string, ts: string): KeyRecord | null;
+    /**
+     * The SPECIFICATION 15.4 check, per method rather than per namespace.
+     *
+     * Core is always present, so a core method is never gated. The reads in
+     * ALWAYS_AVAILABLE are never gated either: a workspace must be able to ask
+     * what it is and to check its own chain, and `audit.verify_chain` belongs to
+     * `audit-scitt/1.0` while chaining also turns on through an option, so
+     * gating it would let a workspace write a hash-linked chain it is refused
+     * permission to verify.
+     */
+    private profileGate;
     private checkStepUp;
     private registerCoreHandlers;
     private registerProfileHandlers;

package/dist/api.d.cts

@@ -1,4 +1,4 @@
 import './methods.cjs';
-export { b as CoordinatorApi, c as CoordinatorError, g as call, m as makeApi } from './api-DiiL0sil.cjs';
+export { b as CoordinatorApi, c as CoordinatorError, g as call, m as makeApi } from './api-BkvwN42r.cjs';
 import './types.cjs';
 import './storage/store.cjs';

package/dist/api.d.ts

@@ -1,4 +1,4 @@
 import './methods.js';
-export { b as CoordinatorApi, c as CoordinatorError, g as call, m as makeApi } from './api-BOGEBNmX.js';
+export { b as CoordinatorApi, c as CoordinatorError, g as call, m as makeApi } from './api-Ddy9fqkY.js';
 import './types.js';
 import './storage/store.js';