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

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;
+}

package/src/version-drift.js

@@ -0,0 +1,98 @@
+import { lstat, readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const SKILL_DISTRIBUTION = /requires distribution version[\s`*:-]+`([^`]+)`/u;
+const SKILL_CONTRACT = /core[\s`*:-]+`contract_version:\s*(\d+)`/u;
+
+export async function inspectVersionDrift({
+  skillPath,
+  packagePath,
+  runningDistribution,
+  runningContractVersion,
+}) {
+  let skillSource;
+  let packageManifest;
+  try {
+    [skillSource, packageManifest] = await Promise.all([
+      readFile(skillPath, 'utf8'),
+      readFile(packagePath, 'utf8').then((source) => JSON.parse(source)),
+    ]);
+  } catch {
+    return unavailable('Could not read the skill or core package metadata.', {
+      skill_path: skillPath,
+      package_path: packagePath,
+    });
+  }
+  const distribution = SKILL_DISTRIBUTION.exec(skillSource)?.[1] ?? null;
+  const contract = Number(SKILL_CONTRACT.exec(skillSource)?.[1] ?? NaN);
+  const requiredDistribution = packageManifest.version;
+  const requiredContract = 5;
+  const details = {
+    installed_distribution: distribution,
+    required_distribution: requiredDistribution,
+    running_distribution: runningDistribution ?? requiredDistribution,
+    installed_contract_version: Number.isSafeInteger(contract) ? contract : null,
+    required_contract_version: requiredContract,
+    running_contract_version: runningContractVersion ?? requiredContract,
+    provenance: await classifyProvenance(skillPath),
+  };
+  const drift = details.installed_distribution !== details.required_distribution
+    || details.running_distribution !== details.required_distribution
+    || details.installed_contract_version !== details.required_contract_version
+    || details.running_contract_version !== details.required_contract_version;
+  if (drift) {
+    return {
+      exit: 4,
+      stdout: {
+        ok: false,
+        command: 'version-drift',
+        contract_version: requiredContract,
+        error: {
+          code: 'version-drift-detected',
+          message: 'The installed skill and running core do not satisfy the required versions.',
+          details: {
+            ...details,
+            remediation: 'Update the skill package or linked checkout, then rerun version-drift before mutation.',
+          },
+        },
+      },
+    };
+  }
+  return {
+    exit: 0,
+    stdout: {
+      ok: true,
+      command: 'version-drift',
+      contract_version: requiredContract,
+      result: details,
+    },
+  };
+}
+
+async function classifyProvenance(skillPath) {
+  try {
+    const info = await lstat(skillPath);
+    if (info.isSymbolicLink()) {
+      return { kind: 'global-link', path: skillPath };
+    }
+  } catch {
+    return { kind: 'unknown', path: skillPath };
+  }
+  const normalized = path.resolve(skillPath).split(path.sep).join('/');
+  if (normalized.includes('/node_modules/')) return { kind: 'registry-package', path: skillPath };
+  if (normalized.includes('/.claude/plugins/cache/')) return { kind: 'plugin-cache', path: skillPath };
+  if (normalized.includes('/.git/')) return { kind: 'git-tag', path: skillPath };
+  return { kind: 'direct-path', path: skillPath };
+}
+
+function unavailable(message, details) {
+  return {
+    exit: 5,
+    stdout: {
+      ok: false,
+      command: 'version-drift',
+      contract_version: 5,
+      error: { code: 'version-drift-unavailable', message, details },
+    },
+  };
+}