@brightbeamai/chap-coordinator 0.3.4 → 0.3.5

package/README.md

@@ -2,7 +2,7 @@
 
 TypeScript reference implementation of the Collaborative Human-Agent Protocol (CHAP).
 
-Covers Core plus every profile, 39 method handlers in total. Spec-aligned
+Covers Core plus every profile, 40 method handlers in total. Spec-aligned
 field names, error codes, and response shapes against `profiles/*.md`.
 The Python reference at `packages/coordinator-py/` implements the same
 surface, so the two interoperate on the same JSON-RPC 2.0 wire.
@@ -13,9 +13,10 @@ surface, so the two interoperate on the same JSON-RPC 2.0 wire.
 npm install @brightbeamai/chap-coordinator
 ```
 
-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`.
+Node 22+ required. No required runtime dependencies; uses Node's built-in
+`crypto` for Ed25519 and JCS. `SqliteStore` uses `better-sqlite3`, an
+optional dependency, where it is installed, and Node's built-in
+`node:sqlite` (Node 22.13 and later) where it is not.
 
 ## Companion packages
 
@@ -87,19 +88,19 @@ 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`; 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` |
+| `review/1.0`          | `review.request`, `review.acknowledge`, `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` |
 | `handoff/1.0`         | `handoff.propose`, `handoff.accept`, `handoff.decline`; multi-task; recipient may be a URI or `group:` |
 | `control/1.0`         | `control.pause`, `control.resume`, `control.cancel`, `control.snapshot`, `control.rollback`, `control.supersede`, `control.set_mode_ceiling`; pause/resume take `scope: task/participant/workspace` |
 | `routing/1.0`         | `task.route`, `review.depth`, `escalate.auto`; each emits a `route_decision` artefact |
 | `modes/1.0`           | Mode handling at `task.create`; `trial` mode forces `review_required`; `control.set_mode_ceiling` shared with control/1.0 |
-| `security-signed/1.0` | `participant.rotate_key`, `participant.revoke_key`; top-level `sig` verified at dispatch when `requireSignatures` is true |
+| `security-signed/1.0` | `participant.rotate_key`, `participant.revoke_key`; top-level `sig` verified at dispatch where the workspace advertises the profile or `requireSignatures` is true, under the workspace's `signature_policy` |
 | `audit-scitt/1.0`     | `audit.submit_to_scitt`, `audit.verify_receipt`, `audit.verify_chain`; SCITT statements assembled and passed to a deployment-supplied submitter; local prev-hash chain linkage retained |
 | `identity-oidc/1.0`   | `participant.join` binding via `verifyOidcToken`; `cnf.jwk` pinning, step-up auth via `enforceStepUp` |
 | `identity-vc/1.0`     | `participant.join` binding via `verifyVc`; holder-key pinning |
 
-**39 method handlers in total**, matching the Python reference exactly.
+**40 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
@@ -110,6 +111,13 @@ 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.
 
+A review records its `authors`, the task's assignee and the member that
+completed the work, and refuses a decision from either with `-32011`, however
+the review is addressed. On a task that requires review only a human member
+decides, and a `review.request` naming an author or an agent is refused. A task
+that holds a review, taken back to `in_progress`, completes only through a
+decision: its next `task.complete` opens a new round.
+
 ## Architecture
 
 The coordinator is transport-agnostic, persistence-agnostic, and
@@ -123,6 +131,20 @@ const response = coord.dispatch(envelope);
 response. State is held in memory; persist by subscribing with
 `coord.onAudit(listener)`.
 
