wowbagger 0.1.0-alpha.9 → 0.5.0

package/src/claim-publication.js

@@ -1,11 +1,17 @@
 import { createHash } from 'node:crypto';
 import { access, writeFile } from 'node:fs/promises';
 import path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
 
 import {
   appendClaimEntry,
+  assertClaimJournalCapacity,
   claimJournalPath,
   claimReconcileLogPath,
+  isClaimJournalCapacityError,
+  isProjectedJournalEntry,
+  parseReconcileLog,
+  replayClaimEntries,
   replayClaimJournal,
   writeReconcileLog,
 } from './claim-journal.js';
@@ -13,9 +19,21 @@ import { advanceClockFloor, readBack } from './claim-operations.js';
 import { claimStorePath, withClaimLock, writeClaimState } from './claim-store.js';
 import { loadLedger, parseLedgerItemSource } from './ledger.js';
 import { MAX_ITEM_SOURCE_BYTES } from './limits.js';
-import { findRevisionOwner, readGitHeadLedger } from './git-reconciliation.js';
+import { findRevisionOwner, readGitHeadLedger, readGitTreeFile } from './git-reconciliation.js';
 import { publishClaimedCandidate, revisionFor } from './mutation.js';
+import {
+  blocksTarget,
+  classifyReconciliation,
+  normalizeRevision,
+  requiresOwnerEvidence,
+} from './reconciliation-classifier.js';
 import { validateLedger } from './validate.js';
+import {
+  assertUniqueWorktreeIdentity,
+  ensureWorktreeIdentity,
+  identityDiagnosticDetails,
+  readWorktreeIdentity,
+} from './worktree-identity.js';
 
 const ITEM_ID = /^wb_[0-7][0-9A-HJKMNP-TV-Z]{25}$/;
 const NAMESPACE_ID = /^wbns_[a-f0-9]{32}$/;
@@ -138,7 +156,11 @@ export async function readPublicationOutcome({ gitCommonDir, namespace, request
   } catch (error) {
     return publicationReadError(request, 'claim-store-unavailable',
       'The durable claim store is unavailable.', {
-        reason: error?.code === 'CLAIM_LOCK_HELD' ? 'claim-store-locked' : 'claim-store-unreadable',
+        reason: error?.code === 'CLAIM_LOCK_HELD'
+          ? 'claim-store-locked'
+          : isClaimJournalCapacityError(error)
+            ? 'journal-capacity-exceeded'
+            : 'claim-store-unreadable',
       }, 6);
   }
 }
