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

package/docs/work-claim-contract.md

@@ -334,57 +334,186 @@ The plain statement: **a recorded private write in one worktree blocks
 mutations targeting that item, not unrelated item mutations in sibling
 worktrees.** Own uncommitted work and out-of-protocol revisions remain global
 safety barriers. This is item-scoped availability, not exclusive dispatch.
+`create` reads that same reconciliation with one extra barrier, because it is
+the one mutation whose output depends on an identity no caller supplied.
+
+**Superseded: create no longer stays journal-silent.** Through alpha.13 this
+contract decided that create records nothing, and three reasons held that
+decision: create already protects its own instant, because publication is
+atomic, refuses to clobber an existing path, and verifies the published bytes
+exactly; a journaled create would serialize every worktree on the
+highest-volume mutation; and the remaining exposure window was judged narrow
+because it closed at the item's first journal-visible mutation.
+
+Item #181 overturns that decision. The first reason answers the wrong
+question. Create's atomic instant protects the path it publishes to, and
+nothing protected the `number` it derives. A schema-version-2 create takes
+`1 + max(existing numbers)` from the items its own checkout holds, so two
+worktrees that have not integrated each other's commits derive the same number
+and both publish. They need not overlap in time: a create today and a create
+tomorrow collide as reliably as two simultaneous ones, because the loser is a
+stale checkout rather than a lost race, and a wider mutex cannot fix a
+sequential failure. Only durable evidence can. `number` is immutable and
+`patch` correctly rejects it, so an undetected collision surfaces at
+integration as a global `duplicate-number` validation failure that stops the
+whole ledger.
+
+**The fixed ordering.** On a provisioned ledger a create is a legacy mutation
+like any other, and the shared namespace lock is held across every step:
+
+1. Acquire the shared namespace lock.
+2. Reconcile the repository state and apply the allocation fence below.
+3. Load this worktree's ledger.
+4. Acquire the item, relation, and number-index lock closure.
+5. Reload and validate the ledger under those locks.
+6. Derive `1 + max(existing numbers)`.
+7. Serialize the candidate item.
+8. Validate the complete candidate ledger.
+9. Reserve journal capacity, then append the create intent.
+10. Publish with atomic no-clobber semantics.
+11. Verify the final path holds the exact candidate bytes.
+12. Append the committed or aborted terminal.
+
+A create appends its `legacy-mutation-intent` with `command: "create-v1"`
+before any byte reaches the item path, and it appends that intent only after
+step 8, so a refusal the command would have returned anyway records no
+attempt. The intent carries `expected_revision: null`, which is valid only for
+`create-v1`; every other command still requires a string revision. The
+committed terminal is `legacy-mutation` with `command: "create-v1"`. The
+create abort carries `command: "create-v1"` and `observed_revision: null`,
+while an abort for any other command remains valid without `command` and still
+requires a string revision. No entry records the assigned number: the
+candidate revision binds the complete item bytes, and the ledger stays the one
+number authority.
+
+**The allocation fence.** Create reconciles with its own item as the target,
+exactly like every other mutation, and one extra barrier reads the result.
+Every global finding blocks create because it blocks every write:
+`git-finalization-required` for this worktree's own uncommitted authorized
+bytes, `unauthorized-revision` for out-of-protocol bytes, and an unresolved
+`legacy-mutation-outcome-unknown`. 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,
+so the next number derived here may be one a sibling already published. A
+stale revision of an item this checkout holds does not block `create`: a
+number is immutable, so the local maximum is already correct, and that finding
+keeps its ordinary target scope.
+
+**The old exposure window is closed on a provisioned ledger.** The journal used
+to learn of an item only at its first `transition` or `patch`, so an
+out-of-protocol overwrite before that mutation went unreported. A journaled
+create records an authorized revision at the item's birth, so the ordinary
+surfaces cover the item from then on: an out-of-protocol overwrite reports
+`unauthorized-revision` and the next mutation refuses. An unprovisioned or
+non-Git ledger keeps only its local number-index lock and its atomic
+no-clobber publication; nothing there coordinates across checkouts, and nothing
+here defends against an actor that bypasses this tool.
+
+**The refusal.** A fenced create refuses before it allocates a number and
+before it writes a byte:
+
+```text
+exit: 6
+ok: false
+namespace: "ledger-mutation"
+command: "create-v1"
+contract_version: 1
+state: "unchanged"
+error.code: "claim-store-unavailable"
+error.details.reason: "publication-reconciliation-required"
+```
 
