@michelj/context-guard 0.4.4 → 0.6.2

package/scripts/shared/protocol-workflow.mjs

@@ -0,0 +1,226 @@
+import { randomUUID } from 'node:crypto';
+import { canonical, fail } from './protocol.mjs';
+import { hash } from './io.mjs';
+
+export const workflowTypes = new Set(['brief.submit', 'review.request', 'review.result', 'task.assign', 'task.message', 'task.report', 'task.rework', 'ci.request', 'ci.result', 'executor.state', 'task.control']);
+export const scopedObjectKey = (p, session, ref) => hash(canonical([p.repositoryId, session.id, session.generation, ref]));
+
+// All effects stay inside ProtocolStore's transaction. Model calls and GitHub
+// polling belong to authenticated adapters, never to this state machine.
+export async function reduceWorkflow(state, principal, message, emit, policy = {}) {
+  const { payload: p, session } = message;
+  const belongs = value => value.repositoryId === principal.repositoryId && canonical(value.session) === canonical(session);
+  const role = (...roles) => { if (!roles.includes(principal.role)) fail('FORBIDDEN', 'This operation requires a different registered role'); };
+  const taskKey = id => scopedObjectKey(principal, session, `task:${id}`);
+  const read = (ref, version, kind) => {
+    const object = state.objects[scopedObjectKey(principal, session, ref)];
+    const saved = object?.versions[version || object.latest];
+    if (!saved || kind && saved.kind !== kind) fail('NOT_FOUND', 'Referenced object or version is missing');
+    return { ...saved, version: version || object.latest };
+  };
+  const put = (ref, kind, content, version = randomUUID()) => {
+    const key = scopedObjectKey(principal, session, ref);
+    const object = state.objects[key] ||= { latest: '', versions: {} };
+    object.versions[version] = { kind, content: structuredClone(content) }; object.latest = version;
+    return { ref, version };
+  };
+  const changed = task => { task.version = randomUUID(); return { taskId: task.id, version: task.version, stage: task.stage }; };
+  const releaseSlot = task => {
+    task.busy = false;
+    if (Object.values(state.tasks).some(value => belongs(value) && value.busy)) return {};
+    const next = Object.values(state.tasks)
+      .filter(value => belongs(value) && value.stage === 'queued' && value.assignmentNotification)
+      .sort((left, right) => (left.assignmentOrder || 0) - (right.assignmentOrder || 0) || String(left.queuedAt || '').localeCompare(String(right.queuedAt || '')) || left.id.localeCompare(right.id))[0];
+    if (!next) return {};
+    next.busy = true; next.stage = 'assigned'; delete next.queuedAt;
+    next.assignmentSeq = emit(next.assignmentNotification); changed(next);
+    return { activatedTaskId: next.id };
+  };
+  const notify = (source = message) => emit({ ...source, id: randomUUID() });
+  if (message.type === 'brief.submit') {
+    role('coordinator');
+    const key = taskKey(p.taskId), previous = state.tasks[key];
+    if (previous && !['brief', 'brief-rejected'].includes(previous.stage)) fail('CONFLICT', 'The approved task cannot be rewritten');
+    const brief = put(`brief:${p.taskId}`, 'brief', { text: p.text, taskId: p.taskId });
+    const task = state.tasks[key] = { id: p.taskId, repositoryId: principal.repositoryId, session, brief, stage: 'brief', busy: false };
+    notify();
+    return { ...changed(task), ...brief };
+  }
+  let task = p.taskId ? state.tasks[taskKey(p.taskId)] : null;
+  if (message.type === 'review.result') {
+    task = Object.values(state.tasks).find(value => belongs(value) &&
+      value.review?.ref === p.ref && value.review?.version === p.version && value.review?.kind === p.kind);
+  }
+  if (message.type === 'executor.state') {
+    const executorId = principal.role === 'device'
+      ? Object.values(state.bindings).find(binding => binding.sessionId === session.id && binding.deviceId === principal.deviceId)?.agentId
+      : principal.agentId;
+    if (p.agentId !== executorId) fail('FORBIDDEN', 'Executor identity differs');
+    const tasks = Object.values(state.tasks).filter(value => belongs(value) && value.busy);
+    if (p.state === 'idle' && tasks.length || p.state === 'busy' && !tasks.some(value => value.id === p.taskId)) fail('CONFLICT', 'Executor state is determined by the task lifecycle');
+    return { state: tasks.length ? 'busy' : 'idle', ...(tasks.length ? { taskId: tasks[0].id } : {}) };
+  }
+  if (!task) fail('NOT_FOUND', 'Task is not registered in this Session');
+  const at = (...stages) => { if (!stages.includes(task.stage)) fail('CONFLICT', 'Task is at a different stage', { currentVersion: task.version }); };
+  if (message.type === 'task.message') {
+    role('coordinator');
+    at('assigned', 'plan-ready', 'plan-rejected', 'executing', 'rework', 'accepted');
+    if (Boolean(p.planRef) !== Boolean(p.planVersion) ||
+        p.planRef && (task.plan?.ref !== p.planRef || task.plan.version !== p.planVersion)) fail('CONFLICT', 'Task Plan changed before guidance');
+    const notification = { ...structuredClone(message), id: randomUUID() };
+    const seq = emit(notification);
+    return { taskId: task.id, version: task.version, stage: task.stage, notificationId: notification.id, seq };
+  }
+  if (message.type === 'review.request') {
+    role('coordinator');
+    if (p.kind === 'brief') {
+      at('brief');
+      if (p.ref !== task.brief.ref || p.version !== task.brief.version) fail('CONFLICT', 'Brief version differs');
+    } else {
+      at('plan-ready');
+      if (p.ref !== task.plan.ref || p.version !== task.plan.version || p.requirementsRef !== task.brief.ref || p.requirementsVersion !== task.brief.version) fail('CONFLICT', 'Plan or approved requirements differ');
+    }
+    task.review = structuredClone(p); notify(); return changed(task);
+  }
+  if (message.type === 'review.result') {
+    role(p.kind === 'plan' ? 'coordinator' : 'human');
+    if (p.receiptId) fail('FORBIDDEN', 'Review receipts are issued by the backend');
+    at(p.kind === 'brief' ? 'brief' : p.kind === 'acceptance' ? 'awaiting-merge' : 'plan-ready');
+    const receiptId = randomUUID();
+    const receipt = put(receiptId, 'reviewReceipt', { ...p, receiptId, issuer: principal.agentId }, receiptId);
+    task[`${p.kind}Review`] = { ...receipt, decision: p.decision, reason: p.reason };
+    if (p.kind === 'acceptance') task.acceptanceAt = new Date().toISOString();
+    task.stage = p.decision === 'approved' ? ({ brief: 'approved', plan: 'executing', acceptance: 'accepted' }[p.kind]) : `${p.kind}-rejected`;
+    delete task.review;
+    emit({ ...message, id: randomUUID(), payload: { ...p, receiptId } });
+    const status = changed(task);
+    const released = p.kind === 'acceptance' && p.decision === 'approved' ? releaseSlot(task) : {};
+    return { ...status, ...released, taskVersion: status.version, receiptId, version: receipt.version };
+  }
+  if (message.type === 'task.assign') {
+    role('coordinator'); at('approved');
+    if (p.briefRef !== task.brief.ref || p.briefVersion !== task.brief.version || task.briefReview?.decision !== 'approved') fail('CONFLICT', 'Human approval does not match this brief');
+    if (!await policy.verifyRouting?.(principal, message)) fail('FORBIDDEN', 'Main version and node access could not be verified');
+    task.assignment = structuredClone(p);
+    task.assignmentOrder = state.taskSequence = (state.taskSequence || 0) + 1;
+    task.assignmentNotification = { ...structuredClone(message), id: randomUUID() };
+    if (Object.values(state.tasks).some(value => belongs(value) && value.busy)) {
+      task.busy = false; task.stage = 'queued'; task.queuedAt = new Date().toISOString();
+      return changed(task);
+    }
+    task.busy = true; task.stage = 'assigned'; task.assignmentSeq = emit(task.assignmentNotification);
+    return changed(task);
+  }
+  if (message.type === 'task.report') {
+    role('executor', 'device');
+    if (!task.busy && !(p.stage === 'closed' && task.stage === 'closing')) fail('CONFLICT', 'Task is not active');
+    if (['started', 'finished'].includes(p.stage)) {
+      if (task.assignment?.mode !== 'session' || p.data.deliveryId !== task.assignmentNotification?.id) fail('CONFLICT', 'Execution report differs from the dispatched Session task');
+      if (p.stage === 'started') { at('assigned'); task.stage = 'executing'; task.startedAt = new Date().toISOString(); }
+      else {
+        at('executing'); task.stage = 'finished'; task.busy = false;
+        task.result = { ...structuredClone(p.data), finishedAt: new Date().toISOString() };
+      }
+    } else if (p.stage === 'planReady') {
+      at('assigned', 'plan-rejected', 'rework'); read(p.data.planRef, p.data.planVersion, 'plan');
+      task.plan = { ref: p.data.planRef, version: p.data.planVersion }; task.sourceSha = p.data.sourceSha; task.stage = 'plan-ready';
+    } else if (p.stage === 'progress') {
+      at('executing');
+      if (p.data.seq <= (task.progress?.seq ?? -1)) fail('CONFLICT', 'Progress sequence did not advance');
+      task.progress = structuredClone(p.data);
+    } else if (p.stage === 'interrupted') {
+      if (task.interrupted && Date.parse(p.data.occurredAt) <= Date.parse(task.interrupted.occurredAt)) fail('CONFLICT', 'Interruption observation did not advance');
+      task.interrupted = structuredClone(p.data);
+      // A second interruption during recovery must retain the business stage,
+      // otherwise a resumed receipt returns to "resuming" forever.
+      if (!['interrupted', 'resuming'].includes(task.stage)) task.previousStage = task.stage;
+      task.stage = 'interrupted';
+    } else if (p.stage === 'handoff') {
+      at('executing');
+      const refs = [p.data.ciTodoRef, ...p.data.unitTestRefs, ...p.data.experienceRefs];
+      task.references = Object.fromEntries(refs.map(ref => [ref, read(ref).version]));
+      read(p.data.ciTodoRef, task.references[p.data.ciTodoRef], 'ciTodo');
+      for (const ref of p.data.unitTestRefs) read(ref, task.references[ref], 'evidence');
+      for (const ref of p.data.experienceRefs) read(ref, task.references[ref], 'experience');
+      task.handoff = structuredClone(p.data); task.sourceSha = p.data.sourceSha; task.stage = 'awaiting-ci';
+    } else {
+      if (!task.control || p.data.controlId !== task.control.id) fail('CONFLICT', 'Control receipt differs');
+      if (p.stage === 'cancelled') { at('cancelling'); task.stage = 'cancelled'; }
+      else if (p.stage === 'resumed') {
+        // A retried control can arrive in another native turn with a new request
+        // ID. Acknowledge the same applied control without rewinding the task.
+        if (task.control.resumed) return { taskId: task.id, version: task.version, stage: task.stage };
+        at('resuming'); task.stage = task.previousStage; task.control.resumed = true;
+      }
+      else {
+        at('closing');
+        if (!await policy.verifyClose?.(principal, task, p.data)) fail('FORBIDDEN', 'Close receipt is not verified');
+        task.stage = 'closed'; task.busy = false;
+      }
+    }
+    notify();
+    const status = changed(task);
+    if (['closed', 'finished'].includes(task.stage)) Object.assign(status, releaseSlot(task));
+    return status;
+  }
+  if (message.type === 'ci.request') {
+    role('coordinator', 'ci'); at('awaiting-ci');
+    if (policy.verifyCiReceiver && !await policy.verifyCiReceiver(state, principal, session)) fail('UNAVAILABLE', 'Configure one matching independent CI receiver before requesting tests', { reason: 'CI_RECEIVER_REQUIRED' });
+    if (p.sourceSha !== task.sourceSha || p.ciTodoRef !== task.handoff.ciTodoRef || canonical(p.unitTestRefs) !== canonical(task.handoff.unitTestRefs)) fail('CONFLICT', 'CI request differs from the handoff');
+    const references = Object.fromEntries([p.ciTodoRef, ...p.unitTestRefs].map(ref => [ref, task.references[ref]]));
+    if (p.references && canonical(p.references) !== canonical(references)) fail('CONFLICT', 'CI object versions differ from the handoff');
+    task.stage = 'testing'; notify({ ...message, payload: { ...p, references } }); return changed(task);
+  }
+  if (message.type === 'ci.result') {
+    role('ci'); at('testing');
+    if (p.sourceSha !== task.sourceSha) fail('CONFLICT', 'CI tested a different source commit');
+    if (p.verdict === 'passed' && p.checks.some(check => check.status !== 'passed')) fail('CONFLICT', 'CI checks do not support the verdict');
+    if (new Set(p.checks.map(check => check.testId)).size !== p.checks.length) fail('INVALID_ARGUMENT', 'Duplicate test ID');
+    const todoRef = task.handoff.ciTodoRef, todoVersion = task.references[todoRef];
+    const todo = read(todoRef, todoVersion, 'ciTodo');
+    if (read(todoRef).version !== todoVersion) fail('CONFLICT', 'CI TODO changed after handoff');
+    const items = todo.content.items;
+    if (!Array.isArray(items) || !items.length || items.some(item => typeof item?.id !== 'string' || !item.id || item.id.length > 128) || new Set(items.map(item => item.id)).size !== items.length) fail('INVALID_ARGUMENT', 'CI TODO requires uniquely numbered items');
+    if (p.checks.some(check => !items.some(item => item.id === check.todoId))) fail('CONFLICT', 'CI result references an unknown TODO');
+    if (p.verdict === 'passed' && items.some(item => !p.checks.some(check => check.todoId === item.id && check.status === 'passed'))) fail('CONFLICT', 'CI did not cover every handed-off TODO');
+    const references = {};
+    for (const check of p.checks) {
+      references[check.evidenceRef] = read(check.evidenceRef, undefined, 'evidence').version;
+      if (check.reproductionRef) references[check.reproductionRef] = read(check.reproductionRef, undefined, 'evidence').version;
+    }
+    task.ci = { ...put(`ci:${p.taskId}:${randomUUID()}`, 'ciResult', { ...p, references }), verdict: p.verdict };
+    const annotated = items.map(item => {
+      const checks = p.checks.filter(check => check.todoId === item.id);
+      return { ...item, status: checks.length && checks.every(check => check.status === 'passed') ? 'done' : 'pending', testIds: checks.map(check => check.testId) };
+    });
+    task.ciTodoResult = put(todoRef, 'ciTodo', { ...todo.content, items: annotated, ciResultRef: task.ci.ref });
+    task.stage = p.verdict === 'passed' ? 'awaiting-merge' : 'ci-failed';
+    if (p.verdict === 'passed') task.review = { kind: 'acceptance', ref: task.ci.ref, version: task.ci.version };
+    delete task.acceptanceReview;
+    notify();
+    return { ...changed(task), ...task.ci, ciTodo: task.ciTodoResult };
+  }
+  if (message.type === 'task.rework') {
+    role('coordinator'); at('ci-failed', 'acceptance-rejected');
+    if (p.sourceSha !== task.sourceSha || p.ciResultRef !== task.ci.ref) fail('CONFLICT', 'Rework does not reference the failed revision');
+    const result = read(task.ci.ref, task.ci.version, 'ciResult');
+    if (task.stage === 'acceptance-rejected' && (p.reason !== task.acceptanceReview?.reason || p.failedTestIds.length)) fail('CONFLICT', 'Preserve the human rejection feedback; do not invent failed CI tests');
+    if (p.failedTestIds.some(id => !result.content.checks.some(check => check.testId === id && check.status !== 'passed'))) fail('CONFLICT', 'Rework test IDs differ from CI evidence');
+    task.rework = structuredClone(p); task.stage = 'rework'; notify(); return changed(task);
+  }
+  if (message.type === 'task.control') {
+    role('coordinator');
+    if (p.expectedVersion !== task.version) fail('CONFLICT', 'Task changed', { currentVersion: task.version });
+    if (!task.busy && p.action !== 'complete') fail('CONFLICT', 'Task has no execution slot');
+    if (p.action === 'complete') {
+      at('accepted', 'cancelled');
+      const verified = await policy.verifyCompletion?.(principal, task, p.data);
+      if (!verified) fail('FORBIDDEN', 'Completion policy and receipts are not verified');
+      task.completion = { proof: structuredClone(verified), closeReceiptId: message.id };
+      task.stage = 'closing';
+    } else if (p.action === 'resume') { at('interrupted', 'cancelled'); task.stage = 'resuming'; }
+    else { if (['closing', 'closed', 'cancelling'].includes(task.stage)) fail('CONFLICT', 'Control already pending'); task.previousStage = task.stage; task.stage = 'cancelling'; }
+    task.control = { id: message.id, action: p.action }; emit(structuredClone(message)); return changed(task);
+  }
+  fail('INVALID_ARGUMENT', 'Unsupported task operation');
+}