@@ -152,6 +174,7 @@ export async function publishClaimed({ ledgerDirectory, gitCommonDir, namespace,
   }
 
   const storePath = claimStorePath(gitCommonDir, namespace);
+  let intentAppended = false;
   const journalPath = claimJournalPath(gitCommonDir, namespace);
   try {
     return await withClaimLock(storePath, async (namespaceLock) => {
@@ -176,6 +199,15 @@ export async function publishClaimed({ ledgerDirectory, gitCommonDir, namespace,
       // file, so the first of them is the snapshot the rest share. The read
       // under lock, which the mutation engine still performs on its own, is
       // what makes the revision compare-and-swap meaningful.
+      //
+      // A claimed publication authorizes an item revision, so an ambiguous
+      // domain is refused before reconciliation classifies one. The writer
+      // names itself first, under this same hold, so a domain that cannot
+      // resolve its own identity refuses as its own invalid identity rather
+      // than as an unreadable roster — and so every entry this hold appends
+      // carries one ID resolved exactly once.
+      const currentWorktreeId = await ensureWorktreeIdentity({ ledgerDirectory, gitCommonDir });
+      await assertUniqueWorktreeIdentity({ ledgerDirectory });
       let reconciled;
       try {
         reconciled = await reconcileClaimJournal({
@@ -185,8 +217,18 @@ export async function publishClaimed({ ledgerDirectory, gitCommonDir, namespace,
           replayed,
           physicalNow: new Date().toISOString(),
           targetItemId: request.item_id,
+          currentWorktreeId,
+          writeLogOnUnsafe: false,
         });
       } catch (error) {
+        if (isClaimJournalCapacityError(error)) {
+          return publicationError(request, 'claim-store-unavailable',
+            'The durable claim store is unavailable.', {
+              reason: 'journal-capacity-exceeded',
+              ledger_namespace: request.ledger_namespace,
+              item_id: request.item_id,
+            }, 6);
+        }
         if (error?.code !== 'CLOCK_FLOOR_PERSISTENCE_FAILED') throw error;
         return publicationError(request, 'clock-floor-persistence-failed',
           'The authoritative clock floor could not be persisted.', {
@@ -233,10 +275,9 @@ export async function publishClaimed({ ledgerDirectory, gitCommonDir, namespace,
             active_owner_id: record.active?.owner_id ?? null,
             active_epoch: record.active?.epoch ?? null,
           }, 4);
-        return persistTerminal(entries, journalPath, ledgerDirectory, namespace, request, outcome, replayed.state, storePath);
+        return persistTerminal(entries, journalPath, ledgerDirectory, namespace, request, outcome, replayed.state, storePath, currentWorktreeId);
       }
-      await publicationTestCheckpoint(scenario, 'before-publish-intent', ledgerDirectory);
-      const intent = await appendClaimEntry(journalPath, {
+      const intentEntry = {
         type: 'publish-intent',
         operation_id: request.operation_id,
         operation_digest: operationDigest(request),
@@ -245,20 +286,55 @@ export async function publishClaimed({ ledgerDirectory, gitCommonDir, namespace,
         candidate_sha256: request.candidate_sha256,
         fence: request.claim_fence,
         floor: observedAt,
+        writer_worktree_id: currentWorktreeId,
         state: 'pending',
+      };
+      const terminalEntry = (outcome) => ({
+        type: 'publish-final',
+        operation_id: request.operation_id,
+        operation_digest: operationDigest(request),
+        ledger_namespace: request.ledger_namespace,
+        item_id: request.item_id,
+        writer_worktree_id: currentWorktreeId,
+        outcome,
       });
+      const itemPath = ledgerSnapshot.items.find((item) => item.data.id === request.item_id)?.path;
+      const possibleTerminals = [
+        terminalEntry(publicationSuccess(request, record, observedAt, itemPath, namespace)),
+        terminalEntry(publicationUnknown(request)),
+        terminalEntry(publicationError(request, 'ledger-revision-conflict',
+          'The durable ledger revision no longer matches this publication.', {
+            ledger_namespace: request.ledger_namespace,
+            item_id: request.item_id,
+            expected_revision: request.expected_revision,
+            actual_revision: request.expected_revision,
+          }, 4)),
+      ];
+      const largestTerminal = possibleTerminals.reduce((largest, candidate) => (
+        Buffer.byteLength(JSON.stringify(candidate)) > Buffer.byteLength(JSON.stringify(largest))
+          ? candidate
+          : largest
+      ));
+      await assertClaimJournalCapacity(journalPath, [
+        intentEntry,
+        { type: 'clock', now: observedAt, floor: observedAt },
+        largestTerminal,
+      ]);
+      await publicationTestCheckpoint(scenario, 'before-publish-intent', ledgerDirectory);
+      const intent = await appendClaimEntry(journalPath, intentEntry);
       entries.push(intent);
+      intentAppended = true;
       await publicationTestCheckpoint(scenario, 'after-publish-intent', ledgerDirectory);
       const mutation = await publishClaimedCandidate({
         ledgerDirectory, request, scenario, ledgerSnapshot, namespaceLock, storePath,
       });
       if (!mutation.ok) {
         const outcome = mutationFailure(request, mutation);
-        return persistTerminal(entries, journalPath, ledgerDirectory, namespace, request, outcome, replayed.state, storePath);
+        return persistTerminal(entries, journalPath, ledgerDirectory, namespace, request, outcome, replayed.state, storePath, currentWorktreeId);
       }
       await publicationTestCheckpoint(scenario, 'after-ledger-commit', ledgerDirectory);
       const outcome = publicationSuccess(request, record, observedAt, mutation.item?.path, namespace);
-      const terminal = await persistTerminal(entries, journalPath, ledgerDirectory, namespace, request, outcome, replayed.state, storePath);
+      const terminal = await persistTerminal(entries, journalPath, ledgerDirectory, namespace, request, outcome, replayed.state, storePath, currentWorktreeId);
       await publicationTestCheckpoint(scenario, 'after-terminal-record', ledgerDirectory);
       return terminal;
     });
@@ -268,20 +344,132 @@ export async function publishClaimed({ ledgerDirectory, gitCommonDir, namespace,
         reason: 'claim-store-locked',
       }, 6);
     }
+    if (!intentAppended && isClaimJournalCapacityError(error)) {
+      return publicationError(request, 'claim-store-unavailable', 'The durable claim store is unavailable.', {
+        reason: 'journal-capacity-exceeded',
+      }, 6);
+    }
+    // An identity the coordination domain cannot resolve is a store this
+    // command could not read, not a mutation whose outcome is unknown: it
+    // refused before it appended an intent or touched an item byte.
+    if (error?.code === 'CLAIM_WORKTREE_IDENTITY_INVALID') {
+      return publicationError(request, 'claim-store-unavailable', 'The durable claim store is unavailable.', {
+        reason: 'claim-store-unreadable',
+        ...identityDiagnosticDetails(error),
+      }, 6);
+    }
+    if (!intentAppended) {
+      return publicationError(request, 'claim-store-unavailable', 'The durable claim store is unavailable.', {
+        reason: 'claim-store-unreadable',
+      }, 6);
+    }
     return publicationUnknown(request);
   }
 }
 
+export async function hydrateClaimJournalFromHead({
+  ledgerDirectory,
+  gitCommonDir,
+  namespace,
+  replayed,
+  persist = true,
+}) {
+  let log;
+  try {
+    log = await readGitTreeFile(
+      ledgerDirectory,
+      'HEAD',
+      `.wowbagger/reconcile-${namespace}.md`,
+    );
+  } catch (error) {
+    if (error?.code === 128) return replayed;
+    throw error;
+  }
+  const committed = parseReconcileLog(log, namespace);
+  if (committed.error) throw hydrationError(committed.error.reason);
+  if (committed.length === 0) return replayed;
+  const bySequence = new Map();
+  for (const entry of committed) {
+    if (!Number.isSafeInteger(entry.seq) || entry.seq < 1 || bySequence.has(entry.seq)) {
+      throw hydrationError('non-contiguous-sequence');
+    }
+    bySequence.set(entry.seq, entry);
+  }
+  for (const entry of committed) {
+    if (entry.seq > replayed.entries.length) continue;
+    if (!isDeepStrictEqual(replayed.entries[entry.seq - 1], entry)) {
+      throw hydrationError('local-journal-diverges-from-committed-log');
+    }
+  }
+  const maxSequence = Math.max(...bySequence.keys());
+  if (replayed.entries.length >= maxSequence) return replayed;
+  const fallbackTime = committed
+    .map((entry) => entry.observed_at ?? entry.physical_now)
+    .find((value) => typeof value === 'string')
+    ?? '1970-01-01T00:00:00.000Z';
+  const missingEntries = [];
+  for (let sequence = replayed.entries.length + 1; sequence <= maxSequence; sequence += 1) {
+    const entry = bySequence.get(sequence);
+    if (entry) {
+      const { seq, ...withoutSequence } = entry;
+      missingEntries.push(withoutSequence);
+    } else {
+      missingEntries.push({
+        type: 'clock',
+        now: fallbackTime,
+        floor: fallbackTime,
+      });
+    }
+  }
+  if (!persist) {
+    const entries = [
+      ...replayed.entries,
+      ...missingEntries.map((entry, index) => ({
+        seq: replayed.entries.length + index + 1,
+        ...entry,
+      })),
+    ];
+    return {
+      state: replayClaimEntries(entries, namespace),
+      entries,
+    };
+  }
+  const journalPath = claimJournalPath(gitCommonDir, namespace);
+  for (const entry of missingEntries) {
+    await appendClaimEntry(journalPath, entry);
+  }
+  return replayClaimJournal(journalPath, namespace);
+}
+
+function hydrationError(reason) {
+  const error = new Error('The committed reconciliation log is invalid.');
+  error.code = 'CLAIM_JOURNAL_INVALID';
+  error.reason = reason;
+  return error;
+}
+
 export async function reconcileClaimJournal({
   ledgerDirectory,
   gitCommonDir,
   namespace,
   replayed,
   physicalNow,
+  // The worktree this invocation speaks for, when it has established an
+  // identity. A caller that cannot name itself passes null, and every
+  // recorded writer then reads as unknown.
+  currentWorktreeId = null,
   targetItemId = null,
+  writeLogOnUnsafe = true,
+  writeLogWhenEmpty = true,
 }) {
   const storePath = claimStorePath(gitCommonDir, namespace);
   const journalPath = claimJournalPath(gitCommonDir, namespace);
+  replayed = await hydrateClaimJournalFromHead({
+    ledgerDirectory,
+    gitCommonDir,
+    namespace,
+    replayed,
+  });
   const ledger = await loadLedger(path.resolve(ledgerDirectory));
   const items = new Map(ledger.items.map((item) => [item.data.id, item]));
   const terminalKeys = new Set(replayed.entries
@@ -293,6 +481,16 @@ export async function reconcileClaimJournal({
   ));
   const entries = [...replayed.entries];
   const findings = [];
+  const findingScopes = [];
+  // What each finding refuses is the coordinator's own judgement, never a
+  // published member, so the scope rules on the write as the finding is
+  // recorded and never becomes a member something has to strip back out.
+  let unsafe = false;
+  const addFinding = (scope, finding) => {
+    unsafe ||= blocksTarget(scope, finding.item_id, targetItemId);
+    findings.push(finding);
+    findingScopes.push(scope);
+  };
   const observedAt = advanceClockFloor(replayed.state, physicalNow);
   try {
     entries.push(await appendClaimEntry(journalPath, {
@@ -327,6 +525,12 @@ export async function reconcileClaimJournal({
         command: intent.command,
         committed_revision: actualRevision,
         ...(intent.item_path ? { item_path: intent.item_path } : {}),
+        // The writer that authorized the attempt owns the revision this
+        // resolution ratifies, so its identity travels with the terminal
+        // entry. Absent on alpha.12 intents, which stay valid without it.
+        ...(intent.writer_worktree_id
+          ? { writer_worktree_id: intent.writer_worktree_id }
+          : {}),
         observed_at: observedAt,
       }));
     } else if (actualRevision === intent.expected_revision) {
@@ -335,6 +539,10 @@ export async function reconcileClaimJournal({
         attempt_id: intent.attempt_id,
         ledger_namespace: namespace,
         item_id: intent.item_id,
+        // A create abort names no predecessor revision, so its terminal must
+        // say which command aborted; patch and transition aborts keep their
+        // exact legacy shape and never carry a command.
+        ...(intent.command === 'create-v1' ? { command: intent.command } : {}),
         observed_revision: actualRevision,
         observed_at: observedAt,
       }));
@@ -343,7 +551,7 @@ export async function reconcileClaimJournal({
         ?? intent.item_path
         ?? null;
       const pathLabel = expectedPath ?? `item ${intent.item_id}`;
-      findings.push({
+      addFinding('global', {
         code: 'legacy-mutation-outcome-unknown',
         item_id: intent.item_id,
         attempt_id: intent.attempt_id,
@@ -416,10 +624,17 @@ export async function reconcileClaimJournal({
       operation_digest: intent.operation_digest,
       ledger_namespace: namespace,
       item_id: intent.item_id,
+      // The writer that authorized the publication owns the revision this
+      // resolution ratifies, so its identity travels with the terminal entry.
+      // Absent on alpha.12 intents, which stay valid without it.
+      ...(intent.writer_worktree_id
+        ? { writer_worktree_id: intent.writer_worktree_id }
+        : {}),
       outcome,
     }));
     const unknownPath = itemPathRelativeToLedger(ledgerDirectory, item?.file);
-    findings.push({
+    // A resolved intent is news, not a barrier: it refuses nothing.
+    addFinding(outcome.stdout.state === 'unknown' ? 'global' : 'none', {
       code: outcome.stdout.state === 'unknown'
         ? 'publication-outcome-unknown'
         : 'pending-intent-resolved',
@@ -484,7 +699,12 @@ export async function reconcileClaimJournal({
     const expectedRevision = authorizedRevisionOf(latestAuthorized);
     const authorizedRevisions = new Set(authorized.map(authorizedRevisionOf));
     for (const intent of entries) {
-      if (intent.type === 'legacy-mutation-intent' && intent.item_id === itemId) {
+      // A create names no predecessor revision, so its `null` is the absence of
+      // one, never a ruling that absent bytes are authorized. Reading it as a
+      // revision would make an uncommitted create look finalized in Git.
+      if (intent.type === 'legacy-mutation-intent'
+        && intent.item_id === itemId
+        && intent.expected_revision !== null) {
         authorizedRevisions.add(intent.expected_revision);
       }
     }
@@ -509,7 +729,7 @@ export async function reconcileClaimJournal({
     );
     if (activeMismatch?.earlier) {
       const pathLabel = expectedPath ?? `item ${itemId}`;
-      findings.push({
+      addFinding('global', {
         code: 'stale-write-detected',
         item_id: itemId,
         actual_revision: actualRevision,
@@ -528,21 +748,26 @@ export async function reconcileClaimJournal({
       });
       continue;
     }
+    const expectedWriter = expectedWriterOf(
+      latestAuthorized.writer_worktree_id ?? null,
+      currentWorktreeId,
+    );
     const diagnosis = await reconciliationDiagnosis({
       ledgerDirectory,
       actualRevision,
+      authorizedRevisions,
       expectedPath,
       expectedRevision,
       headRevision,
-      workingTreeChanged,
+      expectedWriter,
     });
-    findings.push({
+    addFinding(diagnosis.scope, {
       code: 'stale-write-detected',
       item_id: itemId,
       actual_revision: workingTreeChanged ? actualRevision : headRevision,
       expected_revision: expectedRevision,
       observed_surface: workingTreeChanged ? 'working-tree' : 'git-head',
-      ...diagnosis,
+      ...diagnosis.finding,
       ...(record?.active ? {
         active_fence: {
           ledger_namespace: namespace,
@@ -575,7 +800,7 @@ export async function reconcileClaimJournal({
       ?? expected.item_path
       ?? null;
     const pathLabel = expectedPath ?? `item ${record.item_id}`;
-    findings.push({
+    addFinding('global', {
       code: earlier ? 'stale-write-detected' : 'revision-regression',
       item_id: record.item_id,
       actual_revision: actualRevision,
@@ -599,11 +824,20 @@ export async function reconcileClaimJournal({
     });
   }
 
-  await writeReconcileLog(
-    claimReconcileLogPath(path.resolve(ledgerDirectory), namespace),
-    namespace,
-    entries,
-  );
+  const logPath = claimReconcileLogPath(path.resolve(ledgerDirectory), namespace);
+  let logExists = true;
+  try {
+    await access(logPath);
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+    logExists = false;
+  }
+  // An unsafe reconciliation and a log with nothing to project both leave the
+  // working tree alone unless the caller asks for the write, so a refusal never
+  // has to answer for a tracked artifact it did not intend to change.
+  const writesLog = (writeLogWhenEmpty || logExists || entries.some(isProjectedJournalEntry))
+    && (writeLogOnUnsafe || !unsafe);
+  if (writesLog) await writeReconcileLog(logPath, namespace, entries);
   try {
     await writeClaimState(storePath, replayed.state);
   } catch {
@@ -612,8 +846,14 @@ export async function reconcileClaimJournal({
   return {
     entries,
     findings,
+    findingScopes,
     gitHead,
     headItems,
+    // Every coordinated item the journal knows and this working ledger does not
+    // hold. An item's number is immutable, so a caller that allocates the next
+    // one needs to know when an allocation exists that it cannot read; a stale
+    // revision of an item that is present hides no number.
+    missingCoordinatedItems: [...coordinatedItems].filter((itemId) => !items.has(itemId)),
     // The snapshot reconciliation judged. Reconciliation writes only the
     // journal, the claim state, and the ledger's `.wowbagger` reconcile log,
     // none of which a complete ledger load reads, so these are still the bytes
@@ -623,15 +863,12 @@ export async function reconcileClaimJournal({
     ledger,
     observedAt,
     state: replayed.state,
-    unsafe: findings.some((finding) => (
-      finding.code !== 'pending-intent-resolved' && blocksTarget(finding, targetItemId)
-    )),
+    unsafe,
   };
 }
 
 // An item's authorized revision is whatever the journal last ruled legitimate:
 // a committed claimed publication, a legacy mutation, or an operator adoption.
-// Adoption is the only one of the three that changes no item byte.
 function authorizingEntries(entries, itemId) {
   return entries.filter((entry) => (
     entry.item_id === itemId
@@ -653,60 +890,110 @@ function itemPathRelativeToLedger(ledgerDirectory, file) {
   return path.relative(path.resolve(ledgerDirectory), file).split(path.sep).join('/');
 }
 
-// A mutation names the item it targets. Another item's unresolved publication
-// waits on a synchronization this mutation does not touch, so it reports as a
-// finding without refusing the write. A caller that names no target, such as
-// the `claim-verify` command, keeps every finding blocking.
-function blocksTarget(finding, targetItemId) {
-  if (targetItemId === null || finding.item_id === targetItemId) return true;
-  return finding.reason !== 'worktree-synchronization-required';
-}
-
 // Ownership is evidence, never a guess: an unreadable history or a missing
 // expected path leaves the revision unattributed instead of naming a ref.
 async function revisionOwnerEvidence(ledgerDirectory, expectedPath, expectedRevision) {
-  if (!expectedPath) return { owner_unavailable: true };
+  if (!expectedPath) return { kind: 'unreachable' };
   try {
     return await findRevisionOwner(ledgerDirectory, expectedPath, expectedRevision);
   } catch {
-    return { owner_unavailable: true };
+    return { kind: 'unreachable' };
+  }
+}
+
+// The classifier decides which topology this is; the sentences stay here.
+// Member order is part of the published finding, so each remedy builds its own
+// shape rather than sharing a base object.
+function topologyFinding(decision, expectedPath, expectedRevision) {
+  const pathLabel = expectedPath ?? 'the item path';
+  const at = expectedPath ? { expected_path: expectedPath } : {};
+  switch (decision.remediation) {
+    case 'commit-in-git':
+      return {
+        reason: decision.reason,
+        ...at,
+        remediation: `Commit ${pathLabel} in Git, then run claim-verify.`,
+      };
+    case 'wait-for-named-owner':
+      return {
+        reason: decision.reason,
+        ...at,
+        owner_ref: decision.owner.ref,
+        owner_commit: decision.owner.commit,
+        remediation: `WAIT for owner ${decision.owner.ref} to publish ${decision.owner.commit}, then synchronize this worktree and run claim-verify.`,
+      };
+    case 'establish-ownership':
+      return {
+        reason: decision.reason,
+        ...at,
+        owner_unavailable: true,
+        remediation: `Ownership of ${pathLabel} revision ${expectedRevision} cannot be established from reachable refs; inspect reachable or dangling commits, restore or explicitly adopt reviewed bytes, then run claim-verify.`,
+      };
+    // Reachable but unowned: the revision is in Git already, so the only honest
+    // instruction is to go read it. Naming an owner to wait for would be a wait
+    // with no end, which is what item #178 found in the field.
+    case 'inspect-reachable-history':
+      return {
+        reason: decision.reason,
+        ...at,
+        owner_unavailable: true,
+        remediation: `Revision ${expectedRevision} of ${pathLabel} is reachable in Git, but no active named worktree owner is established; inspect the reachable history, restore or explicitly adopt reviewed bytes, then run claim-verify.`,
+      };
+    case 'await-owner-commit':
+      return {
+        reason: decision.reason,
+        ...at,
+        owner_unavailable: true,
+        remediation: `Ownership of ${pathLabel} revision ${expectedRevision} is not yet reachable; wait for the owning worktree to commit, then synchronize this worktree and run claim-verify.`,
+      };
+    // Two remedies, both named, in the order that makes the cost obvious. The
+    // field report behind item #113 read the single restore sentence as the
+    // only way out and discarded reviewed, merged work to obey it.
+    case 'restore-or-adopt':
+      return {
+        reason: decision.reason,
+        ...at,
+        remediation: `Restore the authorized revision at ${pathLabel}, then run claim-verify; that discards the edit. Or adopt the committed revision of ${pathLabel} with claim-adopt, then run claim-verify; that keeps the edit.`,
+      };
+    default:
+      throw new Error(`The reconciliation topology named no remedy: ${decision.remediation}.`);
   }
 }
 
+// Who the journal says wrote the authorized revision, judged against who is
+// asking. An entry from before writer identity existed, or a caller that
+// cannot name itself, leaves the writer unknown.
+function expectedWriterOf(recordedWriter, currentWorktreeId) {
+  if (recordedWriter === null || currentWorktreeId === null) return 'unknown';
+  return recordedWriter === currentWorktreeId ? 'current' : 'other';
+}
+
+// Evidence in, scope and public finding out: the classifier rules on the
+// topology, and this gathers exactly the evidence it rules on, then renders
+// the sentence it prescribes.
 async function reconciliationDiagnosis({
   ledgerDirectory,
   actualRevision,
+  authorizedRevisions,
   expectedPath,
   expectedRevision,
   headRevision,
-  workingTreeChanged,
+  expectedWriter,
 }) {
-  const pathLabel = expectedPath ?? 'the item path';
-  if (!workingTreeChanged && headRevision !== expectedRevision) {
-    return {
-      reason: 'git-finalization-required',
-      ...(expectedPath ? { expected_path: expectedPath } : {}),
-      remediation: `Commit ${pathLabel} in Git, then run claim-verify.`,
-    };
-  }
-  if (actualRevision === null && headRevision !== expectedRevision) {
-    const owner = await revisionOwnerEvidence(ledgerDirectory, expectedPath, expectedRevision);
-    return {
-      reason: 'worktree-synchronization-required',
-      ...(expectedPath ? { expected_path: expectedPath } : {}),
-      ...owner,
-      remediation: owner.owner_ref
-        ? `WAIT for owner ${owner.owner_ref} to publish ${owner.owner_commit}, then synchronize this worktree and run claim-verify.`
-        : `Ownership of ${pathLabel} revision ${expectedRevision} cannot be established from reachable refs; inspect reachable or dangling commits, restore or explicitly adopt reviewed bytes, then run claim-verify.`,
-    };
-  }
-  // Two remedies, both named, in the order that makes the cost obvious. The
-  // field report behind item #113 read the single restore sentence as the only
-  // way out and discarded reviewed, merged work to obey it.
+  const revisions = {
+    workingTree: normalizeRevision(actualRevision, expectedRevision, authorizedRevisions),
+    head: normalizeRevision(headRevision, expectedRevision, authorizedRevisions),
+  };
+  const decision = classifyReconciliation({
+    ...revisions,
+    expectedOwner: requiresOwnerEvidence(revisions)
+      ? await revisionOwnerEvidence(ledgerDirectory, expectedPath, expectedRevision)
+      : null,
+    expectedWriter,
+  });
   return {
-    reason: 'unauthorized-revision',
-    ...(expectedPath ? { expected_path: expectedPath } : {}),
-    remediation: `Restore the authorized revision at ${pathLabel}, then run claim-verify; that discards the edit. Or adopt the committed revision of ${pathLabel} with claim-adopt, then run claim-verify; that keeps the edit.`,
+    scope: decision.scope,
+    finding: topologyFinding(decision, expectedPath, expectedRevision),
   };
 }
 
@@ -771,18 +1058,32 @@ export async function verifyClaimJournal({
   gitCommonDir,
   namespace,
   targetItemId = null,
+  writeLogOnUnsafe = true,
+  writeLogWhenEmpty = true,
 }) {
   const storePath = claimStorePath(gitCommonDir, namespace);
   const journalPath = claimJournalPath(gitCommonDir, namespace);
   try {
     return await withClaimLock(storePath, async () => {
+      // Verification writes no item byte and creates no identity: it reports on
+      // the worktree it runs in, and an unidentified worktree simply cannot
+      // recognize itself in a recorded writer. Its own file is judged first, so
+      // bytes this worktree owns keep reporting as its own invalid identity
+      // rather than as an unreadable roster.
+      const currentWorktreeId = await readWorktreeIdentity({ ledgerDirectory, gitCommonDir });
+      // Verification reasons from recorded writers, so it refuses an ambiguous
+      // domain before it classifies anything, exactly as a mutation does.
+      await assertUniqueWorktreeIdentity({ ledgerDirectory });
       const reconciled = await reconcileClaimJournal({
         ledgerDirectory,
         gitCommonDir,
         namespace,
         replayed: await replayClaimJournal(journalPath, namespace),
         physicalNow: new Date().toISOString(),
+        currentWorktreeId,
         targetItemId,
+        writeLogWhenEmpty,
+        writeLogOnUnsafe,
       });
       return {
         exit: reconciled.unsafe ? 6 : 0,
@@ -795,7 +1096,17 @@ export async function verifyClaimJournal({
           result: {
             ledger_namespace: namespace,
             observed_at: reconciled.observedAt,
-            findings: reconciled.findings,
+            verification_scope: targetItemId === null
+              ? { mode: 'repository' }
+              : { mode: 'target-item', item_id: targetItemId },
+            findings: reconciled.findings.map((finding, index) => ({
+              ...finding,
+              blocks_verification_scope: blocksTarget(
+                reconciled.findingScopes[index],
+                finding.item_id,
+                targetItemId,
+              ),
+            })),
             ledger_validation: ledgerValidationReport(reconciled.ledger),
             publications: publicationStatuses(reconciled.entries),
           },
@@ -817,7 +1128,10 @@ export async function verifyClaimJournal({
           details: {
             reason: error?.code === 'CLAIM_LOCK_HELD'
               ? 'claim-store-locked'
-              : 'claim-store-unreadable',
+              : isClaimJournalCapacityError(error)
+                ? 'journal-capacity-exceeded'
+                : 'claim-store-unreadable',
+            ...identityDiagnosticDetails(error),
           },
         },
       },
@@ -829,20 +1143,30 @@ export async function verifyClaimJournal({
 // re-baselines the coordinator's authorized revision onto bytes that are
 // already committed, and writes no item byte. It runs while reconciliation is
 // unsafe on purpose — clearing that state is the point — so it never refuses on
-// `publication-reconciliation-required` the way a claim lifecycle operation
-// does. Every precondition is checked under the claim lock against the state
-// reconciliation just observed.
+// `publication-reconciliation-required` the way `claim acquire` or
+// `claim renew` do. Every precondition is checked under the claim lock against
+// the state reconciliation just observed.
 export async function adoptItemRevision({ ledgerDirectory, gitCommonDir, namespace, request }) {
   const storePath = claimStorePath(gitCommonDir, namespace);
   const journalPath = claimJournalPath(gitCommonDir, namespace);
   try {
     return await withClaimLock(storePath, async () => {
+      // Adoption writes no item byte and creates no identity, so it names
+      // itself by reading the ID it already answers to. Its own file is judged
+      // first, so bytes this worktree owns keep reporting as its own invalid
+      // identity rather than as an unreadable roster, exactly as claim-verify
+      // reports them.
+      const currentWorktreeId = await readWorktreeIdentity({ ledgerDirectory, gitCommonDir });
+      // Adoption re-baselines an authorized revision, so it too refuses an
+      // ambiguous domain before reconciliation classifies one.
+      await assertUniqueWorktreeIdentity({ ledgerDirectory });
       const reconciled = await reconcileClaimJournal({
         ledgerDirectory,
         gitCommonDir,
         namespace,
         replayed: await replayClaimJournal(journalPath, namespace),
         physicalNow: new Date().toISOString(),
+        currentWorktreeId,
       });
       const refusal = adoptionRefusal(reconciled, ledgerDirectory, request);
       if (refusal) return refusal;
@@ -901,17 +1225,26 @@ export async function adoptItemRevision({ ledgerDirectory, gitCommonDir, namespa
         contract_version: 1,
         state: 'unchanged',
         error: {
-          code: error?.code === 'CLOCK_FLOOR_PERSISTENCE_FAILED'
-            ? 'clock-floor-persistence-failed'
-            : 'claim-store-unavailable',
-          message: error?.code === 'CLOCK_FLOOR_PERSISTENCE_FAILED'
-            ? 'The authoritative clock floor could not be persisted.'
-            : 'The durable claim store is unavailable.',
-          details: error?.code === 'CLOCK_FLOOR_PERSISTENCE_FAILED' ? {} : {
-            reason: error?.code === 'CLAIM_LOCK_HELD'
-              ? 'claim-store-locked'
-              : 'claim-store-unreadable',
-          },
+          code: isClaimJournalCapacityError(error)
+            ? 'claim-store-unavailable'
+            : error?.code === 'CLOCK_FLOOR_PERSISTENCE_FAILED'
+              ? 'clock-floor-persistence-failed'
+              : 'claim-store-unavailable',
+          message: isClaimJournalCapacityError(error)
+            ? 'The durable claim store is unavailable.'
+            : error?.code === 'CLOCK_FLOOR_PERSISTENCE_FAILED'
+              ? 'The authoritative clock floor could not be persisted.'
+              : 'The durable claim store is unavailable.',
+          details: isClaimJournalCapacityError(error)
+            ? { reason: 'journal-capacity-exceeded' }
+            : error?.code === 'CLOCK_FLOOR_PERSISTENCE_FAILED'
+              ? {}
+              : {
+                reason: error?.code === 'CLAIM_LOCK_HELD'
+                  ? 'claim-store-locked'
+                  : 'claim-store-unreadable',
+                ...identityDiagnosticDetails(error),
+              },
         },
       },
     };
@@ -1017,13 +1350,14 @@ export function operationDigest(request) {
   return `sha256:${createHash('sha256').update(canonicalJson(request)).digest('hex')}`;
 }
 
-async function persistTerminal(entries, journalPath, ledgerDirectory, namespace, request, outcome, state, storePath) {
+async function persistTerminal(entries, journalPath, ledgerDirectory, namespace, request, outcome, state, storePath, writerWorktreeId) {
   const terminal = await appendClaimEntry(journalPath, {
     type: 'publish-final',
     operation_id: request.operation_id,
     operation_digest: operationDigest(request),
     ledger_namespace: request.ledger_namespace,
     item_id: request.item_id,
+    writer_worktree_id: writerWorktreeId,
     outcome,
   });
   entries.push(terminal);