agents-can-communicate 0.1.0

package/node_modules/@agents-can-communicate/protocol/src/schema.mjs

@@ -0,0 +1,175 @@
+import { AccError, EXIT } from "./errors.mjs";
+import { flag, id, invalid, listOf, nullable, oneOf, plainObject, positiveInteger,
+  resourceUri, sequence, text, timestamp } from "./fields.mjs";
+
+export const SCHEMA_VERSION = 1;
+
+const line = text();
+const prose = text({ max: 4000, multiline: true });
+const summary = text({ max: 280 });
+const artifactKind = oneOf("file", "git", "url", "report", "image", "data");
+
+/** @typedef {{ sequence: string, eventId: string, workspaceId: string,
+ * actorSessionId: string, type: string, occurredAt: string, payload: object }} AccEvent */
+/** @typedef {{ cursor: string, events: AccEvent[] }} EventPage */
+/** @typedef {{ kind: string, priority: number, sourceId: string, summary: string }} AttentionItem */
+/** @typedef {{ workspace: object, participants: object[], sessions: object[],
+ * intents: object[], workstreams: object[], tasks: object[], claims: object[] }} WorkspaceSnapshot */
+
+// Field names stay mappable to the A2A Agent Card, Task, Message, and Artifact
+// concepts (spec section 11) without importing any A2A transport.
+const artifactRef = (value, field) => {
+  plainObject(value, field);
+  const known = new Set(["kind", "uri", "description", "sha256"]);
+  for (const key of Object.keys(value)) {
+    if (!known.has(key)) invalid(`${field}.${key}`, "is not a known artifact field", value[key]);
+  }
+  artifactKind(value.kind, `${field}.kind`);
+  resourceUri(value.uri, `${field}.uri`);
+  line(value.description, `${field}.description`);
+  if (value.sha256 !== undefined && !/^[a-f0-9]{64}$/.test(value.sha256)) {
+    invalid(`${field}.sha256`, "must be a lowercase SHA-256 digest", value.sha256);
+  }
+  return value;
+};
+
+// Every event ACC itself appends. Closed on purpose: `type` used to be free
+// text, so a record written by hand validated cleanly and `acc doctor` called
+// the store healthy. That is not theoretical - a session that could not run the
+// CLI wrote its own events, inventing `task.completed`, and the store reported
+// no problem.
+const EVENT_TYPES = Object.freeze([
+  "workspace.materialised",
+  "session.opened", "session.closed",
+  "intent.published", "intent.cleared",
+  "workstream.created", "workstream.coordinator_acquired",
+  "workstream.coordinator_released",
+  "task.created", "task.claimed", "task.transitioned", "task.unblocked",
+  "task.declined", "task.released",
+  "claim.acquired", "claim.released", "claim.renewed", "claim.force_released",
+  "message.sent", "decision.recorded", "handoff.created",
+  // Delivery transitions and request outcomes are templated from their state,
+  // so the set has to carry each one they can produce.
+  ...["recorded", "queued", "injected", "seen", "acknowledged", "failed"]
+    .map(state => `message.${state}`),
+  ...["accepted", "declined", "review", "done", "released"]
+    .map(outcome => `work.${outcome}`),
+  "work.requested",
+]);
+
+const eventType = oneOf(...EVENT_TYPES);
+
+const RECORDS = Object.freeze({
+  workspace: { workspaceId: id, displayName: line, source: oneOf("config", "git", "directory"),
+    roots: listOf(line), createdAt: timestamp },
+
+  participant: { participantId: id, workspaceId: id, displayName: line,
+    kind: oneOf("agent", "human"), createdAt: timestamp },
+
+  // `enforcement` and `lifecycle` are what this session's harness can actually
+  // do, declared at attach. The harness name does not imply them: the same
+  // client guards or does not depending on its model and its approval mode, and
+  // a peer deciding whether to rely on a claim needs the answer, not the brand.
+  // A workspace spans every worktree of one repository, so the workspace id
+  // cannot say which checkout a session is sitting in. Recorded at attach from
+  // what discovery already resolved: without it nobody can tell which worktrees
+  // have an owner, and asking cannot answer for the agents that are not running
+  // - which are exactly the ones a clean-up is looking for.
+  session: { sessionId: id, participantId: id, workspaceId: id, generation: id,
+    harness: line, state: oneOf("open", "closed"), parentSessionId: nullable(id),
+    checkoutRoot: nullable(line), branch: nullable(line),
+    enforcement: oneOf("guarded", "advisory"), lifecycle: oneOf("managed", "manual"),
+    heartbeatCadenceMs: positiveInteger, startedAt: timestamp, heartbeatAt: timestamp },
+
+  intent: { sessionId: id, workspaceId: id, summary,
+    mode: oneOf("observe", "explore", "edit", "review", "coordinate", "wait"),
+    resourceHints: listOf(resourceUri), workstreamId: nullable(id),
+    state: oneOf("active", "blocked", "waiting", "done"), updatedAt: timestamp },
+
+  workstream: { workstreamId: id, workspaceId: id, title: line, objective: prose,
+    coordinatorSessionId: nullable(id),
+    state: oneOf("open", "paused", "complete", "cancelled"), createdAt: timestamp },
+
+  // Two assignees, deliberately. `assigneeParticipantId` is who the work is
+  // for and survives that agent restarting; `assigneeSessionId` is the exact
+  // session doing it right now and dies with the process. Asking one field to
+  // be both would either lose the request when a terminal closes or claim a
+  // dead session is still working.
+  task: { taskId: id, workstreamId: nullable(id), workspaceId: id, title: line,
+    state: oneOf("pending", "in_progress", "review", "done", "blocked"),
+    assigneeParticipantId: nullable(id), assigneeSessionId: nullable(id),
+    // Who asked. Without it nothing could tell the requester that their work
+    // was accepted, declined or finished - the task knew who it was for and
+    // had no idea who was waiting on it.
+    requestedByParticipantId: nullable(id),
+    dependsOn: listOf(id), acceptance: listOf(line), detail: nullable(prose),
+    createdAt: timestamp },
+
+  claim: { claimId: id, workspaceId: id, ownerSessionId: id, resource: resourceUri,
+    mode: oneOf("shared", "exclusive"), enforcement: oneOf("advisory", "guarded"),
+    reason: line, acquiredAt: timestamp, expiresAt: timestamp, generation: id },
+
+  // `fromParticipantId` beside the session: a session ends, and the one fact
+  // that has to outlive it is who was speaking. Resolving the sender by looking
+  // its session up meant the record could never be retired, and an agent whose
+  // client had restarted stopped being told about its own unanswered question.
+  message: { messageId: id, workspaceId: id, fromSessionId: id,
+    fromParticipantId: id, toParticipantIds: listOf(id),
+    type: oneOf("note", "question", "answer", "contract_request", "contract_response",
+      "decision_proposal", "decision_result", "blocker", "review_request",
+      "review_result", "handoff", "work_request", "work_response"),
+    subject: line, body: prose, priority: oneOf("low", "normal", "high", "urgent"),
+    workstreamId: nullable(id), taskId: nullable(id), inReplyTo: nullable(id),
+    requiresAck: flag, artifacts: listOf(artifactRef), sentAt: timestamp },
+
+  receipt: { messageId: id, workspaceId: id, recipientParticipantId: id,
+    state: oneOf("recorded", "queued", "injected", "seen", "acknowledged", "failed"),
+    updatedAt: timestamp },
+
+  decision: { decisionId: id, workspaceId: id, workstreamId: nullable(id), title: line,
+    outcome: prose, authority: oneOf("human", "workstream", "policy"),
+    decidedBy: listOf(id), evidence: listOf(artifactRef), supersedes: nullable(id),
+    decidedAt: timestamp },
+
+  artifact: { kind: artifactKind, uri: resourceUri, description: line },
+
+  handoff: { handoffId: id, workspaceId: id, fromSessionId: id, toParticipantId: nullable(id),
+    goal: line, status: oneOf("complete", "partial", "blocked"), completed: listOf(line),
+    remaining: listOf(line), blockers: listOf(line), claimsToRelease: listOf(resourceUri),
+    verification: listOf(artifactRef), artifacts: listOf(artifactRef), createdAt: timestamp },
+
+  event: { sequence, eventId: id, workspaceId: id, actorSessionId: id, type: eventType,
+    occurredAt: timestamp, payload: plainObject },
+});
+
+export const RECORD_KINDS = Object.freeze(Object.keys(RECORDS));
+
+export function validateRecord(kind, value) {
+  const fields = RECORDS[kind];
+  if (fields === undefined) {
+    throw new AccError(EXIT.DATA, `unknown record kind: ${kind}`, { kind });
+  }
+  plainObject(value, kind);
+  if (value.schemaVersion !== SCHEMA_VERSION) {
+    throw new AccError(EXIT.DATA,
+      `${kind} has an unknown schemaVersion: ${String(value.schemaVersion)}`,
+      { kind, schemaVersion: value.schemaVersion });
+  }
+  for (const key of Object.keys(value)) {
+    if (key === "schemaVersion" || key === "extensions") continue;
+    if (!Object.hasOwn(fields, key)) {
+      invalid(`${kind}.${key}`, "is not a known field", value[key]);
+    }
+  }
+  for (const [field, check] of Object.entries(fields)) {
+    if (!Object.hasOwn(value, field)) {
+      throw new AccError(EXIT.DATA, `${kind} requires ${field}`, { kind, field });
+    }
+    check(value[field], field);
+  }
+  // Forward-compatible metadata is tolerated only inside a named container, so
+  // an older reader can round-trip a newer writer's record without guessing
+  // which unknown top-level keys are safe.
+  if (Object.hasOwn(value, "extensions")) plainObject(value.extensions, "extensions");
+  return value;
+}

