wowbagger 0.1.0-alpha.1 → 0.1.0-alpha.2

package/skills/wowbagger/SKILL.md

@@ -18,8 +18,8 @@ so a version mismatch is detectable rather than silent.
 wowbagger capabilities --json
 ```
 
-Read `contract_version` from the result. **This skill requires
-`contract_version: 2`.**
+Read the top-level `contract_version` from this core response. **This skill
+requires core `contract_version: 2`.**
 
 - Command not found → the core is not installed. Tell the user, point them at
   <https://github.com/lstutzman/wowbagger>, and stop. Do not fall back to
@@ -67,6 +67,9 @@ wowbagger transition --ledger <dir> --input request.json --json
 
 - `create` publishes only a caller-supplied canonical ID, atomically and
   no-clobber. It will not invent an ID for you.
+- `create` starts an empty ledger on schema version 2 and returns the selected
+  version at `result.item.core.schema_version`. A non-empty schema-version-1
+  ledger stays on version 1 until its complete ledger is migrated.
 - `transition` changes **one** item. If the change would require touching a
   dependent or a child, it refuses. That refusal is correct — make it a
   reviewable multi-file Git change instead of forcing it.
@@ -77,6 +80,7 @@ wowbagger transition --ledger <dir> --input request.json --json
 ## Work claims are merge-coordinated
 
 ```sh
+wowbagger claim capabilities --ledger <dir> --json
 wowbagger provision --ledger <dir> --json
 wowbagger claim capabilities --ledger <dir> --json
 wowbagger claim read|acquire|renew|release --ledger <dir> --input request.json --json
@@ -94,25 +98,35 @@ It is not exclusive coordination. Direct filesystem writes, hostile processes,
 other clones, and alternate tools can bypass the protocol. Never present a
 claim as a lock or build a dispatch loop that requires exclusive ownership.
 
+An item stays in `backlog` while claimed work runs. The active claim is the work-in-flight signal.
+Do not use legacy `transition` to set `in-progress` after acquiring a claim; it
+correctly refuses with `active-claim-write-refused`.
+
 Use the claimed write path as one complete loop:
 
-1. Run `provision` once for the ledger. Keep its `ledger_namespace`.
-2. Run `claim capabilities --ledger <dir> --json`. Stop if the namespace is
-   absent or the mode is not `merge-coordinated`.
-3. Read the current claim record. Acquire with its observed state in
+1. Before provisioning, run `claim capabilities --ledger <dir> --json`. Require
+   `result.operations.work_claim.supported: true`; `false` means the ledger is
+   not in an accessible Git checkout. Stop before mutation.
+2. Run `provision` once for the ledger. Keep its `ledger_namespace`.
+3. Run `claim capabilities --ledger <dir> --json` again. Require
+   `result.operations.work_claim.api_version: 1`. Do not compare the claim
+   response's top-level `contract_version` with the core version; it is the
+   legacy claim-envelope marker. Stop if the namespace is absent or the mode is
+   not `merge-coordinated`.
+4. Read the current claim record. Acquire with its observed state in
    `expected`; keep the returned `owner_id`, `epoch`, and expiry as the fence.
-4. Renew before the lease expires if the work continues.
-5. Inspect the item again. Build the complete desired item bytes.
-6. Call `publish-claimed` with a unique operation ID, the exact inspected
+5. Renew before the lease expires if the work continues.
+6. Inspect the item again. Build the complete desired item bytes.
+7. Call `publish-claimed` with a unique operation ID, the exact inspected
    revision, the candidate bytes and digest, and the active claim fence. Never
    retry with only the operation ID; retry the complete request.
-7. Commit the item change, or merge the worker commit into the coordinating
+8. Commit the item change, or merge the worker commit into the coordinating
    branch.
-8. Run `claim-verify` after the commit or merge. It finalizes the Git outcome,
+9. Run `claim-verify` after the commit or merge. It finalizes the Git outcome,
    repairs response-loss cases, and reports later revision drift. Run it again
    before the next fenced operation if the prior outcome was not final.
-9. Release the claim with its current observed state.
-10. Run `validate` and show the resulting diff.
+10. Release the claim with its current observed state.
+11. Run `validate` and show the resulting diff.
 
 Legacy `create` refuses an ID with claim history. Legacy `transition` refuses an
 item with an active claim. Do not bypass those refusals. Read

package/src/claim-journal.js

@@ -21,8 +21,8 @@ export function claimJournalPath(commonDir, namespace) {
   return path.join(commonDir, 'wowbagger', namespace, 'journal.ndjson');
 }
 
