agents-can-communicate 0.1.18 → 0.2.0

package/node_modules/@agents-can-communicate/protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/protocol",
-  "version": "0.1.18",
+  "version": "0.2.0",
   "private": true,
   "type": "module",
   "exports": {

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

@@ -12,7 +12,7 @@ export const CONFIG_FILENAME = "acc.workspace.json";
 // the wrong place for them, and a config carrying them is either a mistake or
 // an attempt to hand a peer state it would otherwise have to earn.
 export const RUNTIME_KEYS = Object.freeze(["sessions", "participants", "messages",
-  "claims", "receipts", "intents", "events", "tokens", "credentials"]);
+  "claims", "receipts", "intents", "events", "deliveryBindings", "tokens", "credentials"]);
 
 const KNOWN_KEYS = Object.freeze(["schemaVersion", "workspaceId", "displayName",
   "roots", "policy", "requiredAdapters", "extensions"]);

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

@@ -0,0 +1,64 @@
+import { AccError, EXIT } from "./errors.mjs";
+
+export const VALID_OBLIGATIONS = Object.freeze({
+  note: Object.freeze(["none"]),
+  question: Object.freeze(["reply"]),
+  request: Object.freeze(["reply"]),
+  answer: Object.freeze(["none"]),
+  decision: Object.freeze(["none", "acknowledge"]),
+  handoff: Object.freeze(["none", "acknowledge"]),
+});
+
+export const MESSAGE_KINDS = Object.freeze(Object.keys(VALID_OBLIGATIONS));
+// The generic send surface cannot construct reply links or structured handoff
+// payloads. Those two complete shapes belong to reply and finish respectively.
+export const GENERIC_MESSAGE_KINDS = Object.freeze(
+  ["note", "question", "request", "decision"]);
+export const OBLIGATIONS = Object.freeze(["none", "acknowledge", "reply"]);
+
+const data = (message, details) => {
+  throw new AccError(EXIT.DATA, message, details);
+};
+
+export function assertMessageSemantics(message) {
+  const room = message.toParticipantIds.length === 0;
+  if (room && !["note", "decision", "handoff"].includes(message.kind)) {
+    data(`a room message cannot have kind ${message.kind}`, { kind: message.kind });
+  }
+  if (room && message.obligation !== "none") {
+    data("a room message must have obligation none", { obligation: message.obligation });
+  }
+
+  const valid = VALID_OBLIGATIONS[message.kind] ?? [];
+  if (!valid.includes(message.obligation)) {
+    data(`message obligation ${message.obligation} is invalid for ${message.kind}`,
+      { kind: message.kind, obligation: message.obligation });
+  }
+
+  const root = message.threadId === message.messageId;
+  if (message.kind === "answer" && message.inReplyTo === null) {
+    data("an answer requires inReplyTo", { messageId: message.messageId });
+  }
+  if (message.kind === "answer" && root) {
+    data("an answer cannot be a thread root", { messageId: message.messageId });
+  }
+  if (message.inReplyTo === null && !root) {
+    data("a thread root requires threadId to equal messageId",
+      { threadId: message.threadId, messageId: message.messageId });
+  }
+  if (message.inReplyTo !== null && root) {
+    data("a thread root must have inReplyTo null", { inReplyTo: message.inReplyTo });
+  }
+
+  if (message.kind === "handoff" && message.handoff === null) {
+    data("a handoff message requires a handoff payload", { messageId: message.messageId });
+  }
+  if (!room && message.kind === "handoff" && message.obligation !== "acknowledge") {
+    data("an addressed handoff requires acknowledgement",
+      { messageId: message.messageId, obligation: message.obligation });
+  }
+  if (message.kind !== "handoff" && message.handoff !== null) {
+    data(`a ${message.kind} message must have handoff null`, { kind: message.kind });
+  }
+  return message;
+}

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