package/scripts/shared/protocol.mjs

@@ -0,0 +1,125 @@
+// Shared wire validation. Authentication and business authorization run separately.
+export class ProtocolError extends Error {
+  constructor(code, message, details) {
+    super(message); this.code = code; this.details = details;
+    this.status = ({ UNAUTHORIZED: 401, FORBIDDEN: 403, NOT_FOUND: 404, CONFLICT: 409, ID_REUSED: 409, STALE_SESSION: 409, TOO_LARGE: 413, UNAVAILABLE: 503 })[code] || 400;
+  }
+}
+export const fail = (code, message, details) => { throw new ProtocolError(code, message, details); };
+export const MAX_MESSAGE_BYTES = 256 * 1024;
+const check = (ok, where) => { if (!ok) fail('INVALID_ARGUMENT', `Invalid ${where}`); };
+const string = (max = 128, empty = false) => (v, p) => check(typeof v === 'string' && (empty || v.trim().length > 0) && v.length <= max, p);
+const id = string(), version = string(4096), emptyVersion = string(4096, true), text = string(2000);
+const integer = (min = 0, max = Number.MAX_SAFE_INTEGER) => (v, p) => check(Number.isSafeInteger(v) && v >= min && v <= max, p);
+const choice = (...values) => (v, p) => check(values.includes(v), p);
+const optional = rule => Object.assign((v, p) => { if (v !== undefined) rule(v, p); }, { optional: true });
+const object = fields => (v, p = 'payload') => {
+  check(v !== null && typeof v === 'object' && !Array.isArray(v), p);
+  check(Object.keys(v).every(k => Object.hasOwn(fields, k)), `${p} fields`);
+  for (const [key, rule] of Object.entries(fields)) { check(rule.optional || Object.hasOwn(v, key), `${p}.${key}`); rule(v[key], `${p}.${key}`); }
+};
+const array = (rule, min = 0, max = 100) => (v, p) => { check(Array.isArray(v) && v.length >= min && v.length <= max, p); v.forEach((x, i) => rule(x, `${p}[${i}]`)); };
+const ids = (v, p) => { array(id, 1)(v, p); check(new Set(v).size === v.length, p); };
+const jsonObject = (v, p) => check(v !== null && typeof v === 'object' && !Array.isArray(v), p);
+const sha = (v, p) => check(typeof v === 'string' && /^[a-f0-9]{40}$/.test(v), p);
+const session = object({ id, generation: integer(1) });
+const refs = array(id);
+const reportData = {
+  started: object({ deliveryId: id }),
+  finished: object({ deliveryId: id, outcome: choice('success', 'failed', 'cancelled'), summary: text }),
+  planReady: object({ planRef: id, planVersion: version, sourceSha: sha }),
+  progress: object({ seq: integer(), summary: text }),
+  interrupted: object({ reason: text, occurredAt: (v, p) => check(typeof v === 'string' && /^\d{4}-\d\d-\d\dT.*(?:Z|[+-]\d\d:\d\d)$/.test(v) && Number.isFinite(Date.parse(v)), p) }),
+  handoff: object({ sourceSha: sha, ciTodoRef: id, unitTestRefs: refs, experienceRefs: refs }),
+  cancelled: object({ controlId: id }), resumed: object({ controlId: id }), closed: object({ controlId: id, closeReceiptId: id }),
+};
+const controls = {
+  cancel: object({ reason: text }), resume: object({ reason: text }),
+  complete: object({ gitReceiptRef: optional(id), cloudReceiptRef: optional(id), archiveReceiptRef: id }),
+};
+const fields = {
+  node: { parentId: optional(id), title: text, purpose: optional(text), kind: choice('module', 'work'), state: choice('dirty', 'untested', 'success', 'failed'), order: optional(integer()), proposal: optional(choice('proposed', 'accepted', 'cancelled')),
+    owns: optional(array(string(500), 1)), proposalEvidence: optional(object({ parentId: id, basis: choice('new-module', 'new-interface', 'new-component', 'new-responsibility'), reason: string(1000), files: array(string(500), 1) })) },
+  todo: { nodeId: id, title: text, status: choice('pending', 'processing', 'done'), description: optional(text) },
+  bug: { nodeId: id, title: text, status: choice('open', 'resolved'), reproduction: optional(text) },
+  message: { nodeId: optional(id), text },
+  memory: { nodeId: id, text, refs: optional(array(object({ ref: id, version }))) },
+  idea: { nodeId: id, text, refs: optional(array(object({ ref: id, version }))) },
+  relation: { from: id, to: id, label: optional(text) },
+  access: { nodeId: id, agentId: id, allow: choice('read', 'write', 'none') },
+};
+const change = (v, p) => {
+  object({ op: choice('create', 'update', 'delete'), kind: choice(...Object.keys(fields)), id, fields: optional(jsonObject) })(v, p);
+  if (v.op === 'delete') { check(!Object.hasOwn(v, 'fields'), p); return; }
+  const rules = v.op === 'update' ? Object.fromEntries(Object.entries(fields[v.kind]).map(([k, r]) => [k, optional(r)])) : fields[v.kind];
+  object(rules)(v.fields, `${p}.fields`);
+  check(Object.keys(v.fields).length > 0, `${p}.fields`);
+};
+export const payloadRules = {
+  'object.put': object({ kind: choice('plan', 'evidence', 'experience', 'ciTodo'), ref: id, baseVersion: emptyVersion, content: jsonObject }),
+  'object.read': object({ ref: id, version }),
+  'auth.open': object({ repository: string(2048), password: string(1024), clientId: id }),
+  'auth.close': object({}),
+  'sync.heartbeat': object({ creationResults: optional(array(object({ id, error: string(80) }), 0, 20)), sessions: array(object({
+    id,
+    generation: integer(1),
+    ackedSeq: integer(),
+    name: optional(string(240)),
+    platform: optional(string(64)),
+    execution: optional(object({ status: choice('active', 'stopped', 'interrupted', 'failed', 'unknown'), at: string(64, true) })),
+  })) }),
+  'sync.read': object({ afterSeq: integer(), limit: integer(1, 100) }),
+  'sync.ack': object({ items: array((v, p) => { object({ seq: integer(1), outcome: choice('applied', 'rejected', 'cancelled'), reason: optional(text), deliveryState: optional(choice('stored', 'received', 'uncertain')) })(v, p); check(v.outcome === 'applied' || !!v.reason, p); }, 1) }),
+  'sync.event': object({ latestSeq: integer() }),
+  'workbench.patch': object({ baseVersion: version, changes: array(change, 1) }),
+  'main.structure.patch': object({ baseVersion: version, changes: array(change, 1) }),
+  'workbench.read': v => {
+    object({ scope: choice('main', 'session'), nodeIds: optional(ids), version: optional(version), cursor: string(4096, true), limit: integer(1, 100), recovery: optional(choice(true, false)) })(v);
+    check(!v.recovery || v.scope === 'session' && !v.nodeIds, 'recovery scope');
+  },
+  'blob.put': object({ name: string(255), size: integer(0, 64 * 1024 * 1024), sha256: (v, p) => check(typeof v === 'string' && /^[a-f0-9]{64}$/.test(v), p), mediaType: string(255) }),
+  'blob.get': object({ blobId: id }),
+  'merge.request': object({ sessionVersion: version, baseMainVersion: version, sourceSha: sha, contentRef: id }),
+  'merge.result': v => { object({ mergeId: id, state: choice('merged', 'conflict', 'failed'), mainVersion: optional(version), error: optional(text) })(v); check(v.state === 'merged' ? !!v.mainVersion : !!v.error, 'merge result'); },
+  'brief.submit': object({ taskId: id, text }),
+  'review.request': v => { object({ kind: choice('brief', 'plan'), ref: id, version, taskId: id, requirementsRef: optional(id), requirementsVersion: optional(version), rulesVersion: optional(version) })(v); if (v.kind === 'plan') check(!!v.requirementsRef && !!v.requirementsVersion && !!v.rulesVersion, 'plan review references'); },
+  'review.result': object({ kind: choice('brief', 'plan', 'acceptance'), ref: id, version, decision: choice('approved', 'rejected'), reason: text, receiptId: optional(id) }),
+  'task.assign': object({ taskId: id, briefRef: id, briefVersion: version, sessionId: id, nodeIds: ids, mainVersion: version, mode: optional(choice('session', 'reviewed')) }),
+  'task.message': object({ taskId: id, text, planRef: optional(id), planVersion: optional(version) }),
+  'task.report': v => { object({ taskId: id, stage: choice(...Object.keys(reportData)), data: jsonObject })(v); reportData[v.stage](v.data); },
+  'task.rework': v => { object({ taskId: id, sourceSha: sha, ciResultRef: id, failedTestIds: refs, reason: optional(text) })(v); check(v.failedTestIds.length > 0 || !!v.reason, 'rework evidence or human feedback'); check(new Set(v.failedTestIds).size === v.failedTestIds.length, 'unique failed tests'); },
+  'ci.request': object({ taskId: id, sourceSha: sha, ciTodoRef: id, unitTestRefs: refs, references: optional(jsonObject) }),
+  'ci.result': object({ taskId: id, sourceSha: sha, verdict: choice('passed', 'failed', 'incomplete'), checks: array(v => { object({ testId: id, todoId: id, status: choice('passed', 'failed', 'incomplete'), evidenceRef: id, reproductionRef: optional(id) })(v); check(v.status !== 'failed' || !!v.reproductionRef, 'failed check reproduction'); }, 1) }),
+  'executor.state': v => { object({ agentId: id, state: choice('busy', 'idle'), taskId: optional(id) })(v); check(v.state === 'busy' ? !!v.taskId : v.taskId === undefined, 'executor task'); },
+  'session.bind': object({ sessionId: id, worktreeId: id, agentId: id, expectedBindingVersion: emptyVersion }),
+  'task.control': v => { object({ taskId: id, action: choice(...Object.keys(controls)), expectedVersion: version, data: jsonObject })(v); controls[v.action](v.data); },
+};
+const projectTypes = new Set(['auth.open', 'auth.close', 'sync.heartbeat', 'session.bind', 'main.structure.patch']);
+export function validateMessage(input) {
+  let bytes;
+  try { bytes = Buffer.byteLength(JSON.stringify(input)); } catch { fail('INVALID_ARGUMENT', 'Message must be JSON'); }
+  if (bytes > MAX_MESSAGE_BYTES) fail('TOO_LARGE', 'Message exceeds 256 KiB');
+  const pending = [[input, 0]];
+  while (pending.length) {
+    const [value, depth] = pending.pop();
+    check(depth <= 64, 'JSON nesting depth');
+    if (value === null || typeof value === 'string' || typeof value === 'boolean') continue;
+    if (typeof value === 'number') { check(Number.isFinite(value), 'JSON number'); continue; }
+    check(typeof value === 'object' && (Array.isArray(value) || Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null), 'JSON value');
+    for (const child of Object.values(value)) pending.push([child, depth + 1]);
+  }
+  object({ v: choice(2), id, type: choice(...Object.keys(payloadRules)), session: optional(session), payload: jsonObject })(input, 'message');
+  check(projectTypes.has(input.type) ? input.session === undefined : input.session !== undefined, 'message.session');
+  payloadRules[input.type](input.payload);
+  if (input.type === 'task.assign') check(input.payload.sessionId === input.session.id, 'assignment session');
+  return input;
+}
+export function errorReply(id, error) {
+  const known = error instanceof ProtocolError;
+  return { id, ok: false, error: { code: known ? error.code : 'UNAVAILABLE', message: known ? error.message : 'Operation temporarily unavailable', retryable: !known || error.code === 'UNAVAILABLE', ...(known && error.details ? { details: error.details } : {}) } };
+}
+export function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (value && typeof value === 'object') return `{${Object.keys(value).sort().map(k => `${JSON.stringify(k)}:${canonical(value[k])}`).join(',')}}`;
+  return JSON.stringify(value);
+}