@brightbeamai/chap-coordinator 0.2.10 → 0.2.13

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 {

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

@@ -75,6 +75,8 @@ interface CoordinatorOptions {
     requireSignatures?: boolean;
     enforceStepUp?: boolean;
     requireReadMembership?: boolean;
+    /** Largest envelope accepted (default 1 MiB), published in the descriptor. */
+    maxEnvelopeBytes?: number;
     onAudit?: AuditListener;
     onAutoEscalate?: (task: Task, to: ParticipantUri) => void;
     verifyOidcToken?: TokenVerifier;

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

@@ -75,6 +75,8 @@ interface CoordinatorOptions {
     requireSignatures?: boolean;
     enforceStepUp?: boolean;
     requireReadMembership?: boolean;
+    /** Largest envelope accepted (default 1 MiB), published in the descriptor. */
+    maxEnvelopeBytes?: number;
     onAudit?: AuditListener;
     onAutoEscalate?: (task: Task, to: ParticipantUri) => void;
     verifyOidcToken?: TokenVerifier;

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-CcT_8H5j.cjs';
+export { b as CoordinatorApi, c as CoordinatorError, g as call, m as makeApi } from './api-DiiL0sil.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-Cvkhcalw.js';
+export { b as CoordinatorApi, c as CoordinatorError, g as call, m as makeApi } from './api-BOGEBNmX.js';
 import './types.js';
 import './storage/store.js';

package/dist/index.cjs

@@ -323,6 +323,11 @@ function isValidEnvelope(env) {
 var PatchError = class extends Error {
 };
 var DANGEROUS_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+var ARRAY_INDEX_RE = /^(0|[1-9][0-9]*)$/;
+function arrayIndex(seg) {
+  if (!ARRAY_INDEX_RE.test(seg)) throw new PatchError(`Array index expected at ${JSON.stringify(seg)}`);
+  return Number(seg);
+}
 function unescape(token) {
   return token.replace(/~1/g, "/").replace(/~0/g, "~");
 }
@@ -347,8 +352,8 @@ function navigate(doc, parts) {
   for (let i = 0; i < parts.length - 1; i++) {
     const part = parts[i];
     if (Array.isArray(parent)) {
-      const idx = Number(part);
-      if (!Number.isInteger(idx) || idx < 0 || idx >= parent.length) {
+      const idx = arrayIndex(part);
+      if (idx >= parent.length) {
         throw new PatchError(`Index out of range at /${parts.slice(0, i + 1).join("/")}`);
       }
       parent = parent[idx];
@@ -364,11 +369,7 @@ function navigate(doc, parts) {
   const last = parts[parts.length - 1];
   if (Array.isArray(parent)) {
     if (last === "-") return [parent, "-"];
-    const idx = Number(last);
-    if (!Number.isInteger(idx)) {
-      throw new PatchError(`Array index expected at ${JSON.stringify(last)}`);
-    }
-    return [parent, idx];
+    return [parent, arrayIndex(last)];
   }
   return [parent, last];
 }
@@ -819,7 +820,7 @@ function registerControl(coord) {
     if (scope === "task") {
       const task = ws.tasks.get(p.task_id);
       if (!task) return { error: rpcError(E.PARAMS, "Unknown task") };
-      if (task.state === "completed" || task.state === "declined" || task.state === "cancelled") {
+      if (task.state === "completed" || task.state === "declined" || task.state === "cancelled" || task.state === "superseded") {
         return { error: rpcError(E.CONTROL_NOT_AUTHORISED, `Cannot pause ${task.state} task`) };
       }
       task.paused = true;
@@ -876,7 +877,7 @@ function registerControl(coord) {
     if (!ws) return { error: rpcError(E.PARAMS, "Unknown workspace") };
     const task = ws.tasks.get(p.task_id);
     if (!task) return { error: rpcError(E.PARAMS, "Unknown task") };
-    if (task.state === "completed" || task.state === "declined" || task.state === "cancelled") {
+    if (task.state === "completed" || task.state === "declined" || task.state === "cancelled" || task.state === "superseded") {
       return { error: rpcError(E.CONTROL_NOT_AUTHORISED, `Cannot cancel ${task.state} task`) };
     }
     task.state = "cancelled";
@@ -898,7 +899,7 @@ function registerControl(coord) {
       }));
     }
     if (include.includes("open_tasks")) {
-      state.open_tasks = Array.from(ws.tasks.values()).filter((t) => t.state !== "completed" && t.state !== "declined" && t.state !== "cancelled").map((t) => ({ id: t.id, kind: t.kind, state: t.state, assignee: t.assignee }));
+      state.open_tasks = Array.from(ws.tasks.values()).filter((t) => t.state !== "completed" && t.state !== "declined" && t.state !== "cancelled" && t.state !== "superseded").map((t) => ({ id: t.id, kind: t.kind, state: t.state, assignee: t.assignee }));
     }
     if (include.includes("mode_ceiling")) state.mode_ceiling = ws.mode_ceiling;
     if (include.includes("policy")) state.routing_policy_uri = ws.routing_policy_uri;
@@ -966,6 +967,13 @@ function registerControl(coord) {
     if (!ws.members.has(assignee)) {
       return { error: rpcError(E.PARAMS, "successor assignee not in workspace") };
     }
+    const requestedMode = newSpec.mode ?? old.mode;
+    if (!modeLE(requestedMode, ws.mode_ceiling)) {
+      return { error: rpcError(
+        E.MODE_CEILING_EXCEEDED,
+        `Requested mode ${requestedMode} exceeds ceiling ${ws.mode_ceiling}`
+      ) };
+    }
     const now = coord.now();
     const newId = coord.ids.taskId();
     const newTask = {
@@ -977,7 +985,7 @@ function registerControl(coord) {
       input: newSpec.input ?? {},
       created_at: now,
       updated_at: now,
-      mode: newSpec.mode ?? old.mode,
+      mode: requestedMode,
       supersedes: old.id,
       history: [{
         ts: now,
@@ -987,6 +995,8 @@ function registerControl(coord) {
       }],
       paused: false
     };
+    if (ws.profiles.some((pr) => pr.startsWith("modes/")) && newTask.mode === "trial") newTask.review_required = true;
+    else if ("review_required" in newSpec) newTask.review_required = !!newSpec.review_required;
     ws.tasks.set(newId, newTask);
     old.state = "superseded";
     old.superseded_by = newId;
@@ -1740,6 +1750,8 @@ var READ_ONLY_METHODS = /* @__PURE__ */ new Set([
   "audit.verify_chain",
   "audit.verify_receipt"
 ]);
+var MAX_IDEMPOTENCY_KEYS = 1e4;
+var DEFAULT_MAX_ENVELOPE_BYTES = 1048576;
 function nowIso(clockMs) {
   const d = clockMs === void 0 ? /* @__PURE__ */ new Date() : new Date(clockMs);
   return d.toISOString().replace(/\.(\d{3})Z$/, ".$1Z");
@@ -1758,12 +1770,32 @@ function tagsError(p) {
 function linkHash(envelope, prev) {
   return sha256Hex(Buffer.concat([canonicalize(envelope), Buffer.from(prev, "utf-8")]));
 }
+function reviewRuleSupported(rule) {
+  if (rule === "any_one_approves" || rule === "all_approve") return true;
+  if (rule.startsWith("quorum:")) {
+    const arg = rule.slice("quorum:".length);
+    return /^[0-9]+$/.test(arg) && parseInt(arg, 10) >= 1;
+  }
+  return false;
+}
+function reviewSatisfied(review) {
+  const approvers = new Set(review.decisions.filter((d) => d.kind === "approve").map((d) => d.reviewer));
+  const rule = review.rule || "any_one_approves";
+  if (rule === "all_approve") {
+    const named = review.requested_to.filter((r) => !(r.startsWith("workspace:") || r.startsWith("group:")));
+    if (named.length === 0) return approvers.size >= 1;
+    return named.every((r) => approvers.has(r));
+  }
+  if (rule.startsWith("quorum:")) return approvers.size >= parseInt(rule.slice("quorum:".length), 10);
+  return approvers.size >= 1;
+}
 function reply(env, body) {
   const out = { jsonrpc: "2.0", id: env.id };
   if (body.error !== void 0) out.error = body.error;
   else out.result = body.result;
   return out;
 }
+var REVIEW_REQUEST_STOPPED = ["cancelled", "superseded", "paused"];
 var Coordinator = class {
   workspaces = /* @__PURE__ */ new Map();
   options;
@@ -1983,6 +2015,18 @@ var Coordinator = class {
     if (!isValidEnvelope(envelope) || !envelope.method) {
       return reply(envelope, { error: rpcError(E.REQUEST, "Invalid JSON-RPC 2.0 request") });
     }
+    const maxBytes = this.options.maxEnvelopeBytes ?? DEFAULT_MAX_ENVELOPE_BYTES;
+    let size = 0;
+    try {
+      size = canonicalize(envelope).length;
+    } catch {
+    }
+    if (size > maxBytes) {
+      return reply(envelope, { error: rpcError(
+        E.REQUEST,
+        `Envelope exceeds max_envelope_bytes (${size} > ${maxBytes})`
+      ) });
+    }
     const method = envelope.method;
     const rawParams = envelope.params;
     if (rawParams !== void 0 && rawParams !== null && (typeof rawParams !== "object" || Array.isArray(rawParams))) {
@@ -2007,7 +2051,7 @@ var Coordinator = class {
       const stale = this.checkStepUp(params);
       if (stale) return reply(envelope, { error: stale });
     }
-    if (method.startsWith("control.") || method.startsWith("deliberate.") || method.startsWith("handoff.")) {
+    if (method.startsWith("control.") || method.startsWith("deliberate.") || method.startsWith("handoff.") || method.startsWith("whisper.")) {
       const wsId2 = params.workspace;
       const ws = typeof wsId2 === "string" ? this.workspaces.get(wsId2) : void 0;
       if (ws) {
@@ -2116,6 +2160,9 @@ var Coordinator = class {
     if (member.keys.some((k) => k.kid === kid && k.revoked_at !== void 0 && now >= k.revoked_at)) {
       return rpcError(E.SIG_KEY_REVOKED, `Key ${kid} is revoked`);
     }
+    if (member.keys.some((k) => k.kid === kid && k.valid_until !== void 0 && now >= k.valid_until)) {
+      return rpcError(E.SIG_KEY_NOT_FOUND, `Key ${kid} is no longer valid`);
+    }
     const key = this.lookupKey(member, kid, ts);
     if (!key) {
       const revoked = member.keys.find((k) => k.kid === kid && k.revoked_at);
@@ -2131,9 +2178,8 @@ var Coordinator = class {
         return rpcError(E.SIG_VERIFY_FAILED, "Signature failed verification");
       }
       return null;
-    } catch (e) {
-      const msg = e instanceof Error ? e.message : String(e);
-      return rpcError(E.INTERNAL, `Signature check error: ${msg}`);
+    } catch {
+      return rpcError(E.SIG_VERIFY_FAILED, "Signature failed verification");
     }
   }
   /** Lookup the key valid for a given participant at a given time. */
@@ -2257,6 +2303,7 @@ var Coordinator = class {
       state: ws.state,
       mode: ws.mode,
       mode_ceiling: ws.mode_ceiling,
+      max_envelope_bytes: this.options.maxEnvelopeBytes ?? DEFAULT_MAX_ENVELOPE_BYTES,
       step_up_window_sec: ws.step_up_window_sec,
       profiles: ws.profiles,
       members: Array.from(ws.members.values()).map(memberToDict),
@@ -2397,10 +2444,14 @@ var Coordinator = class {
       history: [{ ts: now, from: p.from, state: "created" }],
       paused: false
     };
-    if (task.mode === "trial") task.review_required = true;
+    if (ws.profiles.some((pr) => pr.startsWith("modes/")) && task.mode === "trial") task.review_required = true;
     else if ("review_required" in p) task.review_required = !!p.review_required;
     ws.tasks.set(taskId, task);
-    if (typeof p.idempotency_key === "string") ws.idempotency_keys[p.idempotency_key] = taskId;
+    if (typeof p.idempotency_key === "string") {
+      ws.idempotency_keys[p.idempotency_key] = taskId;
+      const keys = Object.keys(ws.idempotency_keys);
+      if (keys.length > MAX_IDEMPOTENCY_KEYS) delete ws.idempotency_keys[keys[0]];
+    }
     return { result: { task_id: taskId, state: "created" } };
   }
   opTaskUpdate(p) {
@@ -2414,12 +2465,18 @@ var Coordinator = class {
     const legal = {
       created: ["in_progress", "declined", "paused"],
       in_progress: ["in_progress", "completed", "declined", "review_requested", "paused"],
-      review_requested: ["in_progress", "completed", "declined"],
+      review_requested: ["in_progress"],
       paused: ["in_progress", "cancelled"]
     };
     if (!legal[task.state]?.includes(newState)) {
       return { error: rpcError(E.PARAMS, `Illegal transition ${task.state} -> ${newState}`) };
     }
+    if (newState === "completed" && task.review_required) {
+      return { error: rpcError(
+        E.PARAMS,
+        "This task requires review. Submit the output with task.complete, which opens the review; a reviewer decision completes it."
+      ) };
+    }
     task.state = newState;
     task.updated_at = this.now();
     task.history.push({
@@ -2440,6 +2497,30 @@ var Coordinator = class {
     if (task.state !== "created" && task.state !== "in_progress") {
       return { error: rpcError(E.PARAMS, `Cannot complete task in state: ${task.state}`) };
     }
+    if (task.review_required) {
+      const now = this.now();
+      task.pending_artefact = p.output;
+      if (!task.review) {
+        const producer = p.from;
+        const eligible = [...ws.members.entries()].filter(([uri, member]) => uri !== producer && uri !== task.assignee && member.type === "human").map(([uri]) => uri);
+        if (eligible.length === 0) {
+          return { error: rpcError(
+            E.NOT_AUTHORISED,
+            "Task requires review but has no eligible human reviewer (needs a human member other than its assignee and completer)"
+          ) };
+        }
+        task.review = { requested_at: now, requested_to: eligible, rule: "any_one_approves", decisions: [] };
+      }
+      task.state = "review_requested";
+      task.updated_at = now;
+      task.history.push({
+        ts: now,
+        from: p.from,
+        state: "review_requested",
+        note: "review required; opened on task.complete"
+      });
+      return { result: { state: "review_requested", review_id: task.id } };
+    }
     task.output = p.output;
     if (typeof p.confidence === "number" || typeof p.confidence === "string") task.confidence = p.confidence;
     task.state = "completed";
@@ -2486,11 +2567,18 @@ var Coordinator = class {
     if (notMember) return notMember;
     const task = ws.tasks.get(p.task_id);
     if (!task) return { error: rpcError(E.PARAMS, "Unknown task") };
+    if (REVIEW_REQUEST_STOPPED.includes(task.state)) {
+      return { error: rpcError(E.NOT_REVIEWABLE, `Cannot request review for task in state: ${task.state}`) };
+    }
     const to = p.to;
     const reviewers = Array.isArray(to) ? to : typeof to === "string" ? [to] : [];
     if (!reviewers.length) return { error: rpcError(E.PARAMS, "review.request needs 'to'") };
     const now = this.now();
-    const rule = p.rule || "any_one_approves";
+    const declaredRule = p.rule;
+    const rule = declaredRule || "any_one_approves";
+    if (!reviewRuleSupported(rule)) {
+      return { error: rpcError(E.PARAMS, `Unsupported review rule ${JSON.stringify(rule)}: review/1.0 supports any_one_approves, all_approve, quorum:<n>`) };
+    }
     if (task.state === "review_requested" && task.review) {
       if (contentHash(task.pending_artefact) !== contentHash(p.artefact)) {
         return { error: rpcError(
@@ -2498,7 +2586,7 @@ var Coordinator = class {
           "A review is already open on this task with different content. Decide, abstain, escalate or cancel it before requesting review of a new artefact."
         ) };
       }
-      if (rule !== task.review.rule) {
+      if (declaredRule !== void 0 && declaredRule !== task.review.rule) {
         return { error: rpcError(
           E.REVIEW_ALREADY_OPEN,
           `Cannot change the decision rule of an open review (currently ${task.review.rule})`
@@ -2587,8 +2675,10 @@ var Coordinator = class {
       tags: p.tags
     });
     if (kind === "approve") {
-      task.output = task.pending_artefact;
-      task.state = "completed";
+      if (reviewSatisfied(task.review)) {
+        task.output = task.pending_artefact;
+        task.state = "completed";
+      }
     } else {
       task.state = p.request_revision ? "in_progress" : "declined";
     }