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

package/CHANGELOG.md

@@ -7,6 +7,206 @@ consolidation. The first tagged release inherits this file.
 
 ## Unreleased
 
+## 0.1.0-alpha.14 - 2026-08-29
+
+### Changed
+
+- **Upgrading is a hard cutover: upgrade every writer in one Git coordination
+  domain before the first alpha.14 create.** The journal grammar widened —
+  `legacy-mutation-intent` and `legacy-mutation` accept `command: "create-v1"`,
+  a create intent accepts `expected_revision: null`, and a create abort requires
+  `command: "create-v1"` with `observed_revision: null` — and an alpha.13 binary
+  cannot read the new create entry. Run against a ledger whose shared journal
+  already carries one, alpha.13's `create` exits 6 with `error.code`
+  `claim-store-unavailable`, message `The durable claim store is unavailable.`,
+  and `error.details.reason` `claim-store-unreadable`, leaves state unchanged,
+  and writes no item. Failing closed is the compatibility guarantee: an old
+  writer cannot commit another duplicate. It is also the operational limit,
+  because alpha.13 is immutable and can only emit that generic unreadable-store
+  message. Read it as "this repository was written by a newer Wowbagger; upgrade
+  this worktree to continue." There is no automatic migration and no
+  mixed-version grace period; a partial upgrade leaves the remaining alpha.13
+  worktrees unable to make claim-protected mutations until they move. Item #185
+  owns general version-drift detection; nothing here can retrofit a message into
+  an already-published executable. The new reader executes every journal
+  alpha.13 emitted, which is the backward-compatibility direction that had to
+  hold.
+
+- **A create must be committed before the next mutation, and there is still no
+  batch operation.** A created item has no earlier authorized revision, so Git
+  `HEAD` is the only surface that can carry its authorized bytes; an uncommitted
+  create raises the global `git-finalization-required` barrier for every later
+  mutation, including the next create. It cannot occupy the authorized
+  predecessor/successor window a `patch` or `transition` may occupy, and that
+  window was never permission to skip a commit. The supported bulk pattern is
+  the create-then-commit loop — filing ten items is ten cycles, and
+  `--auto-commit` on each create is its shortest form. Safe batch design is
+  item #186.
+
+- **The measured cost of the fence is two extra fsync'd journal appends.** A
+  provisioned create already took the namespace lock, replayed the journal,
+  loaded the ledger, read Git `HEAD`, and reconciled, so the fence adds no new
+  Git roster or history traversal to a clean create; on a 1,500-item fixture the
+  captured `git` invocation sequence is identical before and after. The durable
+  cost is journal growth: each successful create adds one intent and one
+  committed terminal, so with no other activity the 65,536-entry limit permits
+  at most 21,845 three-entry create cycles, and the 8 MiB byte limit may bind
+  first. Other claim and mutation activity lowers that ceiling. Capacity is
+  reserved before the intent append, so an exhausted journal refuses unchanged
+  rather than stranding an attempt. Journal compaction is not part of this
+  change.
+
+### Fixed
+
+- **Two worktrees can no longer commit two items carrying the same number.**
+  Through alpha.13, `create` was journal-silent by design: it derived
+  `1 + max(existing numbers)` from the items its own checkout held and recorded
+  nothing in the shared claim journal. Two worktrees that had not integrated
+  each other's commits therefore derived the same number and both published,
+  and they did not have to race to do it — a create today and a create tomorrow
+  collided just as reliably, because the loser was a stale checkout rather than
+  a lost race. `number` is immutable and `patch` correctly refuses it, so the
+  collision surfaced only at integration, as a global `duplicate-number`
+  validation failure that stopped the whole ledger. On a provisioned ledger,
+  `create` is now a journaled legacy mutation: under the shared namespace lock
+  it reconciles, validates the complete candidate ledger, reserves journal
+  capacity, appends a `legacy-mutation-intent` with `command: "create-v1"` and
+  `expected_revision: null` before any byte reaches the item path, publishes
+  atomically and no-clobber, verifies the exact bytes, and appends its terminal
+  — `legacy-mutation` when the bytes landed, or an abort carrying
+  `command: "create-v1"` and `observed_revision: null` when the path stayed
+  absent. Allocation is fenced in front of all of that: every global finding
+  blocks `create` as it blocks any write, and in addition any coordinated item
+  this checkout does not hold blocks `create`, because its number cannot be
+  read here. A stale revision of an item this checkout does hold stays
+  nonblocking, because a number is immutable. A fenced create refuses with
+  exit 6, `state: "unchanged"`, `error.code: "claim-store-unavailable"`,
+  `error.details.reason: "publication-reconciliation-required"`, and no item
+  file; integrate the named item, run `claim-verify` to exit 0, and resend the
+  same request ID to take the next number. **What this fixes and what it does
+  not:** it closes the reported PropertyCompass2 collision, so cooperating
+  alpha.14 worktrees of one clone that share one Git common directory can no
+  longer commit the same number, because every such create is visible through
+  the shared journal before publication even without branch integration.
+  Separate clones, separate machines, alpha.13 writers before the hard cutover,
+  and noncooperating writes stay outside that fence and still rely on branch
+  integration plus `validate`. A ledger that already carries duplicate numbers
+  is not repaired here; item #182 owns that fenced recovery. Core
+  `contract_version` stays `5` and the create success and refusal envelopes add,
+  remove, and rename no member.
+
+- **`create --auto-commit` commits its reconciliation log with the item.**
+  Because create now owns journal entries, its commit set is exactly the created
+  item and `<ledger>/.wowbagger/reconcile-<namespace>.md`, and
+  `mutation-finalize` accepts that same two-path recovery token. Between the
+  fence landing and this fix, `create --auto-commit` failed outright with
+  `git-commit-failed`, `failure_stage: "prepare-commit-set"`, and
+  `reason: "tree-changed"`, because the commit set excluded a log the mutation
+  had just written. Owning that log is not absorbing what was already in it:
+  `create` still refuses a reconciliation log that was dirty before the
+  invocation, and every other dirty ledger path still refuses.
+
+- **A revision Git can already reach is no longer an instruction to wait for
+  it.** When the expected revision was reachable only from a tag, a
+  remote-tracking ref, a branch no worktree had checked out, or a live worktree
+  on a detached `HEAD`, the `worktree-synchronization-required` finding rendered
+  the not-yet-reachable sentence: "wait for the owning worktree to commit, then
+  synchronize this worktree and run claim-verify." The commit already existed
+  and no named worktree was ever going to publish it, so that wait could not
+  end. Those cases now render: "Revision <revision> of <path> 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."
+  A revision no reachable commit carries keeps the not-yet-reachable sentence
+  and its wait, and an item that has never existed in this checkout keeps the
+  cannot-be-established sentence. **A consumer that matches on `remediation`
+  text must update its patterns:** a finding that used to match "not yet
+  reachable" now matches "reachable in Git" for the four reachable-unowned
+  cases. Nothing else moves. The `reason` stays
+  `worktree-synchronization-required`, the code stays `stale-write-detected`,
+  `owner_unavailable: true` with no `owner_ref` or `owner_commit` is unchanged,
+  the finding stays advisory — it blocks a mutation targeting its own item and
+  lets an unrelated mutation proceed — and core `contract_version` stays `5`,
+  because no field, code, reason, or scope changes and the text correction
+  replaces a false instruction.
+
+### Documentation
+
+- **Worktree identity and its refusals are now documented.** Alpha.13 shipped an
+  explicit worktree identity — an opaque random UUID a worktree creates once in
+  its private Git directory — and started recording it as the optional
+  `writer_worktree_id` member on `legacy-mutation-intent`, `legacy-mutation`,
+  `publish-intent`, and `publish-final` journal entries. Reconciliation reads it
+  to tell this worktree's own unreachable successor from a sibling's, which is
+  what turns that topology into a global `unauthorized-revision` barrier instead
+  of advisory `worktree-synchronization-required`. Alpha.13 also began refusing
+  before it classifies anything when two live worktrees answer to one UUID, or
+  when the worktree roster cannot be read to completion: exit 6
+  `claim-store-unavailable`, reason `claim-store-unreadable`, plus one new
+  `error.details.identity_diagnostic` carrying `duplicate-worktree-identity`
+  with `worktree_id` and `live_worktree_count`, or `worktree-enumeration-failed`
+  with no further member, and the same diagnostic inside
+  `auto-commit-preflight-failed` with `retryable: false`. All of that shipped
+  without a release note; the alpha.13 entry mentioned writer identity only in
+  passing while describing which callers read it. The work-claim contract
+  section 3.1, the mutation contract auto-commit preflight details, and the
+  installed skill now state the journal field, its alpha.12-and-earlier
+  compatibility (such entries stay valid, attribute nothing, and leave the
+  writer unknown), what the identity discloses in committed history, and both
+  diagnostics. Core `contract_version` stays `5` and no public request or
+  success envelope changes.
+
+- **Owner evidence names only an active named worktree, and the contract now
+  says so.** Through alpha.12 the owner search was a reachability search, so a
+  finding could report `owner_ref` naming a tag, a remote-tracking ref, or a
+  branch no worktree had checked out — an owner that could never publish
+  anything, and an instruction to wait forever. Alpha.13 replaced that with the
+  live worktree roster: this checkout first, then live worktrees on a branch
+  ordered by branch ref and then path, with bare and prunable records excluded.
+  `owner_ref` is therefore always the branch of a live worktree. A revision
+  reachable only from a tag, a remote-tracking ref, an unchecked-out branch, or
+  a live worktree on a detached `HEAD` now reports `owner_unavailable: true` and
+  no `owner_ref`. That narrowing shipped in alpha.13 with no release note, and
+  the alpha.11 note promising that a finding "retains that `owner_ref` and
+  `owner_commit`" no longer describes those cases. The contract and the
+  installed skill now state the roster rule, the three distinct meanings of
+  `owner_unavailable`, and which remediation sentence each one gets.
+
+- **Repository-wide `claim-verify` and target-scoped mutation are stated as
+  different questions.** The mutation contract still said a recorded write in
+  one worktree "refuses every mutation in the others", which target scoping
+  stopped being true before alpha.11. It now states the item scope, and both
+  contracts and the installed skill now say plainly that a successful mutation
+  is not proof of a globally clean claim store: `claim-verify` names no target,
+  so it stays exit 6 while any item in the repository carries a blocking
+  finding, including an unrelated one. Item #184 is open in triage to decide the
+  supported verification surface; nothing about that behavior changed here, and
+  a gate that demands a globally clean `claim-verify` on a repository with live
+  sibling work is still unsatisfiable.
+
+- **A refused reconciliation still persists the clock floor.** Reconciliation
+  has written its clock entry before it classifies anything since work claims
+  were implemented, so a command that then refuses with
+  `publication-reconciliation-required` has already advanced the durable
+  monotonic floor to `max(physical_utc, previous_floor)`. Section 4 documented
+  the floor only for authoritative lease decisions, so the pre-decision advance
+  and its one observable consequence were undocumented: because the floor never
+  rolls back, a lease or fence observed expired at that floor can never read
+  live again, and a holder on a ledger whose floor runs ahead of its own wall
+  clock may find its lease expired the moment it asks after clearing a barrier.
+  Behavior is unchanged; the contract now says it.
+
+- **The reconciliation topology classifier moved without changing an answer.**
+  The topology decision that was spread across owner lookup, diagnosis, and
+  scope inference now lives in one pure module,
+  `src/reconciliation-classifier.js`, which takes normalized evidence and
+  returns a typed decision. That type is internal: scope travels beside a
+  finding and no response has ever carried it, so a consumer must keep reading
+  the refusal rather than the `reason` string. Every public seam — reason,
+  blocking behavior, owner fields, remediation sentence, exit, state, and
+  envelope domain — is byte-identical to alpha.13 on every matrix row, which is
+  the whole point of the change and the only claim made for it. No behavior
+  shipped with it.
+
 ## 0.1.0-alpha.13 - 2026-08-28
 
 ### Fixed