package/node_modules/@agents-can-communicate/protocol/src/states.mjs

@@ -0,0 +1,55 @@
+import { AccError, EXIT } from "./errors.mjs";
+
+// recorded -> queued -> injected -> seen -> acknowledged, with failed branching
+// off before the message was ever exposed. States are monotonic: one
+// recipient's receipt can only move forwards, and never rewrites another
+// recipient's state.
+export const DELIVERY_STATES = Object.freeze(
+  ["recorded", "queued", "injected", "seen", "acknowledged", "failed"]);
+
+const DELIVERY_NEXT = Object.freeze({
+  recorded: ["queued", "injected", "seen", "acknowledged", "failed"],
+  queued: ["injected", "seen", "acknowledged", "failed"],
+  injected: ["seen", "acknowledged"],
+  seen: ["acknowledged"],
+  acknowledged: [],
+  failed: [],
+});
+
+export const TASK_STATES = Object.freeze(
+  ["pending", "in_progress", "review", "done", "blocked"]);
+
+const TASK_NEXT = Object.freeze({
+  pending: ["in_progress", "blocked"],
+  in_progress: ["review", "done", "blocked"],
+  review: ["in_progress", "done", "blocked"],
+  blocked: ["pending", "in_progress"],
+  done: [],
+});
+
+function step(machine, allowed, label, current, next) {
+  if (!machine.includes(current)) {
+    throw new AccError(EXIT.DATA, `unknown ${label} state: ${String(current)}`,
+      { current, next });
+  }
+  if (!machine.includes(next)) {
+    throw new AccError(EXIT.DATA, `unknown ${label} state: ${String(next)}`,
+      { current, next });
+  }
+  // Re-declaring the current state is idempotent. Adapters retry at safe
+  // points, and a repeated receipt is not a protocol violation.
+  if (current === next) return next;
+  if (!allowed[current].includes(next)) {
+    throw new AccError(EXIT.CONFLICT,
+      `illegal ${label} transition from ${current} to ${next}`, { current, next });
+  }
+  return next;
+}
+
+export function advanceDelivery(current, next) {
+  return step(DELIVERY_STATES, DELIVERY_NEXT, "delivery", current, next);
+}
+
+export function transitionTask(current, next) {
+  return step(TASK_STATES, TASK_NEXT, "task", current, next);
+}