-**Decided: create stays journal-silent.** The asymmetry is intended. Three
-reasons hold it:
-
-1. Create already protects its own instant. Publication is atomic, it refuses
-   to clobber an existing path, and it verifies the published bytes exactly
-   after the write. A journal entry adds no protection to that instant.
-2. A journaled create would serialize every worktree on the highest-volume
-   mutation. The field reports name create as the most frequent mutation and as
-   the most frequent victim of a block. Making create a blocker as well as a
-   victim multiplies a cost that consumers already report.
-3. The remaining exposure window is real but narrow, and it closes at the
-   item's first journal-visible mutation.
-
-**The exposure window, stated honestly.** The journal does not know a created
-item until that item's first journal-visible mutation, which is a `transition`
-or a `patch`. Until then an out-of-protocol overwrite of the item's bytes is
-not detected. A commit alone does not close the window, because reconciliation
-compares only the revisions the journal expects, and the journal expects none
-for that item. From the first `transition` or `patch`, the ordinary surfaces
-cover the item: with the authorized revision committed, an out-of-protocol
-overwrite of the working-tree bytes reports `unauthorized-revision` and the
-next mutation refuses. Inside the window, only an actor that bypasses this tool
-can overwrite the item, and this protocol does not defend against that actor.
-It is merge-coordinated, not exclusive.
-
-**Warning: the same window lets more than one worktree commit one item number,
-and nothing repairs it** (items #181 and #182). Because create is
-journal-silent, nothing coordinates the number a create derives. Any two
-worktrees whose checkouts have not been integrated derive the next schema-v2
-`number` from the base each can see, and both derive the same one. The two
-creates need not overlap in time: a create in one worktree today and a create
-in another worktree tomorrow collide just as surely, so long as neither
-worktree has seen the other's commit. Both creates succeed, both refuse
-nothing, and reconciliation reports nothing, because there is no recorded
-revision to compare. The collision becomes visible only when the branches are
-integrated: `validate` then fails globally with `duplicate-number` on every
-colliding item, and an invalid ledger blocks every mutation, so the whole
-ledger stops accepting work. `number` is immutable and `patch` correctly
-rejects it, so this protocol currently offers no operation that repairs the
-collision.
-
-Until both items ship, serialize `create` through a single worktree, and run
-`validate` immediately after you integrate branches so a collision surfaces at
-the merge rather than at the next mutation. Editing `number` in the item
-source by hand, committing it, and then running `claim-adopt` is **not a
-supported workaround**: one field deployment did exactly that as an emergency
+`error.details.findings` names the item whose authorized create this checkout
+cannot see, and each finding's own `remediation` string stays authoritative:
+commit this worktree's bytes for `git-finalization-required`; synchronize the
+named sibling revision when `owner_ref` names a live worktree; inspect the
+reachable or dangling history and restore or explicitly adopt reviewed bytes
+for a locally absent or reachable-unowned revision; and restore or adopt for
+unauthorized bytes. The reproduced stale-sibling case is locally absent on both
+surfaces, so it renders the cannot-be-established sentence, which is an
+instruction to inspect and integrate, never an instruction to wait. Once the
+ledger validates and `claim-verify` exits 0, retry the same request ID: the
+refusal published no byte, so the retry is an ordinary no-clobber create and
+takes the next number. The fence does not trap recovery — `claim-verify` stays
+read-only, `claim-adopt` keeps its explicit override, claim release stays
+available under barriers, and Git synchronization was never this tool's to
+block.
+
+**Recovery from an interrupted create.** An intent with no terminal resolves on
+the next invocation from the item path alone: the candidate revision present
+appends the committed terminal, the path absent appends the create abort, and
+any third revision reports `legacy-mutation-outcome-unknown` as a global
+barrier. Recovery never guesses a number and never publishes an item. Because
+capacity for the intent, one clock entry, and one terminal is reserved before
+the intent is appended, an exhausted journal refuses unchanged before
+publication rather than stranding an unresolvable attempt.
+
+**Create owns its item and its reconciliation log.** A successful create is
+journal-visible from the item's birth, so its `changed_paths` and its
+`--auto-commit` commit set are exactly the created item and
+`<ledger>/.wowbagger/reconcile-<namespace>.md`. Owning the log it writes is not
+permission to absorb residue: a reconciliation log already dirty before the
+invocation is foreign, and create still refuses it.
+
+**Commit every create before the next mutation.** A create has no authorized
+predecessor — there is no earlier revision of an item that did not exist — so
+Git `HEAD` is the only surface that can hold its authorized bytes, and an
+uncommitted create reports the global `git-finalization-required` until it is
+committed. A `patch` or `transition` may instead occupy the documented
+authorized predecessor/successor window and run before its predecessor is
+committed, but that window is an accepted overlap, not a licence: commit every
+mutation before the next one. Alpha.14 ships no batch mutation. The supported
+bulk pattern is the create-then-commit loop, one commit per created item, and
+item #186 owns the design of a safe batch create.
+
+**Cost.** A provisioned create already took the namespace lock, replayed the
+journal, loaded the ledger, read Git `HEAD`, and reconciled. The fence changes
+which findings refuse; it adds no new Git roster or history traversal to a
+clean create, and the measured cost of the change is two extra fsync'd journal
+appends. 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 checked before publication and fails closed. Journal
+compaction is not part of this change.
+
+**A ledger that already carries duplicate numbers is item #182's recovery
+work, not this fix's.** Such a ledger fails validation and refuses every
+mutation before allocation, and item #182 owns the fenced repair. #181 prevents
+new collisions in every valid ledger; it neither renumbers damaged items nor
+makes an invalid ledger worse. Editing `number` in the item source by hand,
+committing it, and then running `claim-adopt` is **not a supported
+workaround**: one field deployment did exactly that as an emergency
 intervention during an outage, and it bypasses the number-collision and
 reference checks every mutation performs, so it can leave dangling
 `depends_on`, `related`, and parent references that nothing reports.
 
+**What alpha.14 guarantees, and what it does not.** Alpha.14 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 that fence and still rely on branch
+integration plus `validate`.
+
+**The upgrade is a hard cutover.** Alpha.13 cannot read a `create-v1` legacy
+intent. Executed against a ledger whose shared journal already carries one, its
+create exits 6 with `error.code` `claim-store-unavailable`, message
+`The durable claim store is unavailable.`, and `error.details.reason`
+`claim-store-unreadable`, leaving the state unchanged and writing no item. That
+fail-closed behavior is the compatibility guarantee: an old writer cannot
+commit another duplicate. It is also the operational limit, because alpha.13 is
+immutable and emits a generic unreadable-store message rather than upgrade
+guidance. Read that exact refusal 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: upgrade every writer in one Git coordination
+domain before the first alpha.14 create. If a partial upgrade writes the new
+grammar first, every remaining alpha.13 worktree stops making claim-protected
+mutations until it is upgraded. Item #185 owns the general ability of a running
+old binary to diagnose its own version drift; no change here can retrofit a
+message into an already-published executable.
+
 **`unauthorized-revision` has two remedies, and only one of them is
 destructive.** Restoring the authorized revision discards the out-of-protocol
 edit. Adopting the committed revision keeps it and moves the coordinator's
@@ -401,6 +530,16 @@ Each refusal carries a `reason` that separates the cases:
 | `worktree-synchronization-required` | another worktree wrote the item | wait for the owner named by `owner_ref`/`owner_commit`, then synchronize this checkout and run `claim-verify`; if `owner_unavailable` is true, follow the finding's `remediation` (section 3.2 step 4) |
 | `unauthorized-revision` | the item was changed outside the protocol | restore the authorized revision and discard the edit, then `claim-verify`; or adopt the committed revision and keep the edit, then `claim-verify` (section 3.3) |
 
+**Scope is the coordinator's judgement, not a published member.** What a
+finding refuses — every write, only a write against the item it names, or
+nothing — is decided from the topology and travels beside the finding, never
+inside it. No response carries it. A consumer MUST NOT infer scope from the
+`reason` string, from the `remediation` sentence, or from whether `owner_ref`
+is present: those are diagnostics for a person, and reading them as a scope
+signal is exactly how alpha.11 treated an out-of-protocol revision as advisory
+synchronization. The only supported scope signal is the refusal itself: a
+mutation that returns exit 6 was blocked, and one that returns exit 0 was not.
+
 Ownership on the current symbolic ref is never reported as a foreign worktree
 owner, and a detached `HEAD` applies the same guard through its reachable
 commit history. If the expected revision is already reachable from the current
@@ -409,16 +548,58 @@ worktree; it remains `unauthorized-revision` and blocks unrelated mutations.
 This distinguishes a real sibling's uncommitted successor from history the
 current checkout already owns.
 
+**`owner_ref` names an active named worktree, and nothing else.** Owner
+evidence is the worktree roster Git reports live, searched this checkout first,
+then every live worktree that has a branch checked out, ordered by branch ref
+and then by path so one revision carried by several live worktrees always names
+the same owner. A bare record, a record Git marks prunable, and a worktree
+whose `HEAD` names no commit are excluded. `owner_ref` is always the branch of
+one of those live worktrees, and `owner_commit` is the commit in that
+worktree's history whose item bytes are the expected revision.
+
+Reachability alone is never ownership. A tag, a remote-tracking ref, a branch
+no worktree has checked out, and a live worktree on a detached `HEAD` can each
+reach the expected revision while naming nobody who could publish it. All of
+them, and a revision no reachable commit carries at all, produce
+`owner_unavailable: true` and no `owner_ref`. So `owner_unavailable` means one
+of three things: the expected revision is not reachable at all, a live sibling
+holds it on a detached `HEAD`, or it is reachable only from refs no active
+worktree has checked out.
+
+Three `owner_unavailable` remediation sentences separate those cases. The
+sentence naming ownership that cannot be established from reachable refs is
+emitted only when this checkout has no item path and `HEAD` has none either, so
+the item has never existed here. A revision Git does reach — from a tag, a
+remote-tracking ref, a branch no worktree has checked out, or a live worktree on
+a detached `HEAD` — gets the sentence saying the revision is reachable in Git
+while no active named worktree owner is established. Its remedy is to inspect
+the reachable history and restore or explicitly adopt reviewed bytes, then run
+`claim-verify`; there is no commit left to wait for. Only a revision no
+reachable commit carries at all gets the not-yet-reachable sentence, whose
+remedy is to wait for the owning worktree to commit, then synchronize this
+checkout and run `claim-verify`.
+
+Through alpha.13 the reachable cases were given the not-yet-reachable sentence
+too, which told a reader to wait for a commit Git already had. The wait never
+ended, because no named worktree was ever going to publish those bytes. The
+`reason`, the codes, the scope, and the finding members are unchanged; only the
+`remediation` text for the reachable-unowned cases is corrected.
+
 **Writer identity.** A legacy mutation and a claimed publication record the
 worktree that authorized them in their journal entries as
 `writer_worktree_id`: `legacy-mutation-intent`, `legacy-mutation`,
 `publish-intent`, and `publish-final`. The field is optional on all of them: an
-entry written before the field existed stays valid and attributes nothing. A
-publication resolves its identity once under the claim lock, so its intent and
-its terminal name one writer, and a terminal that recovery reconstructs after a
-lost response carries the identity its intent recorded. When the journal names
-the current worktree as the writer of the expected revision and no reachable
-ref carries that revision, no sibling can ever produce it, so the finding is
+entry written before the field existed, which is every entry alpha.12 and
+earlier wrote, stays valid, attributes nothing, and leaves the expected writer
+`unknown`. Writer attribution alone therefore cannot turn such a finding into a
+global barrier: it stays advisory `worktree-synchronization-required`. Local
+state and current-checkout ownership are still judged first, and both remain
+global barriers whatever the entry records. A publication resolves its identity
+once under the claim lock, so its intent and its terminal name one writer, and
+a terminal that recovery reconstructs after a lost response carries the
+identity its intent recorded. When the journal names the current worktree as
+the writer of the expected revision and no reachable ref carries that revision,
+no sibling can ever produce it, so the finding is
 `unauthorized-revision` and blocks every mutation instead of
 `worktree-synchronization-required`, which blocks only its own item.
 
@@ -471,13 +652,15 @@ a new UUID, and the removed UUID stays in journal history attributing nothing.
    carries `owner_unavailable: true`.
 3. If an owner is named, WAIT for that owner to publish the commit, then
    synchronize this checkout to it. Do not merge unrelated live work.
-4. If ownership is unavailable, the `remediation` string separates two cases.
+4. If ownership is unavailable, the `remediation` string separates three cases.
    When it says the expected revision is not yet reachable, the owning
    worktree has not committed it yet: wait as in step 3, then synchronize.
-   When it says ownership cannot be established from reachable refs, inspect
-   reachable or dangling commits. Restore the exact authorized bytes or use
-   explicit `claim-adopt` authority after review. Do not copy peer
-   working-tree bytes.
+   When it says the revision is reachable in Git while no active named worktree
+   owner is established, do not wait: inspect the reachable history that carries
+   it, then restore the exact authorized bytes or use explicit `claim-adopt`
+   authority after review. When it says ownership cannot be established from
+   reachable refs, inspect reachable or dangling commits and remedy it the same
+   way. In neither inspection case do you copy peer working-tree bytes.
 5. Run `claim-verify --ledger <dir> --json` in the blocked worktree and require
    exit 0.
 6. Resume the affected item.
@@ -487,6 +670,27 @@ successful mutation requires a valid ledger and no findings blocking the target
 item, not a globally empty findings list. Nonblocking findings remain available
 to `claim-verify`, where a caller that names no target still sees every finding.
 
+**A target-scoped success is not a globally clean claim store.** The two scopes
+answer different questions and a caller MUST NOT substitute one for the other.
+A mutation, and auto-commit inside it, requires only that no finding blocks its
+own target item. `claim-verify` names no target, so every unresolved finding
+blocks it: exit 6 there is the repository-wide answer, and it stays exit 6
+while any item in the repository carries a blocking finding, including one
+belonging to work this caller has nothing to do with. A cooperating worker can
+therefore commit every one of its own mutations while `claim-verify` never
+reaches exit 0, because a sibling worktree's unpublished item is visible from
+every checkout that shares the common directory.
+
+That is current behavior, not a settled design. Item #184 is open in triage to
+choose the supported surface — item-scoped verification, target-aware input, or
+repository-wide success with structured foreign-work warnings, while keeping a
+strict whole-repository mode. Until it ships, an automated gate that demands a
+globally clean `claim-verify` is unsatisfiable in a repository with live
+sibling work. Gate on the mutation's own refusal, and read a repository-wide
+`claim-verify` as the diagnostic it is. Do not hand-edit an item or run
+`claim-adopt` to reach exit 0: adoption moves the coordinator's authorized
+revision and is not a way to silence a sibling's finding.
+
 `claim-verify` in the writing worktree finalizes that worktree's own state; it
 does not make a sibling checkout able to see the item. Synchronization or
 explicit recovery is still required for the affected item.
@@ -666,6 +870,23 @@ fails or its durability is uncertain, the backend returns exit 6 with
 to guess. It cannot report a lease success or semantic rejection whose time
 was not persisted.
 
+**A refused reconciliation has already advanced the floor.** Reconciliation
+persists its clock entry before it classifies anything, so a command that then
+refuses with exit 6 `claim-store-unavailable`, reason
+`publication-reconciliation-required`, has still moved the durable floor to
+`max(physical_utc, previous_floor)`. No claim, epoch, or ledger byte changes,
+and the refusal reports none. The floor is monotonic, so the effect is on time
+alone and it is permanent: once a refused reconciliation has published a floor
+at or past a lease's `expires_at`, that lease can never read live again, and a
+later acquire, renew, or fence check on the same tuple observes it expired.
+On a ledger whose floor already runs ahead of this caller's wall clock, every
+refused reconciliation republishes the higher floor, so a holder whose lease
+looks live by its own clock may find it expired the moment it asks. A caller
+that meets a barrier during a long recovery SHOULD expect to reacquire rather
+than assume its lease survived. This is section 5's rule for a rejected
+decision applied one step earlier: an advanced floor is never evidence that
+anything succeeded.
+
 When `last_epoch` is `18446744073709551615` (the unsigned 64-bit maximum), a
 new acquire or takeover is impossible. After the authoritative decision time
 has been persisted, the backend returns exit 6 `epoch-exhausted` with message
@@ -1095,18 +1316,24 @@ create MUST reject any item identity whose tuple has claim history with exit 4
 high-water mark. Both checks persist authoritative decision time before their
 response.
 
-Before a merge-coordinated backend permits a legacy transition or patch to
-write bytes, it MUST fsync a `legacy-mutation-intent` with the expected and
-candidate revisions. Under the same namespace lock, it MUST reserve journal
-capacity for that intent, one recovery clock entry, and one terminal entry. A
-committed write appends `legacy-mutation`; an unchanged write appends
-`legacy-mutation-abort`. Reconciliation resolves a pending intent to the
-committed terminal when the candidate revision is present, or to the abort
+Before a merge-coordinated backend permits a legacy create, transition, or
+patch to write bytes, it MUST fsync a `legacy-mutation-intent` carrying the
+expected and candidate revisions. Under the same namespace lock, it MUST
+reserve journal capacity for that intent, one recovery clock entry, and one
+terminal entry. A committed write appends `legacy-mutation`; an unchanged write
+appends `legacy-mutation-abort`. Reconciliation resolves a pending intent to
+the committed terminal when the candidate revision is present, or to the abort
 terminal when the expected revision remains. Any third revision produces
 `legacy-mutation-outcome-unknown`. The latest committed terminal is the
 authorized expected revision. A later unrecorded revision remains a stale
 write.
 
+A create has no predecessor, so its intent carries `expected_revision: null`,
+which is valid only for `create-v1`, and the item path's absence is what
+resolves it to the abort terminal. Section 3.1 states the complete create
+ordering, its allocation fence, and the alpha.13 cutover the widened grammar
+forces.
+
 A merge-coordinated backend MUST reconcile before it authorizes a legacy write,
 and section 6 states the same requirement for `publish-claimed`.
 When reconciliation produces any blocking finding, the legacy command MUST

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wowbagger",
-  "version": "0.1.0-alpha.13",
+  "version": "0.1.0-alpha.14",
   "description": "Git-native work ledger for coding agents: deterministic ready queues, guarded CAS mutations, claims and fencing, and self-contained HTML reports.",
   "type": "module",
   "license": "MIT",