wowbagger 0.1.0-alpha.13 → 0.1.0-alpha.17

package/src/cli.js

@@ -38,6 +38,14 @@ import {
 import { readGitTreeFile, readGitTreeLedger } from './git-reconciliation.js';
 import { finalizeFromRecoveryToken, withAutoCommit } from './git-autocommit.js';
 import { loadLedger } from './ledger.js';
+import {
+  finalizeNumberRepairCommit,
+  isNumberRepairRecoveryToken,
+  ledgerRepairInvalidRequest,
+  numberRepair,
+  numberRepairProposal,
+} from './ledger-repair.js';
+import { inspectVersionDrift } from './version-drift.js';
 import {
   assertReportOutputOutsideLedger,
   buildReportModel,
@@ -93,6 +101,7 @@ const AUTO_COMMIT_COMMANDS = new Set([
   'snooze',
   'patch',
   'publish-claimed',
+  'number-repair',
 ]);
 // The report failures this command states. A code outside the set is an
 // unexpected condition, never a classification the command can pass through.
@@ -130,6 +139,8 @@ const COMMAND_SUMMARIES = {
   'claim-sync': 'Import committed adoption evidence into the local claim journal.',
   'claim-adopt': 'Rule a committed out-of-protocol item revision legitimate.',
   'mutation-finalize': 'Complete the Git commit an auto-commit mutation could not establish.',
+  'version-drift': 'Check installed skill and running core version compatibility.',
+  'number-repair': 'Apply a proposed duplicate-number repair to a ledger the mutation gate refuses.',
   provision: 'Provision a Git-backed work-claim namespace.',
   claim: 'Read and coordinate work claims for one ledger.',
   'claim-verify': 'Reconcile the durable claim journal with ledger bytes and Git.',
@@ -157,6 +168,8 @@ const KNOWN_COMMANDS = new Set([
   'claim-sync',
   'claim-adopt',
   'mutation-finalize',
+  'version-drift',
+  'number-repair',
 ]);
 
 const CLAIM_SUBCOMMAND_SUMMARIES = {
@@ -191,6 +204,22 @@ export async function runCli(argumentsList, { scenario } = {}) {
     return;
   }
 
+  if (command === 'version-drift') {
+    const parsedOptions = parseContractOptions(command, argumentsList.slice(1));
+    if (parsedOptions.issues.length > 0) {
+      writeInvalidRequest(command, parsedOptions.issues);
+      return;
+    }
+    writeClaimEnvelope(await inspectVersionDrift({
+      skillPath: parsedOptions.options.skill
+        ?? fileURLToPath(new URL('../skills/wowbagger/SKILL.md', import.meta.url)),
+      packagePath: fileURLToPath(new URL('../package.json', import.meta.url)),
+      runningDistribution: DISTRIBUTION_VERSION,
+      runningContractVersion: 5,
+    }));
+    return;
+  }
+
   if (command === 'capabilities') {
     const parsedOptions = parseContractOptions(command, argumentsList.slice(1));
     if (parsedOptions.issues.length > 0) {
@@ -828,6 +857,13 @@ export async function runCli(argumentsList, { scenario } = {}) {
       writeClaimInvalidRequest(command, parsedOptions.issues);
       return;
     }
+    if (isNumberRepairRecoveryToken(parsedOptions.options.recoveryToken)) {
+      writeClaimEnvelope(await finalizeNumberRepairCommit({
+        ledgerDirectory: parsedOptions.options.ledger,
+        token: parsedOptions.options.recoveryToken,
+      }));
+      return;
+    }
     writeClaimEnvelope(await finalizeFromRecoveryToken({
       ledgerDirectory: parsedOptions.options.ledger,
       token: parsedOptions.options.recoveryToken,
@@ -835,6 +871,47 @@ export async function runCli(argumentsList, { scenario } = {}) {
     return;
   }
 
+  // The proposal is request-free and read-only: the ledger is its whole input.
+  if (command === 'number-repair-proposal') {
+    const parsedOptions = parseContractOptions(command, argumentsList.slice(1));
+    if (parsedOptions.issues.length > 0) {
+      writeClaimEnvelope(ledgerRepairInvalidRequest(command, parsedOptions.issues));
+      return;
+    }
+    writeClaimEnvelope(await numberRepairProposal(parsedOptions.options.ledger));
+    return;
+  }
+
+  if (command === 'number-repair') {
+    const parsedOptions = parseContractOptions(command, argumentsList.slice(1));
+    if (parsedOptions.issues.length > 0) {
+      writeClaimEnvelope(ledgerRepairInvalidRequest(command, parsedOptions.issues));
+      return;
+    }
+    let bytes;
+    try {
+      bytes = await requestSource(parsedOptions.options.input);
+    } catch {
+      writeClaimEnvelope(ledgerRepairInvalidRequest(command, [
+        issue('/input', 'invalid-value', 'Request input could not be read.'),
+      ]));
+      return;
+    }
+    const parsedRequest = parseJsonRequest(bytes);
+    if (parsedRequest.issues.length > 0) {
+      writeClaimEnvelope(ledgerRepairInvalidRequest(command, parsedRequest.issues));
+      return;
+    }
+    // normalizeJsonValue rebuilds the tree into plain objects with every
+    // JsonNumber unwrapped, so the exact-member check cannot be slipped past
+    // with a `__proto__` member and the number witnesses compare as numbers.
+    writeClaimEnvelope(await numberRepair(normalizeJsonValue(parsedRequest.value), {
+      ledgerDirectory: parsedOptions.options.ledger,
+      autoCommit: parsedOptions.options.autoCommit === true,
+    }));
+    return;
+  }
+
   if (command === 'claim-adopt') {
     const parsedOptions = parseContractOptions(command, argumentsList.slice(1));
     if (parsedOptions.issues.length > 0) {
@@ -1315,28 +1392,31 @@ function parseContractOptions(command, argumentsList) {
   const options = {};
   const issues = [];
   const seen = new Set();
-  const valueFlags = command === 'inspect'
-    ? new Map([['--ledger', 'ledger'], ['--id', 'id'], ['--number', 'number'], ['--as-of', 'asOf']])
-    : command === 'report'
-      ? new Map([['--ledger', 'ledger'], ['--as-of', 'asOf'], ['--out', 'out'], ['--view', 'view']])
-      : command === 'create' || command === 'transition' || command === 'patch' || command === 'list'
-        || command === 'parent-migrate'
-        || command === 'snooze'
-        || command === 'extensions-provision'
-        || command === 'publish-claimed' || command === 'publication-read'
-        || command === 'claim-read' || command === 'claim-acquire' || command === 'claim-renew'
-        || command === 'claim-release' || command === 'claim-adopt'
-        ? new Map([['--ledger', 'ledger'], ['--input', 'input']])
-        : command === 'mutation-finalize'
-          ? new Map([['--ledger', 'ledger'], ['--recovery-token', 'recoveryToken']])
-          : command === 'claim-merge-verify'
-            ? new Map([['--ledger', 'ledger'], ['--base', 'base'], ['--head', 'head']])
-            : command === 'provision' || command === 'claim-capabilities' || command === 'claim-verify'
-              || command === 'claim-sync'
-              ? new Map([['--ledger', 'ledger']])
-            : command === 'mint-id'
-              ? new Map([['--date', 'date']])
-              : new Map();
+  const valueFlags = command === 'version-drift'
+    ? new Map([['--skill', 'skill']])
+    : command === 'inspect'
+      ? new Map([['--ledger', 'ledger'], ['--id', 'id'], ['--number', 'number'], ['--as-of', 'asOf']])
+      : command === 'report'
+        ? new Map([['--ledger', 'ledger'], ['--as-of', 'asOf'], ['--out', 'out'], ['--view', 'view']])
+        : command === 'create' || command === 'transition' || command === 'patch' || command === 'list'
+          || command === 'parent-migrate'
+          || command === 'snooze'
+          || command === 'extensions-provision'
+          || command === 'publish-claimed' || command === 'publication-read'
+          || command === 'claim-read' || command === 'claim-acquire' || command === 'claim-renew'
+          || command === 'claim-release' || command === 'claim-adopt'
+          || command === 'number-repair'
+          ? new Map([['--ledger', 'ledger'], ['--input', 'input']])
+          : command === 'mutation-finalize'
+            ? new Map([['--ledger', 'ledger'], ['--recovery-token', 'recoveryToken']])
+            : command === 'claim-merge-verify'
+              ? new Map([['--ledger', 'ledger'], ['--base', 'base'], ['--head', 'head']])
+              : command === 'provision' || command === 'claim-capabilities' || command === 'claim-verify'
+                || command === 'claim-sync' || command === 'number-repair-proposal'
+                ? new Map([['--ledger', 'ledger']])
+                : command === 'mint-id'
+                  ? new Map([['--date', 'date']])
+                  : new Map();
   // Bare flags carry no value. `--auto-commit` is accepted only on the
   // commands whose Git finalization it folds in; `--workbench` only on the one
   const bareFlags = AUTO_COMMIT_COMMANDS.has(command)
@@ -1346,13 +1426,15 @@ function parseContractOptions(command, argumentsList) {
       : command === 'inspect'
         ? new Map([['--workbench', 'workbench']])
         : new Map();
-  const optionalFlags = command === 'mint-id'
-    ? new Set(['--date'])
-    : command === 'report'
-      ? new Set(['--out', '--view'])
-      : command === 'inspect'
-        ? new Set(['--id', '--number', '--as-of'])
-        : new Set();
+  const optionalFlags = command === 'version-drift'
+    ? new Set(['--skill'])
+    : command === 'mint-id'
+      ? new Set(['--date'])
+      : command === 'report'
+        ? new Set(['--out', '--view'])
+        : command === 'inspect'
+          ? new Set(['--id', '--number', '--as-of'])
+          : new Set();
   for (let index = 0; index < argumentsList.length; index += 1) {
     const argument = argumentsList[index];
     if (argument === '--json') {
@@ -1654,20 +1736,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,
@@ -1890,6 +1970,17 @@ function usage(command) {
     return 'Usage: wowbagger mutation-finalize --ledger <dir> --recovery-token <token> --json';
   }
 
+  if (command === 'version-drift') {
+    return 'Usage: wowbagger version-drift [--skill <path>] --json';
+  }
+  if (command === 'number-repair-proposal') {
+    return 'Usage: wowbagger number-repair-proposal --ledger <dir> --json';
+  }
+
+  if (command === 'number-repair') {
+    return 'Usage: wowbagger number-repair --ledger <dir> --input <json-file|-> --json [--auto-commit]';
+  }
+
   if (command === 'claim') {
     return 'Usage: wowbagger claim <read|acquire|renew|release|capabilities> [options]';
   }

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/launch.js

@@ -17,8 +17,8 @@ import { fileURLToPath } from 'node:url';
 
 // The engine floor the package declares. A host that resolves its own Node
 // executable rather than reusing `process.execPath` must check it, because a
-// Node 18 executable will fail somewhere inside the core rather than at launch.
-export const MINIMUM_NODE_MAJOR = 20;
+// Node 22 executable will fail somewhere inside the core rather than at launch.
+export const MINIMUM_NODE_MAJOR = 24;
 
 // The absolute path of the core script. It is resolved from this module's own
 // URL, so it is correct for a global install, a local install, a workspace