@@ -3,7 +3,10 @@ export { AccError, EXIT, isAccError } from "./errors.mjs";
 export { assertPortableId, createId } from "./ids.mjs";
 export { ENVELOPE_VERSION, failure, ok } from "./envelopes.mjs";
 export { RECORD_KINDS, SCHEMA_VERSION, validateRecord } from "./schema.mjs";
+export { GENERIC_MESSAGE_KINDS, MESSAGE_KINDS, OBLIGATIONS, VALID_OBLIGATIONS,
+  assertMessageSemantics }
+  from "./conversations.mjs";
 export { CONFIG_FILENAME, CONFIG_SCHEMA_VERSION, RUNTIME_KEYS, defaultProjectConfig,
   validateProjectConfig } from "./config.mjs";
-export { DELIVERY_STATES, TASK_STATES, advanceDelivery, transitionTask } from "./states.mjs";
+export { RECEIPT_STATES, advanceReceipt } from "./states.mjs";
 export { assertMatchableResource, normaliseResource } from "./resources.mjs";

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

@@ -1,8 +1,9 @@
+import { assertMessageSemantics, MESSAGE_KINDS, OBLIGATIONS } from "./conversations.mjs";
 import { AccError, EXIT } from "./errors.mjs";
-import { flag, id, invalid, listOf, nullable, oneOf, plainObject, positiveInteger,
+import { id, invalid, listOf, nullable, oneOf, plainObject, positiveInteger,
   resourceUri, sequence, text, timestamp } from "./fields.mjs";
 
-export const SCHEMA_VERSION = 2;
+export const SCHEMA_VERSION = 3;
 
 const line = text();
 const prose = text({ max: 4000, multiline: true });
@@ -14,10 +15,22 @@ const artifactKind = oneOf("file", "git", "url", "report", "image", "data");
 /** @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 */
+ * intents: object[], claims: object[], messages: object[], receipts: object[] }} WorkspaceSnapshot */
+
+function closedObject(value, field, fields) {
+  plainObject(value, field);
+  for (const key of Object.keys(value)) {
+    if (!Object.hasOwn(fields, key)) invalid(`${field}.${key}`, "is not a known field", value[key]);
+  }
+  for (const [key, check] of Object.entries(fields)) {
+    if (!Object.hasOwn(value, key)) {
+      throw new AccError(EXIT.DATA, `${field} requires ${key}`, { field, key });
+    }
+    check(value[key], `${field}.${key}`);
+  }
+  return value;
+}
 
-// 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"]);
@@ -33,120 +46,70 @@ const artifactRef = (value, field) => {
   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 handoffPayload = (value, field) => closedObject(value, field, {
+  status: oneOf("complete", "partial", "blocked"),
+  completed: listOf(line),
+  remaining: listOf(line),
+  blockers: listOf(line),
+  verification: listOf(artifactRef),
+});
+
 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",
+  "message.recorded", "message.offered", "message.retrieved", "message.acknowledged",
+  "message.offer_succeeded", "message.offer_failed",
 ]);
 
 const eventType = oneOf(...EVENT_TYPES);
+const receiptState = oneOf("queued", "offered", "retrieved", "acknowledged");
 
-const RECORDS = Object.freeze({
+const DURABLE_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),
-    // The process behind this session, when it can be named. Null means nobody
-    // knows - no process table, or an ancestry that did not resolve - and is
-    // read as "judge this one by age alone", never as "dead".
-    pid: nullable(positiveInteger),
+    checkoutRoot: nullable(line), branch: nullable(line), pid: nullable(positiveInteger),
     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),
+    resourceHints: listOf(resourceUri),
     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 },
+  message: { messageId: id, threadId: id, clientMessageId: id, workspaceId: id,
+    fromParticipantId: id, fromSessionId: id, toParticipantIds: listOf(id),
+    kind: oneOf(...MESSAGE_KINDS), obligation: oneOf(...OBLIGATIONS),
+    subject: line, body: prose, inReplyTo: nullable(id), artifacts: listOf(artifactRef),
+    handoff: nullable(handoffPayload), 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 },
+    state: receiptState, updatedAt: timestamp },
 
   event: { sequence, eventId: id, workspaceId: id, actorSessionId: id, type: eventType,
     occurredAt: timestamp, payload: plainObject },
 });
 