package/README.md

@@ -30,8 +30,8 @@ agent to use those guarantees instead of hand-editing your Markdown.
 
 **Start here:** [install the core and set up a ledger](#start-here).
 
-> **Status: alpha, published, and self-hosted.** `0.1.0-alpha.13` is on npm under
-> the `next` tag and on this repository's `v0.1.0-alpha.13` tag. It is the
+> **Status: alpha, published, and self-hosted.** `0.1.0-alpha.14` is on npm under
+> the `next` tag and on this repository's `v0.1.0-alpha.14` tag. It is the
 > version this repository runs its own backlog on. The API is not frozen and the
 > version will move before a stable release.
 >
@@ -77,7 +77,7 @@ Wowbagger is the core authority for a Git-native work ledger. Use it instead
 of editing ledger Markdown by hand.
 
 ```sh
-wowbagger --version                 # require 0.1.0-alpha.13
+wowbagger --version                 # require 0.1.0-alpha.14
 wowbagger capabilities --json       # require contract_version: 5
 wowbagger validate --ledger ledger --json
 wowbagger ready --ledger ledger --as-of YYYY-MM-DD --json
@@ -103,10 +103,10 @@ cooperating writers; they are not exclusive locks.
 Install the core CLI, then verify it. The core requires Node.js 20 or later:
 
 ```sh
-npm install -g wowbagger@0.1.0-alpha.13   # exact plugin-matched release
+npm install -g wowbagger@0.1.0-alpha.14   # exact plugin-matched release
 # or, from this release's Git tag:
-# npm install -g github:lstutzman/wowbagger#v0.1.0-alpha.13
-wowbagger --version         # 0.1.0-alpha.13
+# npm install -g github:lstutzman/wowbagger#v0.1.0-alpha.14
+wowbagger --version         # 0.1.0-alpha.14
 wowbagger capabilities --json              # must report contract_version: 5
 ```
 
@@ -325,7 +325,7 @@ two supported install routes:
   registry requires a `latest` tag), so a bare install resolves to the same
   bytes.
 - **git tag** —
-  `npm install -g github:lstutzman/wowbagger#v0.1.0-alpha.13` installs this
+  `npm install -g github:lstutzman/wowbagger#v0.1.0-alpha.14` installs this
   release. Installing at a ref installs the core and every adapter that ref
   carries.
 
@@ -397,7 +397,7 @@ Upgrade the pieces you installed:
 
 ```sh
 npm install -g wowbagger@next                  # public npm registry
-npm install -g github:lstutzman/wowbagger#v0.1.0-alpha.13  # immutable Git release
+npm install -g github:lstutzman/wowbagger#v0.1.0-alpha.14  # immutable Git release
 git pull && npm ci                            # or: a direct checkout
 ```
 

package/docs/mutation-contract.md

@@ -792,10 +792,19 @@ another. It is **not** a statement that worktrees write independently.
 
 On a provisioned Git-backed ledger they do not. One claim journal lives in the
 shared Git common directory, so it serializes every worktree of that
-repository: a recorded `transition` or `patch` in one worktree refuses every
-mutation in the others with exit 6 `claim-store-unavailable`, reason
+repository. The serialization is scoped to the item: a recorded `transition` or
+`patch` in one worktree refuses a mutation in the others that targets *that
+item* with exit 6 `claim-store-unavailable`, reason
 `publication-reconciliation-required`, until the writing commit is visible in
-the blocked checkout. Clones do not share the common directory, so
+the blocked checkout. A mutation targeting an unrelated item still runs, and
+the sibling's finding remains visible. Own uncommitted work and
+out-of-protocol revisions are global barriers and refuse every mutation. A
+repository-wide `claim-verify` names no target, so it reports exit 6 while any
+item carries a blocking finding, including an unrelated one: a successful
+mutation is therefore not proof of a globally clean claim store. See
+[the work-claim contract](work-claim-contract.md), section 3.2, for the scopes
+and for the open item #184 that owns the verification-surface decision. Clones
+do not share the common directory, so
 `limits.cross_clone_coordination: false` carries no such consequence.
 
 That serialization is discoverable, per ledger, at
@@ -1558,6 +1567,62 @@ no-clobber publication still protects an intervening creator.
 Successful create returns state committed and the inspect item shape from
 section 5.
 
+### Journal-fenced allocation on a provisioned ledger
+
+On a provisioned merge-coordinated ledger, a schema-version-2 create is a
+journaled legacy mutation. Under the shared namespace lock it reconciles,
+applies the allocation fence below, loads and validates the ledger, derives
+`1 + max(existing numbers)`, serializes the candidate, validates the complete
+candidate ledger, reserves journal capacity, and only then appends its
+`legacy-mutation-intent` with `command: "create-v1"` before any byte reaches
+the item path. Publication, exact-byte verification, and the terminal append
+all happen under that same lock. The intent carries
+`expected_revision: null`, which is valid only for `create-v1`. The committed
+terminal is `legacy-mutation` with `command: "create-v1"`; the create abort
+carries `command: "create-v1"` and `observed_revision: null`. No entry records
+the assigned number, because the candidate revision binds the complete item
+bytes and the ledger remains the one number authority.
+
+The allocation fence reads reconciliation with one extra barrier. Every global
+finding blocks create as it blocks every write. On top of those, any
+coordinated item this checkout does not hold blocks `create`, because the
+journal records a committed terminal for an item whose number this working
+ledger cannot read. A stale revision of an item this checkout holds does not
+block `create`, because a number is immutable and the local maximum is already
+correct. A fenced create refuses with exit 6, `state: "unchanged"`,
+`error.code: "claim-store-unavailable"`, and
+`error.details.reason: "publication-reconciliation-required"` in the
+`ledger-mutation` domain as `create-v1`, having written no item byte. Resolve
+each finding by its own `remediation`, run `claim-verify` until it exits 0, and
+retry the same request ID; the retry takes the next number.
+
+A create has no authorized predecessor, so Git `HEAD` is the only surface that
+can carry its authorized bytes, and an uncommitted create raises the global
+`git-finalization-required` barrier for every later mutation. Commit each
+created item before the next mutating command. This release adds no batch
+mutation; the supported bulk pattern is the create-then-commit loop, and item
+#186 owns safe batch design. A ledger that already carries duplicate numbers is
+item #182's recovery work: it fails validation and refuses every mutation
+before allocation, and nothing here renumbers it.
+
+**What this guarantees, and what it does not.** The fence closes the reported
+PropertyCompass2 collision: cooperating alpha.14 worktrees of one clone that
+share one Git common directory can no longer commit two items carrying the same
+number, because every such create is visible through the shared journal before
+publication even without branch integration. Separate clones, separate
+machines, alpha.13 writers before the hard cutover, and noncooperating writes
+stay outside the fence and still rely on branch integration plus `validate`.
+
+The widened journal grammar forces a hard cutover, so upgrade every writer in
+one Git coordination domain before the first alpha.14 create. An alpha.13
+binary cannot read a `create-v1` intent: it refuses with exit 6,
+`error.code` `claim-store-unavailable`, message
+`The durable claim store is unavailable.`, and `error.details.reason`
+`claim-store-unreadable`, leaving state unchanged and writing no item. That
+refusal means **this repository was written by a newer Wowbagger; upgrade this
+worktree to continue.** There is no automatic migration and no mixed-version
+grace period.
+
 ## 8. Transition
 
 ### Request
@@ -2626,6 +2691,13 @@ That window produces no finding, so another mutation can run before the first
 one is committed. The later command's acceptance does not prove durability;
 the operating rule remains write, commit, `claim-verify`, next write.
 
+`create` never occupies that window. A created item has no earlier authorized
+revision, so Git `HEAD` is the only surface that can carry its authorized
+bytes, and an uncommitted create raises the global `git-finalization-required`
+barrier for every later mutation, including the next create. Filing ten items
+is therefore ten create-then-commit cycles, not one commit at the end. This
+release adds no batch mutation; item #186 owns safe batch design.
+
 The loop that works:
 
 ~~~sh
@@ -2697,7 +2769,13 @@ envelope, subject and commit set included.
 For every blocking finding:
 
 1. Do what `remediation` says, for each finding, using its `expected_path`.
-   `git-finalization-required` means commit that path.
+   `git-finalization-required` means commit that path. A
+   `worktree-synchronization-required` finding means wait only when its
+   `remediation` names an owner to wait for or says the expected revision is not
+   yet reachable. When it says the revision is reachable in Git while no active
+   named worktree owner is established, there is no commit left to wait for:
+   inspect that reachable history, then restore or explicitly adopt reviewed
+   bytes.
 2. Run `wowbagger claim-verify --ledger <dir> --json`.
 3. Exit 0 with `state: "committed"` means the ledger is reconciled and the next
    mutating command may run. Exit 6 means findings remain; repeat from step 1.
@@ -2747,7 +2825,7 @@ by sending the flag, not by reading a version.
 
 Only the paths this invocation owns:
 
-| `create` | the created item |
+| `create` | the created item and one `<ledger>/.wowbagger/reconcile-<namespace>.md` |
 | `transition` | the changed item and one `<ledger>/.wowbagger/reconcile-<namespace>.md` |
 | `parent-migrate` | the changed item and one reconciliation log |
 | `snooze` | the changed item and one reconciliation log |
@@ -2759,13 +2837,11 @@ item bytes at `HEAD`. A byte-identical `parent-migrate`, `snooze`, or `patch`
 still records its decision in the reconciliation log, so its auto-commit set
 contains the log alone.
 
-`create` is journal-silent by design, so its commit set has no log. The
-pre-mutation and post-mutation verification steps do not materialize an empty
-log for `create`; this lets the first auto-commit run after namespace
-provisioning commit the created item without an extra metadata ceremony. For
-the other commands, the log must already carry this invocation's terminal
-entry before it may be staged; if it does not, the invocation reports
-`git-commit-failed` with `reason: "log-unavailable"`.
+`create` is journal-visible from the item's birth, so a successful `create`
+commits exactly the created item and its reconciliation log. For every command,
+the log must already carry this invocation's terminal entry before it may be
+staged; if it does not, the invocation reports `git-commit-failed` with
+`reason: "log-unavailable"`.
 
 Commit subjects are fixed:
 
@@ -2793,8 +2869,10 @@ Before the mutation runs, the invocation takes a per-working-tree mutex and
 requires all of:
 
 - No path staged anywhere in the repository.
-- No dirty path under the ledger except the current namespace reconciliation
-  log for a command that owns and commits that log.
+- No dirty path under the ledger, with one exception: `transition`,
+  `parent-migrate`, `snooze`, `patch`, and `publish-claimed` tolerate a dirty
+  current-namespace reconciliation log, because each rebuilds that one derived
+  file from the authoritative journal. `create` does not tolerate it.
 - A Git identity Git can resolve without committing.
 - A `HEAD` that exists. A detached `HEAD` is supported, because a commit works
   from one; an unborn `HEAD` refuses.
@@ -2812,18 +2890,24 @@ staging, or commit occurs. `details.reason` is one of `staged-paths-present`,
 Every `auto-commit-preflight-failed` refusal also carries
 `details.retryable`. `mutex-held` is retryable inside one working tree.
 `claim-state-unreconciled` also carries optional `claim_verify_code`,
-`claim_verify_reason`, and bounded `findings`; `claim-store-locked` is
-retryable, while persistent reconciliation is not retryable. Every other
+`claim_verify_reason`, `identity_diagnostic`, and bounded `findings`;
+`claim-store-locked` is retryable, while persistent reconciliation is not
+retryable. An `identity_diagnostic` reports an ambiguous or unreadable
+worktree identity — `duplicate-worktree-identity` with `worktree_id` and
+`live_worktree_count`, or `worktree-enumeration-failed` with no further member
+— and is never retryable. Every other
 preflight reason is not retryable. Clients branch on this boolean and the
 underlying verification reason, never on the generic message.
 
 The rule is deliberately strict rather than preserving foreign staged work in
 a temporary index. A journal-owning auto-commit validates and rebuilds the
 dirty derived reconciliation log from the authoritative journal, then commits
-it with the mutation. `create` still refuses a dirty reconciliation log because
-it does not own that path. Every other dirty ledger path refuses. Claim refusal
-evidence is never suppressed: both the authoritative journal and its projected
-log retain the decision before a later command rebuilds or commits the log.
+it with the mutation. Owning the log is not absorbing what was already in it:
+`create` still refuses a dirty reconciliation log, because residue that
+predates the invocation is foreign to the entries create is about to write.
+Every other dirty ledger path refuses. Claim refusal evidence is never
+suppressed: both the authoritative journal and its projected log retain the
+decision before a later command rebuilds or commits the log.
 
 A flagged invocation on an advisory or non-provisioned ledger returns exit 5
 `capability-unavailable` with `state: "unchanged"` before the mutation. It does