wowbagger 0.1.0-alpha.13 → 0.1.0-alpha.14

package/src/claim-publication.js

@@ -18,6 +18,12 @@ import { loadLedger, parseLedgerItemSource } from './ledger.js';
 import { MAX_ITEM_SOURCE_BYTES } from './limits.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,
@@ -403,6 +409,14 @@ export async function reconcileClaimJournal({
   ));
   const entries = [...replayed.entries];
   const findings = [];
+  // 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);
+  };
   const observedAt = advanceClockFloor(replayed.state, physicalNow);
   try {
     entries.push(await appendClaimEntry(journalPath, {
@@ -451,6 +465,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,
       }));
@@ -459,7 +477,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,
@@ -541,7 +559,8 @@ export async function reconcileClaimJournal({
       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',
@@ -606,7 +625,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);
       }
     }
@@ -631,7 +655,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,
@@ -650,13 +674,10 @@ export async function reconcileClaimJournal({
       });
       continue;
     }
-    // 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.
-    const recordedWriter = latestAuthorized.writer_worktree_id ?? null;
-    const expectedWriter = recordedWriter === null || currentWorktreeId === null
-      ? 'unknown'
-      : recordedWriter === currentWorktreeId ? 'current' : 'other';
+    const expectedWriter = expectedWriterOf(
+      latestAuthorized.writer_worktree_id ?? null,
+      currentWorktreeId,
+    );
     const diagnosis = await reconciliationDiagnosis({
       ledgerDirectory,
       actualRevision,
@@ -665,15 +686,14 @@ export async function reconcileClaimJournal({
       expectedRevision,
       headRevision,
       expectedWriter,
-      workingTreeChanged,
     });
-    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,
@@ -706,7 +726,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,
@@ -730,9 +750,6 @@ export async function reconcileClaimJournal({
     });
   }
 
-  const unsafe = findings.some((finding) => (
-    finding.code !== 'pending-intent-resolved' && blocksTarget(finding, targetItemId)
-  ));
   const logPath = claimReconcileLogPath(path.resolve(ledgerDirectory), namespace);
   let logExists = true;
   try {
@@ -757,6 +774,11 @@ export async function reconcileClaimJournal({
     findings,
     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
@@ -793,15 +815,6 @@ 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) {
@@ -813,18 +826,76 @@ async function revisionOwnerEvidence(ledgerDirectory, expectedPath, expectedRevi
   }
 }
 
-// One owner, one shape: only an active named worktree reaches this finding, and
-// the remediation names the same ref and commit the finding does.
-function namedOwnerFinding(owner, expectedPath) {
-  return {
-    reason: 'worktree-synchronization-required',
-    ...(expectedPath ? { expected_path: expectedPath } : {}),
-    owner_ref: owner.ref,
-    owner_commit: owner.commit,
-    remediation: `WAIT for owner ${owner.ref} to publish ${owner.commit}, then synchronize this worktree and run claim-verify.`,
-  };
+// 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,
@@ -833,64 +904,22 @@ async function reconciliationDiagnosis({
   expectedRevision,
   headRevision,
   expectedWriter,
-  workingTreeChanged,
 }) {
-  const pathLabel = expectedPath ?? 'the item path';
-  // 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 unauthorizedRevision = {
-    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.`,
+  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 {
+    scope: decision.scope,
+    finding: topologyFinding(decision, expectedPath, expectedRevision),
   };
-  const hasOutOfProtocolLocalState = (
-    (actualRevision !== null && !authorizedRevisions.has(actualRevision))
-    || (headRevision !== null && !authorizedRevisions.has(headRevision))
-    || (actualRevision === null && headRevision !== null)
-  );
-  if (hasOutOfProtocolLocalState) return unauthorizedRevision;
-  let expectedOwner = null;
-  if (headRevision !== null && actualRevision === headRevision
-    && headRevision !== expectedRevision) {
-    expectedOwner = await revisionOwnerEvidence(ledgerDirectory, expectedPath, expectedRevision);
-    if (expectedOwner.kind === 'named-sibling') return namedOwnerFinding(expectedOwner, expectedPath);
-  }
-  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);
-    if (owner.kind === 'named-sibling') return namedOwnerFinding(owner, expectedPath);
-    return {
-      reason: 'worktree-synchronization-required',
-      ...(expectedPath ? { expected_path: expectedPath } : {}),
-      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.`,
-    };
-  }
-  if (authorizedRevisions.has(actualRevision)) {
-    expectedOwner ??= await revisionOwnerEvidence(ledgerDirectory, expectedPath, expectedRevision);
-    if (expectedOwner.kind === 'named-sibling') return namedOwnerFinding(expectedOwner, expectedPath);
-    // Advice to wait for an owning worktree needs an owner that could still
-    // appear. When the journal names this worktree as the writer of the
-    // expected revision and no active worktree carries it, the successor exists
-    // nowhere but in the journal: there is nothing to synchronize from, and the
-    // local bytes are simply unauthorized.
-    if (expectedWriter !== 'current' && expectedOwner.kind !== 'current') {
-      return {
-        reason: 'worktree-synchronization-required',
-        ...(expectedPath ? { expected_path: expectedPath } : {}),
-        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.`,
-      };
-    }
-  }
-  return unauthorizedRevision;
 }
 
 function activePublicationMismatch(entries, record, actualRevision, observedAt) {

package/src/cli.js

@@ -1654,20 +1654,18 @@ async function runClaimCommand(claimCommand, argumentsList) {
   }
   try {
     const envelope = await withClaimLock(storePath, async () => {
-      let replayed;
-      try {
-        replayed = await replayClaimJournal(journalPath, namespace);
-      } catch (error) {
-        throw taggedFailure('CLAIM_STORE_UNREADABLE', error);
-      }
       // A claim lifecycle command classifies item reconciliation and refuses
       // on it, so it must reason from the same writer evidence every other
       // classifying surface uses; otherwise one command grants a claim on
       // exactly the state another command refuses to write. It writes no item
       // byte and no writer-attributed entry, so it reads the identity it
-      // already answers to rather than creating one.
+      // already answers to rather than creating one. Journal and identity are
+      // both store state this command only reads, so neither reading failure
+      // is anything but an unreadable store.
+      let replayed;
       let currentWorktreeId;
       try {
+        replayed = await replayClaimJournal(journalPath, namespace);
         currentWorktreeId = await readWorktreeIdentity({
           ledgerDirectory: parsedOptions.options.ledger,
           gitCommonDir,

package/src/git-autocommit.js

@@ -119,17 +119,25 @@ async function finalize({
 }) {
   const { root, prefix } = placement;
   const logPath = ledgerRelative(ledgerDirectory, claimReconcileLogPath(path.resolve(ledgerDirectory), namespace));
-  const journalOwned = command !== 'create';
+  // Every mutation, create included, appends its own journal entries and
+  // rebuilds the derived reconciliation log, so every commit set carries that
+  // log alongside the item.
+  //
+  // Log dirt that predates the invocation is a separate question. A mutation on
+  // an existing item rebuilds residue its own prior claim operations left in
+  // this checkout; a create allocates a fresh identity and has no standing to
+  // absorb bytes that were already there, so it refuses instead.
+  const absorbsPriorLogDirt = command !== 'create';
 
   // Preflight, before any Wowbagger write. Any staged path and every dirty
-  // ledger path except the journal-owning command's derived log refuse: a broad
-  // commit would otherwise absorb foreign work.
+  // ledger path except an absorbable derived log refuse: a broad commit would
+  // otherwise take in foreign work.
   const before = await inspectWorktree(root, prefix);
   if (before.staged.length > 0) {
     return shape.preflightFailed('staged-paths-present', { staged_paths: bounded(before.staged) });
   }
   const foreignDirtyBefore = before.dirtyLedger.filter((entry) => (
-    !(journalOwned && entry === logPath)
+    !(absorbsPriorLogDirt && entry === logPath)
   ));
   if (foreignDirtyBefore.length > 0) {
     return shape.preflightFailed('ledger-not-clean', { dirty_paths: bounded(foreignDirtyBefore) });
@@ -165,13 +173,13 @@ async function finalize({
     });
   }
 
-  // Reconciliation rewrites the tracked log. Only a command that will commit
-  // that log may proceed with it dirty; create commits the item alone.
+  // Reconciliation rewrites the tracked log. Every command here will commit
+  // that log, so its own rewrite is never stray; anything else is.
   const afterVerify = await inspectWorktree(root, prefix);
   if (afterVerify.staged.length > 0) {
     return shape.preflightFailed('staged-paths-present', { staged_paths: bounded(afterVerify.staged) });
   }
-  const strayBefore = afterVerify.dirtyLedger.filter((entry) => !(journalOwned && entry === logPath));
+  const strayBefore = afterVerify.dirtyLedger.filter((entry) => entry !== logPath);
   if (strayBefore.length > 0) {
     return shape.preflightFailed('ledger-not-clean', { dirty_paths: bounded(strayBefore) });
   }
@@ -210,10 +218,10 @@ async function finalize({
   const itemChanged = await itemDiffersFromHead(root, prefix, published.path, published.revision);
   const commitSet = [
     ...(itemChanged ? [published.path] : []),
-    ...(journalOwned ? [logPath] : []),
+    logPath,
   ].sort(compareText);
   const subject = commitSubject(command, published.number, published.id);
-  const witness = journalOwned ? shape.terminalWitness(outcome, published) : null;
+  const witness = shape.terminalWitness(outcome, published);
   const context = {
     command,
     head,
@@ -232,7 +240,6 @@ async function finalize({
     context,
     commitSet,
     digests,
-    journalOwned,
     ledgerDirectory,
     logPath,
     ownArtifacts: shape.recoveryArtifactPaths(outcome),
@@ -287,7 +294,7 @@ async function finalize({
     gitCommonDir,
     namespace,
     targetItemId: published.id,
-    writeLogWhenEmpty: journalOwned,
+    writeLogWhenEmpty: true,
   });
   const reconciliation = reconciliationFailureReason(reconciled, commit.commit, context.operationId, published.id);
   if (reconciliation) {
@@ -305,7 +312,7 @@ async function finalize({
 // Every check that must hold between publication and staging. Returning a
 // reason here means the item is published and no Git write has happened yet.
 async function prepareCommitSet({
-  context, commitSet, digests, journalOwned, ledgerDirectory, logPath, ownArtifacts, prefix, root, witness,
+  context, commitSet, digests, ledgerDirectory, logPath, ownArtifacts, prefix, root, witness,
 }) {
   let itemBytes;
   try {
@@ -330,7 +337,6 @@ async function prepareCommitSet({
   ));
   if (stray.length > 0) return { stage: 'prepare-commit-set', reason: 'tree-changed' };
 
-  if (!journalOwned) return null;
   let logBytes;
   try {
     logBytes = await readFile(path.join(path.resolve(ledgerDirectory), logPath));
@@ -852,7 +858,6 @@ export async function finalizeFromRecoveryToken({ ledgerDirectory, token }) {
 
 async function runFinalize({ gitCommonDir, ledgerDirectory, namespace, payload, placement }) {
   const { root, prefix } = placement;
-  const journalOwned = payload.command !== 'create';
   const logPath = ledgerRelative(ledgerDirectory, claimReconcileLogPath(path.resolve(ledgerDirectory), namespace));
   const witness = payload.terminal_witness ?? null;
 
@@ -877,14 +882,15 @@ async function runFinalize({ gitCommonDir, ledgerDirectory, namespace, payload,
     const itemChanged = await itemDiffersFromHead(root, prefix, derived.path, payload.published_revision);
     commitSet = [
       ...(itemChanged ? [derived.path] : []),
-      ...(journalOwned ? [logPath] : []),
+      logPath,
     ].sort(compareText);
   } else {
     commitSet = [...tokenPaths].sort(compareText);
   }
-  const allowedCommitSets = journalOwned
-    ? [[logPath], [derived.path, logPath]]
-    : [[derived.path]];
+  // A token is only ever issued by the auto-commit path above, where every
+  // command owns its reconciliation log, so recovery accepts the same two
+  // shapes for every command.
+  const allowedCommitSets = [[logPath], [derived.path, logPath]];
   const tokenMatchesMutation = allowedCommitSets.some((allowed) => sameSet(tokenPaths, allowed));
   if (payload.item_path !== derived.path
     || !tokenMatchesMutation
@@ -910,7 +916,7 @@ async function runFinalize({ gitCommonDir, ledgerDirectory, namespace, payload,
   }
 
   const refusal = await finalizePreconditions({
-    commitSet, derived, digests, gitPaths, journalOwned, ledgerDirectory, logPath, payload, prefix, root, witness,
+    commitSet, derived, digests, gitPaths, ledgerDirectory, logPath, payload, prefix, root, witness,
   });
   if (refusal) return finalizeRefused(refusal.reason, refusal.details);
 
@@ -952,7 +958,7 @@ async function runFinalize({ gitCommonDir, ledgerDirectory, namespace, payload,
 }
 
 async function finalizePreconditions({
-  commitSet, derived, digests, gitPaths, journalOwned, ledgerDirectory, logPath, payload, prefix, root, witness,
+  commitSet, derived, digests, gitPaths, ledgerDirectory, logPath, payload, prefix, root, witness,
 }) {
   let itemBytes;
   try {
@@ -973,7 +979,6 @@ async function finalizePreconditions({
   }
   const stray = observed.dirtyLedger.filter((entry) => !commitSet.includes(entry));
   if (stray.length > 0) return { reason: 'ledger-not-clean', details: { dirty_paths: bounded(stray) } };
-  if (!journalOwned) return null;
   let logBytes;
   try {
     logBytes = await readFile(path.join(path.resolve(ledgerDirectory), logPath));

package/src/mutation.js

@@ -230,11 +230,15 @@ export async function createItem(ledgerDirectory, request, scenario) {
     ledgerDirectory,
     request.id,
     'create-v1',
-    (authorize, ledgerSnapshot) => createItemUnfenced(ledgerDirectory, request, scenario, ledgerSnapshot),
+    (authorize, ledgerSnapshot) => createItemUnfenced(
+      ledgerDirectory, request, scenario, authorize, ledgerSnapshot,
+    ),
   );
 }
 
-async function createItemUnfenced(ledgerDirectory, request, scenario, ledgerSnapshot) {
+async function createItemUnfenced(
+  ledgerDirectory, request, scenario, authorize, ledgerSnapshot,
+) {
   const root = path.resolve(ledgerDirectory);
   const id = request.id;
   const readPreLockLedger = snapshotReader(root, ledgerSnapshot);
@@ -362,6 +366,15 @@ async function createItemUnfenced(ledgerDirectory, request, scenario, ledgerSnap
         }));
       }
 
+      // The allocation this create proposes becomes journal-visible before any
+      // byte reaches the ledger, so a sibling worktree that cannot see this
+      // item's publication cannot hand the same number out again. The intent is
+      // appended only once the candidate is known publishable, so a refusal
+      // this command would have returned anyway records no attempt.
+      if (authorize) {
+        await authorize(null, revisionFor(bytes), relativeFinalPath);
+      }
+
       temporaryPath = path.join(finalDirectory, `.wowbagger-tmp-${id}-${randomSuffix()}`);
       const temporaryFailure = await prepareTemporary(temporaryPath, bytes, null, scenario);
       if (temporaryFailure) {

package/src/reconciliation-classifier.js

@@ -0,0 +1,117 @@
+// The reconciliation topology, decided once, from evidence alone.
+//
+// Every command that reconciles a claim journal has to answer the same
+// question about a drifted item: which of the recognized topologies is this,
+// and does it block the write in front of us? Answering it inside each command
+// is how the answers drifted apart, so the decision lives here, pure: no Git,
+// no filesystem, no prose. Callers gather the evidence, render the sentences,
+// and keep the scope to themselves.
+//
+// The vocabulary:
+//
+//   revision state  where a surface's bytes stand against the journal —
+//                   `expected` the authorized revision itself, `authorized`
+//                   some other revision the journal once ruled legitimate,
+//                   `unknown` bytes no ruling covers, `absent` no bytes at all.
+//   owner evidence  `{ kind, ref?, commit? }` from `findRevisionOwner`: which
+//                   live worktree, if any, carries the expected revision.
+//   expected writer `current` when the journal names this worktree as the
+//                   writer of the expected revision, `other` when it names
+//                   another, `unknown` when nothing can be attributed.
+//   scope           who a finding blocks: `global` every write, `target` only
+//                   a write against the item it names, `none` nobody.
+//   remediation     which remedy the topology prescribes; the caller renders
+//                   the sentence, so the kinds carry no wording.
+
+// Where one surface's bytes stand against the journal. `expected` is a
+// refinement of `authorized`, so it is tested first.
+export function normalizeRevision(revision, expectedRevision, authorizedRevisions) {
+  if (revision === null) return 'absent';
+  if (revision === expectedRevision) return 'expected';
+  return authorizedRevisions.has(revision) ? 'authorized' : 'unknown';
+}
+
+// Owner evidence costs a walk of every live worktree's history, so the two
+// topologies that never consult it must not pay for it. The predicate answers
+// from the same states the classifier judges, through the same helper, so
+// neither can drift from the other.
+export function requiresOwnerEvidence({ workingTree, head }) {
+  return !isUnattributed(workingTree, head) && workingTree !== 'expected';
+}
+
+// Bytes no ruling covers, on either surface, and a working tree that is gone
+// while another surface still holds bytes. Nothing here is attributable to a
+// writer or an owner: the local state is simply out of protocol.
+function isUnattributed(workingTree, head) {
+  return workingTree === 'unknown'
+    || head === 'unknown'
+    || (workingTree === 'absent' && head !== 'absent');
+}
+
+// One topology, one member. `expectedOwner` is required exactly when
+// `requiresOwnerEvidence` says so, and is never read otherwise.
+export function classifyReconciliation({ workingTree, head, expectedOwner, expectedWriter }) {
+  if (isUnattributed(workingTree, head)) return UNAUTHORIZED_REVISION;
+  // The authorized bytes are here and Git has yet to record them. Nothing is
+  // in doubt but the commit.
+  if (workingTree === 'expected') {
+    return { scope: 'global', reason: 'git-finalization-required', remediation: 'commit-in-git' };
+  }
+  // An item absent from both local surfaces has never existed in this
+  // checkout. A sibling may carry the expected revision, but that does not
+  // establish ownership for a checkout with no local history or item path.
+  if (workingTree === 'absent') {
+    return {
+      scope: 'target',
+      reason: 'worktree-synchronization-required',
+      remediation: 'establish-ownership',
+    };
+  }
+  // A live named worktree carries the expected revision, so there is a ref to
+  // wait on and a commit to name. This outranks the remaining synchronization
+  // answers, because it is the only one that names an owner.
+  if (expectedOwner.kind === 'named-sibling') {
+    return {
+      scope: 'target',
+      reason: 'worktree-synchronization-required',
+      owner: expectedOwner,
+      remediation: 'wait-for-named-owner',
+    };
+  }
+  // Advice to wait for an owning worktree needs an owner that could still
+  // appear. When the journal names this worktree as the writer of the expected
+  // revision, or this worktree's own history reaches it, the successor exists
+  // nowhere but in the journal: there is nothing to synchronize from, and the
+  // authorized bytes on disk are simply the wrong ones.
+  if (expectedWriter !== 'current' && expectedOwner.kind !== 'current') {
+    return {
+      scope: 'target',
+      reason: 'worktree-synchronization-required',
+      // Waiting is only truthful while the commit is still missing. Git already
+      // reaches a `reachable-unowned` revision through a tag, a remote-tracking
+      // ref, an unchecked branch, or a detached HEAD, so telling a reader to
+      // wait for a commit names a wait that can never end: the bytes are there
+      // to inspect, and no named worktree will publish them.
+      remediation: expectedOwner.kind === 'reachable-unowned'
+        ? 'inspect-reachable-history'
+        : 'await-owner-commit',
+    };
+  }
+  return UNAUTHORIZED_REVISION;
+}
+
+const UNAUTHORIZED_REVISION = Object.freeze({
+  scope: 'global',
+  reason: 'unauthorized-revision',
+  remediation: 'restore-or-adopt',
+});
+
+// Scope, never reason text, decides what a finding refuses. A mutation names
+// the item it targets, and a synchronization another item waits on is a wait
+// this mutation does not touch. A caller that names no target, such as the
+// `claim-verify` command, keeps every finding blocking.
+export function blocksTarget(scope, itemId, targetItemId) {
+  if (scope === 'none') return false;
+  if (scope === 'global') return true;
+  return targetItemId === null || itemId === targetItemId;
+}