package/node_modules/@agents-can-communicate/storage-filesystem/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@agents-can-communicate/storage-filesystem",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.mjs"
+  },
+  "files": [
+    "src/"
+  ]
+}

package/node_modules/@agents-can-communicate/storage-filesystem/src/atomic-json.mjs

@@ -0,0 +1,135 @@
+import { randomUUID } from "node:crypto";
+import { link, open, readdir, rename, unlink } from "node:fs/promises";
+import path from "node:path";
+
+import { AccError, EXIT } from "@agents-can-communicate/protocol";
+
+import { assertManagedDirectory, ensureManagedDirectory } from "./safe-directory.mjs";
+import { readRegularNoFollow } from "./safe-file.mjs";
+
+async function syncDirectory(directory) {
+  const handle = await open(directory, "r");
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
+async function unlinkIfPresent(filePath) {
+  try {
+    await unlink(filePath);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+}
+
+export function encode(value) {
+  const serialised = JSON.stringify(value, null, 2);
+  if (serialised === undefined) {
+    throw new AccError(EXIT.DATA, "record is not JSON serializable", { value: typeof value });
+  }
+  return Buffer.from(`${serialised}\n`, "utf8");
+}
+
+async function bytesIfPresent(filePath, root) {
+  try {
+    return await readRegularNoFollow(filePath, root);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+/**
+ * Publish bytes atomically.
+ *
+ * Two modes, and the distinction matters: immutable evidence - events, journal
+ * entries, audits - is published by link(), so overwriting is impossible by
+ * construction rather than by a check that could race, and re-publishing
+ * identical bytes is idempotent while different bytes fail closed. Materialised
+ * state is mutable by design, which is what generations exist for, so it is
+ * published by rename(). Conflating the two makes every state update fail.
+ *
+ * @returns {Promise<"published" | "already_published">}
+ */
+export async function publishAtomic(destination, bytes, { root, tmpDir, replace = false }) {
+  const destinationDir = path.dirname(destination);
+  await Promise.all([
+    ensureManagedDirectory(root, tmpDir),
+    ensureManagedDirectory(root, destinationDir),
+  ]);
+  const temporary = path.join(tmpDir, `${path.basename(destination)}.${process.pid}.${randomUUID()}.tmp`);
+  const handle = await open(temporary, "wx");
+  try {
+    await handle.writeFile(bytes);
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  try {
+    if (replace) {
+      await rename(temporary, destination);
+      await syncDirectory(destinationDir);
+      return "published";
+    }
+    await link(temporary, destination);
+    await syncDirectory(destinationDir);
+    return "published";
+  } catch (error) {
+    if (error.code !== "EEXIST") throw error;
+    const existing = await bytesIfPresent(destination, root);
+    if (existing !== null && existing.equals(bytes)) return "already_published";
+    throw new AccError(EXIT.CONFLICT, "record already published with different bytes",
+      { destination });
+  } finally {
+    await unlinkIfPresent(temporary);
+  }
+}
+
+export async function readJsonIfPresent(filePath, root) {
+  const bytes = await bytesIfPresent(filePath, root);
+  if (bytes === null) return null;
+  try {
+    return { value: JSON.parse(bytes.toString("utf8")), bytes };
+  } catch (error) {
+    // Named in the message, not only in the details: human mode prints the
+    // message alone, and "invalid JSON record" sent a reader looking through a
+    // whole workspace for a file the error already knew.
+    throw new AccError(EXIT.DATA, `invalid JSON record: ${filePath}`,
+      { filePath, cause: error.message });
+  }
+}
+
+export async function listDirectoryEntries(dirPath, { root, readDirectory = readdir } = {}) {
+  let before;
+  try {
+    before = await assertManagedDirectory(root, dirPath);
+  } catch (error) {
+    if (error.code === "ENOENT") return [];
+    throw error;
+  }
+  let entries;
+  try {
+    entries = await readDirectory(dirPath, { withFileTypes: true });
+  } catch (error) {
+    if (error.code === "ENOENT") return [];
+    throw error;
+  }
+  const after = await assertManagedDirectory(root, dirPath);
+  if (before.stat.dev !== after.stat.dev || before.stat.ino !== after.stat.ino) {
+    throw new AccError(EXIT.DATA, "managed directory changed while listing", { dirPath, root });
+  }
+  return entries;
+}
+
+export async function listJsonFiles(dirPath, options) {
+  return (await listDirectoryEntries(dirPath, options))
+    .filter(entry => entry.isFile() && entry.name.endsWith(".json"))
+    .map(entry => path.join(dirPath, entry.name))
+    .sort((left, right) => left.localeCompare(right));
+}
+
+export async function removeIfPresent(filePath) {
+  await unlinkIfPresent(filePath);
+}

package/node_modules/@agents-can-communicate/storage-filesystem/src/identity.mjs

@@ -0,0 +1,67 @@
+import path from "node:path";
+
+import { AccError, EXIT, assertPortableId } from "@agents-can-communicate/protocol";
+
+import { encode, publishAtomic, readJsonIfPresent } from "./atomic-json.mjs";
+
+export const STORE_VERSION = 1;
+
+export function identityPath(paths) {
+  return path.join(paths.root, "protocol.json");
+}
+
+function assertIdentity(record, workspaceId, filePath) {
+  if (record?.storeVersion !== STORE_VERSION) {
+    throw new AccError(EXIT.DATA, "unknown store version", { filePath,
+      storeVersion: record?.storeVersion });
+  }
+  if (record.workspaceId !== workspaceId) {
+    throw new AccError(EXIT.DATA, "store belongs to a different workspace",
+      { filePath, expected: workspaceId, actual: record.workspaceId });
+  }
+  return record;
+}
+
+/**
+ * Establish or verify the store's identity before anything else happens.
+ * Opening a directory that already belongs to another workspace must fail
+ * rather than quietly adopt it: an initialisation that silently rewrites a
+ * foreign store is the failure the reconciled prototype fails closed on, and
+ * the same rule applies here.
+ */
+export async function requireStoreIdentity(paths, { workspaceId, clock, create = true }) {
+  assertPortableId(workspaceId, "workspace id");
+  const filePath = identityPath(paths);
+  const found = await readJsonIfPresent(filePath, paths.root);
+  if (found !== null) return assertIdentity(found.value, workspaceId, filePath);
+  if (!create) {
+    throw new AccError(EXIT.DATA, "store is not initialised", { filePath });
+  }
+  const record = { storeVersion: STORE_VERSION, workspaceId, initialisedAt: clock.now() };
+  try {
+    await publishAtomic(filePath, encode(record), { root: paths.root, tmpDir: paths.tmp });
+  } catch (error) {
+    // Losing this race is not a failure. Two agents starting together in a
+    // workspace neither has opened before is the ordinary case, and the two
+    // identity documents they write differ in one field - the moment each was
+    // written - so the second was refused for "different bytes" and that agent
+    // could not attach at all.
+    //
+    // What the store has to refuse is a directory belonging to a *different*
+    // workspace, and that is decided below by reading what is actually there
+    // rather than by whose bytes arrived first.
+    if (error.code !== EXIT.CONFLICT) throw error;
+  }
+  const published = await readJsonIfPresent(filePath, paths.root);
+  return assertIdentity(published.value, workspaceId, filePath);
+}
+
+export async function readStoreIdentity(paths) {
+  const found = await readJsonIfPresent(identityPath(paths), paths.root);
+  if (found === null) return null;
+  if (found.value?.storeVersion !== STORE_VERSION) {
+    throw new AccError(EXIT.DATA, "unknown store version",
+      { filePath: identityPath(paths), storeVersion: found.value?.storeVersion });
+  }
+  return found.value;
+}

package/node_modules/@agents-can-communicate/storage-filesystem/src/index.mjs

@@ -0,0 +1,4 @@
+// CoordinationStore backed by the reconciled filesystem protocol.
+export { openFilesystemStore, storePaths, ZERO_CURSOR } from "./store.mjs";
+export { diagnoseFilesystemStore, repairFilesystemStore } from "./recovery.mjs";
+export { readStoreIdentity, requireStoreIdentity, STORE_VERSION } from "./identity.mjs";

package/node_modules/@agents-can-communicate/storage-filesystem/src/journal.mjs

@@ -0,0 +1,87 @@
+import path from "node:path";
+
+import { AccError, EXIT } from "@agents-can-communicate/protocol";
+
+import { encode, listJsonFiles, publishAtomic, readJsonIfPresent, removeIfPresent }
+  from "./atomic-json.mjs";
+
+export const JOURNAL_VERSION = 1;
+
+// A journal entry is written only after the transaction callback has succeeded
+// and every byte is known. Its existence therefore means "this transaction was
+// decided", which is what makes roll-forward - rather than rollback - the
+// correct recovery. Roll-forward is idempotent because publication is
+// no-replace and identical bytes are accepted as already published.
+export function journalPath(paths, transactionId) {
+  return path.join(paths.journal, `${transactionId}.json`);
+}
+
+export function journalEntry(transactionId, firstSequence, publications, startedAt) {
+  return {
+    journalVersion: JOURNAL_VERSION,
+    transactionId,
+    firstSequence,
+    startedAt,
+    publications: publications.map(item => ({
+      path: item.path,
+      // A removal is journalled like any other publication, so a crash between
+      // two deletions replays to the same end state rather than a partial one.
+      bytes: item.remove === true ? null : item.bytes.toString("base64"),
+      replace: item.replace === true,
+      remove: item.remove === true,
+    })),
+  };
+}
+
+export async function writeJournalEntry(paths, options, entry) {
+  await publishAtomic(journalPath(paths, entry.transactionId), encode(entry), options);
+  return entry;
+}
+
+export async function retireJournalEntry(paths, transactionId) {
+  await removeIfPresent(journalPath(paths, transactionId));
+}
+
+export async function readOpenJournals(paths, root) {
+  const files = await listJsonFiles(paths.journal, { root });
+  const entries = [];
+  for (const file of files) {
+    const found = await readJsonIfPresent(file, root);
+    if (found === null) continue;
+    const entry = found.value;
+    if (entry?.journalVersion !== JOURNAL_VERSION) {
+      throw new AccError(EXIT.DATA, "unknown journal version", { file,
+        journalVersion: entry?.journalVersion });
+    }
+    if (path.basename(file, ".json") !== entry.transactionId) {
+      throw new AccError(EXIT.DATA, "journal entry does not match its filename", { file });
+    }
+    entries.push(entry);
+  }
+  return entries.sort((left, right) => left.firstSequence.localeCompare(right.firstSequence));
+}
+
+// Publishing every listed file and then retiring the entry. Already-published
+// identical bytes are accepted, differing bytes fail closed, so running this
+// twice changes nothing and a genuine conflict is never papered over.
+export async function rollForward(paths, options, entry) {
+  const published = [];
+  for (const publication of entry.publications) {
+    const destination = path.resolve(options.root, publication.path);
+    if (publication.remove === true) {
+      await removeIfPresent(destination);
+      published.push(publication.path);
+      await options.failAt?.(`after:${publication.path}`);
+      continue;
+    }
+    const bytes = Buffer.from(publication.bytes, "base64");
+    const outcome = await publishAtomic(destination, bytes,
+      { ...options, replace: publication.replace === true });
+    if (outcome === "published") published.push(publication.path);
+    // Seam for the crash-window tests: abort between two publications of the
+    // same decided transaction.
+    await options.failAt?.(`after:${publication.path}`);
+  }
+  await retireJournalEntry(paths, entry.transactionId);
+  return published;
+}

package/node_modules/@agents-can-communicate/storage-filesystem/src/record-id.mjs

@@ -0,0 +1,44 @@
+import path from "node:path";
+
+import { AccError, EXIT, assertPortableId } from "@agents-can-communicate/protocol";
+
+// State files carry an envelope rather than the bare record. The envelope names
+// the kind, the id, and the generation, so a file that is moved or renamed can
+// be detected instead of being trusted because of where it happens to sit.
+// This is the generalisation of the reconciled prototype's filename binding.
+export function stateEnvelope(kind, id, generation, record) {
+  return { kind, id, generation, record };
+}
+
+export function statePath(paths, kind, id) {
+  assertPortableId(kind, "record kind");
+  assertPortableId(id, "record id");
+  return path.join(paths.state, kind, `${id}.json`);
+}
+
+export function assertStateBinding(envelope, kind, id, filePath) {
+  const shaped = envelope !== null && typeof envelope === "object"
+    && typeof envelope.kind === "string" && typeof envelope.id === "string"
+    && typeof envelope.generation === "string";
+  if (!shaped) {
+    throw new AccError(EXIT.DATA, "state record is not a valid envelope", { filePath });
+  }
+  if (envelope.kind !== kind || envelope.id !== id) {
+    throw new AccError(EXIT.DATA, "state record does not match its path",
+      { filePath, expected: { kind, id }, actual: { kind: envelope.kind, id: envelope.id } });
+  }
+  return envelope;
+}
+
+export function eventPath(paths, sequence) {
+  return path.join(paths.events, `${sequence}.json`);
+}
+
+export function assertEventBinding(event, filePath) {
+  const sequence = path.basename(filePath, ".json");
+  if (event?.sequence !== sequence) {
+    throw new AccError(EXIT.DATA, "event record does not match its filename",
+      { filePath, expected: sequence, actual: event?.sequence });
+  }
+  return event;
+}