-export const RECORD_KINDS = Object.freeze(Object.keys(RECORDS));
+const RECORDS = Object.freeze({
+  ...DURABLE_RECORDS,
+  deliveryBinding: { sessionId: id, generation: id, adapterId: id, clientVersion: line,
+    availableModes: listOf(oneOf("nextTurn", "livePush", "replyRoute")),
+    livePolicy: oneOf("off", "actionable", "all"), opaqueEndpointRef: prose,
+    leaseUntil: timestamp },
+});
+
+export const RECORD_KINDS = Object.freeze(Object.keys(DURABLE_RECORDS));
 
 export function validateRecord(kind, value) {
   const fields = RECORDS[kind];
@@ -161,9 +124,7 @@ export function validateRecord(kind, value) {
   }
   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]);
-    }
+    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)) {
@@ -171,9 +132,7 @@ export function validateRecord(kind, value) {
     }
     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");
+  if (kind === "message") assertMessageSemantics(value);
   return value;
 }

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

@@ -1,55 +1,28 @@
 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"]);
+export const RECEIPT_STATES = Object.freeze(
+  ["queued", "offered", "retrieved", "acknowledged"]);
 
-const DELIVERY_NEXT = Object.freeze({
-  recorded: ["queued", "injected", "seen", "acknowledged", "failed"],
-  queued: ["injected", "seen", "acknowledged", "failed"],
-  injected: ["seen", "acknowledged"],
-  seen: ["acknowledged"],
+const RECEIPT_NEXT = Object.freeze({
+  queued: ["offered", "retrieved", "acknowledged"],
+  offered: ["retrieved", "acknowledged"],
+  retrieved: ["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)}`,
+export function advanceReceipt(current, next) {
+  if (!RECEIPT_STATES.includes(current)) {
+    throw new AccError(EXIT.DATA, `unknown receipt state: ${String(current)}`,
       { current, next });
   }
-  if (!machine.includes(next)) {
-    throw new AccError(EXIT.DATA, `unknown ${label} state: ${String(next)}`,
+  if (!RECEIPT_STATES.includes(next)) {
+    throw new AccError(EXIT.DATA, `unknown receipt 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)) {
+  if (!RECEIPT_NEXT[current].includes(next)) {
     throw new AccError(EXIT.CONFLICT,
-      `illegal ${label} transition from ${current} to ${next}`, { current, next });
+      `illegal receipt 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

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/storage-filesystem",
-  "version": "0.1.18",
+  "version": "0.2.0",
   "private": true,
   "type": "module",
   "exports": {

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

@@ -0,0 +1,230 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import path from "node:path";
+
+import { AccError, EXIT, assertPortableId } from "@agents-can-communicate/protocol";
+
+import { encode, publishAtomic } from "./atomic-json.mjs";
+import { withRegularNoFollow } from "./safe-file.mjs";
+
+const ACTIVE_JOURNAL_VERSION = 2;
+const AUTHORITY_BYTES_LIMIT = 1024;
+const GENERATION_WIDTH = 16;
+const READ_ATTEMPTS = 4;
+
+const data = (message, details) => {
+  throw new AccError(EXIT.DATA, message, details);
+};
+
+export function activeJournalPath(paths, slot) {
+  if (slot !== 0 && slot !== 1) data("invalid active journal slot", { slot });
+  return path.join(paths.journal, `active.${slot}`);
+}
+
+function exactKeys(value, expected, filePath) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)
+    || Object.keys(value).sort().join("\0") !== [...expected].sort().join("\0")) {
+    data("active journal record is not closed", { filePath });
+  }
+}
+
+function checksum(record) {
+  return createHash("sha256").update(JSON.stringify(record)).digest("hex");
+}
+
+function encodeAuthority(record) {
+  return encode({ activeJournalChecksum: checksum(record), record });
+}
+
+function validateActiveRecord(record, filePath) {
+  const base = ["activeJournalVersion", "generation", "previousChecksum", "state"];
+  if (record?.state === "idle") exactKeys(record, base, filePath);
+  else if (record?.state === "open") {
+    exactKeys(record, [...base, "transactionId", "firstSequence"], filePath);
+  } else data("invalid active journal state", { filePath, state: record?.state });
+
+  if (record.activeJournalVersion !== ACTIVE_JOURNAL_VERSION) {
+    data("unknown active journal version", { filePath,
+      activeJournalVersion: record.activeJournalVersion });
+  }
+  if (typeof record.generation !== "string"
+    || !/^\d{16}$/.test(record.generation)) {
+    data("invalid active journal generation", { filePath, generation: record.generation });
+  }
+  const generation = BigInt(record.generation);
+  if (generation === 0n) {
+    if (record.state !== "idle" || record.previousChecksum !== null) {
+      data("invalid active journal genesis", { filePath });
+    }
+  } else if (typeof record.previousChecksum !== "string"
+    || !/^[0-9a-f]{64}$/.test(record.previousChecksum)) {
+    data("invalid active journal previous checksum", { filePath });
+  }
+  if (record.state === "open") {
+    assertPortableId(record.transactionId, "transaction id");
+    if (typeof record.firstSequence !== "string"
+      || !/^\d{16}$/.test(record.firstSequence)) {
+      data("invalid active journal first sequence", { filePath,
+        firstSequence: record.firstSequence });
+    }
+  }
+  return generation;
+}
+
+function decodeAuthority(bytes, filePath, slot) {
+  let envelope;
+  try {
+    envelope = JSON.parse(bytes.toString("utf8"));
+  } catch (error) {
+    data("invalid active journal authority", { filePath, cause: error.message });
+  }
+  exactKeys(envelope, ["activeJournalChecksum", "record"], filePath);
+  const generation = validateActiveRecord(envelope.record, filePath);
+  if (Number(generation % 2n) !== slot) {
+    data("active journal generation chain is invalid", { filePath,
+      generation: envelope.record.generation, slot });
+  }
+  if (typeof envelope.activeJournalChecksum !== "string"
+    || envelope.activeJournalChecksum !== checksum(envelope.record)) {
+    data("active journal checksum mismatch", { filePath });
+  }
+  if (!bytes.equals(encodeAuthority(envelope.record))) {
+    data("active journal authority is not canonical", { filePath });
+  }
+  return { checksum: envelope.activeJournalChecksum, generation,
+    record: envelope.record, slot };
+}
+
+async function readSlotBytes(paths, root, slot, openFile) {
+  const filePath = activeJournalPath(paths, slot);
+  try {
+    return await withRegularNoFollow(filePath, root, constants.O_RDONLY,
+      async (handle, stat) => {
+        if (stat.size < 1 || stat.size > AUTHORITY_BYTES_LIMIT) {
+          data("invalid active journal authority size", { filePath, size: stat.size });
+        }
+        return handle.readFile();
+      }, openFile);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+function sameBytes(left, right) {
+  if (left === null || right === null) return left === right;
+  return left.equals(right);
+}
+
+// Slot zero is read twice. Because writers alternate slots and generations
+// never repeat, equal reads prove that the pair existed at one instant even if
+// another process published between descriptor opens.
+async function readStableSlots(paths, root, openFile) {
+  for (let attempt = 0; attempt < READ_ATTEMPTS; attempt += 1) {
+    const slot0 = await readSlotBytes(paths, root, 0, openFile);
+    const slot1 = await readSlotBytes(paths, root, 1, openFile);
+    const slot0Confirmation = await readSlotBytes(paths, root, 0, openFile);
+    if (sameBytes(slot0, slot0Confirmation)) return [slot0, slot1];
+  }
+  throw new AccError(EXIT.CONFLICT, "active journal changed while being read", {});
+}
+
+function validateTransition(current, previous, filePath) {
+  const expected = previous.state === "idle" ? "open" : "idle";
+  if (current.state !== expected) {
+    data("invalid active journal transition", { filePath,
+      previous: previous.state, current: current.state });
+  }
+}
+
+function compareGenerations(left, right) {
+  if (left.generation < right.generation) return -1;
+  if (left.generation > right.generation) return 1;
+  return 0;
+}
+
+function selectAuthority(paths, bytes) {
+  // Decode every present slot before selection. Falling back from a corrupt
+  // latest slot to an older valid peer would turn corruption into rollback.
+  const found = bytes.map((value, slot) => value === null
+    ? null
+    : decodeAuthority(value, activeJournalPath(paths, slot), slot)).filter(Boolean);
+  if (found.length === 0) return null;
+  if (found.length === 1) {
+    const [only] = found;
+    if (only.slot === 0 && only.generation === 0n) return only;
+    data("active journal authority peer is missing", { slot: only.slot,
+      generation: only.record.generation });
+  }
+  found.sort(compareGenerations);
+  const [previous, current] = found;
+  if (current.generation !== previous.generation + 1n) {
+    data("active journal generation chain is invalid", {
+      previous: previous.record.generation, current: current.record.generation });
+  }
+  if (current.record.previousChecksum !== previous.checksum) {
+    data("active journal checksum chain is invalid", { slot: current.slot });
+  }
+  validateTransition(current.record, previous.record,
+    activeJournalPath(paths, current.slot));
+  return current;
+}
+
+async function readCurrent(paths, root, openFile) {
+  return selectAuthority(paths, await readStableSlots(paths, root, openFile));
+}
+
+const genesis = () => ({ activeJournalVersion: ACTIVE_JOURNAL_VERSION,
+  generation: "0".repeat(GENERATION_WIDTH), previousChecksum: null, state: "idle" });
+
+export async function initialiseActiveJournal(paths, options) {
+  const current = await readCurrent(paths, options.root);
+  if (current !== null) return current.record;
+  try {
+    await publishAtomic(activeJournalPath(paths, 0), encodeAuthority(genesis()), options);
+  } catch (error) {
+    if (error.code !== EXIT.CONFLICT) throw error;
+  }
+  return readActiveJournal(paths, options.root);
+}
+
+export async function readActiveJournal(paths, root, openFile) {
+  const current = await readCurrent(paths, root, openFile);
+  if (current === null) data("active journal has no authority", { journal: paths.journal });
+  return current.record;
+}
+
+function nextGeneration(current) {
+  const next = current.generation + 1n;
+  const generation = next.toString().padStart(GENERATION_WIDTH, "0");
+  if (generation.length !== GENERATION_WIDTH) {
+    data("active journal generation is exhausted", { current: current.record.generation });
+  }
+  return generation;
+}
+
+async function appendTransition(paths, options, fields, expected) {
+  const current = await readCurrent(paths, options.root, options.openFile);
+  if (current === null || !expected(current.record)) {
+    throw new AccError(EXIT.CONFLICT, "active journal transition conflicts",
+      { current: current?.record ?? null, next: fields });
+  }
+  const record = { activeJournalVersion: ACTIVE_JOURNAL_VERSION,
+    generation: nextGeneration(current), previousChecksum: current.checksum, ...fields };
+  validateActiveRecord(record, activeJournalPath(paths, 1 - current.slot));
+  await publishAtomic(activeJournalPath(paths, 1 - current.slot), encodeAuthority(record),
+    { ...options, tmpDir: options.tmpDir ?? paths.tmp ?? path.join(options.root, "tmp"),
+      replace: true });
+  return record;
+}
+
+export function activateJournal(paths, options, entry) {
+  return appendTransition(paths, options, { state: "open",
+    transactionId: entry.transactionId, firstSequence: entry.firstSequence },
+    current => current.state === "idle");
+}
+
+export function idleJournal(paths, options, transactionId) {
+  return appendTransition(paths, options, { state: "idle" },
+    current => current.state === "open" && current.transactionId === transactionId);
+}