+With a `store` option (`SqliteStore`, or a store of your own), each call's
+changes are written before `dispatch` returns, and the listeners hear of an
+entry once it is written. A call whose write fails is answered with
+`-32603` and `data: { reason: "store" }`, and its workspace goes back to
+what the store holds. Before each call on a workspace the coordinator asks
+the store how many entries it holds, and reloads a workspace another
+instance has written, so instances that share a store take turns
+([SPECIFICATION.md §10.3](../../SPECIFICATION.md#103-writers)).
+
+A handler that throws is answered with `-32603` and no detail, since an
+exception's text can name a path or another workspace's data. The error
+goes to `onInternalError(err, { method, workspace })`, or to stderr when
+the option is unset.
+
 Reference HTTP bindings:
 - `reference/core/` and `reference/core-plus-review/` (standalone TS
   servers used by the conformance harness and the demo playground)
@@ -160,7 +182,12 @@ const coord = new Coordinator({
 
 If a `participant.join` envelope includes `oidc_token` or
 `vc_presentation`, the relevant hook is called and the bound key is
-added to the participant's key history.
+added to the participant's key history. A token with no `cnf.jwk` binds
+the key in the join's `jwks` whose RFC 7638 thumbprint is the token's
+`nonce`. Where a hook is configured and the workspace advertises its
+profile, a `human` joins with the credential it checks or is refused
+(`-32403`, `-32410`), and the log records the credential as its SHA-256
+digest, never the credential itself.
 
 ## Signed envelopes (security-signed/1.0)
 
@@ -168,6 +195,14 @@ added to the participant's key history.
 const coord = new Coordinator({ requireSignatures: true });
 ```
 
+A workspace also requires signatures when it advertises
+`security-signed/1.0`, and cannot stop advertising it once it does. Its
+`signature_policy`, a `workspace.create` param that falls back to the
+`signaturePolicy` option, is `"all"` by default; under `"humans"` an
+unsigned call is taken from a member that is not human, so an agent on the
+server's own transport works unsigned, and every person's decision is
+still signed.
+
 Each participant registers one or more JWKs at `participant.join` via
 `jwks: { keys: [...] }`. Senders sign the JCS canonicalisation of the
 envelope **with the top-level `sig` field removed**, then attach the
@@ -175,6 +210,17 @@ signature as a top-level `sig: "ed25519:<kid>:<base64>"` field. The
 Coordinator looks up the verifying key by `(from, kid, ts)`, so
 historical envelopes verify across key rotation.
 
+A key held by a browser's authenticator, a P-256 JWK with a `webauthn`
+member naming its `rp_id`, signs with a WebAuthn assertion whose challenge
+is the SHA-256 of those same bytes, tagged
+`webauthn:<kid>:<authenticatorData>.<clientDataJSON>.<signature>`
+([profiles/security-signed.md](../../profiles/security-signed.md) §3).
+
+A signed request takes effect once. The same signed call sent again, its
+`sig` re-encoded or not, is refused with `-32075` and
+`data.accepted_at_seq`, and a copy of a recorded refusal is answered with
+that refusal; neither is evaluated again.
+
 Key lifecycle:
 - `participant.rotate_key` is signed with the old key; the Coordinator
   marks `valid_until` on the old key and `valid_from` on the new one.

package/dist/{api-59aU01Bs.d.cts → api-CjZQnj63.d.cts}

@@ -1,6 +1,6 @@
-import { MethodParams, WorkspaceCreateResult, WorkspaceDescribeResult, OkResult, TaskCreateResult, TaskRouteResult, ReviewRequestResult, ReviewDepthResult, DecideOverrideResult, EscalateRaiseResult, EscalateAutoResult, WhisperAskResult, DeliberateOpenResult, DeliberateCloseResult, HandoffProposeResult, ControlSupersedeResult, ControlSnapshotResult, AuditReadResult, AuditSubmitToScittResult, AuditVerifyReceiptResult, AuditVerifyChainResult, MethodName, MethodResult } from './methods.cjs';
+import { MethodParams, WorkspaceCreateResult, WorkspaceDescribeResult, OkResult, WorkspaceInviteResult, TaskCreateResult, TaskRouteResult, ReviewRequestResult, ReviewAcknowledgeResult, ReviewDepthResult, DecideOverrideResult, EscalateRaiseResult, EscalateAutoResult, WhisperAskResult, DeliberateOpenResult, DeliberateCloseResult, HandoffProposeResult, ControlSupersedeResult, ControlSnapshotResult, AuditReadResult, AuditSubmitToScittResult, AuditVerifyReceiptResult, AuditVerifyChainResult, MethodName, MethodResult } from './methods.cjs';
 import { Store } from './storage/store.cjs';
-import { Workspace, AuditListener, Task, ParticipantUri, Envelope, WorkspaceId, Member, KeyRecord } from './types.cjs';
+import { Workspace, SignaturePolicy, JoinPolicy, AuditListener, Task, ParticipantUri, Envelope, WorkspaceId, Member, KeyRecord } from './types.cjs';
 
 /**
  * @brightbeamai/chap-coordinator/ids
@@ -72,23 +72,59 @@ interface CoordinatorOptions {
     deterministicIds?: boolean;
     deterministicClock?: boolean;
     enableChain?: boolean;
+    /**
+     * Require signatures on every workspace, as advertising
+     * `security-signed/1.0` does on one.
+     */
     requireSignatures?: boolean;
+    /**
+     * The signature policy of a workspace whose `workspace.create` names none:
+     * "all" (the default) verifies every call, and "humans" takes an unsigned
+     * call from an agent member.
+     */
+    signaturePolicy?: SignaturePolicy;
+    /**
+     * The join policy of a workspace whose `workspace.create` names none:
+     * "open" (the default) admits anyone, and "invite" admits only a
+     * participant an admin invited, and the first member.
+     */
+    joinPolicy?: JoinPolicy;
     enforceStepUp?: boolean;
     requireReadMembership?: boolean;
     /** Largest envelope accepted (default 1 MiB), published in the descriptor. */
     maxEnvelopeBytes?: number;
+    /** Told of each audit entry once the store has taken it. */
     onAudit?: AuditListener;
     onAutoEscalate?: (task: Task, to: ParticipantUri) => void;
     /**
      * Called when a write to the store fails, with the workspace and the
      * version the write would have reached. When unset, the failure is written
-     * to stderr. The call itself has already succeeded in memory; the next
-     * write to the workspace carries what this one did not.
+     * to stderr. What happens to the call is `storeErrors`'s to say.
      */
     onStoreError?: (err: unknown, record: {
         id: string;
         version: number;
     }) => void;
+    /**
+     * What a failed synchronous write does to the call that made it. "raise"
+     * (the default): the call is answered with -32603 and
+     * `data: { reason: "store" }`, and the workspace goes back to what the
+     * store holds. "log": the call is answered as it was, and the next write
+     * carries its change again. A write another writer got to first is
+     * answered as "raise" says under either, and the call may be sent again.
+     * An asynchronous write's call was answered already, and the next write
+     * to the workspace carries what this one did not.
+     */
+    storeErrors?: "raise" | "log";
+    /**
+     * Called when a handler throws, with the error and the call's method and
+     * workspace. The caller is answered with -32603 and no detail. When unset,
+     * the error is written to stderr.
+     */
+    onInternalError?: (err: unknown, call: {
+        method: string;
+        workspace?: string;
+    }) => void;
     verifyOidcToken?: TokenVerifier;
     verifyVc?: CredentialVerifier;
     scittSubmitter?: ScittSubmitter;
@@ -130,13 +166,21 @@ declare class Coordinator {
     private unflushed;
     /** Workspaces with a write queued behind an async write in flight. */
     private flushQueued;
+    /**
+     * Workspaces whose store copy may differ from memory after a synchronous
+     * write failed or conflicted. Each is reloaded from the store before the
+     * next call on it, which is refused while the reload fails.
+     */
+    private held;
+    /** Entries appended and not yet written, which the audit listeners hear of once they are. */
+    private unannounced;
     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.
+     * recorded refusals with their seq and code, and accepted calls with their
+     * seq. Rebuilt from the log when missing, so a snapshot never carries it.
      */
     private signedIndexes;
     /** Method handler registry; profiles plug into this. */
@@ -174,13 +218,21 @@ declare class Coordinator {
     private flush;
     private chainWrite;
     private writeChange;
-    /** The change since the last write, taking the recorded keys with it. */
+    /** Tell the audit listeners of the entries now written, up to `upTo`. */
+    private announce;
+    /**
+     * The change since the last write, taking the recorded keys with it. Each
+     * object is written as a copy in the shape a restore gives back, so a
+     * coordinator restarted on the store holds what this one holds, and the
+     * workspace's own objects are left as they are.
+     */
     private takeChange;
     /** A failed write's keys go back, so the next write carries them again. */
     private giveBack;
     /** Persist the whole workspace, for a store that implements only `save`. */
     private persistSnapshot;
     private trackSave;
+    private reportInternalError;
     private reportStoreError;
     drainSaves(): Promise<void>;
     private advanceClock;
@@ -201,19 +253,24 @@ declare class Coordinator {
      */
     private requireMember;
     /**
-     * Assert that `sender` was addressed in the task's review. Applied to
-     * review-decision methods (decide.* and abstain.declare): to act on a
-     * review you must be one of the reviewers it was addressed to (the
-     * `to` set on review.request). Membership is the floor; this is the
-     * eligibility ceiling for decisions. Returns an error fragment if not
-     * eligible, else null.
+     * Assert that `sender` may decide the task's open review. Applied to
+     * review-decision methods (decide.* and abstain.declare) and to
+     * review.acknowledge: to act on a review you must not be an author of the
+     * work under review, must be a human member where the task requires
+     * review, and must be one of the reviewers it was addressed to (the `to`
+     * set on review.request).
+     * Membership is the floor; this is the eligibility ceiling for decisions.
+     * Returns an error fragment if not eligible, else null.
      */
     private requireReviewer;
     /** Serialise all workspaces to a JSON-safe structure for persistence. */
     snapshot(): unknown;
     /** The workspace's own fields: everything except its collections and log. */
     private metaOf;
-    /** One workspace as `snapshot()` holds it. Reads nothing as a change. */
+    /**
+     * One workspace as `snapshot()` holds it: each object of its collections a
+     * copy in the shape the store keeps. Reads nothing as a change.
+     */
     private snapshotOf;
     /** Restore from a snapshot produced by ``snapshot()``. Replaces
      *  any existing in-memory workspaces. */
@@ -221,6 +278,24 @@ declare class Coordinator {
     /** One workspace from a snapshot entry, its maps tracked. */
     private rebuild;
     dispatch(envelope: Envelope): Envelope;
+    /**
+     * Work that changes a workspace outside any call, a whisper lapse check
+     * for one, kept to the rules a call keeps (SPECIFICATION 10.3): the
+     * workspace is first brought up to date with the store, and left alone
+     * as long as it is held; what the work changed is written once, when it ends;
+     * and where that write fails, the workspace goes back to what the store
+     * holds and the work's results are dropped, since none took effect.
+     */
+    outsideCall<T>(id: WorkspaceId, work: () => T[]): T[];
+    /**
+     * Before a call on a workspace: where the store holds a different number of
+     * audit entries for it than this instance last wrote, another writer has
+     * written it, and it is reloaded. A workspace held after a failed write is
+     * reloaded as well, and the call refused while that fails.
+     */
+    private keepUp;
+    /** Replace a workspace with what the store holds of it. False when it cannot be read. */
+    private reload;
     private _dispatch;
     recordAudit(ws: Workspace, envelope: Envelope): void;
     /**
@@ -236,6 +311,20 @@ declare class Coordinator {
     private signedIndex;
     private appendEntry;
     private verifySignature;
+    /**
+     * SPECIFICATION 6.5: an identity profile states that a verifier checks
+     * people's credentials, so advertising one this coordinator has no
+     * verifier for describes a guarantee it does not give.
+     */
+    private unverifiedIdentity;
+    /** Whether a workspace requires signatures: it advertises security-signed/1.0, or this coordinator is configured to. */
+    private requiresSignatures;
+    /**
+     * Whether a participant of this type signs its calls in a workspace that
+     * requires signatures: every participant under "all", and every one but an
+     * agent under "humans". A non-member signs.
+     */
+    private mustSign;
     /** Lookup the key valid for a given participant at a given time. */
     lookupKey(member: Member, kid: string, ts: string): KeyRecord | null;
     /**
@@ -253,15 +342,38 @@ declare class Coordinator {
     private registerCoreHandlers;
     private registerProfileHandlers;
     private opWorkspaceCreate;
+    /**
+     * The workspace a workspace.create with these params makes, or why it
+     * cannot be made. Nothing is registered, so participant.join can judge a
+     * join by the workspace it would make and make it only once the join
+     * passes.
+     */
+    private buildWorkspace;
+    private addWorkspace;
     private opWorkspaceDescribe;
     private opWorkspaceSetProfiles;
     private opParticipantJoin;
+    /**
+     * SPECIFICATION 6.3.3: an admin invites a participant. For a URI that is
+     * not a member it records an invitation, which the invitee's join takes
+     * up. For a member that holds no key in force it registers the
+     * invitation's keys: the way back for a member whose keys were all revoked,
+     * or who joined a workspace that requires signatures with none.
+     */
+    private opWorkspaceInvite;
     private opParticipantLeave;
     private opTaskCreate;
     private opTaskUpdate;
     private opTaskComplete;
     private opAuditRead;
     private opReviewRequest;
+    /**
+     * review/1.0 S3.6: a reviewer says they have begun the open review. Only
+     * someone who may decide it can, so the log's record of who took a review
+     * up, and when, names reviewers alone. It changes nothing else: the review
+     * stays open and the acknowledgement counts towards no rule.
+     */
+    private opReviewAcknowledge;
     /**
      * Verify an optional `approved_artefact_digest` against the artefact under
      * review (review/1.0 S3.2).
@@ -296,6 +408,7 @@ declare function makeApi(coord: Coordinator): {
         create: (p: MethodParams<"workspace.create">) => WorkspaceCreateResult;
         describe: (p: MethodParams<"workspace.describe">) => WorkspaceDescribeResult;
         set_profiles: (p: MethodParams<"workspace.set_profiles">) => OkResult;
+        invite: (p: MethodParams<"workspace.invite">) => WorkspaceInviteResult;
     };
     participant: {
         join: (p: MethodParams<"participant.join">) => OkResult;
@@ -311,6 +424,7 @@ declare function makeApi(coord: Coordinator): {
     };
     review: {
         request: (p: MethodParams<"review.request">) => ReviewRequestResult;
+        acknowledge: (p: MethodParams<"review.acknowledge">) => ReviewAcknowledgeResult;
         depth: (p: MethodParams<"review.depth">) => ReviewDepthResult;
     };
     decide: {

package/dist/{api-CxciGFHA.d.ts → api-DG0VFGVr.d.ts}

@@ -1,6 +1,6 @@
-import { MethodParams, WorkspaceCreateResult, WorkspaceDescribeResult, OkResult, TaskCreateResult, TaskRouteResult, ReviewRequestResult, ReviewDepthResult, DecideOverrideResult, EscalateRaiseResult, EscalateAutoResult, WhisperAskResult, DeliberateOpenResult, DeliberateCloseResult, HandoffProposeResult, ControlSupersedeResult, ControlSnapshotResult, AuditReadResult, AuditSubmitToScittResult, AuditVerifyReceiptResult, AuditVerifyChainResult, MethodName, MethodResult } from './methods.js';
+import { MethodParams, WorkspaceCreateResult, WorkspaceDescribeResult, OkResult, WorkspaceInviteResult, TaskCreateResult, TaskRouteResult, ReviewRequestResult, ReviewAcknowledgeResult, ReviewDepthResult, DecideOverrideResult, EscalateRaiseResult, EscalateAutoResult, WhisperAskResult, DeliberateOpenResult, DeliberateCloseResult, HandoffProposeResult, ControlSupersedeResult, ControlSnapshotResult, AuditReadResult, AuditSubmitToScittResult, AuditVerifyReceiptResult, AuditVerifyChainResult, MethodName, MethodResult } from './methods.js';
 import { Store } from './storage/store.js';
-import { Workspace, AuditListener, Task, ParticipantUri, Envelope, WorkspaceId, Member, KeyRecord } from './types.js';
+import { Workspace, SignaturePolicy, JoinPolicy, AuditListener, Task, ParticipantUri, Envelope, WorkspaceId, Member, KeyRecord } from './types.js';
 
 /**
  * @brightbeamai/chap-coordinator/ids
@@ -72,23 +72,59 @@ interface CoordinatorOptions {
     deterministicIds?: boolean;
     deterministicClock?: boolean;
     enableChain?: boolean;
+    /**
+     * Require signatures on every workspace, as advertising
+     * `security-signed/1.0` does on one.
+     */
     requireSignatures?: boolean;
+    /**
+     * The signature policy of a workspace whose `workspace.create` names none:
+     * "all" (the default) verifies every call, and "humans" takes an unsigned
+     * call from an agent member.
+     */
+    signaturePolicy?: SignaturePolicy;
+    /**
+     * The join policy of a workspace whose `workspace.create` names none:
+     * "open" (the default) admits anyone, and "invite" admits only a
+     * participant an admin invited, and the first member.
+     */
+    joinPolicy?: JoinPolicy;
     enforceStepUp?: boolean;
     requireReadMembership?: boolean;
     /** Largest envelope accepted (default 1 MiB), published in the descriptor. */
     maxEnvelopeBytes?: number;
+    /** Told of each audit entry once the store has taken it. */
     onAudit?: AuditListener;
     onAutoEscalate?: (task: Task, to: ParticipantUri) => void;
     /**
      * Called when a write to the store fails, with the workspace and the
      * version the write would have reached. When unset, the failure is written
-     * to stderr. The call itself has already succeeded in memory; the next
-     * write to the workspace carries what this one did not.
+     * to stderr. What happens to the call is `storeErrors`'s to say.
      */
     onStoreError?: (err: unknown, record: {
         id: string;
         version: number;
     }) => void;
+    /**
+     * What a failed synchronous write does to the call that made it. "raise"
+     * (the default): the call is answered with -32603 and
+     * `data: { reason: "store" }`, and the workspace goes back to what the
+     * store holds. "log": the call is answered as it was, and the next write
+     * carries its change again. A write another writer got to first is
+     * answered as "raise" says under either, and the call may be sent again.
+     * An asynchronous write's call was answered already, and the next write
+     * to the workspace carries what this one did not.
+     */
+    storeErrors?: "raise" | "log";
+    /**
+     * Called when a handler throws, with the error and the call's method and
+     * workspace. The caller is answered with -32603 and no detail. When unset,
+     * the error is written to stderr.
+     */
+    onInternalError?: (err: unknown, call: {
+        method: string;
+        workspace?: string;
+    }) => void;
     verifyOidcToken?: TokenVerifier;
     verifyVc?: CredentialVerifier;
     scittSubmitter?: ScittSubmitter;
@@ -130,13 +166,21 @@ declare class Coordinator {
     private unflushed;
     /** Workspaces with a write queued behind an async write in flight. */
     private flushQueued;
+    /**
+     * Workspaces whose store copy may differ from memory after a synchronous
+     * write failed or conflicted. Each is reloaded from the store before the
+     * next call on it, which is refused while the reload fails.
+     */
+    private held;
+    /** Entries appended and not yet written, which the audit listeners hear of once they are. */
+    private unannounced;
     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.
+     * recorded refusals with their seq and code, and accepted calls with their
+     * seq. Rebuilt from the log when missing, so a snapshot never carries it.
      */
     private signedIndexes;
     /** Method handler registry; profiles plug into this. */
@@ -174,13 +218,21 @@ declare class Coordinator {
     private flush;
     private chainWrite;
     private writeChange;
-    /** The change since the last write, taking the recorded keys with it. */
+    /** Tell the audit listeners of the entries now written, up to `upTo`. */
+    private announce;
+    /**
+     * The change since the last write, taking the recorded keys with it. Each
+     * object is written as a copy in the shape a restore gives back, so a
+     * coordinator restarted on the store holds what this one holds, and the
+     * workspace's own objects are left as they are.
+     */
     private takeChange;
     /** A failed write's keys go back, so the next write carries them again. */
     private giveBack;
     /** Persist the whole workspace, for a store that implements only `save`. */
     private persistSnapshot;
     private trackSave;
+    private reportInternalError;
     private reportStoreError;
     drainSaves(): Promise<void>;
     private advanceClock;
@@ -201,19 +253,24 @@ declare class Coordinator {
      */
     private requireMember;
     /**
-     * Assert that `sender` was addressed in the task's review. Applied to
-     * review-decision methods (decide.* and abstain.declare): to act on a
-     * review you must be one of the reviewers it was addressed to (the
-     * `to` set on review.request). Membership is the floor; this is the
-     * eligibility ceiling for decisions. Returns an error fragment if not
-     * eligible, else null.
+     * Assert that `sender` may decide the task's open review. Applied to
+     * review-decision methods (decide.* and abstain.declare) and to
+     * review.acknowledge: to act on a review you must not be an author of the
+     * work under review, must be a human member where the task requires
+     * review, and must be one of the reviewers it was addressed to (the `to`
+     * set on review.request).
+     * Membership is the floor; this is the eligibility ceiling for decisions.
+     * Returns an error fragment if not eligible, else null.
      */
     private requireReviewer;
     /** Serialise all workspaces to a JSON-safe structure for persistence. */
     snapshot(): unknown;
     /** The workspace's own fields: everything except its collections and log. */
     private metaOf;
-    /** One workspace as `snapshot()` holds it. Reads nothing as a change. */
+    /**
+     * One workspace as `snapshot()` holds it: each object of its collections a
+     * copy in the shape the store keeps. Reads nothing as a change.
+     */
     private snapshotOf;
     /** Restore from a snapshot produced by ``snapshot()``. Replaces
      *  any existing in-memory workspaces. */
@@ -221,6 +278,24 @@ declare class Coordinator {
     /** One workspace from a snapshot entry, its maps tracked. */
     private rebuild;
     dispatch(envelope: Envelope): Envelope;
+    /**
+     * Work that changes a workspace outside any call, a whisper lapse check
+     * for one, kept to the rules a call keeps (SPECIFICATION 10.3): the
+     * workspace is first brought up to date with the store, and left alone
+     * as long as it is held; what the work changed is written once, when it ends;
+     * and where that write fails, the workspace goes back to what the store
+     * holds and the work's results are dropped, since none took effect.
+     */
+    outsideCall<T>(id: WorkspaceId, work: () => T[]): T[];
+    /**
+     * Before a call on a workspace: where the store holds a different number of
+     * audit entries for it than this instance last wrote, another writer has
+     * written it, and it is reloaded. A workspace held after a failed write is
+     * reloaded as well, and the call refused while that fails.
+     */
+    private keepUp;
+    /** Replace a workspace with what the store holds of it. False when it cannot be read. */
+    private reload;
     private _dispatch;
     recordAudit(ws: Workspace, envelope: Envelope): void;
     /**
@@ -236,6 +311,20 @@ declare class Coordinator {
     private signedIndex;
     private appendEntry;
     private verifySignature;
+    /**
+     * SPECIFICATION 6.5: an identity profile states that a verifier checks
+     * people's credentials, so advertising one this coordinator has no
+     * verifier for describes a guarantee it does not give.
+     */
+    private unverifiedIdentity;
+    /** Whether a workspace requires signatures: it advertises security-signed/1.0, or this coordinator is configured to. */
+    private requiresSignatures;
+    /**
+     * Whether a participant of this type signs its calls in a workspace that
+     * requires signatures: every participant under "all", and every one but an
+     * agent under "humans". A non-member signs.
+     */
+    private mustSign;
     /** Lookup the key valid for a given participant at a given time. */
     lookupKey(member: Member, kid: string, ts: string): KeyRecord | null;
     /**
@@ -253,15 +342,38 @@ declare class Coordinator {
     private registerCoreHandlers;
     private registerProfileHandlers;
     private opWorkspaceCreate;
+    /**
+     * The workspace a workspace.create with these params makes, or why it
+     * cannot be made. Nothing is registered, so participant.join can judge a
+     * join by the workspace it would make and make it only once the join
+     * passes.
+     */
+    private buildWorkspace;
+    private addWorkspace;
     private opWorkspaceDescribe;
     private opWorkspaceSetProfiles;
     private opParticipantJoin;
+    /**
+     * SPECIFICATION 6.3.3: an admin invites a participant. For a URI that is
+     * not a member it records an invitation, which the invitee's join takes
+     * up. For a member that holds no key in force it registers the
+     * invitation's keys: the way back for a member whose keys were all revoked,
+     * or who joined a workspace that requires signatures with none.
+     */
+    private opWorkspaceInvite;
     private opParticipantLeave;
     private opTaskCreate;
     private opTaskUpdate;
     private opTaskComplete;
     private opAuditRead;
     private opReviewRequest;
+    /**
+     * review/1.0 S3.6: a reviewer says they have begun the open review. Only
+     * someone who may decide it can, so the log's record of who took a review
+     * up, and when, names reviewers alone. It changes nothing else: the review
+     * stays open and the acknowledgement counts towards no rule.
+     */
+    private opReviewAcknowledge;
     /**
      * Verify an optional `approved_artefact_digest` against the artefact under
      * review (review/1.0 S3.2).
@@ -296,6 +408,7 @@ declare function makeApi(coord: Coordinator): {
         create: (p: MethodParams<"workspace.create">) => WorkspaceCreateResult;
         describe: (p: MethodParams<"workspace.describe">) => WorkspaceDescribeResult;
         set_profiles: (p: MethodParams<"workspace.set_profiles">) => OkResult;
+        invite: (p: MethodParams<"workspace.invite">) => WorkspaceInviteResult;
     };
     participant: {
         join: (p: MethodParams<"participant.join">) => OkResult;
@@ -311,6 +424,7 @@ declare function makeApi(coord: Coordinator): {
     };
     review: {
         request: (p: MethodParams<"review.request">) => ReviewRequestResult;
+        acknowledge: (p: MethodParams<"review.acknowledge">) => ReviewAcknowledgeResult;
         depth: (p: MethodParams<"review.depth">) => ReviewDepthResult;
     };
     decide: {

package/dist/api.cjs

@@ -54,7 +54,8 @@ function makeApi(coord) {
     workspace: {
       create: (p) => c("workspace.create", p),
       describe: (p) => c("workspace.describe", p),
-      set_profiles: (p) => c("workspace.set_profiles", p)
+      set_profiles: (p) => c("workspace.set_profiles", p),
+      invite: (p) => c("workspace.invite", p)
     },
     participant: {
       join: (p) => c("participant.join", p),
@@ -70,6 +71,7 @@ function makeApi(coord) {
     },
     review: {
       request: (p) => c("review.request", p),
+      acknowledge: (p) => c("review.acknowledge", p),
       depth: (p) => c("review.depth", p)
     },
     decide: {