-export function claimReconcileLogPath(repoRoot, namespace) {
-  return path.join(repoRoot, 'wowbagger', `reconcile-${namespace}.md`);
+export function claimReconcileLogPath(ledgerDirectory, namespace) {
+  return path.join(ledgerDirectory, '.wowbagger', `reconcile-${namespace}.md`);
 }
 
 export async function appendClaimEntry(journalPath, entry) {

package/src/claim-publication.js

@@ -477,7 +477,7 @@ export async function reconcileClaimJournal({
   }
 
   await writeReconcileLog(
-    claimReconcileLogPath(path.dirname(path.resolve(ledgerDirectory)), namespace),
+    claimReconcileLogPath(path.resolve(ledgerDirectory), namespace),
     namespace,
     entries,
   );
@@ -495,6 +495,28 @@ export async function reconcileClaimJournal({
   };
 }
 
+function publicationStatuses(entries) {
+  const finalizations = new Map(entries
+    .filter((entry) => entry.type === 'publish-finalization')
+    .map((entry) => [`${entry.operation_id}\0${entry.item_id}`, entry]));
+  return entries
+    .filter((entry) => (
+      entry.type === 'publish-final'
+        && entry.outcome?.stdout?.state === 'committed'
+    ))
+    .map((entry) => {
+      const finalization = finalizations.get(`${entry.operation_id}\0${entry.item_id}`);
+      return {
+        operation_id: entry.operation_id,
+        item_id: entry.item_id,
+        committed_revision: entry.outcome.stdout.result.committed_revision,
+        git_finalized: finalization !== undefined,
+        git_commit: finalization?.git_commit ?? null,
+      };
+    });
+}
+
+
 export async function verifyClaimJournal({ ledgerDirectory, gitCommonDir, namespace }) {
   const storePath = claimStorePath(gitCommonDir, namespace);
   const journalPath = claimJournalPath(gitCommonDir, namespace);
@@ -519,6 +541,7 @@ export async function verifyClaimJournal({ ledgerDirectory, gitCommonDir, namesp
             ledger_namespace: namespace,
             observed_at: reconciled.observedAt,
             findings: reconciled.findings,
+            publications: publicationStatuses(reconciled.entries),
           },
         },
       };
@@ -560,8 +583,11 @@ async function persistTerminal(entries, journalPath, ledgerDirectory, namespace,
     outcome,
   });
   entries.push(terminal);
-  const repoRoot = path.dirname(path.resolve(ledgerDirectory));
-  await writeReconcileLog(claimReconcileLogPath(repoRoot, namespace), namespace, entries);
+  await writeReconcileLog(
+    claimReconcileLogPath(path.resolve(ledgerDirectory), namespace),
+    namespace,
+    entries,
+  );
   try {
     await writeClaimState(storePath, state);
   } catch {

package/src/cli.js

@@ -55,7 +55,7 @@ const DISTRIBUTION_VERSION = JSON.parse(
 const COMMAND_SUMMARIES = {
   validate: 'Validate a ledger and print the single JSON validation result.',
   ready: 'Validate a ledger and print the readiness queue for a date.',
-  capabilities: "Describe the backend's capabilities and versioned contract surface.",
+  capabilities: 'Describe the core contract and unbound default claim profile.',
   inspect: 'Inspect one ledger item as a lossless raw-byte snapshot.',
   create: 'Create one ledger item through atomic, no-clobber publication.',
   transition: "Transition one item's lifecycle, guarded by lock and compare-and-swap.",
@@ -63,7 +63,7 @@ const COMMAND_SUMMARIES = {
   'mint-id': 'Mint a canonical item ID.',
   provision: 'Provision the work-claim namespace.',
   claim: 'Work-claim lifecycle operations on the provisioned store.',
-  'publish-claimed': 'Publish claim-protected ledger results (unavailable on an advisory backend).',
+  'publish-claimed': 'Publish ledger results when its claim profile enables protected publication.',
   'claim-verify': 'Reconcile pending and committed claim-protected publications.',
 };
 
@@ -83,7 +83,7 @@ const KNOWN_COMMANDS = new Set([
 ]);
 
 const CLAIM_SUBCOMMAND_SUMMARIES = {
-  capabilities: 'Describe the work-claim backend and its coordination scope.',
+  capabilities: "Describe the provisioned ledger's work-claim profile.",
   read: 'Read the current claims from the provisioned store.',
   acquire: 'Acquire a cooperative work claim.',
   renew: 'Renew an existing work claim.',
@@ -844,9 +844,8 @@ async function runClaimCommand(claimCommand, argumentsList) {
         throw taggedFailure('CLOCK_FLOOR_PERSISTENCE_FAILED', error);
       }
       try {
-        const repoRoot = path.dirname(path.resolve(parsedOptions.options.ledger));
         await writeReconcileLog(
-          claimReconcileLogPath(repoRoot, namespace),
+          claimReconcileLogPath(path.resolve(parsedOptions.options.ledger), namespace),
           namespace,
           [...reconciled.entries, persisted],
         );
@@ -1056,6 +1055,48 @@ function commandHelp(command) {
         `  ${name.padEnd(12)} ${CLAIM_SUBCOMMAND_SUMMARIES[name]}`
       )),
       '',
+      'Use claim capabilities --ledger <dir> --json to gate work on one provisioned ledger.',
+      'The namespace and backend members identify the work-claim capability context.',
+      'Use operations.work_claim.api_version to negotiate the work-claim API.',
+      'The top-level claim contract_version is a legacy envelope marker.',
+      '',
+    ].join('\n');
+  }
+
+  if (command === 'capabilities') {
+    return [
+      header,
+      '',
+      `${usage(command)}`,
+      '',
+      'Use contract_version to negotiate the core contract.',
+      'Use operations.work_claim.api_version to negotiate the work-claim API.',
+      'Use claim capabilities --ledger <dir> --json to gate claimed work for one ledger.',
+      '',
+    ].join('\n');
+  }
+
+  if (command === 'provision') {
+    return [
+      header,
+      '',
+      `${usage(command)}`,
+      '',
+      'Requires a Git checkout; the namespace and claim journal use its shared Git directory.',
+      'Preflight with claim capabilities --ledger <dir> --json.',
+      'Require result.operations.work_claim.supported: true before provisioning.',
+      '',
+    ].join('\n');
+  }
+
+  if (command === 'publish-claimed') {
+    return [
+      header,
+      '',
+      `${usage(command)}`,
+      '',
+      'Requires the ledger-specific claim capability claim_protected_publication: true.',
+      '',
     ].join('\n');
   }
 

package/src/git-reconciliation.js

@@ -12,7 +12,7 @@ const GIT_ENVIRONMENT = Object.fromEntries(
 export async function readGitHeadLedger(ledgerDirectory) {
   const root = (await gitText(ledgerDirectory, ['rev-parse', '--show-toplevel'])).trim();
   const relativeLedger = path.relative(root, await realpath(ledgerDirectory));
-  if (relativeLedger === '' || relativeLedger.startsWith(`..${path.sep}`) || path.isAbsolute(relativeLedger)) {
+  if (relativeLedger.startsWith(`..${path.sep}`) || path.isAbsolute(relativeLedger)) {
     throw new Error(`ledger is outside the git worktree: ${relativeLedger}`);
   }
   let commit;
@@ -23,12 +23,16 @@ export async function readGitHeadLedger(ledgerDirectory) {
     throw error;
   }
   const gitLedger = toGitPath(relativeLedger);
-  const listing = await gitBuffer(root, [
-    'ls-tree', '-r', '-z', '--name-only', 'HEAD', '--', gitLedger,
-  ]);
-  const prefix = `${gitLedger}/`;
+  const treeArguments = ['ls-tree', '-r', '-z', '--name-only', 'HEAD'];
+  if (gitLedger !== '') treeArguments.push('--', gitLedger);
+  const listing = await gitBuffer(root, treeArguments);
+  const prefix = gitLedger === '' ? '' : `${gitLedger}/`;
   const files = listing.toString('utf8').split('\0')
-    .filter((name) => name.startsWith(prefix) && name.endsWith('.md'));
+    .filter((name) => (
+      name.startsWith(prefix)
+        && !name.slice(prefix.length).startsWith('.wowbagger/')
+        && name.endsWith('.md')
+    ));
   const items = new Map();
   for (const file of files) {
     const bytes = await gitBuffer(root, ['show', `HEAD:${file}`]);

package/src/ledger.js

@@ -140,6 +140,7 @@ async function collectMarkdownFiles(root, directory, fileSystem) {
   const errors = [];
 
   for (const entry of entries.sort((left, right) => compareText(left.name, right.name))) {
+    if (directory === root && entry.name === '.wowbagger') continue;
     const entryPath = path.join(directory, entry.name);
     let entryType = entry;
 

package/src/mutation.js

@@ -277,7 +277,7 @@ async function createItemUnfenced(ledgerDirectory, request, scenario) {
         return await finishUncommitted(mutationError('path-collision', 'The default item path is occupied by a different item.', 'unchanged', 4, details));
       }
 
-      const schemaVersion = current.ledger.items[0]?.data.schema_version ?? 1;
+      const schemaVersion = current.ledger.items[0]?.data.schema_version ?? 2;
       const bytes = createCandidateSource(request, schemaVersion);
       const candidateValidation = validateSerializedCandidate(
         current.ledger,

package/src/schema-migration.js

@@ -52,7 +52,7 @@ export async function migrateSchema2(ledgerDirectory, { apply = false, onItem =
   if (inputValidation.valid && ledger.items.length === 0) {
     throw new SchemaMigrationError(
       'empty-ledger',
-      'An empty ledger has no schema_version stamp to migrate and still defaults to schema version 1. No files were changed.',
+      'An empty ledger has no schema_version stamp to migrate; its first create defaults to schema version 2. No files were changed.',
     );
   }
   if (ledger.items.length > 0 && schemaVersions.size === 1 && schemaVersions.has(2)) {