diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..96c66a1 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,3 @@ +# The portable skill payload is digest-bound. Keep its bytes identical on every +# platform, including Windows checkouts with core.autocrlf enabled. +skills/wip-commit/** text eol=lf diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 8d9878a..1257b8c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -26,6 +26,9 @@ jobs: cache: true - run: go mod verify - run: go test -count=1 ./... + - name: Stress concurrent shared-lane capture on Windows + if: runner.os == 'Windows' + run: go test -run '^TestConcurrentSharedLanesCaptureDisjointPaths$' -count=25 ./cmd/wip - run: go vet ./... race: @@ -41,6 +44,29 @@ jobs: cache: true - run: go test -race -count=3 ./... + benchmark: + # Run real locks and Git processes on every supported CI operating system. + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest, macos-latest, windows-latest] + runs-on: ${{ matrix.os }} + timeout-minutes: 10 + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0 + with: + go-version-file: go.mod + cache: true + - name: Prefetch modules before the offline benchmark + run: go mod download + - name: Run portable behavioral benchmark + run: go run ./skills/wip-commit/benchmark/regression.go --out-dir "${{ runner.temp }}/wip-commit-benchmark" + - name: Prove rejection of the weakened candidate + run: go run ./skills/wip-commit/benchmark/regression.go --prove-weakened --out-dir "${{ runner.temp }}/wip-commit-benchmark" + lint: runs-on: ubuntu-latest timeout-minutes: 10 diff --git a/.github/workflows/release-beta.yml b/.github/workflows/release-beta.yml index 94c8b05..029411d 100644 --- a/.github/workflows/release-beta.yml +++ b/.github/workflows/release-beta.yml @@ -40,7 +40,7 @@ jobs: - name: Build deterministic archives run: go run ./scripts/release --version "$GITHUB_REF_NAME" --out dist - name: Attest release files - uses: actions/attest@508db95dd578ae2727ebd6217d5ba78e4fbda05d # v4.2.1 + uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2 with: subject-path: | dist/*.tar.gz diff --git a/.nicos/product.yaml b/.nicos/product.yaml index cdd7ba2..b15c7ba 100644 --- a/.nicos/product.yaml +++ b/.nicos/product.yaml @@ -5,6 +5,7 @@ surface: products kind: product status: experimental launch: built +license: MIT tags: - go - git @@ -15,5 +16,5 @@ checks: - go - test - ./... -description: Guarded split-commit capture for parallel agents in shared checkouts and linked worktrees. +description: Reviewed, lease-bound Git capture for agents, with operational status and capture-only handoff receipts. portfolio_manifest: portfolio/manifest.yaml diff --git a/CHANGELOG.md b/CHANGELOG.md index 5a4d5dd..f90683a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,22 +5,31 @@ Semantic Versioning. ## [Unreleased] -Planned first prerelease: `v0.1.0-beta.1`. +Planned first prerelease: `v0.2.0-beta.1`. ### Added +- A machine-readable `wip.command/3.0.0` capability contract and a digest-bound + portable-skill contract. +- Preview/apply upgrades for the state marker, installed binary, and portable + skill. Each apply requires the exact reviewed byte digest. +- A version 2 coordination-domain marker with a minimum reader protocol and + required reader capabilities. - Portable `wip-commit` agent skill with a public-only safety contract. - Deterministic six-target release builder, checksums, receipt, and attested prerelease workflow. - Pinned golangci-lint job for hosted pull-request and branch checks. - State compatibility policy and explicit upgrade and downgrade procedures. -- Fail-closed, read-only pre-first-push receipt that binds the reviewed +- Fail-closed, read-only pre-first-push receipt. It binds the reviewed bootstrap, linear split-commit range, complete path delta, public author and committer identities, object integrity, owner approval, and secret scans. - Human-only publication handoff for the first hosted pull request, exact CI check discovery, direct bootstrap fast-forward, and protected-branch setup. +- Fail-closed hosted-correction receipts that bind exact verifier source, local + history, remote refs, pull-request state, no-bypass rulesets, and checks. - Shared-checkout and detached linked-worktree lanes. -- Exact staged-subset capture through private Git indexes. +- Exact `staged_index` and `worktree_snapshot` capture through private source + snapshots and private Git indexes. - All-or-nothing split plans with one final ref compare-and-swap. - Conventional Commit validation, path leases, immutable hooks, bounded verification, durable intents, and exact reconciliation. @@ -29,14 +38,72 @@ Planned first prerelease: `v0.1.0-beta.1`. - Strict bounded state readers, portable Unicode path identity, and Windows atomic replacement and file locks. - NUL-delimited delete/add accounting for renamed paths. +- Operational status with capture-candidate, captured-staged, foreign-staged, + empty-lease, expiry, ref-health, policy, and latest-intent fields, plus a + strict public JSON Schema. +- One version 3 draft/reviewed plan schema with source mode, untracked policy, + source digest, path, lease, lane, and message-policy bindings. +- `wip capture` with a digest-bound version 2 cumulative capture-only handoff + and optional post-handoff lane release. +- A read-only `wip plan --observe` path that does not renew leases, change + repository state, or write an output file. +- A digest-bound coordination migration with shadow comparison, one writer + cutover, forward recovery, rollback before source movement, and a sealed + legacy archive. +- A manifest-bound registry lock that is published before migrated lane and + lease records become readable. +- Immutable `review/v1/handoffs` and `review/v1/plans` storage roots for the + separate review and landing authority. +- Named `conventional-v1` and `safety-only-v1` message policies. +- Automatic complete-set lease renewal on ordinary authenticated lane use. +- Runtime validation of real command data against the published capture JSON + Schemas. +- Version 1 profile and intent compatibility without immutable digest changes. +- Capture-intent schema version 3 with read compatibility for versions 1 and 2. +- Migration status schema version 1.1.0 with separate historical cutover and + current live-store manifest digests. +- A canonical copied-hook environment with capture, phase, target-ref, commit, + and source-read-only markers. Caller values cannot override these markers. +- Reviewed verifier materialization scopes with pre-checkout entry and byte + limits, literal Git pathspecs, and NUL-delimited checkout input. ### Changed +- `wip commit --dry-run` now uses a fail-closed no-exec contract. It snapshots + hooks and constructs the candidate structure without executing repository hooks, + verification commands, publication callbacks, lease renewal, or repository + Git writes. + Result schema 3 reports skipped gates and exact execution counts. +- Source builds now report `0.2.0-dev`. Release builds receive both SemVer and + exact tag identity from the deterministic release builder. +- A zero lock wait now fails after one acquisition attempt. Internal + serialization uses an explicit bounded wait. +- Operational lane and lease reads now use the same registry fence as atomic + record replacement. This prevents Windows sharing violations during capture. - Unsupported state-directory, lane, lease, intent, and profile schemas now fail with `MIGRATION_REQUIRED` before the command changes state. +- Interactive initialization now recommends one linked worktree per task. +- Worktree initialization now requires a destination and reports where to + continue. `env` rejects another checkout before lease renewal. +- A worktree initialization retry can start inside its existing linked + worktree. It resolves and reports the primary checkout as the recovery + anchor. +- Handoff validation, active renewal, and final guided release now keep one + continuous lane lock. Completed receipts always revalidate Git objects. +- Handoff output now validates the unique complete lane chain from base to tip. + A requested plan ID must name the tip segment. +- Worktree-source planning now uses a temporary index and object directory. It + leaves the caller index and repository object database unchanged. +- Released-lane handoff locks existing state without rewriting lock metadata + or creating missing lock paths. +- Commit-message naming checks now run as lane policy before hooks. The capture + kernel keeps only message byte, size, and subject safety checks. - The minimum build toolchain is Go 1.25.12. This patched floor excludes GO-2026-4602, GO-2026-4864, and GO-2026-4970 from reachable standard-library paths found by the release vulnerability scan. +- Completed migration status now accepts valid post-cutover writes in the two + live data roots. It keeps exact checks for incomplete migrations and the + static migration envelope. ### Known limitations diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..5120fc4 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,151 @@ +# Contributor Covenant 3.0 Code of Conduct + +## Our Pledge + +We pledge to make our community welcoming, safe, and equitable for all. + +We are committed to fostering an environment that respects and promotes the +dignity, rights, and contributions of all individuals, regardless of +characteristics including race, ethnicity, caste, color, age, physical +characteristics, neurodiversity, disability, sex or gender, gender identity or +expression, sexual orientation, language, philosophy or religion, national or +social origin, socio-economic position, level of education, or other status. +The same privileges of participation are extended to everyone who participates +in good faith and in accordance with this Covenant. + +## Encouraged Behaviors + +While acknowledging differences in social norms, we all strive to meet our +community's expectations for positive behavior. We also understand that our +words and actions may be interpreted differently than we intend based on +culture, background, or native language. + +With these considerations in mind, we agree to behave mindfully toward each +other and act in ways that center our shared values, including: + +1. Respecting the **purpose of our community**, our activities, and our ways of + gathering. +2. Engaging **kindly and honestly** with others. +3. Respecting **different viewpoints** and experiences. +4. **Taking responsibility** for our actions and contributions. +5. Gracefully giving and accepting **constructive feedback**. +6. Committing to **repairing harm** when it occurs. +7. Behaving in other ways that promote and sustain the **well-being of our + community**. + +## Restricted Behaviors + +We agree to restrict the following behaviors in our community. Instances, +threats, and promotion of these behaviors are violations of this Code of +Conduct. + +1. **Harassment.** Violating explicitly expressed boundaries or engaging in + unnecessary personal attention after any clear request to stop. +2. **Character attacks.** Making insulting, demeaning, or pejorative comments + directed at a community member or group of people. +3. **Stereotyping or discrimination.** Characterizing anyone's personality or + behavior on the basis of immutable identities or traits. +4. **Sexualization.** Behaving in a way that would generally be considered + inappropriately intimate in the context or purpose of the community. +5. **Violating confidentiality.** Sharing or acting on someone's personal or + private information without their permission. +6. **Endangerment.** Causing, encouraging, or threatening violence or other + harm toward any person or group. +7. Behaving in other ways that **threaten the well-being** of our community. + +### Other Restrictions + +1. **Misleading identity.** Impersonating someone else for any reason, or + pretending to be someone else to evade enforcement actions. +2. **Failing to credit sources.** Not properly crediting the sources of content + you contribute. +3. **Promotional materials.** Sharing marketing or other commercial content in + a way that is outside the norms of the community. +4. **Irresponsible communication.** Failing to responsibly present content + which includes, links, or describes any other restricted behaviors. + +## Reporting an Issue + +Tensions can occur between community members even when they are trying their +best to collaborate. Not every conflict represents a code of conduct +violation, and this Code of Conduct reinforces encouraged behaviors and norms +that can help avoid conflicts and minimize harm. + +Use the repository host's private reporting form on the Security tab to report +a possible violation. Start the report title with `Code of Conduct:`. Do not +open a public issue. The repository owner serves as the Community Moderator +and receives these private reports. If a report concerns the repository owner, +use GitHub's content-reporting or support channel instead. + +The Community Moderator takes reports of violations seriously and will make +every effort to respond in a timely manner. The moderator will investigate +reports by reviewing relevant messages, logs, recordings, or witness accounts. +The moderator will keep investigation and enforcement actions as transparent +as possible while prioritizing safety and confidentiality. Enforcement actions +are carried out in private with the involved parties, but communicating to the +whole community may be part of a mutually agreed resolution. + +## Addressing and Repairing Harm + +If an investigation finds that this Code of Conduct has been violated, the +following enforcement ladder may be used to determine how best to repair harm. +The decision depends on the incident's impact on the people involved and the +community as a whole. Depending on the severity of a violation, lower rungs on +the ladder may be skipped. + +1. **Warning** + 1. Event: A violation involving a single incident or series of incidents. + 2. Consequence: A private, written warning from the Community Moderator. + 3. Repair: Examples include a private written apology, acknowledgement of + responsibility, and seeking clarification on expectations. +2. **Temporarily Limited Activities** + 1. Event: A repeated violation that previously resulted in a warning, or the + first occurrence of a more serious violation. + 2. Consequence: A private, written warning with a time-limited cooldown + period. The period may limit particular communication channels or + interactions with particular community members. + 3. Repair: Examples include making an apology, reflecting on actions and + impact, and being thoughtful about re-entering community spaces. +3. **Temporary Suspension** + 1. Event: A pattern of repeated violations that warnings did not resolve, or + a single serious violation. + 2. Consequence: A private written warning with conditions for return from + suspension. + 3. Repair: Examples include respecting the spirit of the suspension, meeting + the conditions for return, and reintegrating thoughtfully. +4. **Permanent Ban** + 1. Event: A pattern that other steps did not resolve, or a violation so + serious that the moderator cannot keep the community safe with this + person as a member. + 2. Consequence: Access to all community spaces, tools, and communication + channels is removed. Permanent bans should be rare and supported by + strong reasoning. + 3. Repair: There is no possible repair in cases of this severity. + +This enforcement ladder is a guideline. It does not limit the Community +Moderator's discretion and judgment when acting in the community's best +interests. + +## Scope + +This Code of Conduct applies within all community spaces. It also applies when +an individual officially represents the community in public or other spaces. +Examples include using an official email address, posting through an official +social account, or acting as an appointed representative at an online or +offline event. + +## Attribution + +This Code of Conduct is adapted from the Contributor Covenant, version 3.0, +permanently available at +[https://www.contributor-covenant.org/version/3/0/](https://www.contributor-covenant.org/version/3/0/). + +Contributor Covenant is stewarded by the Organization for Ethical Source and +licensed under [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/). +The enforcement ladder was inspired by the work of +[Mozilla's code of conduct team](https://github.com/mozilla/inclusion). + +For more guidance, see the Contributor Covenant +[FAQ](https://www.contributor-covenant.org/faq), +[translations](https://www.contributor-covenant.org/translations), and +[resources](https://www.contributor-covenant.org/resources). diff --git a/README.md b/README.md index 1aff171..7dba2ac 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,28 @@ # wip-commit -`wip` lets concurrent agents capture exact staged subsets without moving the -source checkout's `HEAD` or rewriting its Git index. Each agent writes to a -local ref under `refs/heads/wip//`. +`wip` lets concurrent agents capture exact paths from a staged index or a +worktree snapshot. It does not move the source checkout's `HEAD` or rewrite the +caller index. Each agent writes to a local ref under +`refs/heads/wip//`. -The planned first prerelease is `v0.1.0-beta.1`. The current candidate is -suitable for local beta use, but it is not a stable release. Verify the public -tag and release before you treat a checkout as published software. +The source repository is public. No tag or GitHub release exists. The planned +first prerelease is `v0.2.0-beta.1`. The current candidate is suitable for +local beta use, but it is not a stable release. Verify the public tag and +release before you treat a checkout as released software. ## Why it exists A normal `git commit` consumes the complete shared index and moves the checked out branch. When several agents use one checkout, that operation is unsafe. -`wip` uses three controls: +`wip` uses four controls: - Path leases prevent active lanes from claiming overlapping paths. -- A private index contains only the planned staged entries. +- A private source snapshot contains only the reviewed source paths. +- A private index builds only the planned commits. - One compare-and-swap updates the agent ref after all commit groups pass. -Two lanes can therefore capture disjoint staged paths in parallel. They do not -commit directly to the same checked-out branch. Review and landing are separate +Two lanes can therefore capture disjoint source paths in parallel. They do not +commit directly to the checked-out branch. Review and landing are separate operations. One repository can have only one coordination domain. Standalone state uses @@ -41,16 +44,65 @@ Build the current checkout with: ```text go build -trimpath -o ./bin/wip ./cmd/wip ./bin/wip version +./bin/wip --json version +./bin/wip --json contract ``` -For a published `v0.1.0-beta.1` tag, the install command is: +Source builds identify themselves as `0.2.0-dev` with `channel: development`. +The release builder injects both the selected SemVer and its exact tag. Only +that pair reports `channel: release`. Release binaries also report the exact +VCS revision and a clean source state. A local Go build reports VCS fields when +the toolchain supplies them. If `source_stamped` is false, do not let the +binary read or change existing coordination state. + +The version result also reports the executable SHA-256 and the embedded +portable-skill payload SHA-256. An integration must hash the selected regular +executable independently, compare both digests with the contract, and reject a +file identity or digest change before or after each subprocess. + +`wip --json contract` reports the command protocol, explicit capabilities, +portable-skill contract, and embedded portable payload digest. Integrations +must validate those fields. Do not infer compatibility from a display version. +The current development protocol is `wip.command/3.0.0`. + +For a published `v0.2.0-beta.1` tag, the install command is: ```text -go install github.com/nstranquist/wip-commit/cmd/wip@v0.1.0-beta.1 +go install github.com/nstranquist/wip-commit/cmd/wip@v0.2.0-beta.1 ``` Before you run that command, verify that the tag exists at that public address. +## Quick start + +Build the current checkout, then start the setup wizard inside the Git +repository where you want to capture work: + +```text +go build -trimpath -o ./bin/wip ./cmd/wip +./bin/wip init +``` + +The wizard prints the lane environment command. Load it in the agent shell. +Then review an exact worktree-source plan and capture it: + +```text +eval "$(./bin/wip env --lane )" +./bin/wip plan \ + --source worktree_snapshot \ + --untracked forbid \ + --path \ + --out plan.json +# Add one message to each group. Then set state to reviewed. +./bin/wip capture --plan plan.json +./bin/wip release +``` + +Use a linked worktree when one agent owns the complete checkout. Use +shared mode when cooperating agents need disjoint path leases in one checkout. +Automation must capture the exact generated plan. Do not construct a version 3 +plan from a partial example because its source and lease digests are immutable. + ## Use the agent skill The portable skill is in [skills/wip-commit](skills/wip-commit). Install that @@ -64,6 +116,61 @@ plans and treats typed JSON evidence as the capture result. An internal integration can add repository policy around this skill. It must not weaken the path-ownership, split-plan, result-check, or no-landing rules. +## Upgrade an existing installation + +Upgrade one target at a time. Preview is read-only. Apply requires the exact +digest from that preview: + +```text +wip --json upgrade --binary --install-dir ~/.local/bin +wip --json upgrade --binary --install-dir ~/.local/bin \ + --apply --yes --plan-digest sha256: + +wip --json upgrade --skill --skill-dir ~/.agents/skills +wip --json upgrade --skill --skill-dir ~/.agents/skills \ + --apply --yes --plan-digest sha256: +``` + +The binary target must already be a regular executable. The skill target can +be an older canonical bundle, but it cannot contain unknown files, directories, +or symbolic links. Use `wip init --install` or `--install-skill` for a missing +target. Before a binary changes, WIP durably retains the complete previous and +desired executables under the content-addressed `.wip.revisions` directory next +to the install target. WIP does not prune that rollback store. The reviewed +plan reports both revision paths. See +[State compatibility](docs/STATE-COMPATIBILITY.md) for the separate +coordination-marker upgrade. + +## Prove portable behavior + +Run the behavioral benchmark from the repository root: + +```text +go run ./skills/wip-commit/benchmark/regression.go +``` + +The runner builds the candidate with `GOPROXY=off`. It then uses the shipped +entrypoints in disposable Git repositories. It makes no network or AI calls. + +The benchmark checks eight semantic cases and eight negative controls. The +reviewed baseline requires all 16 checks to pass. + +Run the deliberately weakened candidate proof: + +```text +go run ./skills/wip-commit/benchmark/regression.go --prove-weakened +``` + +The proof requires the benchmark to reject the unsafe candidate. The runner +cannot modify [the reviewed baseline](skills/wip-commit/benchmark/baseline.json). + +If `ndev` is available, run `ndev --json skills benchmark wip-commit`. It finds +this external repository before it uses an internal skill fallback. + +The cross-platform benchmark CI job runs the same cases on Linux, macOS, and +Windows. Read [the benchmark guide](skills/wip-commit/benchmark/README.md) for +the report schema, artifact location, and baseline policy. + ## Start with `wip init` Run the wizard in a Git checkout: @@ -74,14 +181,18 @@ wip init The wizard does the following work: -1. It checks the coordination domain and recommends `shared` or `worktree` mode. +1. It checks the coordination domain and recommends `worktree` mode. 2. It asks for the agent, session, lane, base ref, and path claims. 3. It can create a detached linked worktree after you select that mode. 4. It can copy the current binary to `~/.local/bin` after you approve the path. 5. It can install the embedded portable skill in `~/.agents/skills`. -6. It creates the lane, claims the paths, writes a private profile, and checks +6. It binds the lane to a named message policy. +7. It creates the lane, claims the paths, writes a private profile, and checks the staged diff. +Use `worktree` mode for one agent per task. Use `shared` mode only when lanes +must use the same checkout and index. + The staged-path read must succeed when the worktree exists. Git inspection errors stop setup and preserve its recovery receipt. Staged whitespace errors remain nonfatal, but the human and JSON results report them. A future worktree @@ -91,14 +202,21 @@ The installers publish a complete file without overwriting an existing path. They never overwrite different content or follow a target symlink. A retry can finish a matching partial skill bundle after an interruption. The wizard does not change global Git configuration or install hooks. Existing repository hooks -still run during capture. +run during a non-dry capture. + +Copied pre-commit and post-commit hooks receive +`NICOS_PREFLIGHT_READ_ONLY=1` with the private candidate index. Compatible +hooks must inspect only that candidate and must not apply repairs to the source +checkout. This value is a cooperative hook contract, not a sandbox. Repository +hooks remain trusted code and can still change files or use the network. The wizard first validates and bootstraps the coordination domain. It then writes a durable initialization intent before it changes a worktree, lane, lease, profile, binary, or skill. Each completed step is idempotent. If setup stops, the error includes the intent path, completed steps, and an exact resume command. The command pins the absolute repository and worktree paths and the -resolved base commit ID. +resolved base commit ID. If a retry starts inside the created linked worktree, +`wip` resolves the primary checkout and keeps the same immutable setup. An exact retry repeats the full canonical path claim. This action repairs an interruption between lease publication and the lane back-reference. @@ -111,7 +229,8 @@ Use non-interactive setup for an agent: ```text wip --json --repo-dir /repo init \ - --mode shared \ + --mode worktree \ + --create-worktree /worktrees/parser-errors \ --lane parser-errors \ --agent codex \ --session session-42 \ @@ -136,7 +255,31 @@ The command uses `git worktree add --detach`. It refuses to replace an existing directory. If an existing directory contains a matching linked worktree at the requested base, the command reuses it. -## Capture work +The success output reports the linked worktree. Continue the workflow in that +checkout. `wip env` and all other lane commands reject a different checkout +with `WORKTREE_MISMATCH` before they renew a lease. + +## Configuration + +`wip` has no repository configuration file and no background service. The +`wip init` command records the selected lane, worktree, owner, and path leases +below the repository's common Git directory. Linked worktrees therefore share +one coordination domain. + +Use `--repo-dir` to select a repository without changing directories. Use +`--json` when a program needs typed results. `wip env` exports `WIP_LANE`, +`WIP_AGENT`, and `WIP_SESSION` for later commands. An explicit +`GIT_INDEX_FILE` selects the caller index for `staged_index` source mode. Other +inherited repository-routing variables do not override the selected repository. + +Commit plans hold per-group verification commands and optional timeouts. The +default verification and hook timeout is two minutes, and the maximum is 24 +hours. Keep secrets and machine-specific paths out of plan files and commit +messages. + +## Usage + +### Capture work Load the lane identity in each agent shell: @@ -144,48 +287,160 @@ Load the lane identity in each agent shell: eval "$(wip env --lane parser-errors)" ``` -Stage only the paths that the agent owns. Other staged paths can remain in the -same index. +Run this command from the checkout recorded for the lane. A worktree-bound +lane returns `WORKTREE_MISMATCH` from another checkout and does not renew its +lease. + +In a dedicated worktree, select `worktree_snapshot`. This source includes exact +tracked changes in the selected scopes. It does not stage those changes: + +```text +wip --json status +wip --json plan \ + --source worktree_snapshot \ + --untracked forbid \ + --path internal/parser \ + --path docs/parser.md \ + --out plan.json +``` + +The `forbid` policy stops when an untracked path exists in a selected scope. +Use `--untracked include` only after you review every selected untracked path. + +Use `staged_index` for a controlled shared-checkout exception. Stage only the +owned paths. Other staged paths can remain in the caller index: ```text git add -- internal/parser docs/parser.md -wip plan -wip commit +wip --json plan \ + --source staged_index \ + --untracked not_applicable \ + --path internal/parser \ + --path docs/parser.md \ + --out plan.json ``` -`wip plan` is read-only. It groups paths at component boundaries and suggests -one Conventional Commit prefix per group. The type is concrete only for clear -documentation, dependency, CI, and test-only groups. Review semantic intent and -dependency closure before you write the final plan. +`wip status` is the operational read for an agent. It reports: + +- leased entries that are capture candidates. +- captured entries that remain staged. +- foreign staged entries outside the lane. +- active claims with no staged or pending entry. +- lease time, ref health, policy, and latest intent state. + +Status describes the caller index. It does not select or authorize a +`worktree_snapshot` source. + +The command renews active leases after it validates the lane identity. Use +`wip status --observe` when a pure read is required. + +`wip plan` groups the selected source paths at component boundaries. It writes +one draft with all capture bindings and empty message fields. The command +creates `plan.json` without replacing an existing file. -The planner compares the active source index with the lane's current commit. -It omits staged paths that the lane already captured. +The planner compares the selected source with the lane's current commit. It +omits paths that the lane already captured. -Interactive capture uses the same proposals and asks for one Conventional -Commit message per group. No ref moves until all gates pass. +Use `wip plan --observe` to preview the draft without lease renewal or an +output file. The command rejects `--observe` with `--out`. It does not change +the Git common directory, the checkout, or the caller index. -Automation must supply a split plan or explicitly opt out: +Review every group for intent and dependency closure. Add one message to each +group. Then change the top-level `state` from `draft` to `reviewed`. ```json -[ - { - "message": "fix(parser): preserve source error locations", - "files": ["internal/parser"], - "verify": [ - {"argv": ["go", "test", "./internal/parser"], "timeout_ms": 120000} - ] +{ + "schema_version": "3.0.0", + "state": "reviewed", + "lane": "parser-errors", + "agent": "codex", + "session": "parser-errors-review", + "target_ref": "refs/heads/wip/codex/parser-errors", + "lane_tip": "", + "source_head": "", + "source_mode": "worktree_snapshot", + "untracked_policy": "forbid", + "source_digest": "sha256:", + "source_scopes": ["docs/parser.md", "internal/parser"], + "lease_digest": "sha256:", + "message_policy": { + "id": "conventional-v1", + "version": "1.0.0", + "digest": "sha256:" }, - { - "message": "docs(parser): explain source error locations", - "files": ["docs/parser.md"] - } -] + "source_paths": ["docs/parser.md", "internal/parser/errors.go"], + "groups": [ + { + "key": "internal/parser", + "suggested_scope": "parser", + "suggested_prefix": "(parser): ", + "rationale": "nearest component boundary; review intent and dependency closure", + "message": "fix(parser): preserve source error locations", + "files": ["internal/parser/errors.go"], + "verify": [ + { + "argv": ["go", "test", "."], + "directory": "internal/parser", + "materialize": ["go.mod", "go.sum"], + "timeout_ms": 120000 + } + ] + }, + { + "key": "docs/parser", + "suggested_scope": "parser", + "suggested_prefix": "(parser): ", + "rationale": "nearest component boundary; review intent and dependency closure", + "message": "docs(parser): explain source error locations", + "files": ["docs/parser.md"] + } + ], + "instruction": "Review every path group, add a non-empty message to each group, then change state from draft to reviewed. Capture rejects stale bindings and draft plans." +} ``` ```text -wip commit --plan plan.json +wip --json capture --plan plan.json ``` +`wip capture` recalculates the lane, source, path, lease, and policy bindings +before hooks run. It rejects a draft or stale plan. + +A verify command's `directory` implicitly materializes that candidate subtree. +The optional `materialize` array adds reviewed repository-relative files or +subtrees, such as module metadata. A root command with neither field requests +the complete candidate tree. Before it creates a scratch checkout, `wip` +rejects a request above 16,384 entries or 512 MiB. Materialized dependencies +are inputs to verification; they do not become captured paths. + +The result contains the capture receipt and a typed handoff. The handoff is +capture-only evidence. It does not authorize landing, merging, or pushing. + +Use `wip capture --final --plan plan.json` to release the lane after handoff +validation. The command holds the lane lock from validation through release. +The lane ref and commits remain. + +The version 3 plan schema is [docs/PLAN.schema.json](docs/PLAN.schema.json). +The operational status and version 2 cumulative handoff schemas are +[docs/STATUS.schema.json](docs/STATUS.schema.json) and +[docs/HANDOFF.schema.json](docs/HANDOFF.schema.json). +The test suite validates real command data against all four schemas and checks +that strict schemas reject invalid data. + +`wip commit` remains a compatibility and interactive command. It accepts the +reviewed version 3 plan or the legacy plan array. `wip capture` accepts only +version 3. + +`wip commit --dry-run` is a no-exec preview. It snapshots repository hook bytes +and validates the source and candidate tree structure. It does not execute +repository hooks or verification commands. It does not renew leases, create +commits, write an intent, or move a ref. + +The dry-run result uses schema `3.0.0`. It reports `gate_outcome: "skipped"` +and an `execution` object. Each execution count reports planned, executed, and +skipped operations. Every executed count is zero. A successful dry-run is not +proof that the configured gates pass. + When one commit is intentional, use this explicit command: ```text @@ -194,21 +449,43 @@ wip commit --single \ --path internal/parser ``` -The command rejects vague subjects, unsupported commit types, duplicate -messages, subjects longer than 72 characters, and `wip:` unless you pass -`--allow-wip`. +The default `conventional-v1` policy rejects vague subjects, unsupported types, +duplicate messages, long subjects, and unauthorized `wip:` prefixes. + +Select `safety-only-v1` in `.wip-commit.json` when repository policy permits +free-form messages: + +```json +{ + "schema_version": "1.0.0", + "message_policy": "safety-only-v1" +} +``` + +The capture kernel still rejects unsafe bytes, empty subjects, and oversized +messages. Policy checks finish before hooks and verification commands run. ## Continue and finish -Leases last 15 minutes while the agent edits. Renew them between captures: +Leases last 15 minutes without authenticated lane use. `status`, `env`, +`claim`, `plan`, `commit`, `capture`, and `handoff` renew the complete active +set. A handoff for a released lane stays read-only. +It locks the existing lane lock file without creating or rewriting lock +metadata. + +For a pure read, use `--observe`, `--observe=true`, or `-observe` with `status`, +`env`, and `plan`. `--observe=false` keeps normal renewal behavior. An observed +plan cannot write an output file. + +Manual renewal remains available: ```text wip renew ``` -`wip commit` snapshots and renews the lane's complete active lease set before -capture. It renews that same set in the background. The final publication check -renews and compares the set again. +A non-dry `wip commit` snapshots and renews the complete active lease set before +capture. It renews that set in the background. The final publication check +renews and compares the set again. `wip commit --dry-run` does not renew leases. Add another claim with: @@ -222,6 +499,21 @@ Inspect the lane with: wip status ``` +Use `wip handoff` to validate and print the complete base-to-tip capture chain: + +```text +wip --json handoff --lane parser-errors +``` + +The version 2 handoff contains every continuous completed capture segment from +the lane base to its current tip. It binds the exact result with +`handoff_digest`. It sets `landing_authorized` to `false`. + +The handoff omits agent IDs, session IDs, absolute worktree paths, remote URLs, +and file contents. Intent-chain validation, active-lease renewal, and status +construction use one lane lock. A supplied `--plan-id` and `--plan-digest` must +name the tip segment. They cannot select an older single segment. + When the task is complete, release the coordination state: ```text @@ -231,6 +523,45 @@ wip release Release and abort both preserve the local agent ref. Neither command deletes commits, lands a branch, pushes a remote, or merges work. +## Migrate one coordination domain + +Use the explicit migration only during a repository writer freeze. The preview +is byte-for-byte read-only: + +```text +wip --json migrate --preview +``` + +Save the exact `data.plan` object as `migration-plan.json`. Review its producer, +source manifests, destination manifests, ref expectations, dispositions, +conflicts, and `plan_digest`. + +Apply only the same plan with the same source-matched executable: + +```text +wip --json migrate \ + --apply \ + --plan migration-plan.json \ + --plan-digest sha256: \ + --yes +``` + +The migration imports valid capture records into `/wip/v1`. +It copies review records into `/wip/review/v1`. The review store +includes immutable `handoffs/` and `plans/` directories. It moves the legacy +store into a sealed, read-only archive after the new records are durable. + +An active legacy lane is stale when it has no leases, or when all its exact +active leases have expired. The migration gives the lane and its leases an +`archive-only` disposition. It preserves the lane ref and binds its exact SHA +in the plan. A ref that advanced only from the stored cursor is also preserved +and bound. A missing ref, a diverged ref, or a moved ref with a live lease +blocks the migration. + +Use `--resume` with the same plan after an interruption. Use `--rollback` only +before the legacy source moves. The command never dual-writes both domains and +never grants landing authority. + ## Inspect and archive state Run a read-only state audit: @@ -249,15 +580,21 @@ Preview old released records: wip archive --older-than 720h ``` -The preview returns an exact cutoff and plan digest. Reuse both values: +The preview returns an exact cutoff and plan digest. Reuse both values. If the +preview used one or more `--lane` filters, repeat the same filters on apply: ```text wip archive \ + --lane '' \ --cutoff '' \ --plan-digest '' \ --apply --yes ``` +JSON previews also return `lane_filters` as the canonical sorted list to +replay. Omitting a preview filter changes the eligible set and fails closed +with `ARCHIVE_PLAN_MOVED`. + The store compares every reviewed candidate again while it holds the archive, lane, and lease-registry locks. It then moves records into a recoverable archive batch. The receipt binds each lane record and released lease to its candidate. @@ -284,23 +621,28 @@ Restore writes a durable `restoring` state before it moves the first record. If restore stops, run the same restore command again. `wip doctor` reports the receipt until recovery completes. +A `restored` receipt remains as history. If you archive the same records again, +`wip doctor` requires each non-live record to have exactly one validated newer +archive owner. A missing, duplicated, or unbound record fails closed. Restore +the current complete receipt to make rearchived records live. Repeating an +older restored receipt only confirms that its earlier restore completed. + ## Important index behavior -A successful capture leaves the source `HEAD`, worktree, and complete Git index -unchanged. Captured entries therefore remain staged relative to the source -branch. This is deliberate: `wip` cannot safely clear selected entries while an -uncoordinated process can update the shared index. +A successful capture leaves the source `HEAD`, worktree, and complete caller +index unchanged. A `staged_index` capture therefore leaves its entries staged. +A `worktree_snapshot` capture does not stage or unstage any path. `wip` ignores inherited repository-local Git variables that can redirect or reinterpret the repository, common directory, worktree, namespace, refs, -shallow boundary, configuration, or object storage. The canonical repository -selected by `--repo-dir` or the current directory wins. It honors an inherited -`GIT_INDEX_FILE` as the caller's active source index. Capture hooks receive the -private candidate index instead. +shallow boundary, configuration, object storage, or pathspec behavior. The +canonical repository selected by `--repo-dir` or the current directory wins. +It honors an inherited `GIT_INDEX_FILE` as the caller index for `staged_index` +source mode. Capture hooks receive the private candidate index instead. -You can modify and stage a later version of the same leased path. The next -capture compares that staged version with the current lane commit. Do not run a -broad reset, stash, or clean command to hide the staged state. +You can modify a later version of the same leased path. The next capture +compares the selected source with the current lane commit. Do not run a broad +reset, stash, or clean command to hide source state. ## Recover an interrupted capture @@ -317,6 +659,32 @@ Reconciliation compares the target ref, every parent, tree, message, changed pat allowed scope, and final tree before it updates lane metadata. Exact retries are idempotent. +## Troubleshooting + +Start with structured state evidence: + +```text +wip --json doctor +wip --json status +``` + +Do not stash, reset, clean, delete state, or force-update a lane ref during +recovery. Common actions are: + +- `LANE_NOT_ACTIVE`: run `wip init`, or load the exact lane identity. +- `PATH_LEASE_CONFLICT`: select disjoint paths or wait for the owner to release + its lease. +- `SOURCE_MOVED`: inspect the selected source paths and create a new reviewed + plan. +- `LOCK_TIMEOUT`: the default zero wait fails fast. Inspect active lanes and + retry later, or set a bounded `--lock-wait` outside an agent turn. +- `ref_updated: true`: preserve `plan_id` and `plan_digest`, then run the exact + `wip reconcile` command. + +[The error and recovery guide](docs/ERRORS.md) lists every typed code and its +required action. [SUPPORT.md](SUPPORT.md) explains what evidence is safe to +include in a report. + ## Safety scope `wip` protects coordination between cooperating local processes. It does not @@ -333,6 +701,12 @@ A `verify` command does not inherit the active WIP lane identity or source `GIT_INDEX_FILE`. It receives only `WIP_CANDIDATE_TREE` from `wip`. This rule prevents a nested command from selecting the host capture lane by accident. +A copied hook receives one canonical value for `WIP_CAPTURE=1`, +`WIP_SOURCE_READ_ONLY=1`, `WIP_HOOK_PHASE`, and `WIP_TARGET_REF`. +Post-commit hooks also receive `WIP_COMMIT_OBJECT`. Caller values for these +names are removed before the hook starts. Repositories can use the read-only +marker to prevent a capture hook from changing source-side generated files. + See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the transaction model, [docs/ERRORS.md](docs/ERRORS.md) for recovery actions, and [docs/STATE-COMPATIBILITY.md](docs/STATE-COMPATIBILITY.md) for upgrade and @@ -343,21 +717,25 @@ evidence tracker are in [docs/OSS-PUBLIC-BETA.md](docs/OSS-PUBLIC-BETA.md). The beta remains capture-only. [KEP-0001](docs/KEP-0001-capture-to-landing-boundary.md) -defines the safety boundary for a possible future landing command without -authorizing its implementation. Non-authors can use the redacted +defines the adapter boundary for a separate landing authority. It does not +authorize a standalone landing implementation. Non-authors can use the redacted [beta exercise](docs/BETA-EXERCISE.md) to produce independent evidence. Repository owners can use the human-gated [publication handoff](docs/PUBLICATION-HANDOFF.md) and -[hosted setup runbook](docs/HOSTED-SETUP.md). These procedures do not authorize -a push or release tag. +[hosted setup runbook](docs/HOSTED-SETUP.md). Use the +[correction receipt](docs/PUBLICATION-CORRECTION.md) after a hosted candidate +changes. These procedures do not authorize a push or release tag. Project authority and succession are in [GOVERNANCE.md](GOVERNANCE.md). Current support and safe incident-reporting guidance are in [SUPPORT.md](SUPPORT.md). Security reports use [SECURITY.md](SECURITY.md). +Community participation follows [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). The [open source practice guide](docs/OSS-PRACTICE-GUIDE.md) maps official guidance to project rules and records when maintainers must review it again. Local self-hosting receipts and safe-failure results are in [docs/DOGFOOD.md](docs/DOGFOOD.md). +The current public-source, hosted-control, and release boundary is in +[docs/HOSTED-STATUS-2026-08-18.md](docs/HOSTED-STATUS-2026-08-18.md). ## License diff --git a/SECURITY.md b/SECURITY.md index 7132d80..9d90685 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,13 +2,15 @@ ## Supported versions -`0.1.0-beta.1` is a beta. Security fixes apply to the newest beta only. +No release tag exists. `v0.2.0-beta.1` is the planned beta. After publication, +security fixes apply to the newest published beta only. ## Report a vulnerability Do not open a public issue for an unpatched vulnerability. Use the repository host's private security-advisory channel. Include the operating system, Git and -`wip` versions, the smallest reproduction, and whether a ref or source index -moved. Do not include tokens, private repository content, or full local paths. +`wip` versions, the smallest reproduction, the source mode, and whether a ref +or source digest moved. Do not include tokens, private repository content, or +full local paths. The threat boundary is in [THREAT-MODEL.md](THREAT-MODEL.md). diff --git a/SUPPORT.md b/SUPPORT.md index 14e6813..712407a 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -19,9 +19,10 @@ credentials in a report. For a security issue, follow [SECURITY.md](SECURITY.md). Do not report a suspected vulnerability in a public issue. -A confidential conduct-reporting channel is not configured in this local -checkout. The public-beta plan requires the owner to configure that channel and -approve a Code of Conduct before the project solicits public contributions. +Community participation follows [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). Use +the repository host's private reporting form on the Security tab for a +confidential conduct report. Start the title with `Code of Conduct:`. Do not +put a conduct report in a public issue. ## Report a capture problem diff --git a/THREAT-MODEL.md b/THREAT-MODEL.md index 5cb52a5..173a591 100644 --- a/THREAT-MODEL.md +++ b/THREAT-MODEL.md @@ -4,35 +4,37 @@ `wip` protects these local assets during capture: -- the source checkout's `HEAD`; -- all entries in the source Git index; -- staged content outside the selected paths; -- each lane ref and lane cursor; -- path-lease ownership; -- the order, tree, message, and scope of every planned commit; +- the source checkout's `HEAD`. +- all entries in the caller Git index. +- worktree and staged content outside the selected source paths. +- each lane ref and lane cursor. +- path-lease ownership. +- the order, tree, message, and scope of every planned commit. +- the reviewed source mode, digest, paths, lane, lease, and message-policy + bindings. - the recovery record for an applied ref update. -The primary failure to prevent is a successful-looking capture that includes -another agent's staged work, publishes only part of a split plan, or loses the -commit after a process stops. +The primary failure is a successful-looking capture that includes another +agent's work. Other primary failures publish only part of a split plan or lose +the commit after a process stops. ## Trust boundaries The following components are trusted: -- Git and the local filesystem; -- cooperating processes that obey path leases; -- repository hooks; -- commands listed in a plan's `verify` array; +- Git and the local filesystem. +- cooperating processes that obey path leases. +- repository hooks. +- commands listed in a plan's `verify` array. - the operating-system user who owns the repository. The following components are not treated as trusted inputs: -- concurrent lane commands; -- the current shared index outside the selected paths; -- persisted lane, lease, profile, and intent files; -- plan JSON; -- hook paths that can change during capture; +- concurrent lane commands. +- the current caller index and worktree outside the selected paths. +- persisted lane, lease, profile, and intent files. +- plan JSON. +- hook paths that can change during capture. - verify working directories that can contain symlinks. `wip` is not a security boundary against a malicious process with the same user @@ -40,7 +42,7 @@ account, an administrator, compromised Git, or compromised kernel code. ## Controls -### Concurrent staged work +### Concurrent source work Path claims use portable Unicode case folding, NFC normalization, and component boundaries. A repository-wide lease lock serializes claim decisions. Active @@ -54,16 +56,26 @@ the set during long gates. The publication callback renews the same set while it holds the lease-registry lock. Each refresh also audits all active lease records and stops if persisted state contains a cross-lane overlap. +Authenticated status, environment, claim, and plan commands renew the complete +active set after identity validation. Pure `--observe` status, environment, +and plan reads do not renew it. + Normal renewal and release also inspect the complete lease registry before a write. Release verifies lane ownership and both directions of every lease reference. It permits valid partial release so an interrupted release can finish. -Capture reads exact stage-zero index entries for the planned paths into a -private index. It does not use `git add` against the source worktree. A final -digest check detects a selected staged entry that changed while the plan ran. -Changes to unrelated staged paths do not stop a disjoint capture and cannot -enter its private tree. +For `staged_index`, capture reads exact stage-zero caller-index entries for the +planned paths. It copies them into a private index. Unrelated staged paths +cannot enter the private tree. + +For `worktree_snapshot`, capture builds a private source index from the lane +tip. It adds only tracked changes and reviewed untracked paths in the selected +scopes. It never runs `git add` against the caller index. + +A final source-digest check detects a selected source entry that changed while +the plan ran. Changes outside the reviewed scopes do not stop a disjoint +capture and cannot enter its private tree. ### Partial split publication @@ -72,18 +84,50 @@ Every group builds on the preceding private tree. Pre-commit hooks, `git diff created off-ref. One `git update-ref ` compare-and-swap publishes the complete chain. +### Reviewed-plan substitution + +The version 3 plan binds the lane ref, lane tip, and source `HEAD`. It also binds +the source mode, untracked policy, source scopes, source paths, source digest, +active lease digest, and message-policy receipt. + +`wip capture` recalculates every binding before it opens hooks. A changed input +returns `STALE_PLAN` and does not enter the capture transaction. The kernel +also compares its initial private-source snapshot with the reviewed digest. +This check closes the interval between command validation and kernel setup. + +The capture intent stores the canonical reviewed-plan digest. The intent digest +covers that digest and the policy receipt. + +### Message policy + +The capture kernel validates message bytes, size, and subject presence. Named +repository policy validates message style before hooks or verification run. + +The lane profile binds the resolved policy. A plan with another policy fails +before capture. + ### Ref and metadata races Each lane has an operating-system file lock. The ref update also requires the -expected old object ID. The source `HEAD`, selected index digest, hook snapshots, -lane cursor, lane identity, worktree binding, and active lease set are checked -again at the publication boundary. +expected old object ID. The source `HEAD`, selected source digest, hook +snapshots, lane cursor, lane identity, worktree binding, and active lease set +are checked again at the publication boundary. + +Handoff validation and final release use the same lane lock. Another lane +transaction cannot change the cursor, intent selection, or lease links between +the validated handoff and release. ### Crash recovery Lane creation writes a `creating` manifest before it creates the ref. An exact retry can finish either side of that boundary. +Initialization publishes its intent before setup side effects, then holds the +per-intent transaction lock until every side effect is journaled or the command +fails. Exact retries and `init-abort` use the same lock. An abort therefore +cannot remove the recovery intent between lane creation and the corresponding +journal update. + A capture writes an immutable `prepared` intent before it updates the ref. It then records `applied` after the ref compare-and-swap and `complete` after lane metadata advances. Intent files use mode `0600`, bounded strict JSON, a digest @@ -96,12 +140,39 @@ success. This receipt permits exact reconciliation after the ref moved. `wip reconcile` checks all immutable Git evidence before it advances metadata. +### Capture handoff + +The handoff command accepts only one unique, complete intent chain from the lane +base to its tip. Every intent and Git object must pass receipt validation. A +gap, ambiguity, branch, cycle, moved ref, or invalid object fails closed. + +The version 2 handoff binds the complete chain with `handoff_digest`. It is +review-eligible only when every segment has an exact reviewed-plan, +message-policy, and version 3 private-source binding. + +The command holds the lane lock while it validates the chain, renews an active +lease, and builds status. A failed renewal does not emit a successful handoff. + +A released-lane handoff opens and locks the existing regular lock file without +creating directories or rewriting owner metadata. A missing, replaced, or +non-regular lock file fails closed. + +The handoff omits agent IDs, session IDs, absolute paths, remote URLs, and file +contents. It states that the receipt does not authorize landing. A separate +review authority must bind any landing decision to the full handoff digest. + ### Hooks -`wip` opens each pre-commit and post-commit hook, compares the open file with the -path, requires a regular non-symlink file, limits it to 4 MiB, and copies it to a -private mode-`0700` path. It validates the original path again before the ref -update. The copied hook runs with the private index. +`wip` opens each pre-commit and post-commit hook and compares the open file with +the path. It requires a regular non-symlink file and limits it to 4 MiB. It then +copies the hook to a private mode-`0700` path. It validates the original path +again before the ref update. The copied hook runs with the private index and a +forced `NICOS_PREFLIGHT_READ_ONLY=1` value. It also receives canonical capture, +phase, target-ref, and source-read-only markers. Caller values for those names +are removed first. A post-commit hook also receives the exact commit object. +Compatible hook wrappers use the read-only markers to inspect the candidate +without applying repairs to the source checkout. These values are a cooperative +contract. They do not restrict arbitrary hook code. On Windows, Git 2.36 or newer runs the private hook so that Git for Windows can apply its normal interpreter rules. @@ -109,10 +180,15 @@ apply its normal interpreter rules. ### Verify commands Plan commands use typed argument arrays. They do not pass through a shell. Each -command runs in a temporary checkout of the candidate private index. A command -directory cannot be absolute, escape with `..`, or follow a symlink outside the -candidate tree. Time, argument, output, command-count, group-count, path-count, -and plan-size limits are enforced. +command runs in a temporary checkout of the candidate private index. Its +directory is an implicit materialization scope. A reviewed `materialize` array +can add repository-relative dependencies. A root command with no explicit +scope requests the full tree. `wip` enumerates the immutable candidate tree and +enforces the 16,384-entry and 512 MiB limits before it creates the checkout. It +passes selected paths to Git as NUL-delimited input. A command directory cannot +be absolute, escape with `..`, or follow a symlink outside the candidate tree. +Time, argument, output, scope-count, command-count, group-count, path-count, +tree-entry, tree-byte, and plan-size limits are enforced. On Unix, a timed-out command kills its process group. Other platforms use Go's bounded process wait behavior. @@ -123,10 +199,10 @@ State readers require bounded regular non-symlink files, reject path replacement during reads, reject unknown JSON fields, and validate stored identities and canonical paths. A first write creates and synchronizes a complete temporary file, then uses a same-filesystem hard link to publish it without overwrite. -Atomic replacement is used for state transitions. Windows uses `MoveFileEx` -with replace and write-through flags. Record writes stage temporary files in the -store's `locks` directory, so an interrupted writer cannot add a foreign entry -to a lane, lease, profile, intent, or archive batch directory. +State transitions use atomic replacement. Windows uses `MoveFileEx` with replace +and write-through flags. Record writes stage temporary files in the store's +`locks` directory. Thus, an interrupted writer cannot add a foreign entry to a +lane, lease, profile, intent, or archive batch directory. Each durable writer checks the final encoded size against its reader limit. The archive writer performs this check before it creates a new batch. Thus, a @@ -136,7 +212,7 @@ prevents a valid initial record from blocking a later completion or release. New lease records use cryptographically random identifiers and no-overwrite publication. Normal lane and lease scans reject unexpected record-directory -entries. A partially released lane cannot claim, renew, or capture paths; only +entries. A partially released lane cannot claim, renew, or capture paths. Only the idempotent release operation can finish that state transition. State-directory creation uses a filesystem root handle. The handle confines @@ -151,11 +227,11 @@ Profiles must match the authoritative lane manifest. Shell output uses explicit POSIX or PowerShell quoting. An invalid lane ID fails before path construction. Git commands remove inherited repository-local environment variables except -the active source index. A caller cannot use routing, configuration, namespace, -replacement, shallow-file, or object-storage variables to make `--repo-dir` -inspect one checkout and write objects or refs through another. The caller's -`GIT_INDEX_FILE` remains the active source index. Prepared hooks receive only -the private candidate index for their Git operations. +the caller index selector for `staged_index`. A caller cannot use routing, +configuration, namespace, replacement, shallow-file, or object-storage +variables to redirect `--repo-dir`. Git pathspec mode variables are also +removed, and verifier scopes use literal top-level pathspecs. Prepared hooks +receive only the private candidate index for their Git operations. The public and legacy implementations use one domain lock. Public state and legacy `ndev-wip` state cannot start beside each other. Read-only legacy checks @@ -163,6 +239,18 @@ do not create a legacy state directory. Invalid legacy actions and queue previews also use inspection only. Only explicit legacy lane creation can claim the legacy domain. +Coordination migration requires an exact producer identity, plan digest, +prestate, poststate, and ref set. Preview is byte-for-byte read-only. Apply uses +one writer fence and one journal. It publishes canonical records before it +moves and seals the complete legacy root. It never dual-writes both roots and +never grants landing authority. + +The completion receipt is immutable cutover evidence. It is not a lock on the +future live store. Completed migration status reports later live-store +movement, skips transient private-index contents, and keeps the static +migration envelope exact. Current record health remains the responsibility of +the bounded doctor. + The store rejects unsupported state-directory and record-schema versions. It checks the directory version before it creates local state. This rule prevents an older binary from silently coordinating through a separate state version. @@ -197,11 +285,10 @@ its first move and can continue after an interruption. ## Residual risks - A Git command that does not use `wip` can ignore path leases. The final check - detects selected-index movement before publication, but no transaction can - atomically lock every external Git implementation. A write in the small gap - after the final read can make the receipt describe the earlier staged - snapshot. It cannot make `wip` rewrite the source index or include an - unselected path. + detects selected-source movement before publication. No transaction can lock + every external Git implementation. A later write can make the receipt + describe the earlier snapshot. It cannot make `wip` rewrite the caller index + or include an unselected path. - Hooks and verify commands are trusted code. They can change the worktree, start background work, access credentials, or use the network. - A post-commit hook runs after the ref update. Its failure is reported as a @@ -219,6 +306,8 @@ its first move and can continue after an interruption. - Paths that are not valid UTF-8 are not supported by plans. - Leases use the host wall clock. Large clock changes can shorten or extend a lease. +- A handoff proves local capture integrity. It does not prove review approval, + branch landing, public release, deployment, adoption, or revenue. - `wip` does not land, merge, push, delete, reset, stash, or clean work. Those operations need a separate reviewed policy. diff --git a/assets/brand/wip-commit.svg b/assets/brand/wip-commit.svg new file mode 100644 index 0000000..0b52f0e --- /dev/null +++ b/assets/brand/wip-commit.svg @@ -0,0 +1 @@ +wip-commit original application mark \ No newline at end of file diff --git a/cmd/wip/agent_facing_test.go b/cmd/wip/agent_facing_test.go new file mode 100644 index 0000000..a485667 --- /dev/null +++ b/cmd/wip/agent_facing_test.go @@ -0,0 +1,928 @@ +package main + +import ( + "bytes" + "context" + "encoding/json" + "os" + "path/filepath" + "reflect" + "runtime" + "strings" + "testing" + "time" + + "github.com/nstranquist/wip-commit/internal/engine" + "github.com/nstranquist/wip-commit/internal/fail" + "github.com/nstranquist/wip-commit/internal/gitx" + "github.com/nstranquist/wip-commit/internal/store" +) + +func TestLaneJSONAlwaysSerializesLeaseExpiry(t *testing.T) { + for name, value := range map[string]any{ + "status": operationalStatus{}, + "context": laneContext{}, + } { + body, err := json.Marshal(value) + if err != nil { + t.Fatal(err) + } + if !strings.Contains(string(body), `"lease_expires_at":null`) { + t.Fatalf("%s omitted lease expiry: %s", name, body) + } + } +} + +func TestHandoffReportsNotReadyForUnmovedLane(t *testing.T) { + directory := cliTestRepo(t) + initializeCLI(t, directory, "empty-handoff", "core.txt") + + result := runCLI(t, []string{"--json", "--repo-dir", directory, "handoff", "--lane", "empty-handoff"}, "") + if result.code == 0 || result.envelope.Error == nil || result.envelope.Error.Code != "HANDOFF_NOT_READY" { + t.Fatalf("empty handoff = %#v stderr=%s", result.envelope, result.stderr) + } +} + +func TestReviewedPlanCaptureProducesBoundPrivateHandoff(t *testing.T) { + directory := cliTestRepo(t) + writeCLI(t, directory, "core.txt", "new core\n") + writeCLI(t, directory, "docs.txt", "new docs\n") + cliGit(t, directory, "add", "core.txt", "docs.txt") + head := cliGit(t, directory, "rev-parse", "HEAD") + index := cliGitRaw(t, directory, "ls-files", "-s", "-z") + initializeCLI(t, directory, "guided-capture", "core.txt", "docs.txt") + + planPath := filepath.Join(t.TempDir(), "capture-plan.json") + drafted := runCLI(t, []string{"--json", "--repo-dir", directory, "plan", "--lane", "guided-capture", "--out", planPath}, "") + if drafted.code != 0 || !drafted.envelope.OK { + t.Fatalf("draft plan: %#v stderr=%s", drafted.envelope, drafted.stderr) + } + var plan planProposal + decodeData(t, drafted.envelope.Data, &plan) + if plan.State != "draft" || plan.SchemaVersion != reviewPlanSchemaVersion || len(plan.Groups) != 2 { + t.Fatalf("draft = %#v", plan) + } + plan.State = "reviewed" + for index := range plan.Groups { + if strings.Contains(plan.Groups[index].SuggestedScope, "core") { + plan.Groups[index].Message = "fix(core): preserve reviewed capture" + } else { + plan.Groups[index].Message = "docs(guide): document reviewed capture" + } + } + body, err := json.MarshalIndent(plan, "", " ") + if err != nil { + t.Fatal(err) + } + if err := os.WriteFile(planPath, append(body, '\n'), 0o600); err != nil { + t.Fatal(err) + } + reviewDigest, err := reviewPlanDigest(plan) + if err != nil { + t.Fatal(err) + } + + captured := runCLI(t, []string{"--json", "--repo-dir", directory, "capture", "--lane", "guided-capture", "--plan", planPath, "--review-plan-digest", reviewDigest}, "") + if captured.code != 0 || !captured.envelope.OK { + t.Fatalf("capture: %#v stderr=%s", captured.envelope, captured.stderr) + } + var result guidedCaptureResult + decodeData(t, captured.envelope.Data, &result) + if len(result.Handoff.Segments) != 1 { + t.Fatalf("handoff segments = %#v", result.Handoff.Segments) + } + segment := result.Handoff.Segments[0] + if !result.Handoff.CaptureOnly || result.Handoff.LandingAuthorized || !result.Handoff.ReviewEligible || result.Handoff.HandoffDigest == "" || !segment.MessagePolicyBound || segment.ReviewedPlanDigest != reviewDigest || segment.IntentState != "complete" { + t.Fatalf("handoff = %#v", result.Handoff) + } + if result.Handoff.LaneTip != result.Capture.FinalCommit || result.Handoff.FinalTree != result.Capture.FinalTree || len(segment.Commits) != 2 { + t.Fatalf("capture/handoff mismatch = %#v", result) + } + if result.Capture.SourceDigest != plan.SourceDigest { + t.Fatalf("kernel source digest = %q, reviewed digest = %q", result.Capture.SourceDigest, plan.SourceDigest) + } + encoded, _ := json.Marshal(result.Handoff) + for _, forbidden := range []string{"\"agent\"", "\"session\"", "\"worktree\"", "remote", "new core"} { + if strings.Contains(string(encoded), forbidden) { + t.Fatalf("handoff leaked %q: %s", forbidden, encoded) + } + } + if got := cliGit(t, directory, "rev-parse", "HEAD"); got != head { + t.Fatalf("source HEAD moved: %s", got) + } + if got := cliGitRaw(t, directory, "ls-files", "-s", "-z"); got != index { + t.Fatal("source index changed") + } + + printed := runCLI(t, []string{"--json", "--repo-dir", directory, "handoff", "--lane", "guided-capture"}, "") + if printed.code != 0 || !printed.envelope.OK { + t.Fatalf("handoff command: %#v stderr=%s", printed.envelope, printed.stderr) + } + if printed.envelope.Context == nil || !printed.envelope.Context.LeaseRenewed || printed.envelope.Context.LeaseExpiresAt == nil { + t.Fatalf("active handoff did not renew the lease: %#v", printed.envelope.Context) + } + var receipt captureHandoff + decodeData(t, printed.envelope.Data, &receipt) + if receipt.HandoffDigest != result.Handoff.HandoffDigest || receipt.TipCaptureIntentDigest != result.Handoff.TipCaptureIntentDigest || receipt.LaneTip != result.Handoff.LaneTip { + t.Fatalf("handoff changed = %#v", receipt) + } +} + +func TestCaptureReviewDigestRejectsSameCountPlanSubstitutionBeforeMutation(t *testing.T) { + if runtime.GOOS == "windows" { + t.Skip("fixture uses a POSIX Git hook; Windows runtime coverage is a hosted gate") + } + directory := cliTestRepo(t) + writeCLI(t, directory, "core.txt", "new core\n") + cliGit(t, directory, "add", "core.txt") + initializeCLI(t, directory, "review-digest", "core.txt") + + planPath := filepath.Join(t.TempDir(), "reviewed-plan.json") + drafted := runCLI(t, []string{"--json", "--repo-dir", directory, "plan", "--lane", "review-digest", "--out", planPath}, "") + if drafted.code != 0 { + t.Fatalf("draft plan = %#v stderr=%s", drafted.envelope, drafted.stderr) + } + var plan planProposal + decodeData(t, drafted.envelope.Data, &plan) + plan.State = "reviewed" + plan.Groups[0].Message = "fix(core): bind the exact reviewed plan" + plan.Groups[0].Verify = []engine.VerifyCommand{{Argv: []string{"git", "--version"}}} + reviewDigest, err := reviewPlanDigest(plan) + if err != nil { + t.Fatal(err) + } + + verifyMarker := filepath.Join(t.TempDir(), "verify-ran") + hookMarker := filepath.Join(t.TempDir(), "hook-ran") + t.Setenv("WIP_CAPTURE_VERIFY_MARKER", verifyMarker) + plan.Groups[0].Verify = []engine.VerifyCommand{{Argv: []string{os.Args[0], "-test.run=^TestCapturePlanDigestVerifyMarkerHelper$", "-test.count=1"}}} + body, err := json.MarshalIndent(plan, "", " ") + if err != nil { + t.Fatal(err) + } + if err := os.WriteFile(planPath, append(body, '\n'), 0o600); err != nil { + t.Fatal(err) + } + + hook := cliGit(t, directory, "rev-parse", "--git-path", "hooks/pre-commit") + if !filepath.IsAbs(hook) { + hook = filepath.Join(directory, hook) + } + if err := os.WriteFile(hook, []byte("#!/bin/sh\n: > "+quoteCommandArg(hookMarker)+"\n"), 0o700); err != nil { + t.Fatal(err) + } + repo, err := gitx.Discover(context.Background(), directory) + if err != nil { + t.Fatal(err) + } + laneStore := inspectCLIStore(t, directory) + statusBefore, err := laneStore.Status("review-digest") + if err != nil { + t.Fatal(err) + } + statePaths := []string{ + filepath.Join(repo.CommonDir, "wip-coordination.lock"), + filepath.Join(laneStore.Root, "locks", "lane-review-digest.lock"), + filepath.Join(laneStore.Root, "locks", "leases.lock"), + filepath.Join(laneStore.Root, "lanes", "review-digest.json"), + } + for _, lease := range statusBefore.Leases { + statePaths = append(statePaths, filepath.Join(laneStore.Root, "leases", lease.ID+".json")) + } + stateBefore := make(map[string][]byte, len(statePaths)) + for _, path := range statePaths { + stateBefore[path], err = os.ReadFile(path) + if err != nil { + t.Fatalf("read preflight state %s: %v", path, err) + } + } + refBefore := cliGit(t, directory, "rev-parse", "refs/heads/wip/agent/review-digest") + indexBefore := cliGitRaw(t, directory, "ls-files", "-s", "-z") + + rejected := runCLI(t, []string{ + "--json", "--repo-dir", directory, "capture", "--lane", "review-digest", "--plan", planPath, + "--review-plan-digest", reviewDigest, + }, "") + if rejected.code == 0 || rejected.envelope.Error == nil || rejected.envelope.Error.Code != "REVIEW_PLAN_DIGEST_MISMATCH" { + t.Fatalf("substituted plan result = %#v stderr=%s", rejected.envelope, rejected.stderr) + } + statusAfter, err := laneStore.Status("review-digest") + if err != nil || !reflect.DeepEqual(statusBefore, statusAfter) { + t.Fatalf("digest refusal changed lane or lease timestamps:\nbefore=%#v\nafter=%#v\nerr=%v", statusBefore, statusAfter, err) + } + for path, before := range stateBefore { + after, readErr := os.ReadFile(path) + if readErr != nil || !bytes.Equal(before, after) { + t.Fatalf("digest refusal changed %s: before=%q after=%q err=%v", path, before, after, readErr) + } + } + for _, marker := range []string{hookMarker, verifyMarker} { + if _, err := os.Lstat(marker); !os.IsNotExist(err) { + t.Fatalf("digest refusal executed marker %s: %v", marker, err) + } + } + if got := cliGit(t, directory, "rev-parse", "refs/heads/wip/agent/review-digest"); got != refBefore { + t.Fatalf("digest refusal moved lane ref: before=%s after=%s", refBefore, got) + } + if got := cliGitRaw(t, directory, "ls-files", "-s", "-z"); got != indexBefore { + t.Fatal("digest refusal changed the caller index") + } +} + +func TestCommitDryRunIsNoExecAndBytePure(t *testing.T) { + if runtime.GOOS == "windows" { + t.Skip("fixture uses POSIX hooks; hosted Windows tests cover the no-exec verify path") + } + directory := cliTestRepo(t) + writeCLI(t, directory, "core.txt", "new core\n") + cliGit(t, directory, "add", "core.txt") + initializeCLI(t, directory, "dry-run-no-exec", "core.txt") + + planPath := filepath.Join(t.TempDir(), "dry-run-plan.json") + drafted := runCLI(t, []string{"--json", "--repo-dir", directory, "plan", "--lane", "dry-run-no-exec", "--out", planPath}, "") + if drafted.code != 0 || !drafted.envelope.OK { + t.Fatalf("draft plan = %#v stderr=%s", drafted.envelope, drafted.stderr) + } + var plan planProposal + decodeData(t, drafted.envelope.Data, &plan) + plan.State = "reviewed" + plan.Groups[0].Message = "fix(core): prove byte-pure no-exec preview" + verifyMarker := filepath.Join(t.TempDir(), "verify-ran") + preHookMarker := filepath.Join(t.TempDir(), "pre-commit-ran") + postHookMarker := filepath.Join(t.TempDir(), "post-commit-ran") + t.Setenv("WIP_CAPTURE_VERIFY_MARKER", verifyMarker) + t.Setenv("WIP_DRY_RUN_PRE_HOOK_MARKER", preHookMarker) + t.Setenv("WIP_DRY_RUN_POST_HOOK_MARKER", postHookMarker) + plan.Groups[0].Verify = []engine.VerifyCommand{{Argv: []string{os.Args[0], "-test.run=^TestCapturePlanDigestVerifyMarkerHelper$", "-test.count=1"}}} + body, err := json.MarshalIndent(plan, "", " ") + if err != nil { + t.Fatal(err) + } + if err := os.WriteFile(planPath, append(body, '\n'), 0o600); err != nil { + t.Fatal(err) + } + reviewDigest, err := reviewPlanDigest(plan) + if err != nil { + t.Fatal(err) + } + + repo, err := gitx.Discover(context.Background(), directory) + if err != nil { + t.Fatal(err) + } + hookBodies := map[string][]byte{ + "pre-commit": []byte("#!/bin/sh\n: > \"$WIP_DRY_RUN_PRE_HOOK_MARKER\"\n"), + "post-commit": []byte("#!/bin/sh\n: > \"$WIP_DRY_RUN_POST_HOOK_MARKER\"\n"), + } + for name, hookBody := range hookBodies { + hook := cliGit(t, directory, "rev-parse", "--git-path", "hooks/"+name) + if !filepath.IsAbs(hook) { + hook = filepath.Join(directory, hook) + } + if err := os.WriteFile(hook, hookBody, 0o700); err != nil { + t.Fatal(err) + } + } + + laneStore := inspectCLIStore(t, directory) + statusBefore, err := laneStore.Status("dry-run-no-exec") + if err != nil { + t.Fatal(err) + } + repositoryBefore := commandTreeDigest(t, directory) + commonBefore := commandTreeDigest(t, repo.CommonDir) + headBefore := cliGit(t, directory, "rev-parse", "HEAD") + refBefore := cliGit(t, directory, "rev-parse", "refs/heads/wip/agent/dry-run-no-exec") + indexBefore := cliGitRaw(t, directory, "ls-files", "-s", "-z") + configPath := filepath.Join(repo.CommonDir, "config") + configBefore, err := os.ReadFile(configPath) + if err != nil { + t.Fatal(err) + } + + args := []string{"--repo-dir", directory, "commit", "--lane", "dry-run-no-exec", "--dry-run", "--plan", planPath} + preview := runCLI(t, append([]string{"--json"}, args...), "") + if preview.code != 0 || !preview.envelope.OK { + t.Fatalf("dry-run = %#v stderr=%s", preview.envelope, preview.stderr) + } + var result engine.Result + decodeData(t, preview.envelope.Data, &result) + wantCount := engine.ExecutionCount{Planned: 1, Executed: 0, Skipped: 1} + if result.SchemaVersion != engine.ResultSchemaVersion || !result.DryRun || result.GateOutcome != "skipped" || result.RefUpdated || result.FinalCommit != "" || result.IntentState != "" { + t.Fatalf("dry-run result = %#v", result) + } + if result.Execution == nil || result.Execution.Policy != "no-exec" || result.Execution.PreCommitHooks != wantCount || result.Execution.PostCommitHooks != wantCount || result.Execution.VerifyCommands != wantCount { + t.Fatalf("dry-run execution report = %#v", result.Execution) + } + if preview.envelope.Context == nil || preview.envelope.Context.LeaseRenewed { + t.Fatalf("dry-run claimed lease renewal = %#v", preview.envelope.Context) + } + human := runCLI(t, args, "") + if human.code != 0 || strings.Contains(human.stdout, "passed") || !strings.Contains(human.stdout, "skipped 2 repository hook invocation(s) and 1 verify command(s)") { + t.Fatalf("dry-run human output = %q stderr=%q", human.stdout, human.stderr) + } + + rejected := runCLI(t, []string{ + "--json", "--repo-dir", directory, "capture", "--lane", "dry-run-no-exec", "--dry-run", "--plan", planPath, + "--review-plan-digest", reviewDigest, + }, "") + if rejected.code == 0 || rejected.envelope.Error == nil || rejected.envelope.Error.Code != "REVIEWED_PLAN_REQUIRED" || rejected.envelope.Context != nil || rejected.envelope.Data != nil { + t.Fatalf("guided dry-run refusal = %#v stderr=%s", rejected.envelope, rejected.stderr) + } + + statusAfter, err := laneStore.Status("dry-run-no-exec") + if err != nil || !reflect.DeepEqual(statusBefore, statusAfter) { + t.Fatalf("dry-run changed lane or lease timestamps:\nbefore=%#v\nafter=%#v\nerr=%v", statusBefore, statusAfter, err) + } + for _, marker := range []string{preHookMarker, postHookMarker, verifyMarker} { + if _, statErr := os.Lstat(marker); !os.IsNotExist(statErr) { + t.Fatalf("dry-run executed marker %s: %v", marker, statErr) + } + } + if got := commandTreeDigest(t, directory); got != repositoryBefore { + t.Fatalf("dry-run changed repository bytes: before=%s after=%s", repositoryBefore, got) + } + if got := commandTreeDigest(t, repo.CommonDir); got != commonBefore { + t.Fatalf("dry-run changed common-directory bytes: before=%s after=%s", commonBefore, got) + } + if got := cliGit(t, directory, "rev-parse", "HEAD"); got != headBefore { + t.Fatalf("dry-run moved HEAD: before=%s after=%s", headBefore, got) + } + if got := cliGit(t, directory, "rev-parse", "refs/heads/wip/agent/dry-run-no-exec"); got != refBefore { + t.Fatalf("dry-run moved lane ref: before=%s after=%s", refBefore, got) + } + if got := cliGitRaw(t, directory, "ls-files", "-s", "-z"); got != indexBefore { + t.Fatal("dry-run changed the caller index") + } + if got, readErr := os.ReadFile(configPath); readErr != nil || !bytes.Equal(got, configBefore) { + t.Fatalf("dry-run changed repository config: before=%q after=%q err=%v", configBefore, got, readErr) + } + for name, want := range hookBodies { + hook := cliGit(t, directory, "rev-parse", "--git-path", "hooks/"+name) + if !filepath.IsAbs(hook) { + hook = filepath.Join(directory, hook) + } + if got, readErr := os.ReadFile(hook); readErr != nil || !bytes.Equal(got, want) { + t.Fatalf("dry-run changed %s hook bytes: before=%q after=%q err=%v", name, want, got, readErr) + } + } +} + +func TestCapturePlanDigestVerifyMarkerHelper(t *testing.T) { + marker := os.Getenv("WIP_CAPTURE_VERIFY_MARKER") + if marker == "" { + return + } + if err := os.WriteFile(marker, []byte("verify ran\n"), 0o600); err != nil { + t.Fatal(err) + } +} + +func TestReviewedWorktreeSourceCapturesOwnedUnstagedAndUntrackedPathsWithoutCallerIndexMutation(t *testing.T) { + directory := cliTestRepo(t) + writeCLI(t, directory, "work/core.txt", "base work\n") + cliGit(t, directory, "add", "work/core.txt") + cliGit(t, directory, "commit", "-m", "test: add work fixture") + + writeCLI(t, directory, "work/core.txt", "owned tracked\n") + writeCLI(t, directory, "work/new.txt", "owned untracked\n") + writeCLI(t, directory, "foreign.txt", "foreign staged\n") + cliGit(t, directory, "add", "foreign.txt") + head := cliGit(t, directory, "rev-parse", "HEAD") + indexBefore := cliGitRaw(t, directory, "ls-files", "-s", "-z") + initializeCLI(t, directory, "worktree-source", "work") + + planPath := filepath.Join(t.TempDir(), "worktree-plan.json") + drafted := runCLI(t, []string{ + "--json", "--repo-dir", directory, "plan", "--lane", "worktree-source", + "--source", "worktree_snapshot", "--untracked", "include", "--path", "work", "--out", planPath, + }, "") + if drafted.code != 0 || !drafted.envelope.OK { + t.Fatalf("draft worktree plan: %#v stderr=%s", drafted.envelope, drafted.stderr) + } + var plan planProposal + decodeData(t, drafted.envelope.Data, &plan) + if plan.SourceMode != "worktree_snapshot" || plan.UntrackedPolicy != "include" || !samePlanStrings(plan.SourcePaths, []string{"work/core.txt", "work/new.txt"}) { + t.Fatalf("worktree plan = %#v", plan) + } + plan.State = "reviewed" + plan.Groups[0].Message = "fix(work): capture private worktree source" + body, err := json.MarshalIndent(plan, "", " ") + if err != nil { + t.Fatal(err) + } + if err := os.WriteFile(planPath, append(body, '\n'), 0o600); err != nil { + t.Fatal(err) + } + + captured := runCLI(t, []string{"--json", "--repo-dir", directory, "capture", "--lane", "worktree-source", "--plan", planPath}, "") + if captured.code != 0 || !captured.envelope.OK { + t.Fatalf("worktree capture: %#v stderr=%s", captured.envelope, captured.stderr) + } + var result guidedCaptureResult + decodeData(t, captured.envelope.Data, &result) + if result.Capture.SourceMode != "worktree_snapshot" || result.Capture.UntrackedPolicy != "include" || result.Capture.SourceDigest != plan.SourceDigest || !result.Handoff.ReviewEligible { + t.Fatalf("worktree capture result = %#v", result) + } + if got := cliGitRaw(t, directory, "ls-files", "-s", "-z"); got != indexBefore { + t.Fatalf("caller index changed\nbefore=%q\nafter=%q", indexBefore, got) + } + if got := cliGit(t, directory, "rev-parse", "HEAD"); got != head { + t.Fatalf("source HEAD moved: %s", got) + } + assertCLIFileAtCommit(t, directory, result.Handoff.LaneTip, "work/core.txt", "owned tracked") + assertCLIFileAtCommit(t, directory, result.Handoff.LaneTip, "work/new.txt", "owned untracked") + assertCLIFileAtCommit(t, directory, result.Handoff.LaneTip, "foreign.txt", "base foreign") +} + +func TestCumulativeHandoffCoversEveryReviewedCaptureFromLaneBaseToTip(t *testing.T) { + directory := cliTestRepo(t) + writeCLI(t, directory, "core.txt", "first capture\n") + cliGit(t, directory, "add", "core.txt") + base := cliGit(t, directory, "rev-parse", "HEAD") + initializeCLI(t, directory, "cumulative-handoff", "core.txt", "docs.txt") + + firstPlan := reviewedPlanFile(t, directory, "cumulative-handoff", "fix(core): capture first segment") + firstCapture := runCLI(t, []string{"--json", "--repo-dir", directory, "capture", "--lane", "cumulative-handoff", "--plan", firstPlan}, "") + if firstCapture.code != 0 { + t.Fatalf("first capture = %#v stderr=%s", firstCapture.envelope, firstCapture.stderr) + } + var first guidedCaptureResult + decodeData(t, firstCapture.envelope.Data, &first) + + writeCLI(t, directory, "docs.txt", "second capture\n") + cliGit(t, directory, "add", "docs.txt") + secondPlan := reviewedPlanFile(t, directory, "cumulative-handoff", "docs(guide): capture second segment") + secondCapture := runCLI(t, []string{"--json", "--repo-dir", directory, "capture", "--lane", "cumulative-handoff", "--plan", secondPlan}, "") + if secondCapture.code != 0 { + t.Fatalf("second capture = %#v stderr=%s", secondCapture.envelope, secondCapture.stderr) + } + var second guidedCaptureResult + decodeData(t, secondCapture.envelope.Data, &second) + if !second.Handoff.ReviewEligible || second.Handoff.LaneBaseCommit != base || len(second.Handoff.Segments) != 2 { + t.Fatalf("cumulative handoff = %#v", second.Handoff) + } + firstSegment, secondSegment := second.Handoff.Segments[0], second.Handoff.Segments[1] + if firstSegment.ParentCommit != base || firstSegment.FinalCommit != secondSegment.ParentCommit || secondSegment.FinalCommit != second.Handoff.LaneTip || second.Handoff.TipPlanID != secondSegment.PlanID || second.Handoff.TipCaptureIntentDigest != secondSegment.CaptureIntentDigest { + t.Fatalf("segment chain is not contiguous: %#v", second.Handoff) + } + if first.Handoff.TipPlanID != firstSegment.PlanID || first.Handoff.TipCaptureIntentDigest != firstSegment.CaptureIntentDigest { + t.Fatalf("first handoff was not retained in cumulative chain") + } + + printed := runCLI(t, []string{"--json", "--repo-dir", directory, "handoff", "--lane", "cumulative-handoff"}, "") + if printed.code != 0 { + t.Fatalf("print cumulative handoff = %#v stderr=%s", printed.envelope, printed.stderr) + } + var receipt captureHandoff + decodeData(t, printed.envelope.Data, &receipt) + if receipt.HandoffDigest != second.Handoff.HandoffDigest { + t.Fatalf("handoff digest changed: capture=%s printed=%s", second.Handoff.HandoffDigest, receipt.HandoffDigest) + } + + staleTip := runCLI(t, []string{ + "--json", "--repo-dir", directory, "handoff", "--lane", "cumulative-handoff", + "--plan-id", firstSegment.PlanID, "--plan-digest", firstSegment.CaptureIntentDigest, + }, "") + if staleTip.code == 0 || staleTip.envelope.Error == nil || staleTip.envelope.Error.Code != "HANDOFF_TIP_MISMATCH" { + t.Fatalf("older segment was accepted as lane tip: %#v", staleTip.envelope) + } +} + +func TestCaptureRejectsDraftAndStaleReviewedPlans(t *testing.T) { + directory := cliTestRepo(t) + writeCLI(t, directory, "core.txt", "first change\n") + cliGit(t, directory, "add", "core.txt") + initializeCLI(t, directory, "stale-plan", "core.txt") + planPath := filepath.Join(t.TempDir(), "plan.json") + drafted := runCLI(t, []string{"--json", "--repo-dir", directory, "plan", "--lane", "stale-plan", "--out", planPath}, "") + if drafted.code != 0 { + t.Fatalf("draft: %#v", drafted) + } + draftCapture := runCLI(t, []string{"--json", "--repo-dir", directory, "capture", "--lane", "stale-plan", "--plan", planPath}, "") + if draftCapture.code == 0 || draftCapture.envelope.Error == nil || draftCapture.envelope.Error.Code != "PLAN_NOT_REVIEWED" { + t.Fatalf("draft capture = %#v", draftCapture) + } + var plan planProposal + decodeData(t, drafted.envelope.Data, &plan) + plan.State = "reviewed" + plan.Groups[0].Message = "fix(core): capture first behavior" + body, _ := json.MarshalIndent(plan, "", " ") + if err := os.WriteFile(planPath, body, 0o600); err != nil { + t.Fatal(err) + } + writeCLI(t, directory, "core.txt", "second change\n") + cliGit(t, directory, "add", "core.txt") + stale := runCLI(t, []string{"--json", "--repo-dir", directory, "capture", "--lane", "stale-plan", "--plan", planPath}, "") + if stale.code == 0 || stale.envelope.Error == nil || stale.envelope.Error.Code != "STALE_PLAN" { + t.Fatalf("stale capture = %#v", stale) + } +} + +func TestStatusClassifiesCaptureStateAndForeignIndexEntries(t *testing.T) { + directory := cliTestRepo(t) + writeCLI(t, directory, "core.txt", "new core\n") + writeCLI(t, directory, "foreign.txt", "foreign staged\n") + cliGit(t, directory, "add", "core.txt", "foreign.txt") + initializeCLI(t, directory, "operational-status", "core.txt", "docs.txt") + status := runCLI(t, []string{"--json", "--repo-dir", directory, "status", "--lane", "operational-status"}, "") + if status.code != 0 || status.envelope.Context == nil || !status.envelope.Context.LeaseRenewed { + t.Fatalf("status = %#v", status) + } + var before operationalStatus + decodeData(t, status.envelope.Data, &before) + if !samePlanStrings(before.CaptureCandidates, []string{"core.txt"}) || !samePlanStrings(before.ForeignStaged, []string{"foreign.txt"}) || !samePlanStrings(before.LeasedButNotStaged, []string{"docs.txt"}) { + t.Fatalf("operational sets = %#v", before) + } + captured := runCLI(t, []string{"--json", "--repo-dir", directory, "commit", "--lane", "operational-status", "--single", "--message", "fix(core): capture status behavior", "--path", "core.txt"}, "") + if captured.code != 0 { + t.Fatalf("capture: %#v", captured) + } + afterResult := runCLI(t, []string{"--json", "--repo-dir", directory, "status", "--lane", "operational-status", "--observe"}, "") + var after operationalStatus + decodeData(t, afterResult.envelope.Data, &after) + if len(after.CaptureCandidates) != 0 || !samePlanStrings(after.CapturedButStillStaged, []string{"core.txt"}) || after.Renewal.Attempted || after.LastIntent == nil || after.LastIntent.State != "complete" { + t.Fatalf("captured status = %#v", after) + } +} + +func TestMessagePolicyIsBoundOutsideCaptureKernel(t *testing.T) { + directory := cliTestRepo(t) + config := `{"schema_version":"1.0.0","message_policy":"safety-only-v1"}` + if err := os.WriteFile(filepath.Join(directory, ".wip-commit.json"), []byte(config), 0o600); err != nil { + t.Fatal(err) + } + writeCLI(t, directory, "core.txt", "new core\n") + cliGit(t, directory, "add", "core.txt") + initialized := runCLI(t, []string{"--json", "--repo-dir", directory, "init", "--mode", "shared", "--lane", "policy-lane", "--agent", "agent", "--session", "session", "--path", "core.txt", "--non-interactive", "--no-install", "--no-install-skill"}, "") + if initialized.code != 0 { + t.Fatalf("init: %#v stderr=%s", initialized.envelope, initialized.stderr) + } + plain := runCLI(t, []string{"--json", "--repo-dir", directory, "commit", "--lane", "policy-lane", "--single", "--message", "plain local checkpoint", "--path", "core.txt"}, "") + if plain.code != 0 || !plain.envelope.OK { + t.Fatalf("safety-only capture: %#v stderr=%s", plain.envelope, plain.stderr) + } +} + +func TestGuidedCaptureFinalReleasesAfterHandoffValidation(t *testing.T) { + directory := cliTestRepo(t) + writeCLI(t, directory, "core.txt", "new core\n") + cliGit(t, directory, "add", "core.txt") + initializeCLI(t, directory, "final-capture", "core.txt") + planPath := filepath.Join(t.TempDir(), "plan.json") + drafted := runCLI(t, []string{"--json", "--repo-dir", directory, "plan", "--lane", "final-capture", "--out", planPath}, "") + var plan planProposal + decodeData(t, drafted.envelope.Data, &plan) + plan.State = "reviewed" + plan.Groups[0].Message = "fix(core): finalize reviewed capture" + body, _ := json.MarshalIndent(plan, "", " ") + if err := os.WriteFile(planPath, body, 0o600); err != nil { + t.Fatal(err) + } + captured := runCLI(t, []string{"--json", "--repo-dir", directory, "capture", "--lane", "final-capture", "--plan", planPath, "--final"}, "") + if captured.code != 0 || !captured.envelope.OK { + t.Fatalf("final capture: %#v stderr=%s", captured.envelope, captured.stderr) + } + var result guidedCaptureResult + decodeData(t, captured.envelope.Data, &result) + if !result.LaneReleased || len(result.Handoff.Segments) != 1 || result.Handoff.Segments[0].IntentState != "complete" { + t.Fatalf("final result = %#v", result) + } + laneStore := inspectCLIStore(t, directory) + common := cliGit(t, directory, "rev-parse", "--path-format=absolute", "--git-common-dir") + stateBefore := commandTreeDigest(t, common) + lockPath := filepath.Join(laneStore.Root, "locks", "lane-final-capture.lock") + lockBefore, err := os.ReadFile(lockPath) + if err != nil { + t.Fatal(err) + } + printed := runCLI(t, []string{"--json", "--repo-dir", directory, "handoff", "--lane", "final-capture"}, "") + if printed.code != 0 || !printed.envelope.OK { + t.Fatalf("released handoff: %#v stderr=%s", printed.envelope, printed.stderr) + } + lockAfter, err := os.ReadFile(lockPath) + if err != nil { + t.Fatal(err) + } + if !bytes.Equal(lockAfter, lockBefore) { + t.Fatalf("released handoff changed the lane lock: before=%q after=%q", lockBefore, lockAfter) + } + if stateAfter := commandTreeDigest(t, common); stateAfter != stateBefore { + t.Fatalf("released handoff changed repository state: before=%s after=%s", stateBefore, stateAfter) + } +} + +func TestGuidedCaptureKeepsLaneLockThroughFinalRelease(t *testing.T) { + directory := cliTestRepo(t) + writeCLI(t, directory, "core.txt", "new core\n") + cliGit(t, directory, "add", "core.txt") + initializeCLI(t, directory, "locked-final", "core.txt") + planPath := reviewedPlanFile(t, directory, "locked-final", "fix(core): finalize under one lane lock") + + entered := make(chan struct{}) + proceed := make(chan struct{}) + var stdout, stderr bytes.Buffer + application := app{ + stdin: strings.NewReader(""), stdout: &stdout, stderr: &stderr, + beforeFinalRelease: func() { + close(entered) + <-proceed + }, + } + done := make(chan int, 1) + go func() { + done <- application.run(context.Background(), []string{"--json", "--repo-dir", directory, "capture", "--lane", "locked-final", "--plan", planPath, "--final"}) + }() + waitForBarrier(t, entered, "final capture validation") + unblocked := false + defer func() { + if !unblocked { + close(proceed) + } + }() + + laneStore := inspectCLIStore(t, directory) + lock, err := laneStore.LaneLock("locked-final", 100*time.Millisecond) + if err == nil { + _ = lock.Release() + t.Fatal("another lane transaction acquired the lock before final release") + } + if fail.Code(err) != "LOCK_TIMEOUT" { + t.Fatalf("competing lane lock error = %v (%s)", err, fail.Code(err)) + } + lane, err := laneStore.Load("locked-final") + if err != nil || lane.State != "active" { + t.Fatalf("lane before final release = %#v err=%v", lane, err) + } + close(proceed) + unblocked = true + + select { + case code := <-done: + if code != 0 { + t.Fatalf("final capture code=%d stdout=%s stderr=%s", code, stdout.String(), stderr.String()) + } + case <-time.After(20 * time.Second): + t.Fatal("final capture did not finish") + } + lane, err = laneStore.Load("locked-final") + if err != nil || lane.State != "released" { + t.Fatalf("lane after final release = %#v err=%v", lane, err) + } +} + +func TestHandoffKeepsLaneLockThroughValidationAndRenewal(t *testing.T) { + directory := cliTestRepo(t) + writeCLI(t, directory, "core.txt", "new core\n") + cliGit(t, directory, "add", "core.txt") + initializeCLI(t, directory, "locked-handoff", "core.txt") + planPath := reviewedPlanFile(t, directory, "locked-handoff", "fix(core): validate handoff under one lock") + captured := runCLI(t, []string{"--json", "--repo-dir", directory, "capture", "--lane", "locked-handoff", "--plan", planPath}, "") + if captured.code != 0 { + t.Fatalf("capture = %#v stderr=%s", captured.envelope, captured.stderr) + } + + entered := make(chan struct{}) + proceed := make(chan struct{}) + var stdout, stderr bytes.Buffer + application := app{ + stdin: strings.NewReader(""), stdout: &stdout, stderr: &stderr, + afterHandoffValidation: func() { + close(entered) + <-proceed + }, + } + done := make(chan int, 1) + go func() { + done <- application.run(context.Background(), []string{"--json", "--repo-dir", directory, "handoff", "--lane", "locked-handoff"}) + }() + waitForBarrier(t, entered, "handoff validation") + unblocked := false + defer func() { + if !unblocked { + close(proceed) + } + }() + + laneStore := inspectCLIStore(t, directory) + writerFence, err := store.AcquireWriterFence(laneStore.Repo, 100*time.Millisecond) + if err == nil { + _ = writerFence.Release() + t.Fatal("another writer acquired the repository fence after active handoff validation") + } + if fail.Code(err) != "LOCK_TIMEOUT" { + t.Fatalf("competing writer-fence error = %v (%s)", err, fail.Code(err)) + } + lock, err := laneStore.LaneLock("locked-handoff", 100*time.Millisecond) + if err == nil { + _ = lock.Release() + t.Fatal("another lane transaction acquired the lock after handoff validation") + } + if fail.Code(err) != "LOCK_TIMEOUT" { + t.Fatalf("competing lane lock error = %v (%s)", err, fail.Code(err)) + } + close(proceed) + unblocked = true + + select { + case code := <-done: + if code != 0 { + t.Fatalf("handoff code=%d stdout=%s stderr=%s", code, stdout.String(), stderr.String()) + } + case <-time.After(20 * time.Second): + t.Fatal("handoff did not finish") + } +} + +func reviewedPlanFile(t *testing.T, directory, lane, message string) string { + t.Helper() + path := filepath.Join(t.TempDir(), "reviewed-plan.json") + drafted := runCLI(t, []string{"--json", "--repo-dir", directory, "plan", "--lane", lane, "--out", path}, "") + if drafted.code != 0 { + t.Fatalf("draft plan = %#v stderr=%s", drafted.envelope, drafted.stderr) + } + var plan planProposal + decodeData(t, drafted.envelope.Data, &plan) + plan.State = "reviewed" + for index := range plan.Groups { + plan.Groups[index].Message = message + } + body, err := json.MarshalIndent(plan, "", " ") + if err != nil { + t.Fatal(err) + } + if err := os.WriteFile(path, append(body, '\n'), 0o600); err != nil { + t.Fatal(err) + } + return path +} + +func inspectCLIStore(t *testing.T, directory string) store.Store { + t.Helper() + repo, err := gitx.Discover(context.Background(), directory) + if err != nil { + t.Fatal(err) + } + laneStore, initialized, err := store.Inspect(repo) + if err != nil || !initialized { + t.Fatalf("inspect initialized=%v err=%v", initialized, err) + } + return laneStore +} + +func waitForBarrier(t *testing.T, barrier <-chan struct{}, label string) { + t.Helper() + select { + case <-barrier: + case <-time.After(20 * time.Second): + t.Fatalf("%s did not reach its test barrier", label) + } +} + +func TestPlanOutputDoesNotOverwriteAndLeaseChangesMakeReviewStale(t *testing.T) { + directory := cliTestRepo(t) + writeCLI(t, directory, "core.txt", "new core\n") + writeCLI(t, directory, "docs.txt", "new docs\n") + cliGit(t, directory, "add", "core.txt", "docs.txt") + initializeCLI(t, directory, "plan-binding", "core.txt") + + existingPath := filepath.Join(t.TempDir(), "existing.json") + if err := os.WriteFile(existingPath, []byte("operator-owned\n"), 0o600); err != nil { + t.Fatal(err) + } + refused := runCLI(t, []string{"--json", "--repo-dir", directory, "plan", "--lane", "plan-binding", "--out", existingPath}, "") + if refused.code == 0 || refused.envelope.Error == nil || refused.envelope.Error.Code != "PLAN_EXISTS" { + t.Fatalf("no-overwrite plan = %#v", refused) + } + if body, err := os.ReadFile(existingPath); err != nil || string(body) != "operator-owned\n" { + t.Fatalf("existing output changed: %q err=%v", body, err) + } + + planPath := filepath.Join(t.TempDir(), "review.json") + drafted := runCLI(t, []string{"--json", "--repo-dir", directory, "plan", "--lane", "plan-binding", "--out", planPath}, "") + if drafted.code != 0 { + t.Fatalf("draft = %#v", drafted) + } + var plan planProposal + decodeData(t, drafted.envelope.Data, &plan) + plan.State = "reviewed" + plan.Groups[0].Message = "fix(plan): bind the active lease set" + body, _ := json.MarshalIndent(plan, "", " ") + if err := os.WriteFile(planPath, append(body, '\n'), 0o600); err != nil { + t.Fatal(err) + } + claimed := runCLI(t, []string{"--json", "--repo-dir", directory, "claim", "--lane", "plan-binding", "--path", "docs.txt"}, "") + if claimed.code != 0 { + t.Fatalf("claim = %#v", claimed) + } + stale := runCLI(t, []string{"--json", "--repo-dir", directory, "capture", "--lane", "plan-binding", "--plan", planPath}, "") + if stale.code == 0 || stale.envelope.Error == nil || stale.envelope.Error.Code != "STALE_PLAN" { + t.Fatalf("lease-stale capture = %#v", stale) + } +} + +func TestConventionalPolicyRejectsBeforeRepositoryHooks(t *testing.T) { + if runtime.GOOS == "windows" { + t.Skip("fixture uses a POSIX hook") + } + directory := cliTestRepo(t) + writeCLI(t, directory, "core.txt", "new core\n") + cliGit(t, directory, "add", "core.txt") + initializeCLI(t, directory, "policy-before-hook", "core.txt") + marker := filepath.Join(t.TempDir(), "hook-ran") + hook := cliGit(t, directory, "rev-parse", "--git-path", "hooks/pre-commit") + if !filepath.IsAbs(hook) { + hook = filepath.Join(directory, hook) + } + script := "#!/bin/sh\n: > " + quoteCommandArg(marker) + "\n" + if err := os.WriteFile(hook, []byte(script), 0o700); err != nil { + t.Fatal(err) + } + result := runCLI(t, []string{"--json", "--repo-dir", directory, "commit", "--lane", "policy-before-hook", "--single", "--message", "plain local checkpoint", "--path", "core.txt"}, "") + if result.code == 0 || result.envelope.Error == nil || result.envelope.Error.Code != "MESSAGE_POLICY_REJECTED" { + t.Fatalf("policy result = %#v stderr=%s", result.envelope, result.stderr) + } + if _, err := os.Stat(marker); !os.IsNotExist(err) { + t.Fatalf("policy failure ran the repository hook: %v", err) + } +} + +func TestLegacyProfileReadPreservesBytesAndInfersDefaultPolicy(t *testing.T) { + directory := cliTestRepo(t) + initializeCLI(t, directory, "legacy-profile", "core.txt") + gitDir := cliGit(t, directory, "rev-parse", "--git-common-dir") + if !filepath.IsAbs(gitDir) { + gitDir = filepath.Join(directory, gitDir) + } + path := filepath.Join(gitDir, "wip", "v1", "profiles", "legacy-profile.json") + body, err := os.ReadFile(path) + if err != nil { + t.Fatal(err) + } + var record map[string]any + if err := json.Unmarshal(body, &record); err != nil { + t.Fatal(err) + } + record["schema_version"] = float64(legacyProfileSchemaVersion) + delete(record, "message_policy") + legacy, _ := json.MarshalIndent(record, "", " ") + legacy = append(legacy, '\n') + if err := os.WriteFile(path, legacy, 0o600); err != nil { + t.Fatal(err) + } + + result := runCLI(t, []string{"--json", "--repo-dir", directory, "status", "--lane", "legacy-profile", "--observe"}, "") + if result.code != 0 || result.envelope.Context == nil || result.envelope.Context.MessagePolicy.ID != "conventional-v1" { + t.Fatalf("legacy profile status = %#v stderr=%s", result.envelope, result.stderr) + } + after, err := os.ReadFile(path) + if err != nil || string(after) != string(legacy) { + t.Fatalf("legacy profile read changed bytes: err=%v", err) + } +} + +func TestLegacyInitIntentReadPreservesHistoricalDigestAndBytes(t *testing.T) { + directory := cliTestRepo(t) + initialized := runCLI(t, []string{"--json", "--repo-dir", directory, "init", "--mode", "shared", "--lane", "legacy-init", "--agent", "agent", "--session", "session", "--path", "core.txt", "--non-interactive", "--no-install", "--no-install-skill"}, "") + if initialized.code != 0 { + t.Fatalf("init = %#v stderr=%s", initialized.envelope, initialized.stderr) + } + var setup initResult + decodeData(t, initialized.envelope.Data, &setup) + intent, err := loadInitIntent(setup.IntentPath) + if err != nil { + t.Fatal(err) + } + intent.SchemaVersion = legacyInitIntentSchemaVersion + intent.MessagePolicy = nil + intent.ID, intent.Digest = "", "" + digest, err := digestInitIntent(intent) + if err != nil { + t.Fatal(err) + } + intent.Digest = digest + intent.ID = "init-" + strings.TrimPrefix(digest, "sha256:")[:24] + legacy, err := json.MarshalIndent(intent, "", " ") + if err != nil { + t.Fatal(err) + } + legacy = append(legacy, '\n') + legacyPath := filepath.Join(filepath.Dir(setup.IntentPath), intent.ID+".json") + if legacyPath != setup.IntentPath { + if err := os.Rename(setup.IntentPath, legacyPath); err != nil { + t.Fatal(err) + } + } + if err := os.WriteFile(legacyPath, legacy, 0o600); err != nil { + t.Fatal(err) + } + + loaded, err := loadInitIntent(legacyPath) + if err != nil || loaded.SchemaVersion != legacyInitIntentSchemaVersion || loaded.Digest != digest || loaded.MessagePolicy != nil { + t.Fatalf("legacy intent = %#v err=%v", loaded, err) + } + after, err := os.ReadFile(legacyPath) + if err != nil || string(after) != string(legacy) { + t.Fatalf("legacy intent read changed bytes: err=%v", err) + } +} diff --git a/cmd/wip/app.go b/cmd/wip/app.go index 878de12..b52c058 100644 --- a/cmd/wip/app.go +++ b/cmd/wip/app.go @@ -16,11 +16,14 @@ import ( ) type app struct { - stdin io.Reader - stdout, stderr io.Writer - jsonMode bool - repoDir string - leaseHeartbeat func(context.Context, store.Store, store.Lane, []string) (context.Context, func() error, error) + stdin io.Reader + stdout, stderr io.Writer + jsonMode bool + repoDir string + leaseHeartbeat func(context.Context, store.Store, store.Lane, []string) (context.Context, func() error, error) + beforeFinalRelease func() + afterHandoffValidation func() + migrationProducer migrationProducerFunc } type errorPayload struct { @@ -29,10 +32,11 @@ type errorPayload struct { } type envelope struct { - OK bool `json:"ok"` - Action string `json:"action"` - Data any `json:"data,omitempty"` - Error *errorPayload `json:"error,omitempty"` + OK bool `json:"ok"` + Action string `json:"action"` + Data any `json:"data,omitempty"` + Context *laneContext `json:"context,omitempty"` + Error *errorPayload `json:"error,omitempty"` } func (application *app) run(ctx context.Context, args []string) int { @@ -54,7 +58,14 @@ func (application *app) run(ctx context.Context, args []string) int { } return 0 case "version", "--version": - return application.success("version", map[string]string{"version": version}, "wip "+version) + build := currentVersionInfo() + return application.success("version", build, build.human()) + case "contract": + result, contractErr := currentContractResult() + if contractErr != nil { + return application.failure("contract", fail.Wrap("CONTRACT_FAILED", contractErr), nil, 1) + } + return application.success("contract", result, result.human()) } if len(rest) == 1 && (rest[0] == "--help" || rest[0] == "-h") { if application.printCommandHelp(command) { @@ -62,6 +73,14 @@ func (application *app) run(ctx context.Context, args []string) int { } return 2 } + if command == "upgrade" { + return application.runUpgrade(ctx, rest) + } + if command == "capture" { + if err := application.preflightCapturePlan(rest); err != nil { + return application.failure(command, err, nil, 2) + } + } repo, err := gitx.Discover(ctx, application.repoDir) if err != nil { return application.failure(command, err, nil, 1) @@ -75,11 +94,28 @@ func (application *app) run(ctx context.Context, args []string) int { if command == "archive" { return application.runArchive(ctx, repo, rest) } + if command == "migrate" { + return application.runMigrate(ctx, repo, rest) + } + if command == "init-abort" { + return application.runInitAbort(ctx, repo, rest) + } readOnly := false switch command { - case "status", "env", "plan": + case "env": + readOnly = envObserveRequested(rest) + case "handoff": + // The handler inspects the lane first. It retains a writer fence for an + // active-lane renewal and keeps a released-lane handoff byte-for-byte + // read-only. readOnly = true - case "claim", "renew", "commit", "reconcile", "release", "abort": + case "status": + readOnly = statusObserveRequested(rest) + case "plan": + readOnly = planObserveRequested(rest) + case "commit": + readOnly = booleanFlagRequested(rest, "dry-run") + case "claim", "renew", "capture", "reconcile", "release", "abort": default: return application.failure(command, fail.Errorf("INVALID_ARGS", "unknown command %q", command), nil, 2) } @@ -91,30 +127,39 @@ func (application *app) run(ctx context.Context, args []string) int { return application.failure(command, err, nil, 1) } if !readOnly { - laneStore, err = store.Open(repo) + writerFence, fenceErr := store.AcquireWriterFence(repo, store.DefaultWriterFenceWait) + if fenceErr != nil { + return application.failure(command, fenceErr, nil, 1) + } + defer func() { _ = writerFence.Release() }() + laneStore, err = store.OpenWithWriterFence(repo, writerFence) } if err != nil { return application.failure(command, err, nil, 1) } switch command { case "status": - return application.runStatus(laneStore, rest) + return application.runStatus(ctx, laneStore, rest) case "env": - return application.runEnv(laneStore, rest) + return application.runEnv(ctx, laneStore, rest) case "claim": - return application.runClaim(laneStore, rest) + return application.runClaim(ctx, laneStore, rest) case "renew": - return application.runRenew(laneStore, rest) + return application.runRenew(ctx, laneStore, rest) case "plan": return application.runPlan(ctx, laneStore, rest) case "commit": return application.runCommit(ctx, laneStore, rest) + case "capture": + return application.runCapture(ctx, laneStore, rest) + case "handoff": + return application.runHandoff(ctx, laneStore, rest) case "reconcile": return application.runReconcile(ctx, laneStore, rest) case "release": - return application.runRelease(laneStore, rest, false) + return application.runRelease(ctx, laneStore, rest, false) case "abort": - return application.runRelease(laneStore, rest, true) + return application.runRelease(ctx, laneStore, rest, true) } return application.failure(command, fail.Errorf("INVALID_ARGS", "unknown command %q", command), nil, 2) } @@ -137,8 +182,12 @@ func (application *app) parseGlobal(args []string) (string, []string, error) { } func (application app) success(action string, data any, human string) int { + return application.successWithContext(action, data, human, nil) +} + +func (application app) successWithContext(action string, data any, human string, laneContext *laneContext) int { if application.jsonMode { - _ = json.NewEncoder(application.stdout).Encode(envelope{OK: true, Action: action, Data: data}) + _ = json.NewEncoder(application.stdout).Encode(envelope{OK: true, Action: action, Data: data, Context: laneContext}) } else if human != "" { _, _ = fmt.Fprintln(application.stdout, human) } @@ -146,9 +195,13 @@ func (application app) success(action string, data any, human string) int { } func (application app) failure(action string, err error, data any, code int) int { + return application.failureWithContext(action, err, data, code, nil) +} + +func (application app) failureWithContext(action string, err error, data any, code int, laneContext *laneContext) int { payload := &errorPayload{Code: fail.Code(err), Message: err.Error()} if application.jsonMode { - _ = json.NewEncoder(application.stdout).Encode(envelope{OK: false, Action: action, Data: data, Error: payload}) + _ = json.NewEncoder(application.stdout).Encode(envelope{OK: false, Action: action, Data: data, Context: laneContext, Error: payload}) } else { _, _ = fmt.Fprintf(application.stderr, "wip %s: %s: %s\n", action, payload.Code, payload.Message) } @@ -163,25 +216,31 @@ func (application app) flagSet(command string) *flag.FlagSet { func (application app) printHelp() { output := application.stdout - _, _ = fmt.Fprintln(output, `wip safely captures exact staged subsets on agent-owned refs. + _, _ = fmt.Fprintln(output, `wip safely captures exact private sources on agent-owned refs. Usage: wip [--json] [--repo-dir DIR] [options] Commands: init interactively install and initialize a shared or worktree lane + init-abort preview or abort one safe pre-lane initialization intent doctor audit bounded state, refs, and recovery requirements archive preview or apply recoverable state-record archival - status show the active lane and leases + upgrade preview or apply one digest-bound state, binary, or skill upgrade + migrate preview or apply one digest-bound coordination migration + status classify staged state and show lane, lease, ref, and intent health env print shell environment for a lane claim claim additional paths renew renew active path leases - plan preview deterministic split suggestions for staged leased paths + plan create one bound draft for selected leased source paths commit capture one atomic split plan + capture capture one reviewed bound plan and emit a typed handoff + handoff validate and print a capture-only handoff reconcile finish metadata after an interrupted successful ref update release release the lane and its leases abort abort the lane and release its leases version print the version + contract print the machine-readable command and skill contract Run wip --help for command options.`) } @@ -196,25 +255,43 @@ Interactively initialize and optionally install wip. Important options: --lane ID short task slug --agent ID --session ID owner identity --base-ref REF starting commit (default HEAD) + --message-policy ID override the repository message policy --path PATH path claim; repeatable --install --install-dir DIR copy this binary without overwriting --install-skill --skill-dir DIR install the embedded portable skill safely --non-interactive --yes do not prompt --dry-run validate without changing Git or installing`, + "init-abort": `Usage: wip init-abort --intent ID [options] + +Preview is the default. Apply requires the digest from that preview. + --intent ID pending initialization intent + --intent-digest SHA256 exact digest from the reviewed preview + --apply --yes remove a safe intent before lane creation`, "commit": `Usage: wip commit [options] -Capture one all-or-nothing staged split plan. Important options: +Capture one all-or-nothing private-source split plan. Important options: --plan FILE strict JSON plan, or - for stdin - --single --message MESSAGE explicit one-commit opt-out + --single --message MESSAGE explicit one-commit compatibility path --path PATH staged scope for --single; repeatable - --dry-run run gates without commits or a ref update + --dry-run validate structure without hooks, verify commands, commits, or a ref update --allow-wip authorize the wip: prefix --hook-timeout DURATION hook limit --verify-timeout DURATION default verify limit - --lock-wait DURATION lane-lock wait`, - "status": "Usage: wip status [--lane ID] [--agent ID] [--session ID]", - "doctor": "Usage: wip doctor\n\nRead-only audit of bounded state records, refs, and recovery intents.", + --lock-wait DURATION lane-lock wait; zero fails fast`, + "capture": `Usage: wip capture --plan FILE [options] + +Capture one reviewed v3 plan and emit a validated cumulative capture-only handoff. + --plan FILE reviewed bound plan from wip plan + --review-plan-digest SHA256 exact canonical digest supplied by the reviewer + --final release the lane after the handoff validates + --allow-wip authorize the wip: prefix + --hook-timeout DURATION hook limit + --verify-timeout DURATION default verify limit + --lock-wait DURATION lane-lock wait; zero fails fast`, + "handoff": "Usage: wip handoff [identity options] [--plan-id ID --plan-digest SHA256]\n\nValidate and output one cumulative, capture-only, non-authorizing handoff. Active-lane use renews leases.", + "status": "Usage: wip status [--lane ID] [--agent ID] [--session ID] [--observe]\n\nStatus renews active leases by default. Use --observe for a pure read.", + "doctor": "Usage: wip doctor\n\nRead-only audit of bounded state records, refs, and recovery intents.", "archive": `Usage: wip archive [options] Preview is the default. Important options: @@ -222,17 +299,42 @@ Preview is the default. Important options: --lane ID narrow to an eligible lane; repeatable --cutoff TIME --plan-digest SHA256 exact values from the reviewed preview + repeat every preview --lane value on apply --apply --yes apply the exact reviewed archive plan --resume ARCHIVE_ID resume a prepared receipt; requires --apply --yes --restore ARCHIVE_ID restore records; also requires --apply --yes`, - "env": "Usage: wip env --lane ID", - "claim": "Usage: wip claim [identity options] --path PATH [--path PATH...]", - "renew": "Usage: wip renew [--lane ID] [--agent ID] [--session ID]", - "plan": "Usage: wip plan [identity options] [--path PATH...]\n\nRead-only split suggestions. Review them before writing a commit plan.", + "env": "Usage: wip env --lane ID [--observe]", + "claim": "Usage: wip claim [identity options] --path PATH [--path PATH...]", + "renew": "Usage: wip renew [--lane ID] [--agent ID] [--session ID]", + "plan": `Usage: wip plan [identity options] [--path PATH...] [--out FILE] + +Create one bound private-source draft. Add messages and set its state to reviewed before capture. + --source staged_index|worktree_snapshot + select the exact source model + --untracked not_applicable|forbid|include + select explicit untracked behavior + --observe do not renew leases or write an output file`, "reconcile": "Usage: wip reconcile [identity options] --plan-id ID --plan-digest SHA256", "release": "Usage: wip release [--lane ID] [--agent ID] [--session ID]", "abort": "Usage: wip abort [--lane ID] [--agent ID] [--session ID]", "version": "Usage: wip version", + "contract": "Usage: wip contract\n\nPrint the command protocol, capabilities, and portable skill digest.", + "upgrade": `Usage: wip upgrade (--state | --binary | --skill) [options] + +Preview is the default. Apply one exact reviewed target at a time. + --plan-digest SHA256 exact digest from the reviewed preview + --apply --yes apply only that byte-bound plan + --install-dir DIR binary install directory (default ~/.local/bin) + --skill-dir DIR agent skill directory (default ~/.agents/skills)`, + "migrate": `Usage: wip migrate (--preview | --status | --apply | --resume | --rollback) [options] + +Experimental coordination-domain migration. Preview and status are read-only. + --preview emit the complete immutable migration plan + --status [--migration-id ID] inspect journal, receipt, and archive state + --apply|--resume|--rollback select one exact mutation mode + --plan FILE strict reviewed plan; use - for stdin + --plan-digest SHA256 --yes bind and confirm the exact reviewed plan + --lock-wait DURATION common writer-lock wait; zero fails fast`, } if text, ok := usage[command]; ok { _, _ = fmt.Fprintln(application.stdout, text) diff --git a/cmd/wip/archive.go b/cmd/wip/archive.go index 450206b..acd1249 100644 --- a/cmd/wip/archive.go +++ b/cmd/wip/archive.go @@ -16,11 +16,12 @@ import ( ) type archiveResult struct { - DryRun bool `json:"dry_run"` - Cutoff time.Time `json:"cutoff,omitempty"` - PlanDigest string `json:"plan_digest,omitempty"` - Candidates []store.ArchiveCandidate `json:"candidates"` - Receipt *store.ArchiveReceipt `json:"receipt,omitempty"` + DryRun bool `json:"dry_run"` + Cutoff time.Time `json:"cutoff,omitempty"` + PlanDigest string `json:"plan_digest,omitempty"` + LaneFilters []string `json:"lane_filters"` + Candidates []store.ArchiveCandidate `json:"candidates"` + Receipt *store.ArchiveReceipt `json:"receipt,omitempty"` } func (application app) runArchive(ctx context.Context, repo gitx.Repo, args []string) int { @@ -53,12 +54,13 @@ func (application app) runArchive(ctx context.Context, repo gitx.Repo, args []st if !*apply || !*yes { return application.failure("archive", fail.New("CONFIRMATION_REQUIRED", "archive restore requires --apply --yes"), nil, 2) } - laneStore, err := inspectArchiveStore(repo) + laneStore, writerFence, err := openArchiveStoreForWrite(repo) if err != nil { return application.failure("archive", err, nil, 1) } + defer func() { _ = writerFence.Release() }() receipt, err := laneStore.RestoreArchive(ctx, *restore) - result := archiveResult{DryRun: false, Candidates: []store.ArchiveCandidate{}, Receipt: &receipt} + result := archiveResult{DryRun: false, LaneFilters: []string{}, Candidates: []store.ArchiveCandidate{}, Receipt: &receipt} if err != nil { return application.failure("archive", err, result, 1) } @@ -71,12 +73,13 @@ func (application app) runArchive(ctx context.Context, repo gitx.Repo, args []st if !*apply || !*yes { return application.failure("archive", fail.New("CONFIRMATION_REQUIRED", "archive resume requires --apply --yes"), nil, 2) } - laneStore, err := inspectArchiveStore(repo) + laneStore, writerFence, err := openArchiveStoreForWrite(repo) if err != nil { return application.failure("archive", err, nil, 1) } + defer func() { _ = writerFence.Release() }() receipt, err := laneStore.ResumeArchive(ctx, *resume) - result := archiveResult{DryRun: false, Cutoff: receipt.Before, Candidates: receipt.Candidates, Receipt: &receipt} + result := archiveResult{DryRun: false, Cutoff: receipt.Before, LaneFilters: []string{}, Candidates: receipt.Candidates, Receipt: &receipt} if err != nil { return application.failure("archive", err, result, 1) } @@ -94,7 +97,7 @@ func (application app) runArchive(ctx context.Context, repo gitx.Repo, args []st if err != nil { return application.failure("archive", err, nil, 1) } - result := archiveResult{DryRun: !*apply, Cutoff: cutoff, Candidates: []store.ArchiveCandidate{}} + result := archiveResult{DryRun: !*apply, Cutoff: cutoff, LaneFilters: []string{}, Candidates: []store.ArchiveCandidate{}} if !initialized { return application.success("archive", result, "no wip coordination state is initialized") } @@ -112,7 +115,9 @@ func (application app) runArchive(ctx context.Context, repo gitx.Repo, args []st return application.failure("archive", fail.New("INVALID_ARGS", "duplicate --lane value: "+lane), result, 2) } wanted[lane] = true + result.LaneFilters = append(result.LaneFilters, lane) } + sort.Strings(result.LaneFilters) filtered := candidates[:0] for _, candidate := range candidates { if wanted[candidate.LaneID] { @@ -145,12 +150,17 @@ func (application app) runArchive(ctx context.Context, repo gitx.Repo, args []st return application.failure("archive", fail.New("ARCHIVE_PLAN_REQUIRED", "apply requires --cutoff and --plan-digest from the reviewed preview"), result, 2) } if strings.TrimSpace(*expectedDigest) != result.PlanDigest { - return application.failure("archive", fail.New("ARCHIVE_PLAN_MOVED", "eligible archive records differ from the reviewed plan"), result, 1) + return application.failure("archive", fail.New("ARCHIVE_PLAN_MOVED", "eligible archive records differ from the reviewed plan; repeat every --lane filter from the preview or run a new preview"), result, 1) } if len(candidates) == 0 { return application.failure("archive", fail.New("ARCHIVE_EMPTY", "no eligible lanes match the reviewed archive plan"), result, 1) } - laneStore, err = store.Open(repo) + writerFence, err := store.AcquireWriterFence(repo, store.DefaultWriterFenceWait) + if err != nil { + return application.failure("archive", err, result, 1) + } + defer func() { _ = writerFence.Release() }() + laneStore, err = store.OpenWithWriterFence(repo, writerFence) if err != nil { return application.failure("archive", err, result, 1) } @@ -163,15 +173,30 @@ func (application app) runArchive(ctx context.Context, repo gitx.Repo, args []st return application.success("archive", result, fmt.Sprintf("archived %d released lane record(s) in %s; all lane refs and commits were preserved", len(receipt.Candidates), receipt.ID)) } -func inspectArchiveStore(repo gitx.Repo) (store.Store, error) { - laneStore, initialized, err := store.Inspect(repo) +func openArchiveStoreForWrite(repo gitx.Repo) (store.Store, *store.WriterFence, error) { + _, initialized, err := store.Inspect(repo) if err != nil { - return store.Store{}, err + return store.Store{}, nil, err } if !initialized { - return store.Store{}, fail.New("ARCHIVE_NOT_FOUND", "archive receipt does not exist because wip state is not initialized") + return store.Store{}, nil, fail.New("ARCHIVE_NOT_FOUND", "archive receipt does not exist because wip state is not initialized") } - return laneStore, nil + fence, err := store.AcquireWriterFence(repo, store.DefaultWriterFenceWait) + if err != nil { + return store.Store{}, nil, err + } + laneStore, initialized, err := store.Inspect(repo) + if err == nil && !initialized { + err = fail.New("ARCHIVE_NOT_FOUND", "archive receipt does not exist because wip state is not initialized") + } + if err == nil { + laneStore, err = store.OpenWithWriterFence(repo, fence) + } + if err != nil { + _ = fence.Release() + return store.Store{}, nil, err + } + return laneStore, fence, nil } func formatArchivePreview(result archiveResult) string { @@ -182,7 +207,14 @@ func formatArchivePreview(result archiveResult) string { for _, candidate := range result.Candidates { lines = append(lines, fmt.Sprintf("%s %s %s leases=%d", candidate.LaneID, candidate.State, candidate.Commit, candidate.LeaseCount)) } - lines = append(lines, "cutoff: "+result.Cutoff.Format(time.RFC3339Nano), "plan digest: "+result.PlanDigest, "Review this list, then reuse the exact --cutoff and --plan-digest with --apply --yes. Lane refs and commits are never moved or deleted.") + if len(result.LaneFilters) > 0 { + filters := make([]string, 0, len(result.LaneFilters)) + for _, lane := range result.LaneFilters { + filters = append(filters, "--lane "+lane) + } + lines = append(lines, "lane filters: "+strings.Join(filters, " ")) + } + lines = append(lines, "cutoff: "+result.Cutoff.Format(time.RFC3339Nano), "plan digest: "+result.PlanDigest, "Review this list, then reuse the exact --cutoff and --plan-digest and repeat every listed --lane filter with --apply --yes. Lane refs and commits are never moved or deleted.") return strings.Join(lines, "\n") } diff --git a/cmd/wip/commands.go b/cmd/wip/commands.go index bfa7821..a6d90f6 100644 --- a/cmd/wip/commands.go +++ b/cmd/wip/commands.go @@ -1,8 +1,11 @@ package main import ( + "context" "fmt" + "strconv" "strings" + "time" "github.com/nstranquist/wip-commit/internal/fail" "github.com/nstranquist/wip-commit/internal/store" @@ -16,9 +19,14 @@ func (values *stringList) Set(value string) error { return nil } -func (application app) runStatus(laneStore store.Store, args []string) int { +func statusObserveRequested(args []string) bool { + return booleanFlagRequested(args, "observe") +} + +func (application app) runStatus(ctx context.Context, laneStore store.Store, args []string) int { set := application.flagSet("status") var identity identityFlags + observe := set.Bool("observe", false, "inspect without renewing active leases") identity.bind(set) if err := set.Parse(args); err != nil { return application.failure("status", fail.Wrap("INVALID_ARGS", err), nil, 2) @@ -30,21 +38,62 @@ func (application app) runStatus(laneStore store.Store, args []string) int { if err != nil { return application.failure("status", err, nil, 1) } - active, err := laneStore.ActivePaths(status.Lane.ID) + renewal := renewalStatus{} + if !*observe { + renewal.Attempted = true + if _, err := laneStore.Renew(status.Lane.ID, status.Lane.Agent, status.Lane.Session); err != nil { + data, inspectErr := buildOperationalStatus(ctx, laneStore, status, renewal) + if inspectErr != nil { + return application.failure("status", err, nil, 1) + } + return application.failureWithContext("status", err, data, 1, data.context()) + } + now := time.Now().UTC() + renewal.Succeeded, renewal.RenewedAt = true, &now + status, err = laneStore.Status(status.Lane.ID) + if err != nil { + return application.failure("status", err, nil, 1) + } + } + data, err := buildOperationalStatus(ctx, laneStore, status, renewal) if err != nil { return application.failure("status", err, nil, 1) } - data := struct { - store.Status - ActivePaths []string `json:"active_paths"` - }{Status: status, ActivePaths: active} - human := fmt.Sprintf("lane %s (%s) -> %s\nref %s\nactive paths: %s", status.Lane.ID, status.Lane.Mode, status.Lane.CurrentSHA, status.Lane.Ref, strings.Join(active, ", ")) - return application.success("status", data, human) + human := fmt.Sprintf("lane %s (%s) -> %s\nref %s\ncapture candidates: %s\nalready captured and staged: %s\nforeign staged: %s\nlease remaining: %dms", status.Lane.ID, status.Lane.Mode, status.Lane.CurrentSHA, status.Lane.Ref, strings.Join(data.CaptureCandidates, ", "), strings.Join(data.CapturedButStillStaged, ", "), strings.Join(data.ForeignStaged, ", "), data.LeaseRemainingMS) + return application.successWithContext("status", data, human, data.context()) +} + +func envObserveRequested(args []string) bool { + return booleanFlagRequested(args, "observe") +} + +func booleanFlagRequested(args []string, name string) bool { + requested := false + for _, arg := range args { + if arg == "--"+name || arg == "-"+name { + requested = true + continue + } + for _, prefix := range []string{"--" + name + "=", "-" + name + "="} { + if !strings.HasPrefix(arg, prefix) { + continue + } + value, err := strconv.ParseBool(strings.TrimPrefix(arg, prefix)) + if err != nil { + // Keep malformed observe requests read-only until the flag parser + // returns INVALID_ARGS. + return true + } + requested = value + } + } + return requested } -func (application app) runEnv(laneStore store.Store, args []string) int { +func (application app) runEnv(ctx context.Context, laneStore store.Store, args []string) int { set := application.flagSet("env") lane := set.String("lane", envDefault("WIP_LANE"), "lane id (default WIP_LANE)") + observe := set.Bool("observe", false, "print without renewing active leases") if err := set.Parse(args); err != nil { return application.failure("env", fail.Wrap("INVALID_ARGS", err), nil, 2) } @@ -58,10 +107,29 @@ func (application app) runEnv(laneStore store.Store, args []string) int { if err != nil { return application.failure("env", err, nil, 1) } - return application.success("env", saved, shellEnvironment(saved)) + bound, err := laneStore.Load(saved.Lane) + if err != nil { + return application.failure("env", err, nil, 1) + } + if bound.Worktree != laneStore.Repo.Root { + return application.failure("env", fail.New("WORKTREE_MISMATCH", "lane is bound to a different checkout; run wip env from "+bound.Worktree), nil, 1) + } + renewal := renewalStatus{} + if !*observe { + renewal.Attempted = true + if _, err := laneStore.Renew(saved.Lane, saved.Agent, saved.Session); err != nil { + return application.failure("env", err, nil, 1) + } + renewal.Succeeded = true + } + laneContext, err := laneContextFor(ctx, laneStore, saved.Lane, renewal) + if err != nil { + return application.failure("env", err, nil, 1) + } + return application.successWithContext("env", saved, shellEnvironment(saved), laneContext) } -func (application app) runClaim(laneStore store.Store, args []string) int { +func (application app) runClaim(ctx context.Context, laneStore store.Store, args []string) int { set := application.flagSet("claim") var identity identityFlags var paths stringList @@ -84,10 +152,24 @@ func (application app) runClaim(laneStore store.Store, args []string) int { if err != nil { return application.failure("claim", err, nil, 1) } - return application.success("claim", lease, fmt.Sprintf("claimed %s for lane %s until %s", strings.Join(lease.Paths, ", "), lease.LaneID, lease.ExpiresAt.Format("2006-01-02T15:04:05Z"))) + renewed, err := laneStore.Renew(status.Lane.ID, status.Lane.Agent, status.Lane.Session) + if err != nil { + return application.failure("claim", err, lease, 1) + } + for _, candidate := range renewed { + if candidate.ID == lease.ID { + lease = candidate + break + } + } + laneContext, err := laneContextFor(ctx, laneStore, status.Lane.ID, renewalStatus{Attempted: true, Succeeded: true}) + if err != nil { + return application.failure("claim", err, lease, 1) + } + return application.successWithContext("claim", lease, fmt.Sprintf("claimed %s for lane %s until %s", strings.Join(lease.Paths, ", "), lease.LaneID, lease.ExpiresAt.Format("2006-01-02T15:04:05Z")), laneContext) } -func (application app) runRenew(laneStore store.Store, args []string) int { +func (application app) runRenew(ctx context.Context, laneStore store.Store, args []string) int { set := application.flagSet("renew") var identity identityFlags identity.bind(set) @@ -105,10 +187,14 @@ func (application app) runRenew(laneStore store.Store, args []string) int { if err != nil { return application.failure("renew", err, nil, 1) } - return application.success("renew", leases, fmt.Sprintf("renewed %d lease(s) for lane %s", len(leases), status.Lane.ID)) + laneContext, err := laneContextFor(ctx, laneStore, status.Lane.ID, renewalStatus{Attempted: true, Succeeded: true}) + if err != nil { + return application.failure("renew", err, leases, 1) + } + return application.successWithContext("renew", leases, fmt.Sprintf("renewed %d lease(s) for lane %s", len(leases), status.Lane.ID), laneContext) } -func (application app) runRelease(laneStore store.Store, args []string, abort bool) int { +func (application app) runRelease(ctx context.Context, laneStore store.Store, args []string, abort bool) int { action := "release" if abort { action = "abort" @@ -133,5 +219,9 @@ func (application app) runRelease(laneStore store.Store, args []string, abort bo if abort { state = "aborted" } - return application.success(action, map[string]string{"lane": status.Lane.ID, "state": state}, fmt.Sprintf("%s lane %s; its ref was preserved", state, status.Lane.ID)) + laneContext, contextErr := laneContextFor(ctx, laneStore, status.Lane.ID, renewalStatus{}) + if contextErr != nil { + return application.failure(action, contextErr, map[string]string{"lane": status.Lane.ID, "state": state}, 1) + } + return application.successWithContext(action, map[string]string{"lane": status.Lane.ID, "state": state}, fmt.Sprintf("%s lane %s; its ref was preserved", state, status.Lane.ID), laneContext) } diff --git a/cmd/wip/commit.go b/cmd/wip/commit.go index f4345da..d506db5 100644 --- a/cmd/wip/commit.go +++ b/cmd/wip/commit.go @@ -2,6 +2,7 @@ package main import ( "bufio" + "bytes" "context" "fmt" "io" @@ -12,74 +13,148 @@ import ( "github.com/nstranquist/wip-commit/internal/engine" "github.com/nstranquist/wip-commit/internal/fail" + "github.com/nstranquist/wip-commit/internal/filelock" "github.com/nstranquist/wip-commit/internal/pathid" + "github.com/nstranquist/wip-commit/internal/policy" "github.com/nstranquist/wip-commit/internal/store" - "github.com/nstranquist/wip-commit/internal/strictjson" ) const maxPlanBytes = 1 << 20 type commitOptions struct { identity identityFlags - plan, message string + plan, reviewPlanDigest, message string paths stringList single, allowWIP, dryRun, noInteractive bool + final bool hookTimeout, verifyTimeout, lockWait time.Duration } func (application app) runCommit(ctx context.Context, laneStore store.Store, args []string) int { - set := application.flagSet("commit") - options := commitOptions{} - options.identity.bind(set) - set.StringVar(&options.plan, "plan", "", "strict JSON split plan file, or - for stdin") - set.BoolVar(&options.single, "single", false, "explicitly capture one commit instead of the split default") - set.StringVar(&options.message, "message", "", "single-commit Conventional Commit message") - set.Var(&options.paths, "path", "staged path scope for --single (repeatable)") - set.BoolVar(&options.allowWIP, "allow-wip", false, "explicitly authorize the wip: commit prefix") - set.BoolVar(&options.dryRun, "dry-run", false, "run all gates without creating commits or moving the lane ref") - set.BoolVar(&options.noInteractive, "non-interactive", false, "fail instead of prompting for a split plan") - set.DurationVar(&options.hookTimeout, "hook-timeout", engine.DefaultHookTimeout, "pre/post-commit hook timeout") - set.DurationVar(&options.verifyTimeout, "verify-timeout", engine.DefaultVerifyTimeout, "default verify command timeout") - set.DurationVar(&options.lockWait, "lock-wait", 0, "time to wait for the lane lock") - if err := set.Parse(args); err != nil { - return application.failure("commit", fail.Wrap("INVALID_ARGS", err), nil, 2) + return application.runCaptureTransaction(ctx, laneStore, args, false) +} + +func (application app) runCapture(ctx context.Context, laneStore store.Store, args []string) int { + return application.runCaptureTransaction(ctx, laneStore, args, true) +} + +// preflightCapturePlan verifies NDev's exact canonical reviewed-plan digest +// before command dispatch acquires any repository writer lock. The locked +// transaction reopens and rechecks file-backed plans. Stdin is bounded once +// and replayed so the same immutable input is checked again. +func (application *app) preflightCapturePlan(args []string) error { + options, err := application.parseCommitOptions("capture", args, true) + if err != nil { + return err } - if err := noArgs(set); err != nil { - return application.failure("commit", err, nil, 2) + if options.reviewPlanDigest == "" { + return nil } - if options.lockWait < 0 { - return application.failure("commit", fail.New("INVALID_ARGS", "--lock-wait cannot be negative"), nil, 2) + var body []byte + if options.plan == "-" { + body, err = readCommitPlanBody(application.stdin) + if err == nil { + application.stdin = bytes.NewReader(body) + } + } else { + file, openErr := os.Open(options.plan) + if openErr != nil { + return fail.Wrap("INVALID_PLAN", openErr) + } + body, err = readCommitPlanBody(file) + closeErr := file.Close() + if err == nil && closeErr != nil { + err = fail.Wrap("INVALID_PLAN", closeErr) + } + } + if err != nil { + return err + } + resolved, err := decodeCommitPlanBody(body) + if err != nil { + return err + } + if !resolved.Reviewed || resolved.Plan == nil || resolved.Plan.SchemaVersion != reviewPlanSchemaVersion || resolved.Plan.State != "reviewed" { + return fail.New("REVIEWED_PLAN_REQUIRED", "capture requires the reviewed v3 plan schema; legacy arrays remain commit-only") + } + digest, err := reviewPlanDigest(*resolved.Plan) + if err != nil { + return err + } + if digest != options.reviewPlanDigest { + return fail.New("REVIEW_PLAN_DIGEST_MISMATCH", "reviewed plan does not match --review-plan-digest") + } + return nil +} + +func (application app) runCaptureTransaction(ctx context.Context, laneStore store.Store, args []string, guided bool) int { + action := "commit" + if guided { + action = "capture" + } + options, err := application.parseCommitOptions(action, args, guided) + if err != nil { + return application.failure(action, err, nil, 2) } status, err := resolveStatus(laneStore, options.identity) if err != nil { - return application.failure("commit", err, nil, 1) + return application.failure(action, err, nil, 1) + } + var lock *filelock.Lock + if options.dryRun { + lock, err = laneStore.ExistingLaneLock(status.Lane.ID, options.lockWait) + } else { + lock, err = laneStore.LaneLock(status.Lane.ID, options.lockWait) } - lock, err := laneStore.LaneLock(status.Lane.ID, options.lockWait) if err != nil { - return application.failure("commit", err, nil, 1) + return application.failure(action, err, nil, 1) } defer func() { _ = lock.Release() }() lane, err := laneStore.Load(status.Lane.ID) if err != nil { - return application.failure("commit", err, nil, 1) + return application.failure(action, err, nil, 1) } if lane.State != "active" || lane.Agent != status.Lane.Agent || lane.Session != status.Lane.Session || lane.Worktree != laneStore.Repo.Root { - return application.failure("commit", fail.New("LANE_MOVED", "lane identity, state, or worktree changed before capture"), nil, 1) + return application.failure(action, fail.New("LANE_MOVED", "lane identity, state, or worktree changed before capture"), nil, 1) + } + saved, err := loadProfile(laneStore, lane.ID) + if err != nil { + return application.failure(action, err, nil, 1) } allowed, err := laneStore.ActivePaths(lane.ID) if err != nil { - return application.failure("commit", err, nil, 1) + return application.failure(action, err, nil, 1) } if len(allowed) == 0 { - return application.failure("commit", fail.New("LEASE_REQUIRED", "claim or renew paths before capture"), nil, 1) + return application.failure(action, fail.New("LEASE_REQUIRED", "claim or renew paths before capture"), nil, 1) } - heartbeat := application.leaseHeartbeat - if heartbeat == nil { - heartbeat = startLeaseHeartbeat + + // A guided capture validates the exact reviewed plan before it renews a + // lease. The outer command preflight performs the same digest check before + // acquiring the repository writer fence; this locked check closes a plan + // file replacement between preflight and execution. + var resolved resolvedCommitPlan + if guided { + resolved, err = application.resolveGroups(ctx, laneStore, lane, allowed, saved.MessagePolicy, options) + if err != nil { + return application.failure(action, err, nil, 2) + } + if !resolved.Reviewed { + return application.failure(action, fail.New("REVIEWED_PLAN_REQUIRED", "capture requires the reviewed v3 plan schema; legacy arrays remain commit-only"), nil, 2) + } } - captureCtx, stopHeartbeat, err := heartbeat(ctx, laneStore, lane, allowed) - if err != nil { - return application.failure("commit", err, nil, 1) + + captureCtx := ctx + stopHeartbeat := func() error { return nil } + if !options.dryRun { + heartbeat := application.leaseHeartbeat + if heartbeat == nil { + heartbeat = startLeaseHeartbeat + } + captureCtx, stopHeartbeat, err = heartbeat(ctx, laneStore, lane, allowed) + if err != nil { + return application.failure(action, err, nil, 1) + } } heartbeatStopped := false stop := func() error { @@ -90,61 +165,162 @@ func (application app) runCommit(ctx context.Context, laneStore store.Store, arg return stopHeartbeat() } defer func() { _ = stop() }() - groups, err := application.resolveGroups(captureCtx, laneStore, lane.CurrentSHA, allowed, options) - if err != nil { - if heartbeatErr := stop(); heartbeatErr != nil { - return application.failure("commit", heartbeatErr, nil, 1) + if !guided { + resolved, err = application.resolveGroups(captureCtx, laneStore, lane, allowed, saved.MessagePolicy, options) + if err != nil { + if heartbeatErr := stop(); heartbeatErr != nil { + return application.failure(action, heartbeatErr, nil, 1) + } + return application.failure(action, err, nil, 2) } - return application.failure("commit", err, nil, 2) } + hookOutput := application.stdout if application.jsonMode { hookOutput = io.Discard } + var beforePublish func() error + if !options.dryRun { + beforePublish = func() error { return laneStore.RefreshCaptureLease(captureCtx, lane, allowed) } + } result, err := engine.Run(captureCtx, engine.Options{ Repo: laneStore.Repo, TargetRef: lane.Ref, ExpectedRef: lane.CurrentSHA, ExpectedSourceHead: lane.BaseSHA, + ExpectedSourceDigest: resolved.ExpectedSourceDigest, + SourceMode: resolved.SourceMode, + UntrackedPolicy: resolved.UntrackedPolicy, AllowedPaths: allowed, - Groups: groups, + Groups: resolved.Groups, + ReviewPlanDigest: resolved.ReviewDigest, + MessagePolicy: resolved.Policy, AllowWIP: options.allowWIP, DryRun: options.dryRun, HookTimeout: options.hookTimeout, DefaultVerifyTimeout: options.verifyTimeout, - BeforePublish: func() error { - return laneStore.RefreshCaptureLease(captureCtx, lane, allowed) - }, - Output: hookOutput, - ErrorOutput: application.stderr, + BeforePublish: beforePublish, + Output: hookOutput, + ErrorOutput: application.stderr, }) heartbeatErr := stop() if heartbeatErr != nil { - return application.failure("commit", heartbeatErr, result, 1) + return application.failure(action, heartbeatErr, result, 1) } if err != nil { - return application.failure("commit", err, result, 1) + return application.failure(action, err, result, 1) } if !options.dryRun { if err := laneStore.RecordCommit(ctx, lane.ID, result.FinalCommit); err != nil { - return application.failure("commit", err, result, 1) + return application.failure(action, err, result, 1) } intent, markErr := engine.MarkIntent(laneStore.Repo, result.PlanID, result.PlanDigest, "complete") if markErr != nil { - return application.failure("commit", markErr, result, 1) + return application.failure(action, markErr, result, 1) } result.IntentState = intent.State } human := fmt.Sprintf("captured %d commit(s) on %s", len(result.Commits), result.TargetRef) if options.dryRun { - human = fmt.Sprintf("all gates passed for a %d-commit split plan; no ref moved", len(result.Commits)) + hooks, verify := 0, 0 + if result.Execution != nil { + hooks = result.Execution.PreCommitHooks.Skipped + result.Execution.PostCommitHooks.Skipped + verify = result.Execution.VerifyCommands.Skipped + } + human = fmt.Sprintf("validated a %d-commit candidate structure; skipped %d repository hook invocation(s) and %d verify command(s); no ref moved", len(result.Commits), hooks, verify) } else { human += " -> " + result.FinalCommit } - return application.success("commit", result, human) + if !guided { + renewal := renewalStatus{Attempted: !options.dryRun, Succeeded: !options.dryRun} + laneContext, contextErr := laneContextFor(ctx, laneStore, lane.ID, renewal) + if contextErr != nil { + return application.failure(action, contextErr, result, 1) + } + return application.successWithContext(action, result, human, laneContext) + } + current, err := laneStore.Load(lane.ID) + if err != nil { + return application.failure(action, err, result, 1) + } + handoff, err := buildCaptureHandoff(ctx, laneStore, current, result.PlanID, result.PlanDigest) + if err != nil { + return application.failure(action, err, result, 1) + } + guidedResult := guidedCaptureResult{Capture: result, Handoff: handoff} + if options.final { + if application.beforeFinalRelease != nil { + application.beforeFinalRelease() + } + if err := laneStore.ReleaseWithLockHeld(current, false); err != nil { + return application.failure(action, err, guidedResult, 1) + } + guidedResult.LaneReleased = true + current, err = laneStore.Load(current.ID) + if err != nil { + return application.failure(action, err, guidedResult, 1) + } + } + status, statusErr := laneStore.Status(current.ID) + if statusErr != nil { + return application.failure(action, statusErr, guidedResult, 1) + } + operational, inspectErr := buildOperationalStatus(ctx, laneStore, status, renewalStatus{Attempted: true, Succeeded: true}) + if inspectErr != nil { + return application.failure(action, inspectErr, guidedResult, 1) + } + human = fmt.Sprintf("captured %d reviewed commit(s) on %s and emitted a capture-only handoff", len(result.Commits), result.TargetRef) + if options.final { + human += "; lane released" + } + return application.successWithContext(action, guidedResult, human, operational.context()) +} + +func (application app) parseCommitOptions(action string, args []string, guided bool) (commitOptions, error) { + set := application.flagSet(action) + options := commitOptions{} + options.identity.bind(set) + set.StringVar(&options.plan, "plan", "", "strict JSON split plan file, or - for stdin") + set.StringVar(&options.reviewPlanDigest, "review-plan-digest", "", "expected canonical SHA-256 digest of the reviewed plan") + set.BoolVar(&options.single, "single", false, "explicitly capture one commit instead of the split default") + set.StringVar(&options.message, "message", "", "single-commit message under the bound lane policy") + set.Var(&options.paths, "path", "staged path scope for --single (repeatable)") + set.BoolVar(&options.allowWIP, "allow-wip", false, "explicitly authorize the wip: commit prefix") + set.BoolVar(&options.dryRun, "dry-run", false, "validate candidate structure without executing hooks, verify commands, commits, or ref updates") + set.BoolVar(&options.noInteractive, "non-interactive", false, "fail instead of prompting for a split plan") + set.BoolVar(&options.final, "final", false, "release the lane after a validated capture handoff") + set.DurationVar(&options.hookTimeout, "hook-timeout", engine.DefaultHookTimeout, "pre/post-commit hook timeout") + set.DurationVar(&options.verifyTimeout, "verify-timeout", engine.DefaultVerifyTimeout, "default verify command timeout") + set.DurationVar(&options.lockWait, "lock-wait", 0, "time to wait for the lane lock; zero fails fast") + if err := set.Parse(args); err != nil { + return commitOptions{}, fail.Wrap("INVALID_ARGS", err) + } + if err := noArgs(set); err != nil { + return commitOptions{}, err + } + if guided && (options.plan == "" || options.single || options.message != "" || len(options.paths) > 0 || options.noInteractive || options.dryRun) { + return commitOptions{}, fail.New("REVIEWED_PLAN_REQUIRED", "capture requires one reviewed v3 --plan and does not accept --single, --message, --path, --non-interactive, or --dry-run") + } + if !guided && options.final { + return commitOptions{}, fail.New("INVALID_ARGS", "--final is available only with wip capture") + } + if !guided && options.reviewPlanDigest != "" { + return commitOptions{}, fail.New("INVALID_ARGS", "--review-plan-digest is available only with wip capture") + } + if options.reviewPlanDigest != "" && !validSHA256(options.reviewPlanDigest) { + return commitOptions{}, fail.New("INVALID_ARGS", "--review-plan-digest must be sha256 followed by 64 lowercase hexadecimal characters") + } + if options.lockWait < 0 { + return commitOptions{}, fail.New("INVALID_ARGS", "--lock-wait cannot be negative") + } + return options, nil } func startLeaseHeartbeat(parent context.Context, laneStore store.Store, lane store.Lane, allowed []string) (context.Context, func() error, error) { + return startLeaseHeartbeatWithObserver(parent, laneStore, lane, allowed, nil) +} + +func startLeaseHeartbeatWithObserver(parent context.Context, laneStore store.Store, lane store.Lane, allowed []string, afterBackgroundRefresh func()) (context.Context, func() error, error) { if err := laneStore.RefreshCaptureLease(parent, lane, allowed); err != nil { return nil, nil, fail.Wrap("LEASE_HEARTBEAT_FAILED", err) } @@ -176,6 +352,9 @@ func startLeaseHeartbeat(parent context.Context, laneStore store.Store, lane sto done <- fail.Wrap("LEASE_HEARTBEAT_FAILED", err) return } + if afterBackgroundRefresh != nil { + afterBackgroundRefresh() + } } } }() @@ -188,10 +367,10 @@ func startLeaseHeartbeat(parent context.Context, laneStore store.Store, lane sto return captureCtx, stop, nil } -func (application app) resolveGroups(ctx context.Context, laneStore store.Store, laneCommit string, allowed []string, options commitOptions) ([]engine.Group, error) { +func (application app) resolveGroups(ctx context.Context, laneStore store.Store, lane store.Lane, allowed []string, messagePolicy policy.Receipt, options commitOptions) (resolvedCommitPlan, error) { if options.plan != "" { if options.single || options.message != "" || len(options.paths) > 0 { - return nil, fail.New("INVALID_ARGS", "--plan cannot be combined with --single, --message, or --path") + return resolvedCommitPlan{}, fail.New("INVALID_ARGS", "--plan cannot be combined with --single, --message, or --path") } var reader io.Reader if options.plan == "-" { @@ -199,38 +378,63 @@ func (application app) resolveGroups(ctx context.Context, laneStore store.Store, } else { file, err := os.Open(options.plan) if err != nil { - return nil, fail.Wrap("INVALID_PLAN", err) + return resolvedCommitPlan{}, fail.Wrap("INVALID_PLAN", err) } defer func() { _ = file.Close() }() reader = file } - return decodePlan(reader) + resolved, err := decodeCommitPlan(reader) + if err != nil { + return resolvedCommitPlan{}, err + } + if resolved.Reviewed { + digest, digestErr := reviewPlanDigest(*resolved.Plan) + if digestErr != nil { + return resolvedCommitPlan{}, digestErr + } + if options.reviewPlanDigest != "" && digest != options.reviewPlanDigest { + return resolvedCommitPlan{}, fail.New("REVIEW_PLAN_DIGEST_MISMATCH", "reviewed plan does not match --review-plan-digest") + } + return validateReviewedPlan(ctx, laneStore, lane, allowed, resolved.Plan, options.allowWIP) + } + messages := make([]string, 0, len(resolved.Groups)) + for _, group := range resolved.Groups { + messages = append(messages, group.Message) + } + if err := policy.ValidateMessages(messagePolicy, messages, options.allowWIP); err != nil { + return resolvedCommitPlan{}, err + } + return resolved, nil } if options.single { if strings.TrimSpace(options.message) == "" { - return nil, fail.New("INVALID_ARGS", "--single requires --message") + return resolvedCommitPlan{}, fail.New("INVALID_ARGS", "--single requires --message") + } + if err := policy.Validate(messagePolicy, options.message, options.allowWIP); err != nil { + return resolvedCommitPlan{}, err } - selected, err := selectedStaged(ctx, laneStore, laneCommit, allowed, options.paths) + selected, err := selectedStaged(ctx, laneStore, lane.CurrentSHA, allowed, options.paths) if err != nil { - return nil, err + return resolvedCommitPlan{}, err } - return []engine.Group{{Message: options.message, Files: selected}}, nil + return resolvedCommitPlan{Groups: []engine.Group{{Message: options.message, Files: selected}}}, nil } if options.message != "" || len(options.paths) > 0 { - return nil, fail.New("SPLIT_PLAN_REQUIRED", "use --single to opt out, or omit --message and --path for the interactive split planner") + return resolvedCommitPlan{}, fail.New("SPLIT_PLAN_REQUIRED", "use --single to opt out, or omit --message and --path for the interactive split planner") } if options.noInteractive { - return nil, fail.New("SPLIT_PLAN_REQUIRED", "non-interactive capture requires --plan or an explicit --single") + return resolvedCommitPlan{}, fail.New("SPLIT_PLAN_REQUIRED", "non-interactive capture requires --plan or an explicit --single") } - selected, err := selectedStaged(ctx, laneStore, laneCommit, allowed, nil) + selected, err := selectedStaged(ctx, laneStore, lane.CurrentSHA, allowed, nil) if err != nil { - return nil, err + return resolvedCommitPlan{}, err } promptOutput := application.stdout if application.jsonMode { promptOutput = application.stderr } - return interactiveGroups(selected, options.allowWIP, prompt{reader: bufio.NewReader(application.stdin), out: promptOutput}) + groups, err := interactiveGroups(selected, messagePolicy, options.allowWIP, prompt{reader: bufio.NewReader(application.stdin), out: promptOutput}) + return resolvedCommitPlan{Groups: groups}, err } func decodePlan(reader io.Reader) ([]engine.Group, error) { @@ -241,14 +445,7 @@ func decodePlan(reader io.Reader) ([]engine.Group, error) { if len(body) > maxPlanBytes { return nil, fail.Errorf("INVALID_PLAN", "plan exceeds %d bytes", maxPlanBytes) } - var groups []engine.Group - if err := strictjson.Decode(body, &groups); err != nil { - return nil, fail.Wrap("INVALID_PLAN", err) - } - if len(groups) == 0 { - return nil, fail.New("INVALID_PLAN", "plan must contain at least one commit group") - } - return groups, nil + return decodeLegacyPlan(body) } func selectedStaged(ctx context.Context, laneStore store.Store, laneCommit string, allowed []string, requested []string) ([]string, error) { @@ -295,7 +492,7 @@ func selectedStaged(ctx context.Context, laneStore store.Store, laneCommit strin return selected, nil } -func interactiveGroups(paths []string, allowWIP bool, prompter prompt) ([]engine.Group, error) { +func interactiveGroups(paths []string, messagePolicy policy.Receipt, allowWIP bool, prompter prompt) ([]engine.Group, error) { proposals := proposeSplitGroups(paths) _, _ = fmt.Fprintln(prompter.out, "Proposed split groups (one ref update after every group passes):") for _, proposal := range proposals { @@ -316,7 +513,7 @@ func interactiveGroups(paths []string, allowWIP bool, prompter prompt) ([]engine if err != nil { return nil, err } - if err := engine.ValidateMessage(message, allowWIP); err != nil { + if err := policy.Validate(messagePolicy, message, allowWIP); err != nil { _, _ = fmt.Fprintf(prompter.out, "%s: %s\n", fail.Code(err), err) continue } @@ -339,7 +536,7 @@ func (application app) runReconcile(ctx context.Context, laneStore store.Store, identity.bind(set) planID := set.String("plan-id", "", "immutable plan id from the failed commit result") planDigest := set.String("plan-digest", "", "immutable sha256 plan digest") - lockWait := set.Duration("lock-wait", 0, "time to wait for the lane lock") + lockWait := set.Duration("lock-wait", 0, "time to wait for the lane lock; zero fails fast") if err := set.Parse(args); err != nil { return application.failure("reconcile", fail.Wrap("INVALID_ARGS", err), nil, 2) } @@ -368,7 +565,11 @@ func (application app) runReconcile(ctx context.Context, laneStore store.Store, } result := engine.ReconcileResult{PlanID: intent.PlanID, PlanDigest: intent.PlanDigest, Commit: intent.ExpectedNew, IntentState: intent.State, AlreadyClean: alreadyClean} if alreadyClean { - return application.success("reconcile", result, "plan is already fully reconciled") + laneContext, contextErr := laneContextFor(ctx, laneStore, lane.ID, renewalStatus{}) + if contextErr != nil { + return application.failure("reconcile", contextErr, result, 1) + } + return application.successWithContext("reconcile", result, "plan is already fully reconciled", laneContext) } if lane.CurrentSHA != intent.ExpectedNew { if err := laneStore.RecordCommit(ctx, lane.ID, intent.ExpectedNew); err != nil { @@ -386,5 +587,9 @@ func (application app) runReconcile(ctx context.Context, laneStore store.Store, return application.failure("reconcile", err, result, 1) } result.IntentState = intent.State - return application.success("reconcile", result, "reconciled lane "+lane.ID+" to "+intent.ExpectedNew) + laneContext, contextErr := laneContextFor(ctx, laneStore, lane.ID, renewalStatus{}) + if contextErr != nil { + return application.failure("reconcile", contextErr, result, 1) + } + return application.successWithContext("reconcile", result, "reconciled lane "+lane.ID+" to "+intent.ExpectedNew, laneContext) } diff --git a/cmd/wip/contract.go b/cmd/wip/contract.go new file mode 100644 index 0000000..07c30c1 --- /dev/null +++ b/cmd/wip/contract.go @@ -0,0 +1,25 @@ +package main + +import ( + "fmt" + + "github.com/nstranquist/wip-commit/internal/contract" + skillbundle "github.com/nstranquist/wip-commit/skills/wip-commit" +) + +type contractResult struct { + contract.Document + PortableBundleSHA256 string `json:"portable_bundle_sha256"` +} + +func currentContractResult() (contractResult, error) { + digest, err := skillbundle.PayloadDigest() + if err != nil { + return contractResult{}, err + } + return contractResult{Document: contract.Current(), PortableBundleSHA256: digest}, nil +} + +func (result contractResult) human() string { + return fmt.Sprintf("%s\nportable bundle %s", result.Protocol, result.PortableBundleSHA256) +} diff --git a/cmd/wip/contract_test.go b/cmd/wip/contract_test.go new file mode 100644 index 0000000..2d5e5fa --- /dev/null +++ b/cmd/wip/contract_test.go @@ -0,0 +1,31 @@ +package main + +import ( + "bytes" + "context" + "encoding/json" + "testing" + + "github.com/nstranquist/wip-commit/internal/contract" +) + +func TestContractCommandNeedsNoRepository(t *testing.T) { + var stdout, stderr bytes.Buffer + if code := run(context.Background(), []string{"--json", "contract"}, bytes.NewReader(nil), &stdout, &stderr); code != 0 { + t.Fatalf("contract exit = %d, stderr = %s", code, stderr.String()) + } + var result struct { + OK bool `json:"ok"` + Action string `json:"action"` + Data contractResult `json:"data"` + } + if err := json.Unmarshal(stdout.Bytes(), &result); err != nil { + t.Fatal(err) + } + if !result.OK || result.Action != "contract" || result.Data.Protocol != contract.Protocol { + t.Fatalf("contract result = %#v", result) + } + if result.Data.PortableBundleSHA256 == "" { + t.Fatal("contract omitted portable bundle digest") + } +} diff --git a/cmd/wip/doctor.go b/cmd/wip/doctor.go index e7c256c..7bf6497 100644 --- a/cmd/wip/doctor.go +++ b/cmd/wip/doctor.go @@ -32,7 +32,11 @@ type doctorReport struct { Healthy bool `json:"healthy"` StateRoot string `json:"state_root"` Domain string `json:"domain"` + DomainSchema int `json:"domain_schema_version"` StateVersion int `json:"state_version"` + MinimumReader string `json:"minimum_reader_protocol,omitempty"` + RequiredReaders []string `json:"required_reader_capabilities"` + UpgradeRequired bool `json:"upgrade_required"` Counts map[string]int `json:"counts"` ActiveLanes []string `json:"active_lanes"` ExpiredLanes []string `json:"expired_lease_lanes"` @@ -57,11 +61,15 @@ func (application app) runDoctor(ctx context.Context, repo gitx.Repo, args []str } report := doctorReport{ SchemaVersion: "1.0.0", State: "not-initialized", Healthy: true, - StateRoot: laneStore.Root, Domain: "github.com/nstranquist/wip-commit", StateVersion: store.SchemaVersion, + StateRoot: laneStore.Root, Domain: laneStore.Domain.Domain, DomainSchema: laneStore.Domain.SchemaVersion, StateVersion: laneStore.Domain.StateVersion, + MinimumReader: laneStore.Domain.MinimumReaderProtocol, RequiredReaders: append([]string{}, laneStore.Domain.RequiredCapabilities...), UpgradeRequired: laneStore.Domain.UpgradeRequired, Counts: map[string]int{}, ActiveLanes: []string{}, ExpiredLanes: []string{}, PendingInit: []string{}, PendingCapture: []string{}, PendingArchive: []string{}, ArchiveCandidates: []string{}, Findings: []doctorFinding{}, } if initialized { report.State = "initialized" + if report.UpgradeRequired { + report.Findings = append(report.Findings, doctorFinding{Severity: "recovery", Code: "STATE_UPGRADE_REQUIRED", Path: "domain.json", Message: "the legacy marker remains readable, but mutations require a reviewed wip upgrade --state plan"}) + } auditDoctor(ctx, laneStore, &report) } sort.Strings(report.ActiveLanes) diff --git a/cmd/wip/handoff.go b/cmd/wip/handoff.go new file mode 100644 index 0000000..4a7953f --- /dev/null +++ b/cmd/wip/handoff.go @@ -0,0 +1,252 @@ +package main + +import ( + "context" + "crypto/sha256" + "encoding/hex" + "encoding/json" + "fmt" + "time" + + "github.com/nstranquist/wip-commit/internal/engine" + "github.com/nstranquist/wip-commit/internal/fail" + "github.com/nstranquist/wip-commit/internal/filelock" + "github.com/nstranquist/wip-commit/internal/policy" + "github.com/nstranquist/wip-commit/internal/store" +) + +const ( + maxHandoffBytes = 16 << 20 + maxHandoffSegments = 1_000 + maxHandoffCommits = 10_000 +) + +type handoffCommit struct { + Index int `json:"index"` + Message string `json:"message"` + Parent string `json:"parent"` + Commit string `json:"commit"` + Tree string `json:"tree"` + ChangedPaths []string `json:"changed_paths"` + VerifyCount int `json:"verify_count"` + Repairs int `json:"repairs_applied"` +} + +type handoffSegment struct { + Index int `json:"index"` + PlanID string `json:"plan_id"` + CaptureIntentDigest string `json:"capture_intent_digest"` + ReviewedPlanDigest string `json:"reviewed_plan_digest,omitempty"` + MessagePolicy *policy.Receipt `json:"message_policy,omitempty"` + MessagePolicyBound bool `json:"message_policy_bound"` + IntentState string `json:"intent_state"` + SourceHead string `json:"source_head"` + SourceMode engine.SourceMode `json:"source_mode,omitempty"` + UntrackedPolicy engine.UntrackedPolicy `json:"untracked_policy,omitempty"` + SourceDigest string `json:"source_digest,omitempty"` + SourcePaths []string `json:"source_paths,omitempty"` + ParentCommit string `json:"parent_commit"` + FinalCommit string `json:"final_commit"` + FinalTree string `json:"final_tree"` + Commits []handoffCommit `json:"commits"` +} + +type captureHandoff struct { + SchemaVersion string `json:"schema_version"` + Kind string `json:"kind"` + HandoffDigest string `json:"handoff_digest"` + CaptureOnly bool `json:"capture_only"` + LandingAuthorized bool `json:"landing_authorized"` + ReviewEligible bool `json:"review_eligible"` + LaneRef string `json:"lane_ref"` + LaneTip string `json:"lane_tip"` + LaneBaseCommit string `json:"lane_base_commit"` + FinalTree string `json:"final_tree"` + TipPlanID string `json:"tip_plan_id"` + TipCaptureIntentDigest string `json:"tip_capture_intent_digest"` + Segments []handoffSegment `json:"segments"` +} + +type guidedCaptureResult struct { + Capture engine.Result `json:"capture"` + Handoff captureHandoff `json:"handoff"` + LaneReleased bool `json:"lane_released"` +} + +func buildCaptureHandoff(ctx context.Context, laneStore store.Store, lane store.Lane, planID, planDigest string) (captureHandoff, error) { + chain, err := engine.CompleteIntentChain(ctx, laneStore.Repo, lane.Ref, lane.BaseSHA, lane.CurrentSHA) + if err != nil { + return captureHandoff{}, err + } + if len(chain) == 0 { + return captureHandoff{}, fail.New("HANDOFF_NOT_READY", "lane has no completed capture intent chain") + } + if len(chain) > maxHandoffSegments { + return captureHandoff{}, fail.Errorf("HANDOFF_TOO_LARGE", "capture chain has %d segments; maximum is %d", len(chain), maxHandoffSegments) + } + tip := chain[len(chain)-1] + if planID != "" || planDigest != "" { + if planID == "" || planDigest == "" || tip.PlanID != planID || tip.PlanDigest != planDigest { + return captureHandoff{}, fail.New("HANDOFF_TIP_MISMATCH", "requested capture intent does not match the lane tip segment") + } + } + handoff := captureHandoff{ + SchemaVersion: "2.0.0", + Kind: "capture_handoff", + CaptureOnly: true, + LandingAuthorized: false, + ReviewEligible: true, + LaneRef: lane.Ref, + LaneTip: lane.CurrentSHA, + LaneBaseCommit: lane.BaseSHA, + FinalTree: tip.FinalTree, + TipPlanID: tip.PlanID, + TipCaptureIntentDigest: tip.PlanDigest, + Segments: make([]handoffSegment, 0, len(chain)), + } + for segmentIndex, intent := range chain { + messagePolicyBound := intent.ReviewPlanDigest != "" && intent.MessagePolicy != nil + segment := handoffSegment{ + Index: segmentIndex + 1, PlanID: intent.PlanID, CaptureIntentDigest: intent.PlanDigest, + ReviewedPlanDigest: intent.ReviewPlanDigest, MessagePolicy: intent.MessagePolicy, + MessagePolicyBound: messagePolicyBound, IntentState: intent.State, + SourceHead: intent.SourceHead, SourceMode: intent.SourceMode, UntrackedPolicy: intent.UntrackedPolicy, + SourceDigest: intent.SourceDigest, SourcePaths: append([]string(nil), intent.SourcePaths...), + ParentCommit: intent.ExpectedOld, FinalCommit: intent.ExpectedNew, FinalTree: intent.FinalTree, + Commits: make([]handoffCommit, 0, len(intent.Commits)), + } + if !messagePolicyBound || intent.SourceMode == "" || intent.UntrackedPolicy == "" || intent.SourceDigest == "" || len(intent.SourcePaths) == 0 { + handoff.ReviewEligible = false + } + for _, commit := range intent.Commits { + segment.Commits = append(segment.Commits, handoffCommit{ + Index: commit.Index, Message: commit.Message, Parent: commit.Parent, Commit: commit.Commit, + Tree: commit.Tree, ChangedPaths: append([]string(nil), commit.ChangedPaths...), + VerifyCount: commit.VerifyCount, Repairs: commit.Repairs, + }) + } + handoff.Segments = append(handoff.Segments, segment) + } + if count := handoffCommitCount(handoff); count > maxHandoffCommits { + return captureHandoff{}, fail.Errorf("HANDOFF_TOO_LARGE", "capture chain has %d commits; maximum is %d", count, maxHandoffCommits) + } + handoff.HandoffDigest, err = digestCaptureHandoff(handoff) + if err != nil { + return captureHandoff{}, err + } + return handoff, nil +} + +func digestCaptureHandoff(handoff captureHandoff) (string, error) { + handoff.HandoffDigest = "" + body, err := json.Marshal(handoff) + if err != nil { + return "", fail.Wrap("HANDOFF_INVALID", err) + } + if len(body) > maxHandoffBytes { + return "", fail.Errorf("HANDOFF_TOO_LARGE", "capture handoff is %d bytes; maximum is %d", len(body), maxHandoffBytes) + } + sum := sha256.Sum256(body) + return "sha256:" + hex.EncodeToString(sum[:]), nil +} + +func handoffCommitCount(handoff captureHandoff) int { + total := 0 + for _, segment := range handoff.Segments { + total += len(segment.Commits) + } + return total +} + +func (application app) runHandoff(ctx context.Context, laneStore store.Store, args []string) int { + set := application.flagSet("handoff") + var identity identityFlags + identity.bind(set) + planID := set.String("plan-id", "", "tip capture intent id (default complete lane chain)") + planDigest := set.String("plan-digest", "", "capture intent digest; required with --plan-id") + if err := set.Parse(args); err != nil { + return application.failure("handoff", fail.Wrap("INVALID_ARGS", err), nil, 2) + } + if err := noArgs(set); err != nil { + return application.failure("handoff", err, nil, 2) + } + if (*planID == "") != (*planDigest == "") { + return application.failure("handoff", fail.New("INVALID_ARGS", "--plan-id and --plan-digest must be supplied together"), nil, 2) + } + status, err := resolveHandoffStatus(laneStore, identity) + if err != nil { + return application.failure("handoff", err, nil, 1) + } + if status.Lane.State == "active" && !laneStore.WriterFenced() { + writerFence, fenceErr := store.AcquireWriterFence(laneStore.Repo, store.DefaultWriterFenceWait) + if fenceErr != nil { + return application.failure("handoff", fenceErr, nil, 1) + } + defer func() { _ = writerFence.Release() }() + writable, openErr := store.OpenWithWriterFence(laneStore.Repo, writerFence) + if openErr != nil { + return application.failure("handoff", openErr, nil, 1) + } + laneStore = writable + status, err = resolveHandoffStatus(laneStore, identity) + if err != nil { + return application.failure("handoff", err, nil, 1) + } + } + lock, err := laneStore.ExistingLaneLock(status.Lane.ID, filelock.DefaultWait) + if err != nil { + return application.failure("handoff", err, nil, 1) + } + defer func() { _ = lock.Release() }() + status, err = resolveHandoffStatus(laneStore, identity) + if err != nil { + return application.failure("handoff", err, nil, 1) + } + handoff, err := buildCaptureHandoff(ctx, laneStore, status.Lane, *planID, *planDigest) + if err != nil { + return application.failure("handoff", err, nil, 1) + } + if application.afterHandoffValidation != nil { + application.afterHandoffValidation() + } + renewal := renewalStatus{} + if status.Lane.State == "active" { + renewal.Attempted = true + if _, err := laneStore.RenewWithLockHeld(status.Lane); err != nil { + return application.failure("handoff", err, nil, 1) + } + now := time.Now().UTC() + renewal.Succeeded, renewal.RenewedAt = true, &now + status, err = laneStore.Status(status.Lane.ID) + if err != nil { + return application.failure("handoff", err, handoff, 1) + } + } + operational, inspectErr := buildOperationalStatus(ctx, laneStore, status, renewal) + if inspectErr != nil { + return application.failure("handoff", inspectErr, nil, 1) + } + human := fmt.Sprintf("cumulative capture-only handoff for %s at %s (%d segment(s), %d commit(s)); landing is not authorized", handoff.LaneRef, handoff.LaneTip, len(handoff.Segments), handoffCommitCount(handoff)) + return application.successWithContext("handoff", handoff, human, operational.context()) +} + +func resolveHandoffStatus(laneStore store.Store, identity identityFlags) (store.Status, error) { + if identity.lane == "" { + return resolveStatus(laneStore, identity) + } + saved, err := loadProfile(laneStore, identity.lane) + if err != nil { + return store.Status{}, err + } + if identity.agent != "" && identity.agent != saved.Agent || identity.session != "" && identity.session != saved.Session { + return store.Status{}, fail.New("IDENTITY_MISMATCH", "lane belongs to another agent or session") + } + status, err := laneStore.Status(identity.lane) + if err != nil { + return store.Status{}, err + } + if status.Lane.Worktree != laneStore.Repo.Root { + return store.Status{}, fail.New("WORKTREE_MISMATCH", "lane is bound to a different checkout") + } + return status, nil +} diff --git a/cmd/wip/init.go b/cmd/wip/init.go index 96d12ce..638406e 100644 --- a/cmd/wip/init.go +++ b/cmd/wip/init.go @@ -19,13 +19,16 @@ import ( "github.com/nstranquist/wip-commit/internal/atomicfile" "github.com/nstranquist/wip-commit/internal/fail" "github.com/nstranquist/wip-commit/internal/gitx" + "github.com/nstranquist/wip-commit/internal/policy" "github.com/nstranquist/wip-commit/internal/safeio" "github.com/nstranquist/wip-commit/internal/store" ) type initOptions struct { mode, lane, agent, session, baseRef string + messagePolicy string createWorktree, installDir, skillDir string + resolvedMessagePolicy policy.Receipt paths stringList nonInteractive, yes, dryRun bool install, noInstall bool @@ -33,32 +36,35 @@ type initOptions struct { } type initResult struct { - Version string `json:"version"` - DryRun bool `json:"dry_run"` - RepoDir string `json:"repo_dir"` - BaseSHA string `json:"base_sha"` - Lane *store.Lane `json:"lane,omitempty"` - Lease *store.Lease `json:"lease,omitempty"` - ClaimedPaths []string `json:"claimed_paths"` - ProfilePath string `json:"profile_path,omitempty"` - Worktree string `json:"worktree"` - CreatedWorktree bool `json:"created_worktree"` - InstallPath string `json:"install_path,omitempty"` - Installed bool `json:"installed"` - InstallAlreadyValid bool `json:"install_already_valid"` - InstallDirOnPath bool `json:"install_dir_on_path"` - SkillPath string `json:"skill_path,omitempty"` - SkillInstalled bool `json:"skill_installed"` - SkillAlreadyValid bool `json:"skill_already_valid"` - StagedPaths []string `json:"staged_paths"` - DiffCheckRun bool `json:"diff_check_run"` - DiffCheckPassed bool `json:"diff_check_passed"` - Environment string `json:"environment"` - IntentID string `json:"intent_id,omitempty"` - IntentPath string `json:"intent_path,omitempty"` - IntentState string `json:"intent_state,omitempty"` - CompletedSteps []string `json:"completed_steps,omitempty"` - Recovery []string `json:"recovery,omitempty"` + Version string `json:"version"` + DryRun bool `json:"dry_run"` + RepoDir string `json:"repo_dir"` + BaseSHA string `json:"base_sha"` + MessagePolicy policy.Receipt `json:"message_policy"` + ModeRecommendation string `json:"mode_recommendation"` + SharedModeWarning string `json:"shared_mode_warning,omitempty"` + Lane *store.Lane `json:"lane,omitempty"` + Lease *store.Lease `json:"lease,omitempty"` + ClaimedPaths []string `json:"claimed_paths"` + ProfilePath string `json:"profile_path,omitempty"` + Worktree string `json:"worktree"` + CreatedWorktree bool `json:"created_worktree"` + InstallPath string `json:"install_path,omitempty"` + Installed bool `json:"installed"` + InstallAlreadyValid bool `json:"install_already_valid"` + InstallDirOnPath bool `json:"install_dir_on_path"` + SkillPath string `json:"skill_path,omitempty"` + SkillInstalled bool `json:"skill_installed"` + SkillAlreadyValid bool `json:"skill_already_valid"` + StagedPaths []string `json:"staged_paths"` + DiffCheckRun bool `json:"diff_check_run"` + DiffCheckPassed bool `json:"diff_check_passed"` + Environment string `json:"environment"` + IntentID string `json:"intent_id,omitempty"` + IntentPath string `json:"intent_path,omitempty"` + IntentState string `json:"intent_state,omitempty"` + CompletedSteps []string `json:"completed_steps,omitempty"` + Recovery []string `json:"recovery,omitempty"` } type prompt struct { @@ -74,6 +80,7 @@ func (application app) runInit(ctx context.Context, source gitx.Repo, args []str set.StringVar(&options.agent, "agent", envDefault("WIP_AGENT"), "agent id") set.StringVar(&options.session, "session", envDefault("WIP_SESSION"), "session id") set.StringVar(&options.baseRef, "base-ref", "HEAD", "commit from which the lane starts") + set.StringVar(&options.messagePolicy, "message-policy", "", "named commit-message policy (default repo policy or conventional-v1)") set.StringVar(&options.createWorktree, "create-worktree", "", "create or reuse this linked worktree") set.Var(&options.paths, "path", "repository-relative path to claim (repeatable)") set.BoolVar(&options.nonInteractive, "non-interactive", false, "do not prompt; require explicit lane and paths") @@ -122,14 +129,10 @@ func (application app) runInit(ctx context.Context, source gitx.Repo, args []str func prepareInitOptions(ctx context.Context, source gitx.Repo, options *initOptions, prompter prompt) error { if options.mode == "" { - defaultMode := string(store.ModeShared) - if source.GitDir != source.CommonDir { - defaultMode = string(store.ModeWorktree) - } if options.nonInteractive { - options.mode = defaultMode + return fail.New("INVALID_ARGS", "--mode is required in non-interactive mode") } else { - value, err := prompter.ask("Lane mode (shared/worktree)", defaultMode) + value, err := prompter.ask("Lane mode (worktree recommended; shared only for co-located lanes)", string(store.ModeWorktree)) if err != nil { return err } @@ -146,11 +149,16 @@ func prepareInitOptions(ctx context.Context, source gitx.Repo, options *initOpti if options.nonInteractive { return fail.New("WORKTREE_REQUIRED", "worktree mode from an anchor checkout requires --create-worktree") } - value, err := prompter.ask("New linked worktree path", "") - if err != nil { - return err + for strings.TrimSpace(options.createWorktree) == "" { + value, err := prompter.ask("New linked worktree path", "") + if err != nil { + return err + } + options.createWorktree = value + if strings.TrimSpace(options.createWorktree) == "" { + _, _ = fmt.Fprintln(prompter.out, "A linked worktree path is required.") + } } - options.createWorktree = value } if !options.nonInteractive { value, err := prompter.ask("Base ref", options.baseRef) @@ -165,6 +173,11 @@ func prepareInitOptions(ctx context.Context, source gitx.Repo, options *initOpti if _, err := source.Text(ctx, nil, "rev-parse", "--verify", options.baseRef+"^{commit}"); err != nil { return fail.Wrap("BASE_NOT_FOUND", err) } + resolvedPolicy, err := policy.Load(source.Root, options.messagePolicy) + if err != nil { + return err + } + options.resolvedMessagePolicy = resolvedPolicy if options.agent == "" { options.agent = defaultAgent(ctx, source) } @@ -317,7 +330,19 @@ func prepareInitOptions(ctx context.Context, source gitx.Repo, options *initOpti } func executeInit(ctx context.Context, source gitx.Repo, options initOptions, prompter prompt, output io.Writer) (result initResult, returnErr error) { - result = initResult{Version: version, DryRun: options.dryRun, RepoDir: source.Root, Worktree: source.Root, StagedPaths: []string{}} + result = initResult{Version: version, DryRun: options.dryRun, RepoDir: source.Root, Worktree: source.Root, StagedPaths: []string{}, MessagePolicy: options.resolvedMessagePolicy, ModeRecommendation: "Use worktree mode for one agent per task."} + worktreeSource := source + if options.createWorktree != "" { + anchor, err := initWorktreeAnchor(ctx, source) + if err != nil { + return result, err + } + worktreeSource = anchor + result.RepoDir = anchor.Root + } + if options.mode == string(store.ModeShared) { + result.SharedModeWarning = "Shared mode is for lanes that must coexist in one checkout and shared index. Prefer worktree mode otherwise." + } defer func() { if returnErr != nil && result.IntentID != "" && result.IntentState == "pending" { result.Recovery = initRecovery(result, options) @@ -337,7 +362,7 @@ func executeInit(ctx context.Context, source gitx.Repo, options initOptions, pro } result.ClaimedPaths = normalized if !options.yes { - _, _ = fmt.Fprintf(output, "\nSetup summary:\n mode: %s\n lane: %s\n agent: %s\n session: %s\n base: %s\n paths: %s\n", options.mode, options.lane, options.agent, options.session, options.baseRef, strings.Join(normalized, ", ")) + _, _ = fmt.Fprintf(output, "\nSetup summary:\n mode: %s\n lane: %s\n agent: %s\n session: %s\n base: %s\n message policy: %s\n paths: %s\n", options.mode, options.lane, options.agent, options.session, options.baseRef, options.resolvedMessagePolicy.ID, strings.Join(normalized, ", ")) if options.createWorktree != "" { _, _ = fmt.Fprintf(output, " create worktree: %s\n", options.createWorktree) } @@ -355,19 +380,19 @@ func executeInit(ctx context.Context, source gitx.Repo, options initOptions, pro return result, fail.New("CANCELLED", "setup was not applied") } } - baseSHA, err := source.Text(ctx, nil, "rev-parse", "--verify", options.baseRef+"^{commit}") + baseSHA, err := worktreeSource.Text(ctx, nil, "rev-parse", "--verify", options.baseRef+"^{commit}") if err != nil { return result, fail.Wrap("BASE_NOT_FOUND", err) } result.BaseSHA = baseSHA if options.dryRun { - if err := store.Check(source); err != nil { + if err := store.Check(worktreeSource); err != nil { return result, err } target := source targetExists := true if options.createWorktree != "" { - target, targetExists, err = inspectWorktree(ctx, source, options.createWorktree, baseSHA) + target, targetExists, err = inspectWorktree(ctx, worktreeSource, options.createWorktree, baseSHA) if err != nil { return result, err } @@ -386,7 +411,7 @@ func executeInit(ctx context.Context, source gitx.Repo, options initOptions, pro return result, err } } - result.Environment = shellEnvironment(profile{SchemaVersion: profileSchemaVersion, Lane: options.lane, Agent: options.agent, Session: options.session, Mode: store.Mode(options.mode), Worktree: result.Worktree}) + result.Environment = shellEnvironment(profile{SchemaVersion: profileSchemaVersion, Lane: options.lane, Agent: options.agent, Session: options.session, Mode: store.Mode(options.mode), Worktree: result.Worktree, MessagePolicy: options.resolvedMessagePolicy}) if options.install { result.InstallPath, _, result.InstallAlreadyValid, err = inspectSelfInstall(options.installDir) if err != nil { @@ -419,11 +444,16 @@ func executeInit(ctx context.Context, source gitx.Repo, options initOptions, pro plannedWorktree = options.createWorktree } result.Worktree = plannedWorktree - coordinationStore, err := store.Open(source) + writerFence, err := store.AcquireWriterFence(worktreeSource, store.DefaultWriterFenceWait) + if err != nil { + return result, err + } + defer func() { _ = writerFence.Release() }() + coordinationStore, err := store.OpenWithWriterFence(worktreeSource, writerFence) if err != nil { return result, err } - candidateIntent := initIntent{Lane: options.lane, Agent: options.agent, Session: options.session, Mode: store.Mode(options.mode), BaseSHA: baseSHA, Worktree: plannedWorktree, Paths: normalized} + candidateIntent := initIntent{Lane: options.lane, Agent: options.agent, Session: options.session, Mode: store.Mode(options.mode), BaseSHA: baseSHA, Worktree: plannedWorktree, Paths: normalized, MessagePolicy: &options.resolvedMessagePolicy} if options.install { candidateIntent.InstallPath = filepath.Join(options.installDir, binaryName()) } @@ -435,80 +465,109 @@ func executeInit(ctx context.Context, source gitx.Repo, options initOptions, pro return result, err } updateResultIntent(&result, intent, intentPath) - markStep := func(step string) error { - updated, markErr := markInitStep(intentPath, intent, step) - if markErr != nil { - return markErr - } - intent = updated + intent, err = runInitTransaction(intentPath, intent, func(transaction *initTransaction) error { + intent = transaction.intent updateResultIntent(&result, intent, intentPath) - return nil - } - target := source - if options.createWorktree != "" { - var created bool - target, created, err = ensureWorktree(ctx, source, options.createWorktree, baseSHA) + markStep := func(step string) error { + updated, markErr := transaction.mark(step) + if markErr != nil { + return markErr + } + intent = updated + updateResultIntent(&result, intent, intentPath) + return nil + } + target := source + if options.createWorktree != "" { + var created bool + target, created, err = ensureWorktree(ctx, worktreeSource, options.createWorktree, baseSHA) + if err != nil { + return err + } + result.CreatedWorktree = created + } + result.Worktree = target.Root + if err := markStep("worktree-ready"); err != nil { + return err + } + laneStore, err := store.OpenWithWriterFence(target, writerFence) if err != nil { - return result, err + return err } - result.CreatedWorktree = created - } - result.Worktree = target.Root - if err := markStep("worktree-ready"); err != nil { - return result, err - } - laneStore, err := store.Open(target) - if err != nil { - return result, err - } - lane, err := ensureLane(ctx, laneStore, options, baseSHA) - if err != nil { - return result, err - } - result.Lane = &lane - if err := markStep("lane-ready"); err != nil { - return result, err - } - lease, err := laneStore.Claim(lane.ID, lane.Agent, lane.Session, normalized) + lane, err := ensureLane(ctx, laneStore, options, baseSHA) + if err != nil { + return err + } + result.Lane = &lane + if err := markStep("lane-ready"); err != nil { + return err + } + lease, err := laneStore.Claim(lane.ID, lane.Agent, lane.Session, normalized) + if err != nil { + return err + } + result.Lease = &lease + if err := markStep("lease-ready"); err != nil { + return err + } + result.ProfilePath, err = writeProfile(laneStore, lane, options.resolvedMessagePolicy) + if err != nil { + return err + } + if err := markStep("profile-ready"); err != nil { + return err + } + saved := profile{SchemaVersion: profileSchemaVersion, Lane: lane.ID, Agent: lane.Agent, Session: lane.Session, Mode: lane.Mode, Worktree: lane.Worktree, MessagePolicy: options.resolvedMessagePolicy} + result.Environment = shellEnvironment(saved) + if err := inspectStagedGit(ctx, target, &result); err != nil { + return err + } + if options.install { + result.InstallPath, result.Installed, result.InstallAlreadyValid, err = installSelf(options.installDir) + if err != nil { + return err + } + result.InstallDirOnPath = directoryOnPath(options.installDir) + } + if err := markStep("binary-ready"); err != nil { + return err + } + if options.installSkill { + result.SkillPath, result.SkillInstalled, result.SkillAlreadyValid, err = installPortableSkill(options.skillDir) + if err != nil { + return err + } + } + return markStep("skill-ready") + }) if err != nil { return result, err } - result.Lease = &lease - if err := markStep("lease-ready"); err != nil { - return result, err - } - result.ProfilePath, err = writeProfile(laneStore, lane) + updateResultIntent(&result, intent, intentPath) + return result, nil +} + +// initWorktreeAnchor returns the primary checkout for the shared Git directory. +// A recovery command can run from the linked worktree that it is recovering; +// worktree creation must still be evaluated from the primary checkout. +func initWorktreeAnchor(ctx context.Context, source gitx.Repo) (gitx.Repo, error) { + if source.GitDir == source.CommonDir { + return source, nil + } + listing, err := source.Raw(ctx, nil, "worktree", "list", "--porcelain", "-z") if err != nil { - return result, err + return gitx.Repo{}, fail.Wrap("WORKTREE_ANCHOR_NOT_FOUND", err) } - if err := markStep("profile-ready"); err != nil { - return result, err - } - saved := profile{SchemaVersion: profileSchemaVersion, Lane: lane.ID, Agent: lane.Agent, Session: lane.Session, Mode: lane.Mode, Worktree: lane.Worktree} - result.Environment = shellEnvironment(saved) - if err := inspectStagedGit(ctx, target, &result); err != nil { - return result, err - } - if options.install { - result.InstallPath, result.Installed, result.InstallAlreadyValid, err = installSelf(options.installDir) - if err != nil { - return result, err + for _, field := range strings.Split(listing, "\x00") { + if !strings.HasPrefix(field, "worktree ") { + continue } - result.InstallDirOnPath = directoryOnPath(options.installDir) - } - if err := markStep("binary-ready"); err != nil { - return result, err - } - if options.installSkill { - result.SkillPath, result.SkillInstalled, result.SkillAlreadyValid, err = installPortableSkill(options.skillDir) - if err != nil { - return result, err + candidate, discoverErr := gitx.Discover(ctx, strings.TrimPrefix(field, "worktree ")) + if discoverErr == nil && candidate.CommonDir == source.CommonDir && candidate.GitDir == candidate.CommonDir { + return candidate, nil } } - if err := markStep("skill-ready"); err != nil { - return result, err - } - return result, nil + return gitx.Repo{}, fail.New("WORKTREE_ANCHOR_NOT_FOUND", "primary checkout for the linked worktree is unavailable") } func ensureLane(ctx context.Context, laneStore store.Store, options initOptions, baseSHA string) (store.Lane, error) { @@ -774,9 +833,15 @@ func formatInitResult(result initResult) string { if result.Lane != nil { lines = append(lines, fmt.Sprintf("Initialized %s lane %s on %s.", result.Lane.Mode, result.Lane.ID, result.Lane.Ref)) } + if result.SharedModeWarning != "" { + lines = append(lines, result.SharedModeWarning) + } if result.CreatedWorktree { lines = append(lines, "Created linked worktree "+result.Worktree+".") } + if result.Lane != nil && result.Lane.Mode == store.ModeWorktree && result.Worktree != "" && result.Worktree != result.RepoDir { + lines = append(lines, "Continue in linked worktree "+result.Worktree+".") + } if result.InstallPath != "" { state := "Installed" if result.InstallAlreadyValid { @@ -797,7 +862,7 @@ func formatInitResult(result initResult) string { if result.DiffCheckRun && !result.DiffCheckPassed { lines = append(lines, "The staged diff has whitespace errors. Fix them before capture.") } - lines = append(lines, "Use this environment in the agent shell:", result.Environment, "Then run: wip commit") + lines = append(lines, "Use this environment in the agent shell:", result.Environment, "Then run: wip plan --out plan.json, review the plan, and use wip capture --plan plan.json") return strings.Join(lines, "\n") } diff --git a/cmd/wip/init_abort.go b/cmd/wip/init_abort.go new file mode 100644 index 0000000..87d0b70 --- /dev/null +++ b/cmd/wip/init_abort.go @@ -0,0 +1,245 @@ +package main + +import ( + "context" + "errors" + "fmt" + "os" + "path/filepath" + "runtime" + "strings" + + "github.com/nstranquist/wip-commit/internal/fail" + "github.com/nstranquist/wip-commit/internal/filelock" + "github.com/nstranquist/wip-commit/internal/gitx" + "github.com/nstranquist/wip-commit/internal/store" +) + +type initAbortResult struct { + SchemaVersion string `json:"schema_version"` + IntentID string `json:"intent_id"` + IntentDigest string `json:"intent_digest"` + Lane string `json:"lane"` + Agent string `json:"agent"` + Session string `json:"session"` + CompletedSteps []string `json:"completed_steps"` + CanAbort bool `json:"can_abort"` + Applied bool `json:"applied"` + ArchiveRef string `json:"archive_ref,omitempty"` + ArchiveObject string `json:"archive_object,omitempty"` +} + +func (application app) runInitAbort(ctx context.Context, repo gitx.Repo, args []string) int { + set := application.flagSet("init-abort") + intentID := set.String("intent", "", "pending initialization intent id") + intentDigest := set.String("intent-digest", "", "exact digest from the reviewed preview") + apply := set.Bool("apply", false, "remove the reviewed safe intent") + yes := set.Bool("yes", false, "confirm the reviewed abort") + if err := set.Parse(args); err != nil { + return application.failure("init-abort", fail.Wrap("INVALID_ARGS", err), nil, 2) + } + if err := noArgs(set); err != nil { + return application.failure("init-abort", err, nil, 2) + } + if strings.TrimSpace(*intentID) == "" { + return application.failure("init-abort", fail.New("INVALID_ARGS", "--intent is required"), nil, 2) + } + if *apply != *yes { + return application.failure("init-abort", fail.New("INVALID_ARGS", "abort requires both --apply and --yes"), nil, 2) + } + if *apply && strings.TrimSpace(*intentDigest) == "" { + return application.failure("init-abort", fail.New("INVALID_ARGS", "--intent-digest is required with --apply"), nil, 2) + } + + laneStore, initialized, err := store.Inspect(repo) + if err != nil { + return application.failure("init-abort", err, nil, 1) + } + if !initialized { + return application.failure("init-abort", fail.New("LANE_NOT_ACTIVE", "wip state is not initialized"), nil, 1) + } + if *apply { + writerFence, fenceErr := store.AcquireWriterFence(repo, store.DefaultWriterFenceWait) + if fenceErr != nil { + return application.failure("init-abort", fenceErr, nil, 1) + } + defer func() { _ = writerFence.Release() }() + laneStore, err = store.OpenWithWriterFence(repo, writerFence) + if err != nil { + return application.failure("init-abort", err, nil, 1) + } + } + result, err := inspectInitAbort(ctx, laneStore, *intentID, *intentDigest, *apply) + if err != nil { + return application.failure("init-abort", err, result, 1) + } + human := fmt.Sprintf("initialization intent %s can be safely aborted with digest %s", result.IntentID, result.IntentDigest) + if result.Applied { + human = fmt.Sprintf("aborted pre-lane initialization intent %s", result.IntentID) + } + return application.success("init-abort", result, human) +} + +func inspectInitAbort(ctx context.Context, laneStore store.Store, id, expectedDigest string, apply bool) (initAbortResult, error) { + result := initAbortResult{SchemaVersion: "1.0.0"} + if err := store.ValidateID(id, "init intent"); err != nil || !strings.HasPrefix(id, "init-") { + if err == nil { + err = fail.New("INVALID_ID", "initialization intent id must use the init- prefix") + } + return result, err + } + intentPath := filepath.Join(laneStore.Root, "init-intents", id+".json") + lock, err := filelock.Acquire(initIntentLockPath(intentPath), filelock.DefaultWait) + if err != nil { + return result, fail.Wrap("LOCK_TIMEOUT", err) + } + defer func() { _ = lock.Release() }() + + archiveRef := "refs/wip/init-aborts/" + id + intent, archiveObject, archived, err := loadInitAbortIntent(ctx, laneStore, intentPath, archiveRef) + if err != nil { + return result, err + } + result.IntentID = intent.ID + result.IntentDigest = intent.Digest + result.Lane = intent.Lane + result.Agent = intent.Agent + result.Session = intent.Session + result.CompletedSteps = append([]string(nil), intent.CompletedSteps...) + result.ArchiveRef = archiveRef + result.ArchiveObject = archiveObject + if expectedDigest != "" && expectedDigest != intent.Digest { + return result, fail.New("INIT_INTENT_MOVED", "initialization intent digest does not match the reviewed preview") + } + if archived { + result.CanAbort = true + result.Applied = true + return result, nil + } + if intent.State != "pending" { + return result, fail.New("INIT_ABORT_REFUSED", "only a pending initialization intent can be aborted") + } + if len(intent.CompletedSteps) > 1 || len(intent.CompletedSteps) == 1 && intent.CompletedSteps[0] != "worktree-ready" { + return result, fail.New("INIT_ABORT_REFUSED", "initialization reached lane creation; use its typed lane recovery") + } + if _, loadErr := laneStore.Load(intent.Lane); loadErr == nil || fail.Code(loadErr) != "LANE_NOT_FOUND" { + if loadErr == nil { + loadErr = fail.New("INIT_ABORT_REFUSED", "initialization created a lane record") + } + return result, loadErr + } + if _, profileErr := os.Lstat(filepath.Join(laneStore.Root, "profiles", intent.Lane+".json")); profileErr == nil || !errors.Is(profileErr, os.ErrNotExist) { + if profileErr == nil { + profileErr = fail.New("INIT_ABORT_REFUSED", "initialization created a lane profile") + } + return result, profileErr + } + ref := store.LaneRef(intent.Agent, intent.Lane) + if _, refErr := laneStore.Repo.Text(ctx, nil, "rev-parse", "--verify", ref+"^{commit}"); refErr == nil { + return result, fail.New("INIT_ABORT_REFUSED", "initialization created a lane ref") + } + leaseEntries, err := os.ReadDir(filepath.Join(laneStore.Root, "leases")) + if err != nil { + return result, fail.Wrap("INIT_ABORT_REFUSED", err) + } + if len(leaseEntries) > maxDoctorEntries { + return result, fail.New("INIT_ABORT_REFUSED", "lease registry exceeds the bounded recovery scan") + } + for _, entry := range leaseEntries { + if entry.IsDir() || entry.Type()&os.ModeSymlink != 0 || !strings.HasSuffix(entry.Name(), ".json") { + return result, fail.New("INIT_ABORT_REFUSED", "lease registry contains an unexpected entry") + } + leaseID := strings.TrimSuffix(entry.Name(), ".json") + lease, loadErr := laneStore.LoadLease(leaseID) + if loadErr != nil { + return result, loadErr + } + if lease.LaneID == intent.Lane { + return result, fail.New("INIT_ABORT_REFUSED", "initialization created a path lease") + } + } + result.CanAbort = true + if !apply { + return result, nil + } + archiveObject, err = publishInitAbortArchive(ctx, laneStore.Repo, intentPath, archiveRef, intent) + if err != nil { + return result, err + } + result.ArchiveObject = archiveObject + if err := os.Remove(intentPath); err != nil { + return result, fail.Wrap("INIT_ABORT_FAILED", err) + } + result.Applied = true + if runtime.GOOS != "windows" { + directory, openErr := os.Open(filepath.Dir(intentPath)) + if openErr != nil { + return result, fail.Wrap("INIT_ABORT_FAILED", openErr) + } + syncErr := directory.Sync() + closeErr := directory.Close() + if syncErr != nil { + return result, fail.Wrap("INIT_ABORT_FAILED", syncErr) + } + if closeErr != nil { + return result, fail.Wrap("INIT_ABORT_FAILED", closeErr) + } + } + return result, nil +} + +func loadInitAbortIntent(ctx context.Context, laneStore store.Store, intentPath, archiveRef string) (initIntent, string, bool, error) { + intent, err := loadInitIntent(intentPath) + if err == nil { + return intent, "", false, nil + } + if fail.Code(err) != "INIT_INTENT_NOT_FOUND" { + return initIntent{}, "", false, err + } + object, refErr := laneStore.Repo.Text(ctx, nil, "rev-parse", "--verify", archiveRef+"^{blob}") + if refErr != nil { + return initIntent{}, "", false, err + } + body, blobErr := laneStore.Repo.Raw(ctx, nil, "cat-file", "blob", object) + if blobErr != nil { + return initIntent{}, "", false, fail.Wrap("INIT_ABORT_FAILED", blobErr) + } + intent, decodeErr := decodeInitIntent([]byte(body)) + if decodeErr != nil { + return initIntent{}, "", false, decodeErr + } + if intent.ID != strings.TrimSuffix(filepath.Base(intentPath), ".json") { + return initIntent{}, "", false, fail.New("INIT_ABORT_FAILED", "archived initialization intent identity does not match the requested intent") + } + return intent, object, true, nil +} + +func publishInitAbortArchive(ctx context.Context, repo gitx.Repo, intentPath, archiveRef string, intent initIntent) (string, error) { + if _, err := repo.Text(ctx, nil, "check-ref-format", archiveRef); err != nil { + return "", fail.Wrap("INIT_ABORT_FAILED", err) + } + object, err := repo.Text(ctx, nil, "hash-object", "-w", "--", intentPath) + if err != nil { + return "", fail.Wrap("INIT_ABORT_FAILED", err) + } + existing, refErr := repo.Text(ctx, nil, "rev-parse", "--verify", archiveRef+"^{blob}") + if refErr == nil { + if existing != object { + return "", fail.New("INIT_ABORT_REFUSED", "initialization abort archive ref already contains different evidence") + } + } else if _, err := repo.Text(ctx, nil, "update-ref", "-m", "wip init-abort: preserve recovery evidence", archiveRef, object, ""); err != nil { + return "", fail.Wrap("INIT_ABORT_FAILED", err) + } + body, err := repo.Raw(ctx, nil, "cat-file", "blob", object) + if err != nil { + return "", fail.Wrap("INIT_ABORT_FAILED", err) + } + archived, err := decodeInitIntent([]byte(body)) + if err != nil { + return "", err + } + if archived.ID != intent.ID || archived.Digest != intent.Digest { + return "", fail.New("INIT_ABORT_FAILED", "archived initialization evidence does not match the active intent") + } + return object, nil +} diff --git a/cmd/wip/init_abort_test.go b/cmd/wip/init_abort_test.go new file mode 100644 index 0000000..806ea4e --- /dev/null +++ b/cmd/wip/init_abort_test.go @@ -0,0 +1,221 @@ +package main + +import ( + "context" + "os" + "path/filepath" + "testing" + "time" + + "github.com/nstranquist/wip-commit/internal/fail" + "github.com/nstranquist/wip-commit/internal/gitx" + "github.com/nstranquist/wip-commit/internal/store" +) + +func TestInitAbortRequiresReviewedDigestAndRemovesOnlyPreLaneIntent(t *testing.T) { + directory := cliTestRepo(t) + repo, err := gitx.Discover(context.Background(), directory) + if err != nil { + t.Fatal(err) + } + laneStore, err := store.Open(repo) + if err != nil { + t.Fatal(err) + } + base := cliGit(t, directory, "rev-parse", "HEAD") + intent, intentPath, err := beginInitIntent(laneStore, initIntent{ + Lane: "failed-setup", Agent: "agent", Session: "session", Mode: store.ModeShared, + BaseSHA: base, Worktree: directory, Paths: []string{"core.txt"}, + }) + if err != nil { + t.Fatal(err) + } + intent, err = markInitStep(intentPath, intent, "worktree-ready") + if err != nil { + t.Fatal(err) + } + + preview := runCLI(t, []string{"--json", "--repo-dir", directory, "init-abort", "--intent", intent.ID}, "") + if preview.code != 0 || !preview.envelope.OK { + t.Fatalf("preview: %#v stderr=%s", preview.envelope, preview.stderr) + } + var previewResult initAbortResult + decodeData(t, preview.envelope.Data, &previewResult) + if !previewResult.CanAbort || previewResult.Applied || previewResult.IntentDigest != intent.Digest { + t.Fatalf("preview result = %#v", previewResult) + } + + moved := runCLI(t, []string{"--json", "--repo-dir", directory, "init-abort", "--intent", intent.ID, "--intent-digest", "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "--apply", "--yes"}, "") + if moved.code == 0 || moved.envelope.Error == nil || moved.envelope.Error.Code != "INIT_INTENT_MOVED" { + t.Fatalf("moved result = %#v", moved.envelope) + } + if _, err := os.Stat(intentPath); err != nil { + t.Fatalf("intent changed after rejected digest: %v", err) + } + + aborted := runCLI(t, []string{"--json", "--repo-dir", directory, "init-abort", "--intent", intent.ID, "--intent-digest", intent.Digest, "--apply", "--yes"}, "") + if aborted.code != 0 || !aborted.envelope.OK { + t.Fatalf("abort: %#v stderr=%s", aborted.envelope, aborted.stderr) + } + var abortedResult initAbortResult + decodeData(t, aborted.envelope.Data, &abortedResult) + if !abortedResult.CanAbort || !abortedResult.Applied { + t.Fatalf("abort result = %#v", abortedResult) + } + if abortedResult.ArchiveRef == "" || abortedResult.ArchiveObject == "" { + t.Fatalf("missing archive evidence: %#v", abortedResult) + } + if _, err := os.Stat(intentPath); !os.IsNotExist(err) { + t.Fatalf("intent still exists: %v", err) + } + if got := cliGit(t, directory, "rev-parse", "--verify", abortedResult.ArchiveRef+"^{blob}"); got != abortedResult.ArchiveObject { + t.Fatalf("archive ref = %q, want %q", got, abortedResult.ArchiveObject) + } + + retry := runCLI(t, []string{"--json", "--repo-dir", directory, "init-abort", "--intent", intent.ID, "--intent-digest", intent.Digest, "--apply", "--yes"}, "") + if retry.code != 0 || !retry.envelope.OK { + t.Fatalf("idempotent retry: %#v stderr=%s", retry.envelope, retry.stderr) + } + var retryResult initAbortResult + decodeData(t, retry.envelope.Data, &retryResult) + if !retryResult.Applied || retryResult.ArchiveObject != abortedResult.ArchiveObject { + t.Fatalf("retry result = %#v", retryResult) + } +} + +func TestInitAbortRefusesIntentAfterLaneCreation(t *testing.T) { + directory := cliTestRepo(t) + repo, err := gitx.Discover(context.Background(), directory) + if err != nil { + t.Fatal(err) + } + laneStore, err := store.Open(repo) + if err != nil { + t.Fatal(err) + } + base := cliGit(t, directory, "rev-parse", "HEAD") + intent, intentPath, err := beginInitIntent(laneStore, initIntent{ + Lane: "created-lane", Agent: "agent", Session: "session", Mode: store.ModeShared, + BaseSHA: base, Worktree: directory, Paths: []string{"core.txt"}, + }) + if err != nil { + t.Fatal(err) + } + intent, err = markInitStep(intentPath, intent, "worktree-ready") + if err != nil { + t.Fatal(err) + } + if _, err := laneStore.Create(context.Background(), store.CreateOptions{ + ID: intent.Lane, Agent: intent.Agent, Session: intent.Session, + BaseRef: base, Mode: store.ModeShared, Worktree: directory, + }); err != nil { + t.Fatal(err) + } + + result, err := inspectInitAbort(context.Background(), laneStore, intent.ID, intent.Digest, true) + if fail.Code(err) != "INIT_ABORT_REFUSED" || result.Applied { + t.Fatalf("result = %#v, err = %v", result, err) + } + if _, err := os.Stat(intentPath); err != nil { + t.Fatalf("intent changed after refusal: %v", err) + } + if _, err := os.Stat(filepath.Join(laneStore.Root, "lanes", intent.Lane+".json")); err != nil { + t.Fatalf("lane changed after refusal: %v", err) + } +} + +func TestInitAbortWaitsForInitTransactionBeforeLaneDecision(t *testing.T) { + directory := cliTestRepo(t) + repo, err := gitx.Discover(context.Background(), directory) + if err != nil { + t.Fatal(err) + } + laneStore, err := store.Open(repo) + if err != nil { + t.Fatal(err) + } + base := cliGit(t, directory, "rev-parse", "HEAD") + intent, intentPath, err := beginInitIntent(laneStore, initIntent{ + Lane: "racing-setup", Agent: "agent", Session: "session", Mode: store.ModeShared, + BaseSHA: base, Worktree: directory, Paths: []string{"core.txt"}, + }) + if err != nil { + t.Fatal(err) + } + intent, err = markInitStep(intentPath, intent, "worktree-ready") + if err != nil { + t.Fatal(err) + } + + transactionStarted := make(chan struct{}) + allowLaneCreation := make(chan struct{}) + transactionDone := make(chan error, 1) + go func() { + _, transactionErr := runInitTransaction(intentPath, intent, func(transaction *initTransaction) error { + close(transactionStarted) + <-allowLaneCreation + if _, createErr := laneStore.Create(context.Background(), store.CreateOptions{ + ID: intent.Lane, Agent: intent.Agent, Session: intent.Session, + BaseRef: base, Mode: store.ModeShared, Worktree: directory, + }); createErr != nil { + return createErr + } + _, markErr := transaction.mark("lane-ready") + return markErr + }) + transactionDone <- transactionErr + }() + select { + case <-transactionStarted: + case <-time.After(2 * time.Second): + t.Fatal("initialization transaction did not start") + } + + type abortOutcome struct { + result initAbortResult + err error + } + abortStarted := make(chan struct{}) + abortDone := make(chan abortOutcome, 1) + go func() { + close(abortStarted) + result, abortErr := inspectInitAbort(context.Background(), laneStore, intent.ID, intent.Digest, true) + abortDone <- abortOutcome{result: result, err: abortErr} + }() + <-abortStarted + + var premature *abortOutcome + select { + case outcome := <-abortDone: + premature = &outcome + case <-time.After(100 * time.Millisecond): + } + if _, statErr := os.Stat(intentPath); statErr != nil { + close(allowLaneCreation) + t.Fatalf("abort changed the intent during initialization: %v", statErr) + } + close(allowLaneCreation) + select { + case transactionErr := <-transactionDone: + if transactionErr != nil { + t.Fatalf("initialization transaction: %v", transactionErr) + } + case <-time.After(2 * time.Second): + t.Fatal("initialization transaction did not finish") + } + if premature != nil { + t.Fatalf("abort completed inside the initialization transaction: result=%#v err=%v", premature.result, premature.err) + } + var outcome abortOutcome + select { + case outcome = <-abortDone: + case <-time.After(2 * time.Second): + t.Fatal("abort did not finish after initialization released its lock") + } + if fail.Code(outcome.err) != "INIT_ABORT_REFUSED" || outcome.result.Applied { + t.Fatalf("abort result = %#v, err = %v", outcome.result, outcome.err) + } + if _, statErr := os.Stat(intentPath); statErr != nil { + t.Fatalf("refused abort changed the intent: %v", statErr) + } +} diff --git a/cmd/wip/init_intent.go b/cmd/wip/init_intent.go index eb038e2..7dce04b 100644 --- a/cmd/wip/init_intent.go +++ b/cmd/wip/init_intent.go @@ -14,6 +14,7 @@ import ( "github.com/nstranquist/wip-commit/internal/atomicfile" "github.com/nstranquist/wip-commit/internal/fail" "github.com/nstranquist/wip-commit/internal/filelock" + "github.com/nstranquist/wip-commit/internal/policy" "github.com/nstranquist/wip-commit/internal/recordjson" "github.com/nstranquist/wip-commit/internal/safeio" "github.com/nstranquist/wip-commit/internal/store" @@ -21,8 +22,9 @@ import ( ) const ( - initIntentSchemaVersion = 1 - maxInitIntentBytes = 1 << 20 + initIntentSchemaVersion = 2 + legacyInitIntentSchemaVersion = 1 + maxInitIntentBytes = 1 << 20 ) var initStepOrder = []string{ @@ -35,26 +37,36 @@ var initStepOrder = []string{ } type initIntent struct { - SchemaVersion int `json:"schema_version"` - ID string `json:"id"` - Digest string `json:"digest"` - State string `json:"state"` - Lane string `json:"lane"` - Agent string `json:"agent"` - Session string `json:"session"` - Mode store.Mode `json:"mode"` - BaseSHA string `json:"base_sha"` - Worktree string `json:"worktree"` - Paths []string `json:"paths"` - InstallPath string `json:"install_path,omitempty"` - SkillPath string `json:"skill_path,omitempty"` - CompletedSteps []string `json:"completed_steps,omitempty"` - CreatedAt time.Time `json:"created_at"` - UpdatedAt time.Time `json:"updated_at"` + SchemaVersion int `json:"schema_version"` + ID string `json:"id"` + Digest string `json:"digest"` + State string `json:"state"` + Lane string `json:"lane"` + Agent string `json:"agent"` + Session string `json:"session"` + Mode store.Mode `json:"mode"` + BaseSHA string `json:"base_sha"` + Worktree string `json:"worktree"` + Paths []string `json:"paths"` + MessagePolicy *policy.Receipt `json:"message_policy,omitempty"` + InstallPath string `json:"install_path,omitempty"` + SkillPath string `json:"skill_path,omitempty"` + CompletedSteps []string `json:"completed_steps,omitempty"` + CreatedAt time.Time `json:"created_at"` + UpdatedAt time.Time `json:"updated_at"` +} + +type initTransaction struct { + path string + intent initIntent } func beginInitIntent(laneStore store.Store, candidate initIntent) (initIntent, string, error) { candidate.SchemaVersion = initIntentSchemaVersion + if candidate.MessagePolicy == nil { + receipt := policy.Default() + candidate.MessagePolicy = &receipt + } candidate.Paths = append([]string(nil), candidate.Paths...) sort.Strings(candidate.Paths) digest, err := digestInitIntent(candidate) @@ -94,6 +106,45 @@ func beginInitIntent(laneStore store.Store, candidate initIntent) (initIntent, s } func markInitStep(path string, intent initIntent, step string) (initIntent, error) { + lock, err := filelock.Acquire(initIntentLockPath(path), filelock.DefaultWait) + if err != nil { + return initIntent{}, fail.Wrap("INIT_INTENT_FAILED", err) + } + defer func() { _ = lock.Release() }() + return markInitStepLocked(path, intent, step) +} + +func runInitTransaction(path string, intent initIntent, run func(*initTransaction) error) (initIntent, error) { + lock, err := filelock.Acquire(initIntentLockPath(path), filelock.DefaultWait) + if err != nil { + return initIntent{}, fail.Wrap("INIT_INTENT_FAILED", err) + } + defer func() { _ = lock.Release() }() + + current, err := loadInitIntent(path) + if err != nil { + return initIntent{}, err + } + if current.Digest != intent.Digest { + return initIntent{}, fail.New("INIT_INTENT_CONFLICT", "initialization intent changed while setup was running") + } + transaction := initTransaction{path: path, intent: current} + if err := run(&transaction); err != nil { + return transaction.intent, err + } + return transaction.intent, nil +} + +func (transaction *initTransaction) mark(step string) (initIntent, error) { + updated, err := markInitStepLocked(transaction.path, transaction.intent, step) + if err != nil { + return initIntent{}, err + } + transaction.intent = updated + return updated, nil +} + +func markInitStepLocked(path string, intent initIntent, step string) (initIntent, error) { stepIndex := -1 for index, candidate := range initStepOrder { if candidate == step { @@ -104,11 +155,6 @@ func markInitStep(path string, intent initIntent, step string) (initIntent, erro if stepIndex < 0 { return initIntent{}, fail.New("INIT_INTENT_FAILED", "unknown initialization step: "+step) } - lock, err := filelock.Acquire(initIntentLockPath(path), 0) - if err != nil { - return initIntent{}, fail.Wrap("INIT_INTENT_FAILED", err) - } - defer func() { _ = lock.Release() }() current, err := loadInitIntent(path) if err != nil { return initIntent{}, err @@ -142,11 +188,16 @@ func loadInitIntent(path string) (initIntent, error) { if err != nil { return intent, fail.Wrap("INIT_INTENT_FAILED", err) } + return decodeInitIntent(body) +} + +func decodeInitIntent(body []byte) (initIntent, error) { + var intent initIntent if err := strictjson.Decode(body, &intent); err != nil { return initIntent{}, fail.Wrap("INIT_INTENT_FAILED", err) } - if intent.SchemaVersion != initIntentSchemaVersion { - return initIntent{}, fail.Errorf("MIGRATION_REQUIRED", "init intent schema version %d is unsupported; this wip release supports version %d", intent.SchemaVersion, initIntentSchemaVersion) + if intent.SchemaVersion != legacyInitIntentSchemaVersion && intent.SchemaVersion != initIntentSchemaVersion { + return initIntent{}, fail.Errorf("MIGRATION_REQUIRED", "init intent schema version %d is unsupported; this wip release supports versions %d and %d", intent.SchemaVersion, legacyInitIntentSchemaVersion, initIntentSchemaVersion) } if err := validateInitIntent(intent); err != nil { return initIntent{}, err @@ -176,6 +227,18 @@ func loadInitIntent(path string) (initIntent, error) { } func validateInitIntent(intent initIntent) error { + if intent.SchemaVersion == legacyInitIntentSchemaVersion { + if intent.MessagePolicy != nil { + return fail.New("INIT_INTENT_FAILED", "legacy initialization intent contains unsupported policy data") + } + } else { + if intent.MessagePolicy == nil { + return fail.New("INIT_INTENT_FAILED", "initialization intent message policy is missing") + } + if err := policy.ValidateReceipt(*intent.MessagePolicy); err != nil { + return fail.Wrap("INIT_INTENT_FAILED", err) + } + } for label, value := range map[string]string{"init intent": intent.ID, "lane": intent.Lane, "agent": intent.Agent, "session": intent.Session} { if err := store.ValidateID(value, label); err != nil { return fail.Wrap("INIT_INTENT_FAILED", err) diff --git a/cmd/wip/main.go b/cmd/wip/main.go index dad12e9..20029e9 100644 --- a/cmd/wip/main.go +++ b/cmd/wip/main.go @@ -6,7 +6,9 @@ import ( "os" ) -var version = "0.1.0-beta.1" +// Source builds are always development builds. The release builder injects a +// SemVer and its exact v-prefixed tag together. +var version = "0.2.0-dev" func main() { os.Exit(run(context.Background(), os.Args[1:], os.Stdin, os.Stdout, os.Stderr)) diff --git a/cmd/wip/main_test.go b/cmd/wip/main_test.go index 32167ae..b13deba 100644 --- a/cmd/wip/main_test.go +++ b/cmd/wip/main_test.go @@ -86,6 +86,150 @@ func TestIdentityEnvironmentDefaultsRemainSupported(t *testing.T) { } } +func TestObserveFlagSpellingsSelectReadOnlyMode(t *testing.T) { + tests := []struct { + args []string + want bool + }{ + {args: []string{"--observe"}, want: true}, + {args: []string{"-observe"}, want: true}, + {args: []string{"--observe=true"}, want: true}, + {args: []string{"-observe=1"}, want: true}, + {args: []string{"--observe=false"}, want: false}, + {args: []string{"--observe=invalid"}, want: true}, + {args: []string{"--observe", "--observe=false"}, want: false}, + } + for _, test := range tests { + if got := booleanFlagRequested(test.args, "observe"); got != test.want { + t.Errorf("booleanFlagRequested(%q) = %v, want %v", test.args, got, test.want) + } + } +} + +func TestObserveFlagVariantsDoNotRenewLeases(t *testing.T) { + directory := cliTestRepo(t) + initializeCLI(t, directory, "observe-variants", "core.txt") + repo, err := gitx.Discover(context.Background(), directory) + if err != nil { + t.Fatal(err) + } + laneStore, initialized, err := store.Inspect(repo) + if err != nil || !initialized { + t.Fatalf("inspect initialized=%v err=%v", initialized, err) + } + status, err := laneStore.Status("observe-variants") + if err != nil || len(status.Leases) != 1 { + t.Fatalf("status=%#v err=%v", status, err) + } + original := status.Leases[0] + + for _, spelling := range []string{"--observe=true", "-observe"} { + result := runCLI(t, []string{"--json", "--repo-dir", directory, "status", "--lane", "observe-variants", spelling}, "") + if result.code != 0 || result.envelope.Context == nil || result.envelope.Context.LeaseRenewed { + t.Fatalf("status %s = %#v stderr=%s", spelling, result.envelope, result.stderr) + } + stored, err := laneStore.LoadLease(original.ID) + if err != nil || !stored.UpdatedAt.Equal(original.UpdatedAt) || !stored.ExpiresAt.Equal(*original.ExpiresAt) { + t.Fatalf("status %s changed lease=%#v err=%v", spelling, stored, err) + } + } + invalid := runCLI(t, []string{"--json", "--repo-dir", directory, "status", "--lane", "observe-variants", "--observe=invalid"}, "") + if invalid.code == 0 || invalid.envelope.Error == nil || invalid.envelope.Error.Code != "INVALID_ARGS" { + t.Fatalf("invalid observe = %#v stderr=%s", invalid.envelope, invalid.stderr) + } + stored, err := laneStore.LoadLease(original.ID) + if err != nil || !stored.UpdatedAt.Equal(original.UpdatedAt) || !stored.ExpiresAt.Equal(*original.ExpiresAt) { + t.Fatalf("invalid observe changed lease=%#v err=%v", stored, err) + } + + renewed := runCLI(t, []string{"--json", "--repo-dir", directory, "status", "--lane", "observe-variants", "--observe=false"}, "") + if renewed.code != 0 || renewed.envelope.Context == nil || !renewed.envelope.Context.LeaseRenewed { + t.Fatalf("renewing status = %#v stderr=%s", renewed.envelope, renewed.stderr) + } + stored, err = laneStore.LoadLease(original.ID) + if err != nil || !stored.UpdatedAt.After(original.UpdatedAt) { + t.Fatalf("explicit false did not renew lease=%#v err=%v", stored, err) + } +} + +func TestPlanObserveIsRepositoryByteForByteReadOnly(t *testing.T) { + directory := cliTestRepo(t) + writeCLI(t, directory, "core.txt", "planned without renewal\n") + cliGit(t, directory, "add", "core.txt") + initializeCLI(t, directory, "plan-observe", "core.txt") + common := cliGit(t, directory, "rev-parse", "--path-format=absolute", "--git-common-dir") + before := commandTreeDigest(t, common) + + result := runCLI(t, []string{ + "--json", "--repo-dir", directory, "plan", "--lane", "plan-observe", + "--source", "staged_index", "--untracked", "not_applicable", "--observe", + }, "") + if result.code != 0 || !result.envelope.OK { + t.Fatalf("observe plan = %#v stderr=%s", result.envelope, result.stderr) + } + var proposal planProposal + decodeData(t, result.envelope.Data, &proposal) + if proposal.SchemaVersion != reviewPlanSchemaVersion || !samePlanStrings(proposal.SourcePaths, []string{"core.txt"}) { + t.Fatalf("observe proposal = %#v", proposal) + } + if after := commandTreeDigest(t, common); after != before { + t.Fatalf("plan --observe changed repository state: before=%s after=%s", before, after) + } +} + +func TestStatusObserveIsRepositoryByteForByteReadOnly(t *testing.T) { + directory := cliTestRepo(t) + initializeCLI(t, directory, "status-observe-bytes", "core.txt") + common := cliGit(t, directory, "rev-parse", "--path-format=absolute", "--git-common-dir") + before := commandTreeDigest(t, common) + + result := runCLI(t, []string{ + "--json", "--repo-dir", directory, "status", "--lane", "status-observe-bytes", "--observe", + }, "") + if result.code != 0 || !result.envelope.OK || result.envelope.Context == nil || result.envelope.Context.LeaseRenewed { + t.Fatalf("observe status = %#v stderr=%s", result.envelope, result.stderr) + } + if after := commandTreeDigest(t, common); after != before { + t.Fatalf("status --observe changed repository state: before=%s after=%s", before, after) + } +} + +func TestEnvRejectsAnotherWorktreeWithoutRenewing(t *testing.T) { + anchor := cliTestRepo(t) + linked := filepath.Join(t.TempDir(), "bound-worktree") + cliGit(t, anchor, "worktree", "add", "--detach", linked, "HEAD") + initialized := runCLI(t, []string{"--json", "--repo-dir", linked, "init", "--mode", "worktree", "--lane", "bound-env", "--agent", "agent", "--session", "session", "--path", "core.txt", "--non-interactive", "--no-install", "--no-install-skill"}, "") + if initialized.code != 0 { + t.Fatalf("init = %#v stderr=%s", initialized.envelope, initialized.stderr) + } + repo, err := gitx.Discover(context.Background(), linked) + if err != nil { + t.Fatal(err) + } + laneStore, _, err := store.Inspect(repo) + if err != nil { + t.Fatal(err) + } + status, err := laneStore.Status("bound-env") + if err != nil || len(status.Leases) != 1 { + t.Fatalf("status=%#v err=%v", status, err) + } + original := status.Leases[0] + for _, args := range [][]string{ + {"--json", "--repo-dir", anchor, "env", "--lane", "bound-env"}, + {"--json", "--repo-dir", anchor, "env", "--lane", "bound-env", "--observe=true"}, + } { + result := runCLI(t, args, "") + if result.code == 0 || result.envelope.Error == nil || result.envelope.Error.Code != "WORKTREE_MISMATCH" { + t.Fatalf("wrong-worktree env = %#v stderr=%s", result.envelope, result.stderr) + } + stored, err := laneStore.LoadLease(original.ID) + if err != nil || !stored.UpdatedAt.Equal(original.UpdatedAt) || !stored.ExpiresAt.Equal(*original.ExpiresAt) { + t.Fatalf("wrong-worktree env changed lease=%#v err=%v", stored, err) + } + } +} + func TestConcurrentSharedLanesCaptureDisjointPaths(t *testing.T) { directory := cliTestRepo(t) writeCLI(t, directory, "core.txt", "new core\n") @@ -126,7 +270,22 @@ func TestConcurrentSharedLanesCaptureDisjointPaths(t *testing.T) { t.Fatalf("decode %s output %q: %v; stderr=%s", captured.lane, captured.stdout, err, captured.stderr) } if captured.code != 0 || !output.OK { - t.Fatalf("%s capture: code=%d output=%#v stderr=%s", captured.lane, captured.code, output, captured.stderr) + errorCode, errorMessage := "", "" + if output.Error != nil { + errorCode, errorMessage = output.Error.Code, output.Error.Message + } + data, marshalErr := json.Marshal(output.Data) + if marshalErr != nil { + data = []byte("") + } + var recovery engine.Result + if output.Data != nil { + _ = json.Unmarshal(data, &recovery) + } + t.Fatalf("%s capture: code=%d error_code=%q error_message=%q recovery={ref_updated:%t plan_id:%q plan_digest:%q intent_path:%q intent_state:%q final_commit:%q} data=%s stdout=%q stderr=%q", + captured.lane, captured.code, errorCode, errorMessage, + recovery.RefUpdated, recovery.PlanID, recovery.PlanDigest, recovery.IntentPath, recovery.IntentState, recovery.FinalCommit, + data, captured.stdout, captured.stderr) } var result engine.Result decodeData(t, output.Data, &result) @@ -222,6 +381,51 @@ func TestPlanPreviewUsesComponentBoundariesWithoutMutation(t *testing.T) { } } +func TestPlanForRootDotfileHasGuidanceAndValidatesReviewedDryRun(t *testing.T) { + directory := cliTestRepo(t) + writeCLI(t, directory, ".staticcheck-version", "v0.8.0-rc.1\n") + cliGit(t, directory, "add", ".staticcheck-version") + initializeCLI(t, directory, "root-config-plan", ".staticcheck-version") + head := cliGit(t, directory, "rev-parse", "HEAD") + index := cliGitRaw(t, directory, "ls-files", "-s", "-z") + + planPath := filepath.Join(t.TempDir(), "plan.json") + drafted := runCLI(t, []string{"--json", "--repo-dir", directory, "plan", "--lane", "root-config-plan", "--out", planPath}, "") + if drafted.code != 0 || !drafted.envelope.OK { + t.Fatalf("draft root config plan: %#v stderr=%s", drafted.envelope, drafted.stderr) + } + var plan planProposal + decodeData(t, drafted.envelope.Data, &plan) + if len(plan.Groups) != 1 || plan.Groups[0].Key != "repository-config" || plan.Groups[0].SuggestedScope != "config" || plan.Groups[0].Rationale == "" { + t.Fatalf("root config guidance = %#v", plan.Groups) + } + plan.State = "reviewed" + plan.Groups[0].Message = "build(config): pin compatible analyzer" + body, err := json.MarshalIndent(plan, "", " ") + if err != nil { + t.Fatal(err) + } + if err := os.WriteFile(planPath, append(body, '\n'), 0o600); err != nil { + t.Fatal(err) + } + + dryRun := runCLI(t, []string{"--json", "--repo-dir", directory, "commit", "--lane", "root-config-plan", "--dry-run", "--plan", planPath}, "") + if dryRun.code != 0 || !dryRun.envelope.OK { + t.Fatalf("reviewed root config dry-run: %#v stderr=%s", dryRun.envelope, dryRun.stderr) + } + var result engine.Result + decodeData(t, dryRun.envelope.Data, &result) + if result.GateOutcome != "skipped" || result.Execution == nil || result.Execution.Policy != "no-exec" { + t.Fatalf("reviewed root config dry-run contract = %#v", result) + } + if got := cliGit(t, directory, "rev-parse", "HEAD"); got != head { + t.Fatalf("dry-run moved HEAD: %s -> %s", head, got) + } + if got := cliGitRaw(t, directory, "ls-files", "-s", "-z"); got != index { + t.Fatal("dry-run changed the source index") + } +} + func TestPlanPreviewExcludesAlreadyCapturedStagedPaths(t *testing.T) { directory := cliTestRepo(t) writeCLI(t, directory, "core.txt", "new core\n") @@ -249,7 +453,7 @@ func TestPlanPreviewExcludesAlreadyCapturedStagedPaths(t *testing.T) { } var proposal planProposal decodeData(t, preview.envelope.Data, &proposal) - if len(proposal.StagedPaths) != 1 || proposal.StagedPaths[0] != "docs.txt" || len(proposal.Groups) != 1 { + if len(proposal.SourcePaths) != 1 || proposal.SourcePaths[0] != "docs.txt" || len(proposal.Groups) != 1 { t.Fatalf("incremental proposal = %#v", proposal) } } @@ -333,6 +537,94 @@ func TestInitCanCreateAndCaptureLinkedWorktreeWithoutMovingCheckouts(t *testing. assertCLIFileAtCommit(t, directory, capture.FinalCommit, "core.txt", "linked core") } +func TestEnvRejectsWrongWorktreeWithoutChangingLeaseOrGitState(t *testing.T) { + directory := cliTestRepo(t) + linked := filepath.Join(t.TempDir(), "agent-worktree") + initialized := runCLI(t, []string{ + "--json", "--repo-dir", directory, "init", "--mode", "worktree", + "--create-worktree", linked, "--lane", "bound-env", "--agent", "agent", + "--session", "session", "--path", "core.txt", "--non-interactive", "--no-install", + }, "") + if initialized.code != 0 || !initialized.envelope.OK { + t.Fatalf("worktree init: %#v stderr=%s", initialized.envelope, initialized.stderr) + } + + repo, err := gitx.Discover(context.Background(), directory) + if err != nil { + t.Fatal(err) + } + laneStore, err := store.Open(repo) + if err != nil { + t.Fatal(err) + } + before, err := laneStore.Status("bound-env") + if err != nil || len(before.Leases) != 1 { + t.Fatalf("initial status = %#v, err=%v", before, err) + } + head := cliGit(t, directory, "rev-parse", "HEAD") + anchorIndex := cliGitRaw(t, directory, "ls-files", "-s", "-z") + linkedIndex := cliGitRaw(t, linked, "ls-files", "-s", "-z") + + wrong := runCLI(t, []string{"--json", "--repo-dir", directory, "env", "--lane", "bound-env"}, "") + if wrong.code != 1 || wrong.envelope.OK || wrong.envelope.Error == nil || wrong.envelope.Error.Code != "WORKTREE_MISMATCH" { + t.Fatalf("wrong-worktree env = %#v code=%d stderr=%s", wrong.envelope, wrong.code, wrong.stderr) + } + after, err := laneStore.Status("bound-env") + if err != nil || len(after.Leases) != 1 { + t.Fatalf("status after refusal = %#v, err=%v", after, err) + } + expiryChanged := (before.Leases[0].ExpiresAt == nil) != (after.Leases[0].ExpiresAt == nil) + if before.Leases[0].ExpiresAt != nil && after.Leases[0].ExpiresAt != nil { + expiryChanged = !after.Leases[0].ExpiresAt.Equal(*before.Leases[0].ExpiresAt) + } + if !after.Leases[0].UpdatedAt.Equal(before.Leases[0].UpdatedAt) || expiryChanged { + t.Fatalf("wrong-worktree env changed lease: before=%#v after=%#v", before.Leases[0], after.Leases[0]) + } + if got := cliGit(t, directory, "rev-parse", "HEAD"); got != head { + t.Fatalf("wrong-worktree env moved HEAD: %s", got) + } + if got := cliGitRaw(t, directory, "ls-files", "-s", "-z"); got != anchorIndex { + t.Fatal("wrong-worktree env changed anchor index") + } + if got := cliGitRaw(t, linked, "ls-files", "-s", "-z"); got != linkedIndex { + t.Fatal("wrong-worktree env changed linked index") + } + + correct := runCLI(t, []string{"--json", "--repo-dir", linked, "env", "--lane", "bound-env"}, "") + if correct.code != 0 || !correct.envelope.OK { + t.Fatalf("bound-worktree env = %#v code=%d stderr=%s", correct.envelope, correct.code, correct.stderr) + } +} + +func TestInitRecoveryCanRunFromItsCreatedLinkedWorktree(t *testing.T) { + directory := cliTestRepo(t) + linked := filepath.Join(t.TempDir(), "agent-worktree") + args := []string{"--json", "--repo-dir", directory, "init", "--mode", "worktree", "--create-worktree", linked, "--lane", "linked-recovery", "--agent", "agent", "--session", "session", "--path", "core.txt", "--non-interactive", "--no-install", "--no-install-skill"} + created := runCLI(t, args, "") + if created.code != 0 || !created.envelope.OK { + t.Fatalf("initial worktree setup: %#v stderr=%s", created.envelope, created.stderr) + } + + args[2] = linked + recovered := runCLI(t, args, "") + if recovered.code != 0 || !recovered.envelope.OK { + t.Fatalf("linked-worktree recovery: %#v stderr=%s", recovered.envelope, recovered.stderr) + } + var result initResult + decodeData(t, recovered.envelope.Data, &result) + anchorRepo, anchorErr := gitx.Discover(context.Background(), directory) + linkedRepo, linkedErr := gitx.Discover(context.Background(), linked) + if anchorErr != nil || linkedErr != nil { + t.Fatalf("discover recovery roots: anchor=%v linked=%v", anchorErr, linkedErr) + } + if result.RepoDir != anchorRepo.Root || result.Worktree != linkedRepo.Root || result.CreatedWorktree { + t.Fatalf("recovery roots = %#v, want anchor %q and existing worktree %q", result, anchorRepo.Root, linkedRepo.Root) + } + if len(result.Recovery) != 0 || result.IntentState != "complete" { + t.Fatalf("recovery did not complete the immutable init intent: %#v", result) + } +} + func TestInitDryRunAndInstallerAreNonDestructive(t *testing.T) { directory := cliTestRepo(t) linked := filepath.Join(t.TempDir(), "not-created") @@ -488,6 +780,46 @@ func TestInitSkipsHomeResolutionWhenInstallationIsDisabled(t *testing.T) { } } +func TestInteractiveWorktreeInitRequiresAndReportsDestination(t *testing.T) { + directory := cliTestRepo(t) + repo, err := gitx.Discover(context.Background(), directory) + if err != nil { + t.Fatal(err) + } + destination := filepath.Join(t.TempDir(), "agent-worktree") + options := initOptions{ + mode: string(store.ModeWorktree), lane: "guided-worktree", agent: "agent", session: "session", baseRef: "HEAD", + paths: stringList{"core.txt"}, noInstall: true, noInstallSkill: true, + } + input := strings.Join([]string{"", destination, "", "", "", ""}, "\n") + "\n" + var output bytes.Buffer + if err := prepareInitOptions(context.Background(), repo, &options, prompt{reader: bufio.NewReader(strings.NewReader(input)), out: &output}); err != nil { + t.Fatal(err) + } + if options.createWorktree != destination || !strings.Contains(output.String(), "A linked worktree path is required.") { + t.Fatalf("worktree=%q output=%q", options.createWorktree, output.String()) + } + human := formatInitResult(initResult{ + Lane: &store.Lane{Mode: store.ModeWorktree, ID: "guided-worktree", Ref: store.LaneRef("agent", "guided-worktree")}, + CreatedWorktree: true, + RepoDir: directory, + Worktree: destination, + Environment: "export WIP_LANE=guided-worktree", + }) + if !strings.Contains(human, "Continue in linked worktree "+destination+".") { + t.Fatalf("init result did not report navigation: %q", human) + } + reused := formatInitResult(initResult{ + Lane: &store.Lane{Mode: store.ModeWorktree, ID: "guided-worktree", Ref: store.LaneRef("agent", "guided-worktree")}, + RepoDir: directory, + Worktree: destination, + Environment: "export WIP_LANE=guided-worktree", + }) + if !strings.Contains(reused, "Continue in linked worktree "+destination+".") || strings.Contains(reused, "Created linked worktree") { + t.Fatalf("reused worktree result = %q", reused) + } +} + func TestInteractiveInitCanSkipConflictingOptionalSkill(t *testing.T) { directory := cliTestRepo(t) repo, err := gitx.Discover(context.Background(), directory) @@ -830,9 +1162,12 @@ func TestDoctorRejectsLeaseOwnerMismatch(t *testing.T) { func TestArchiveRequiresExactPreviewAndPreservesRefs(t *testing.T) { directory := cliTestRepo(t) initializeCLI(t, directory, "archive-cli", "core.txt") - release := runCLI(t, []string{"--json", "--repo-dir", directory, "release", "--lane", "archive-cli"}, "") - if release.code != 0 || !release.envelope.OK { - t.Fatalf("release for archive: %#v stderr=%s", release.envelope, release.stderr) + initializeCLI(t, directory, "archive-other", "docs.txt") + for _, laneID := range []string{"archive-cli", "archive-other"} { + release := runCLI(t, []string{"--json", "--repo-dir", directory, "release", "--lane", laneID}, "") + if release.code != 0 || !release.envelope.OK { + t.Fatalf("release %s for archive: %#v stderr=%s", laneID, release.envelope, release.stderr) + } } repo, err := gitx.Discover(context.Background(), directory) if err != nil { @@ -842,40 +1177,55 @@ func TestArchiveRequiresExactPreviewAndPreservesRefs(t *testing.T) { if err != nil { t.Fatal(err) } - lane, err := laneStore.Load("archive-cli") - if err != nil { - t.Fatal(err) - } - lane.UpdatedAt = time.Now().UTC().Add(-48 * time.Hour) - body, err := json.MarshalIndent(lane, "", " ") - if err != nil { - t.Fatal(err) - } - if err := os.WriteFile(filepath.Join(laneStore.Root, "lanes", lane.ID+".json"), append(body, '\n'), 0o600); err != nil { - t.Fatal(err) + var lane store.Lane + for _, laneID := range []string{"archive-cli", "archive-other"} { + current, err := laneStore.Load(laneID) + if err != nil { + t.Fatal(err) + } + current.UpdatedAt = time.Now().UTC().Add(-48 * time.Hour) + body, err := json.MarshalIndent(current, "", " ") + if err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(laneStore.Root, "lanes", current.ID+".json"), append(body, '\n'), 0o600); err != nil { + t.Fatal(err) + } + if laneID == "archive-cli" { + lane = current + } } refBefore := cliGit(t, directory, "rev-parse", lane.Ref) - preview := runCLI(t, []string{"--json", "--repo-dir", directory, "archive", "--older-than", "24h"}, "") + preview := runCLI(t, []string{"--json", "--repo-dir", directory, "archive", "--older-than", "24h", "--lane", lane.ID}, "") if preview.code != 0 || !preview.envelope.OK { t.Fatalf("archive preview: %#v stderr=%s", preview.envelope, preview.stderr) } var plan archiveResult decodeData(t, preview.envelope.Data, &plan) - if !plan.DryRun || len(plan.Candidates) != 1 || plan.PlanDigest == "" { + if !plan.DryRun || len(plan.Candidates) != 1 || plan.PlanDigest == "" || len(plan.LaneFilters) != 1 || plan.LaneFilters[0] != lane.ID { t.Fatalf("archive plan = %#v", plan) } missing := runCLI(t, []string{"--json", "--repo-dir", directory, "archive", "--older-than", "24h", "--lane", "not-eligible"}, "") if missing.code == 0 || missing.envelope.Error == nil || missing.envelope.Error.Code != "ARCHIVE_REFUSED" { t.Fatalf("missing archive lane = %#v", missing.envelope) } - wrong := runCLI(t, []string{"--json", "--repo-dir", directory, "archive", "--cutoff", plan.Cutoff.Format(time.RFC3339Nano), "--plan-digest", "sha256:wrong", "--apply", "--yes"}, "") + wrong := runCLI(t, []string{"--json", "--repo-dir", directory, "archive", "--lane", lane.ID, "--cutoff", plan.Cutoff.Format(time.RFC3339Nano), "--plan-digest", "sha256:wrong", "--apply", "--yes"}, "") if wrong.code == 0 || wrong.envelope.Error == nil || wrong.envelope.Error.Code != "ARCHIVE_PLAN_MOVED" { t.Fatalf("wrong archive digest = %#v", wrong.envelope) } if _, err := laneStore.Load(lane.ID); err != nil { t.Fatalf("wrong archive digest moved state: %v", err) } - applied := runCLI(t, []string{"--json", "--repo-dir", directory, "archive", "--cutoff", plan.Cutoff.Format(time.RFC3339Nano), "--plan-digest", plan.PlanDigest, "--apply", "--yes"}, "") + omittedFilter := runCLI(t, []string{"--json", "--repo-dir", directory, "archive", "--cutoff", plan.Cutoff.Format(time.RFC3339Nano), "--plan-digest", plan.PlanDigest, "--apply", "--yes"}, "") + if omittedFilter.code == 0 || omittedFilter.envelope.Error == nil || omittedFilter.envelope.Error.Code != "ARCHIVE_PLAN_MOVED" || !strings.Contains(omittedFilter.envelope.Error.Message, "--lane") { + t.Fatalf("omitted archive lane filter = %#v", omittedFilter.envelope) + } + for _, laneID := range []string{lane.ID, "archive-other"} { + if _, err := laneStore.Load(laneID); err != nil { + t.Fatalf("omitted archive lane filter moved %s: %v", laneID, err) + } + } + applied := runCLI(t, []string{"--json", "--repo-dir", directory, "archive", "--lane", lane.ID, "--cutoff", plan.Cutoff.Format(time.RFC3339Nano), "--plan-digest", plan.PlanDigest, "--apply", "--yes"}, "") if applied.code != 0 || !applied.envelope.OK { t.Fatalf("archive apply: %#v stderr=%s", applied.envelope, applied.stderr) } @@ -884,6 +1234,9 @@ func TestArchiveRequiresExactPreviewAndPreservesRefs(t *testing.T) { if archived.Receipt == nil || archived.Receipt.State != "complete" { t.Fatalf("archive receipt = %#v", archived) } + if other, err := laneStore.Load("archive-other"); err != nil || other.State != "released" { + t.Fatalf("scoped archive moved other lane = %#v err=%v", other, err) + } receiptPath := filepath.Join(laneStore.Root, "archive", archived.Receipt.ID, "receipt.json") archived.Receipt.State = "prepared" receiptBody, err := json.MarshalIndent(archived.Receipt, "", " ") @@ -922,6 +1275,36 @@ func TestArchiveRequiresExactPreviewAndPreservesRefs(t *testing.T) { if got := cliGit(t, directory, "rev-parse", lane.Ref); got != refBefore { t.Fatalf("restore moved ref: %s -> %s", refBefore, got) } + secondPreview := runCLI(t, []string{"--json", "--repo-dir", directory, "archive", "--older-than", "23h", "--lane", lane.ID}, "") + if secondPreview.code != 0 || !secondPreview.envelope.OK { + t.Fatalf("rearchive preview: %#v stderr=%s", secondPreview.envelope, secondPreview.stderr) + } + var secondPlan archiveResult + decodeData(t, secondPreview.envelope.Data, &secondPlan) + secondApply := runCLI(t, []string{"--json", "--repo-dir", directory, "archive", "--lane", lane.ID, "--cutoff", secondPlan.Cutoff.Format(time.RFC3339Nano), "--plan-digest", secondPlan.PlanDigest, "--apply", "--yes"}, "") + if secondApply.code != 0 || !secondApply.envelope.OK { + t.Fatalf("rearchive apply: %#v stderr=%s", secondApply.envelope, secondApply.stderr) + } + var secondArchive archiveResult + decodeData(t, secondApply.envelope.Data, &secondArchive) + if secondArchive.Receipt == nil || secondArchive.Receipt.State != "complete" || secondArchive.Receipt.ID == archived.Receipt.ID { + t.Fatalf("rearchive receipt = %#v; first=%s", secondArchive, archived.Receipt.ID) + } + doctor = runCLI(t, []string{"--json", "--repo-dir", directory, "doctor"}, "") + if doctor.code != 0 || !doctor.envelope.OK { + t.Fatalf("doctor after rearchive: %#v stderr=%s", doctor.envelope, doctor.stderr) + } + decodeData(t, doctor.envelope.Data, &doctorState) + if !doctorState.Healthy || len(doctorState.Findings) != 0 || stringContains(doctorState.ArchiveCandidates, lane.ID) { + t.Fatalf("doctor after rearchive report = %#v", doctorState) + } + secondRestored := runCLI(t, []string{"--json", "--repo-dir", directory, "archive", "--restore", secondArchive.Receipt.ID, "--apply", "--yes"}, "") + if secondRestored.code != 0 || !secondRestored.envelope.OK { + t.Fatalf("rearchive restore: %#v stderr=%s", secondRestored.envelope, secondRestored.stderr) + } + if got := cliGit(t, directory, "rev-parse", lane.Ref); got != refBefore { + t.Fatalf("rearchive lifecycle moved ref: %s -> %s", refBefore, got) + } } func TestReconcileFinishesInterruptedRefPublicationIdempotently(t *testing.T) { @@ -1266,7 +1649,7 @@ func TestLeaseHeartbeatKeepsLongCaptureFenceActive(t *testing.T) { if err != nil { t.Fatal(err) } - laneStore.LeaseTTL = 3 * time.Second + laneStore.LeaseTTL = 9 * time.Second lane, err := laneStore.Create(context.Background(), store.CreateOptions{ID: "heartbeat", Agent: "agent", Session: "session", Mode: store.ModeShared}) if err != nil { t.Fatal(err) @@ -1283,20 +1666,32 @@ func TestLeaseHeartbeatKeepsLongCaptureFenceActive(t *testing.T) { t.Fatal(err) } defer func() { _ = lock.Release() }() - _, stop, err := startLeaseHeartbeat(context.Background(), laneStore, lane, []string{"core.txt"}) + refreshed := make(chan struct{}, 1) + _, stop, err := startLeaseHeartbeatWithObserver(context.Background(), laneStore, lane, []string{"core.txt"}, func() { + select { + case refreshed <- struct{}{}: + default: + } + }) if err != nil { t.Fatal(err) } - time.Sleep(4 * time.Second) + defer func() { + if err := stop(); err != nil { + t.Errorf("stop heartbeat: %v", err) + } + }() + select { + case <-refreshed: + case <-time.After(12 * time.Second): + t.Fatal("heartbeat did not renew the lease") + } if active, err := laneStore.ActivePaths(lane.ID); err != nil || len(active) != 1 || active[0] != "core.txt" { t.Fatalf("heartbeat active paths = %v, err=%v", active, err) } if _, err := laneStore.Claim(other.ID, other.Agent, other.Session, []string{"core.txt"}); fail.Code(err) != "PATH_LEASE_CONFLICT" { t.Fatalf("heartbeat did not fence competing claim: %v (%s)", err, fail.Code(err)) } - if err := stop(); err != nil { - t.Fatal(err) - } } func TestLateHeartbeatFailureReturnsAppliedReceiptForReconciliation(t *testing.T) { diff --git a/cmd/wip/migrate.go b/cmd/wip/migrate.go new file mode 100644 index 0000000..3071467 --- /dev/null +++ b/cmd/wip/migrate.go @@ -0,0 +1,181 @@ +package main + +import ( + "context" + "crypto/sha256" + "encoding/hex" + "errors" + "fmt" + "io" + "strings" + + "github.com/nstranquist/wip-commit/internal/coordmigration" + "github.com/nstranquist/wip-commit/internal/fail" + "github.com/nstranquist/wip-commit/internal/gitx" + "github.com/nstranquist/wip-commit/internal/safeio" +) + +const migrationPlanLimit = coordmigration.MaxPlanBytes + +type migrationProducerFunc func() (coordmigration.ProducerIdentity, error) + +type migrationCommandResult struct { + SchemaVersion string `json:"schema_version"` + Mode string `json:"mode"` + Plan *coordmigration.Plan `json:"plan,omitempty"` + Status *coordmigration.Status `json:"status,omitempty"` + Applied bool `json:"applied,omitempty"` + Resumed bool `json:"resumed,omitempty"` + RolledBack bool `json:"rolled_back,omitempty"` +} + +func (application *app) runMigrate(ctx context.Context, repo gitx.Repo, args []string) int { + set := application.flagSet("migrate") + preview := set.Bool("preview", false, "create a read-only migration plan") + statusMode := set.Bool("status", false, "inspect migration state without mutation") + apply := set.Bool("apply", false, "apply an exact reviewed migration plan") + resume := set.Bool("resume", false, "resume an interrupted exact migration plan") + rollback := set.Bool("rollback", false, "roll back exact outputs before the source move") + planPath := set.String("plan", "", "strict migration plan file") + planDigest := set.String("plan-digest", "", "exact reviewed sha256 plan digest") + migrationID := set.String("migration-id", "", "migration identity for status") + yes := set.Bool("yes", false, "confirm an apply, resume, or rollback") + lockWait := set.Duration("lock-wait", 0, "common writer-lock wait") + if err := set.Parse(args); err != nil { + return application.failure("migrate", fail.Wrap("INVALID_ARGS", err), nil, 2) + } + if set.NArg() != 0 { + return application.failure("migrate", fail.New("INVALID_ARGS", "migrate accepts no positional arguments"), nil, 2) + } + modes := 0 + for _, selected := range []bool{*preview, *statusMode, *apply, *resume, *rollback} { + if selected { + modes++ + } + } + if modes != 1 { + return application.failure("migrate", fail.New("INVALID_ARGS", "select exactly one of --preview, --status, --apply, --resume, or --rollback"), nil, 2) + } + if *preview { + if *planPath != "" || *planDigest != "" || *migrationID != "" || *yes { + return application.failure("migrate", fail.New("INVALID_ARGS", "preview does not accept apply, status, or confirmation inputs"), nil, 2) + } + producer, err := application.resolveMigrationProducer() + if err != nil { + return application.failure("migrate", fail.Wrap("MIGRATION_PRODUCER_INVALID", err), nil, 1) + } + plan, err := coordmigration.Preview(ctx, repo, coordmigration.PreviewOptions{Producer: producer}) + if err != nil { + return application.failure("migrate", err, nil, 1) + } + result := migrationCommandResult{SchemaVersion: coordmigration.StatusSchemaVersion, Mode: "preview", Plan: &plan} + human := fmt.Sprintf("Migration preview %s is %s. Review plan digest %s.", plan.MigrationID, plan.State, plan.PlanDigest) + return application.success("migrate", result, human) + } + if *statusMode { + if *planPath != "" || *planDigest != "" || *yes { + return application.failure("migrate", fail.New("INVALID_ARGS", "status does not accept a plan or confirmation"), nil, 2) + } + status, err := coordmigration.InspectStatus(repo, strings.TrimSpace(*migrationID)) + if err != nil { + return application.failure("migrate", err, nil, 1) + } + result := migrationCommandResult{SchemaVersion: coordmigration.StatusSchemaVersion, Mode: "status", Status: &status} + return application.success("migrate", result, fmt.Sprintf("Coordination migration state: %s.", status.State)) + } + if strings.TrimSpace(*migrationID) != "" { + return application.failure("migrate", fail.New("INVALID_ARGS", "--migration-id is valid only with --status"), nil, 2) + } + if !*yes || strings.TrimSpace(*planPath) == "" || strings.TrimSpace(*planDigest) == "" { + return application.failure("migrate", fail.New("CONFIRMATION_REQUIRED", "apply, resume, and rollback require --plan, --plan-digest, and --yes"), nil, 2) + } + plan, err := readMigrationPlan(application.stdin, *planPath) + if err != nil { + return application.failure("migrate", fail.Wrap("MIGRATION_PLAN_INVALID", err), nil, 1) + } + producer, err := application.resolveMigrationProducer() + if err != nil { + return application.failure("migrate", fail.Wrap("MIGRATION_PRODUCER_INVALID", err), nil, 1) + } + options := coordmigration.ApplyOptions{Resume: *resume, Rollback: *rollback, LockWait: *lockWait, Producer: producer} + applied, err := coordmigration.Apply(ctx, repo, plan, strings.TrimSpace(*planDigest), options) + if err != nil { + return application.failure("migrate", err, nil, 1) + } + result := migrationCommandResult{SchemaVersion: coordmigration.StatusSchemaVersion, Mode: applied.Mode, Plan: &plan, Status: &applied.Status, Applied: applied.Applied, Resumed: applied.Resumed, RolledBack: applied.RolledBack} + return application.success("migrate", result, fmt.Sprintf("Coordination migration %s: %s.", plan.MigrationID, applied.Status.State)) +} + +func (application *app) resolveMigrationProducer() (coordmigration.ProducerIdentity, error) { + if application.migrationProducer != nil { + producer, err := application.migrationProducer() + if err != nil { + return coordmigration.ProducerIdentity{}, err + } + if err := producer.Validate(); err != nil { + return coordmigration.ProducerIdentity{}, err + } + return producer, nil + } + return currentMigrationProducer() +} + +func currentMigrationProducer() (coordmigration.ProducerIdentity, error) { + versionInfo := currentVersionInfo() + if !versionInfo.SourceStamped || versionInfo.Revision == "" { + return coordmigration.ProducerIdentity{}, errors.New("running executable has no exact source revision") + } + if versionInfo.SourceState != "clean" && versionInfo.SourceState != "modified" { + return coordmigration.ProducerIdentity{}, errors.New("running executable has no exact clean or modified source state") + } + if versionInfo.ReleaseTag != "" && versionInfo.Channel != "release" { + return coordmigration.ProducerIdentity{}, errors.New("running executable has an unverified release tag") + } + contractResult, err := currentContractResult() + if err != nil { + return coordmigration.ProducerIdentity{}, err + } + _, executable, err := selfExecutable() + if err != nil { + return coordmigration.ProducerIdentity{}, err + } + executableSum := sha256.Sum256(executable) + producer := coordmigration.ProducerIdentity{ + CommandProtocol: contractResult.Protocol, + Product: "github.com/nstranquist/wip-commit", + Version: versionInfo.Version, + SourceRevision: versionInfo.Revision, + SourceState: versionInfo.SourceState, + ReleaseTagged: versionInfo.Channel == "release", + PortableBundleSHA256: contractResult.PortableBundleSHA256, + ExecutableSHA256: "sha256:" + hex.EncodeToString(executableSum[:]), + } + if producer.ReleaseTagged { + producer.ReleaseTag = versionInfo.ReleaseTag + } + if err := producer.Validate(); err != nil { + return coordmigration.ProducerIdentity{}, err + } + return producer, nil +} + +func readMigrationPlan(stdin io.Reader, path string) (coordmigration.Plan, error) { + var body []byte + var err error + if path == "-" { + if stdin == nil { + return coordmigration.Plan{}, errors.New("stdin is unavailable") + } + limited := io.LimitReader(stdin, migrationPlanLimit+1) + body, err = io.ReadAll(limited) + } else { + body, err = safeio.ReadRegular(path, migrationPlanLimit) + } + if err != nil { + return coordmigration.Plan{}, err + } + if len(body) > migrationPlanLimit { + return coordmigration.Plan{}, fmt.Errorf("plan exceeds %d bytes", migrationPlanLimit) + } + return coordmigration.DecodePlan(body) +} diff --git a/cmd/wip/migrate_test.go b/cmd/wip/migrate_test.go new file mode 100644 index 0000000..de71822 --- /dev/null +++ b/cmd/wip/migrate_test.go @@ -0,0 +1,155 @@ +package main + +import ( + "bytes" + "context" + "crypto/sha256" + "encoding/hex" + "encoding/json" + "fmt" + "io/fs" + "os" + "path/filepath" + "sort" + "strings" + "testing" + + "github.com/nstranquist/wip-commit/internal/coordmigration" +) + +func TestExperimentalMigrationCommandPreviewApplyAndStatus(t *testing.T) { + directory := cliTestRepo(t) + common := cliGit(t, directory, "rev-parse", "--path-format=absolute", "--git-common-dir") + before := commandTreeDigest(t, common) + preview := runMigrationCLI(t, []string{"--json", "--repo-dir", directory, "migrate", "--preview"}, "") + if preview.code != 0 || !preview.envelope.OK || preview.envelope.Action != "migrate" { + t.Fatalf("preview = %#v stderr=%s", preview.envelope, preview.stderr) + } + if after := commandTreeDigest(t, common); after != before { + t.Fatalf("read-only command preview changed the common directory: before=%s after=%s", before, after) + } + var previewData migrationCommandResult + decodeData(t, preview.envelope.Data, &previewData) + if previewData.Mode != "preview" || previewData.Plan == nil || previewData.Plan.State != "ready" { + t.Fatalf("preview data = %#v", previewData) + } + planBody, err := json.Marshal(previewData.Plan) + if err != nil { + t.Fatal(err) + } + applied := runMigrationCLI(t, []string{"--json", "--repo-dir", directory, "migrate", "--apply", "--plan", "-", "--plan-digest", previewData.Plan.PlanDigest, "--yes"}, string(planBody)) + if applied.code != 0 || !applied.envelope.OK { + t.Fatalf("apply = %#v stderr=%s", applied.envelope, applied.stderr) + } + var applyData migrationCommandResult + decodeData(t, applied.envelope.Data, &applyData) + if !applyData.Applied || applyData.Status == nil || applyData.Status.State != "complete" { + t.Fatalf("apply data = %#v", applyData) + } + statusBefore := commandTreeDigest(t, common) + status := runMigrationCLI(t, []string{"--json", "--repo-dir", directory, "migrate", "--status", "--migration-id", previewData.Plan.MigrationID}, "") + if status.code != 0 || !status.envelope.OK { + t.Fatalf("status = %#v stderr=%s", status.envelope, status.stderr) + } + if statusAfter := commandTreeDigest(t, common); statusAfter != statusBefore { + t.Fatalf("read-only command status changed the common directory: before=%s after=%s", statusBefore, statusAfter) + } + var statusData migrationCommandResult + decodeData(t, status.envelope.Data, &statusData) + if statusData.Status == nil || statusData.Status.Receipt == nil || statusData.Status.State != "complete" { + t.Fatalf("status data = %#v", statusData) + } + doctor := runCLI(t, []string{"--json", "--repo-dir", directory, "doctor"}, "") + doctorData, err := json.Marshal(doctor.envelope.Data) + if err != nil { + t.Fatal(err) + } + if doctor.code != 0 || !doctor.envelope.OK || !strings.Contains(string(doctorData), `"healthy":true`) { + t.Fatalf("post-apply canonical doctor = %#v stderr=%s", doctor.envelope, doctor.stderr) + } +} + +func TestMigrationCommandRequiresExplicitModeAndReviewedDigest(t *testing.T) { + directory := cliTestRepo(t) + missingMode := runMigrationCLI(t, []string{"--json", "--repo-dir", directory, "migrate"}, "") + if missingMode.code != 2 || missingMode.envelope.Error == nil || missingMode.envelope.Error.Code != "INVALID_ARGS" { + t.Fatalf("missing mode = %#v", missingMode) + } + preview := runMigrationCLI(t, []string{"--json", "--repo-dir", directory, "migrate", "--preview"}, "") + var data migrationCommandResult + decodeData(t, preview.envelope.Data, &data) + body, _ := json.Marshal(data.Plan) + before := commandTreeDigest(t, cliGit(t, directory, "rev-parse", "--path-format=absolute", "--git-common-dir")) + wrong := runMigrationCLI(t, []string{"--json", "--repo-dir", directory, "migrate", "--apply", "--plan", "-", "--plan-digest", "sha256:" + strings.Repeat("0", 64), "--yes"}, string(body)) + if wrong.code != 1 || wrong.envelope.Error == nil || wrong.envelope.Error.Code != "MIGRATION_PLAN_DIGEST_MISMATCH" { + t.Fatalf("wrong digest = %#v", wrong) + } + if after := commandTreeDigest(t, cliGit(t, directory, "rev-parse", "--path-format=absolute", "--git-common-dir")); after != before { + t.Fatalf("digest refusal changed common state: before=%s after=%s", before, after) + } +} + +func runMigrationCLI(t *testing.T, args []string, input string) cliRun { + t.Helper() + for _, name := range []string{"WIP_LANE", "WIP_AGENT", "WIP_SESSION"} { + t.Setenv(name, "") + } + contractResult, err := currentContractResult() + if err != nil { + t.Fatal(err) + } + producer := coordmigration.ProducerIdentity{ + CommandProtocol: contractResult.Protocol, Product: "github.com/nstranquist/wip-commit", + Version: "0.2.0-beta.1", SourceRevision: strings.Repeat("a", 40), SourceState: "modified", + PortableBundleSHA256: contractResult.PortableBundleSHA256, + ExecutableSHA256: "sha256:" + strings.Repeat("b", 64), + } + var stdout, stderr bytes.Buffer + application := app{ + stdin: strings.NewReader(input), stdout: &stdout, stderr: &stderr, + migrationProducer: func() (coordmigration.ProducerIdentity, error) { return producer, nil }, + } + code := application.run(context.Background(), args) + result := cliRun{code: code, stdout: stdout.String(), stderr: stderr.String()} + if strings.Contains(strings.Join(args, " "), "--json") { + if err := json.Unmarshal(stdout.Bytes(), &result.envelope); err != nil { + t.Fatalf("decode JSON output %q: %v; stderr=%s", stdout.String(), err, stderr.String()) + } + } + return result +} + +func commandTreeDigest(t *testing.T, root string) string { + t.Helper() + var records []string + err := filepath.WalkDir(root, func(path string, entry fs.DirEntry, walkErr error) error { + if walkErr != nil { + return walkErr + } + info, err := os.Lstat(path) + if err != nil { + return err + } + relative, err := filepath.Rel(root, path) + if err != nil { + return err + } + record := fmt.Sprintf("%s\x00%s\x00%04o", filepath.ToSlash(relative), info.Mode().Type(), info.Mode().Perm()) + if info.Mode().IsRegular() { + body, err := os.ReadFile(path) + if err != nil { + return err + } + sum := sha256.Sum256(body) + record += "\x00" + hex.EncodeToString(sum[:]) + } + records = append(records, record) + return nil + }) + if err != nil { + t.Fatal(err) + } + sort.Strings(records) + sum := sha256.Sum256([]byte(strings.Join(records, "\n"))) + return "sha256:" + hex.EncodeToString(sum[:]) +} diff --git a/cmd/wip/plan_command.go b/cmd/wip/plan_command.go index bbb6e86..4f96f19 100644 --- a/cmd/wip/plan_command.go +++ b/cmd/wip/plan_command.go @@ -2,63 +2,185 @@ package main import ( "context" + "encoding/json" + "errors" "fmt" "path/filepath" "sort" "strings" + "time" + "github.com/nstranquist/wip-commit/internal/atomicfile" + "github.com/nstranquist/wip-commit/internal/engine" "github.com/nstranquist/wip-commit/internal/fail" + "github.com/nstranquist/wip-commit/internal/pathid" + "github.com/nstranquist/wip-commit/internal/policy" "github.com/nstranquist/wip-commit/internal/store" ) type splitProposal struct { - Key string `json:"key"` - SuggestedScope string `json:"suggested_scope"` - SuggestedPrefix string `json:"suggested_prefix"` - Rationale string `json:"rationale"` - Files []string `json:"files"` + Key string `json:"key"` + SuggestedScope string `json:"suggested_scope"` + SuggestedPrefix string `json:"suggested_prefix"` + Rationale string `json:"rationale"` + Message string `json:"message"` + Files []string `json:"files"` + Verify []engine.VerifyCommand `json:"verify,omitempty"` } type planProposal struct { - SchemaVersion string `json:"schema_version"` - Lane string `json:"lane"` - StagedPaths []string `json:"staged_paths"` - Groups []splitProposal `json:"groups"` - Instruction string `json:"instruction"` + SchemaVersion string `json:"schema_version"` + State string `json:"state"` + Lane string `json:"lane"` + Agent string `json:"agent"` + Session string `json:"session"` + TargetRef string `json:"target_ref"` + LaneTip string `json:"lane_tip"` + SourceHead string `json:"source_head"` + SourceMode engine.SourceMode `json:"source_mode"` + UntrackedPolicy engine.UntrackedPolicy `json:"untracked_policy"` + SourceDigest string `json:"source_digest"` + SourceScopes []string `json:"source_scopes"` + LeaseDigest string `json:"lease_digest"` + MessagePolicy policy.Receipt `json:"message_policy"` + SourcePaths []string `json:"source_paths"` + Groups []splitProposal `json:"groups"` + Instruction string `json:"instruction"` +} + +func planObserveRequested(args []string) bool { + return booleanFlagRequested(args, "observe") } func (application app) runPlan(ctx context.Context, laneStore store.Store, args []string) int { set := application.flagSet("plan") var identity identityFlags var paths stringList + out := set.String("out", "", "write the draft plan without overwriting an existing file") + source := set.String("source", string(engine.SourceStagedIndex), "capture source: staged_index or worktree_snapshot") + untracked := set.String("untracked", "", "untracked policy: not_applicable, forbid, or include") + observe := set.Bool("observe", false, "create a plan without renewing leases or writing an output file") identity.bind(set) - set.Var(&paths, "path", "leased staged scope to include (repeatable; default all leased staged paths)") + set.Var(&paths, "path", "leased source scope to include (repeatable; default all leased scopes)") if err := set.Parse(args); err != nil { return application.failure("plan", fail.Wrap("INVALID_ARGS", err), nil, 2) } if err := noArgs(set); err != nil { return application.failure("plan", err, nil, 2) } + if *observe && strings.TrimSpace(*out) != "" { + return application.failure("plan", fail.New("INVALID_ARGS", "--observe cannot be combined with --out"), nil, 2) + } status, err := resolveStatus(laneStore, identity) if err != nil { return application.failure("plan", err, nil, 1) } + renewal := renewalStatus{} + if !*observe { + renewal.Attempted = true + if _, err := laneStore.Renew(status.Lane.ID, status.Lane.Agent, status.Lane.Session); err != nil { + return application.failure("plan", err, nil, 1) + } + now := time.Now().UTC() + renewal.Succeeded, renewal.RenewedAt = true, &now + status, err = laneStore.Status(status.Lane.ID) + if err != nil { + return application.failure("plan", err, nil, 1) + } + } allowed, err := laneStore.ActivePaths(status.Lane.ID) if err != nil { return application.failure("plan", err, nil, 1) } - selected, err := selectedStaged(ctx, laneStore, status.Lane.CurrentSHA, allowed, paths) + mode, untrackedPolicy, err := engine.NormalizeSource(engine.SourceMode(*source), engine.UntrackedPolicy(*untracked)) + if err != nil { + return application.failure("plan", err, nil, 2) + } + scopes, err := planSourceScopes(laneStore, allowed, paths) + if err != nil { + return application.failure("plan", err, nil, 1) + } + snapshot, err := engine.InspectSource(ctx, laneStore.Repo, status.Lane.CurrentSHA, scopes, mode, untrackedPolicy) + if err != nil { + return application.failure("plan", err, nil, 1) + } + if len(snapshot.Paths) == 0 { + return application.failure("plan", fail.New("EMPTY_SELECTION", "no changed source paths are covered by the selected active leases"), nil, 1) + } + for _, scope := range scopes { + matched := false + for _, path := range snapshot.Paths { + if pathid.Covered(path, []string{scope}) { + matched = true + break + } + } + if len(paths) > 0 && !matched { + return application.failure("plan", fail.Errorf("EMPTY_SELECTION", "requested scope %q contains no changed source path", scope), nil, 1) + } + } + saved, err := loadProfile(laneStore, status.Lane.ID) if err != nil { return application.failure("plan", err, nil, 1) } proposal := planProposal{ - SchemaVersion: "1.0.0", - Lane: status.Lane.ID, - StagedPaths: selected, - Groups: proposeSplitGroups(selected), - Instruction: "Review dependency closure, move any cross-cutting file into its best-fit group, then write one distinct Conventional Commit message per group in a commit plan.", + SchemaVersion: reviewPlanSchemaVersion, + State: "draft", + Lane: status.Lane.ID, + Agent: status.Lane.Agent, + Session: status.Lane.Session, + TargetRef: status.Lane.Ref, + LaneTip: status.Lane.CurrentSHA, + SourceHead: status.Lane.BaseSHA, + SourceMode: snapshot.Mode, + UntrackedPolicy: snapshot.UntrackedPolicy, + SourceDigest: snapshot.Digest, + SourceScopes: append([]string(nil), scopes...), + LeaseDigest: leaseScopeDigest(status.Leases, time.Now().UTC()), + MessagePolicy: saved.MessagePolicy, + SourcePaths: append([]string(nil), snapshot.Paths...), + Groups: proposeSplitGroups(snapshot.Paths), + Instruction: "Review every path group, add a non-empty message to each group, then change state from draft to reviewed. Capture rejects stale bindings and draft plans.", + } + if strings.TrimSpace(*out) != "" { + body, marshalErr := json.MarshalIndent(proposal, "", " ") + if marshalErr != nil { + return application.failure("plan", fail.Wrap("PLAN_WRITE_FAILED", marshalErr), nil, 1) + } + path, absoluteErr := filepath.Abs(*out) + if absoluteErr != nil { + return application.failure("plan", fail.Wrap("PLAN_WRITE_FAILED", absoluteErr), nil, 1) + } + if writeErr := atomicfile.Create(path, append(body, '\n'), 0o600); writeErr != nil { + if errors.Is(writeErr, atomicfile.ErrExists) { + writeErr = fail.New("PLAN_EXISTS", "refusing to overwrite existing plan: "+path) + } else { + writeErr = fail.Wrap("PLAN_WRITE_FAILED", writeErr) + } + return application.failure("plan", writeErr, nil, 1) + } + } + operational, err := buildOperationalStatus(ctx, laneStore, status, renewal) + if err != nil { + return application.failure("plan", err, proposal, 1) } - return application.success("plan", proposal, formatPlanProposal(proposal)) + return application.successWithContext("plan", proposal, formatPlanProposal(proposal), operational.context()) +} + +func planSourceScopes(laneStore store.Store, allowed, requested []string) ([]string, error) { + if len(requested) == 0 { + return append([]string(nil), allowed...), nil + } + scopes, err := laneStore.Repo.NormalizePaths(requested) + if err != nil { + return nil, err + } + for _, scope := range scopes { + if !pathid.Covered(scope, allowed) { + return nil, fail.Errorf("LEASE_REQUIRED", "requested scope %q is outside the active lease set", scope) + } + } + return scopes, nil } func proposeSplitGroups(paths []string) []splitProposal { @@ -125,7 +247,11 @@ func splitGroupKey(path string) string { case "CHANGELOG.md": return "changelog" } - return strings.TrimSuffix(name, filepath.Ext(name)) + key := strings.TrimSuffix(name, filepath.Ext(name)) + if strings.TrimSpace(key) == "" { + return "repository-config" + } + return key } if parts[0] == ".github" && len(parts) >= 2 { return strings.Join(parts[:2], "/") @@ -150,6 +276,8 @@ func splitScope(key string) string { return "deps" case "repository-docs", "docs": return "docs" + case "repository-config": + return "config" case ".github/workflows": return "ci" } @@ -183,6 +311,8 @@ func splitRationale(key string) string { return "dependency manifests and lockfiles must stay synchronized" case "repository-docs": return "repository-level policy and onboarding documentation" + case "repository-config": + return "repository-level configuration and tool pins" case "changelog": return "release history remains an explicit concern" case ".github/workflows": diff --git a/cmd/wip/plan_schema.go b/cmd/wip/plan_schema.go new file mode 100644 index 0000000..2a99d35 --- /dev/null +++ b/cmd/wip/plan_schema.go @@ -0,0 +1,222 @@ +package main + +import ( + "context" + "crypto/sha256" + "encoding/hex" + "encoding/json" + "io" + "sort" + "strings" + "time" + + "github.com/nstranquist/wip-commit/internal/engine" + "github.com/nstranquist/wip-commit/internal/fail" + "github.com/nstranquist/wip-commit/internal/pathid" + "github.com/nstranquist/wip-commit/internal/policy" + "github.com/nstranquist/wip-commit/internal/store" + "github.com/nstranquist/wip-commit/internal/strictjson" +) + +const reviewPlanSchemaVersion = "3.0.0" + +type resolvedCommitPlan struct { + Groups []engine.Group + ReviewDigest string + ExpectedSourceDigest string + SourceMode engine.SourceMode + UntrackedPolicy engine.UntrackedPolicy + Policy policy.Receipt + Reviewed bool + Plan *planProposal +} + +func decodeCommitPlan(reader io.Reader) (resolvedCommitPlan, error) { + body, err := readCommitPlanBody(reader) + if err != nil { + return resolvedCommitPlan{}, err + } + return decodeCommitPlanBody(body) +} + +func readCommitPlanBody(reader io.Reader) ([]byte, error) { + body, err := io.ReadAll(io.LimitReader(reader, maxPlanBytes+1)) + if err != nil { + return nil, fail.Wrap("INVALID_PLAN", err) + } + if len(body) > maxPlanBytes { + return nil, fail.Errorf("INVALID_PLAN", "plan exceeds %d bytes", maxPlanBytes) + } + return body, nil +} + +func decodeCommitPlanBody(body []byte) (resolvedCommitPlan, error) { + trimmed := strings.TrimSpace(string(body)) + if strings.HasPrefix(trimmed, "[") { + groups, err := decodeLegacyPlan(body) + return resolvedCommitPlan{Groups: groups}, err + } + var plan planProposal + if err := strictjson.Decode(body, &plan); err != nil { + return resolvedCommitPlan{}, fail.Wrap("INVALID_PLAN", err) + } + return resolvedCommitPlan{Groups: planGroups(plan), Reviewed: true, Plan: &plan}, nil +} + +func decodeLegacyPlan(body []byte) ([]engine.Group, error) { + var groups []engine.Group + if err := strictjson.Decode(body, &groups); err != nil { + return nil, fail.Wrap("INVALID_PLAN", err) + } + if len(groups) == 0 { + return nil, fail.New("INVALID_PLAN", "plan must contain at least one commit group") + } + return groups, nil +} + +func planGroups(plan planProposal) []engine.Group { + groups := make([]engine.Group, 0, len(plan.Groups)) + for _, group := range plan.Groups { + groups = append(groups, engine.Group{Message: group.Message, Files: append([]string(nil), group.Files...), Verify: append([]engine.VerifyCommand(nil), group.Verify...)}) + } + return groups +} + +func validateReviewedPlan(ctx context.Context, laneStore store.Store, lane store.Lane, allowed []string, plan *planProposal, allowWIP bool) (resolvedCommitPlan, error) { + if plan.SchemaVersion != reviewPlanSchemaVersion { + return resolvedCommitPlan{}, fail.Errorf("MIGRATION_REQUIRED", "capture plan schema %q is unsupported; this wip release supports %s", plan.SchemaVersion, reviewPlanSchemaVersion) + } + if plan.State != "reviewed" { + return resolvedCommitPlan{}, fail.New("PLAN_NOT_REVIEWED", "set plan state to reviewed only after replacing every empty message and reviewing each path group") + } + if plan.Lane != lane.ID || plan.Agent != lane.Agent || plan.Session != lane.Session || plan.TargetRef != lane.Ref || plan.LaneTip != lane.CurrentSHA { + return resolvedCommitPlan{}, fail.New("STALE_PLAN", "plan lane identity or tip no longer matches the active lane") + } + if plan.SourceHead != lane.BaseSHA { + return resolvedCommitPlan{}, fail.New("STALE_PLAN", "plan source HEAD no longer matches the lane base") + } + head, err := laneStore.Repo.Text(ctx, nil, "rev-parse", "HEAD") + if err != nil { + return resolvedCommitPlan{}, fail.Wrap("GIT_FAILED", err) + } + if head != plan.SourceHead { + return resolvedCommitPlan{}, fail.New("STALE_PLAN", "source HEAD changed after the plan was drafted") + } + saved, err := loadProfile(laneStore, lane.ID) + if err != nil { + return resolvedCommitPlan{}, err + } + if plan.MessagePolicy != saved.MessagePolicy { + return resolvedCommitPlan{}, fail.New("STALE_PLAN", "plan message policy differs from the lane profile") + } + if err := policy.ValidateReceipt(plan.MessagePolicy); err != nil { + return resolvedCommitPlan{}, err + } + status, err := laneStore.Status(lane.ID) + if err != nil { + return resolvedCommitPlan{}, err + } + if plan.LeaseDigest != leaseScopeDigest(status.Leases, time.Now().UTC()) { + return resolvedCommitPlan{}, fail.New("STALE_PLAN", "active lease scope changed after the plan was drafted") + } + mode, untracked, err := engine.NormalizeSource(plan.SourceMode, plan.UntrackedPolicy) + if err != nil || mode != plan.SourceMode || untracked != plan.UntrackedPolicy { + return resolvedCommitPlan{}, fail.New("INVALID_PLAN", "reviewed plan source mode or untracked policy is invalid") + } + scopes, err := laneStore.Repo.NormalizePaths(plan.SourceScopes) + if err != nil || len(scopes) == 0 || !samePlanStrings(scopes, plan.SourceScopes) { + return resolvedCommitPlan{}, fail.New("INVALID_PLAN", "reviewed plan source scopes are empty or not canonical") + } + for _, scope := range scopes { + if !pathid.Covered(scope, allowed) { + return resolvedCommitPlan{}, fail.New("STALE_PLAN", "reviewed plan source scope is outside the active lease set") + } + } + current, err := engine.InspectSource(ctx, laneStore.Repo, lane.CurrentSHA, scopes, mode, untracked) + if err != nil { + return resolvedCommitPlan{}, err + } + if !samePlanStrings(current.Paths, plan.SourcePaths) || current.Digest != plan.SourceDigest { + return resolvedCommitPlan{}, fail.New("STALE_PLAN", "the reviewed source path set or content changed after the plan was drafted") + } + groups := planGroups(*plan) + if len(groups) == 0 { + return resolvedCommitPlan{}, fail.New("INVALID_PLAN", "reviewed plan must contain at least one commit group") + } + var plannedPaths []string + for index, group := range plan.Groups { + if strings.TrimSpace(group.Key) == "" || strings.TrimSpace(group.SuggestedScope) == "" || strings.TrimSpace(group.SuggestedPrefix) == "" || strings.TrimSpace(group.Rationale) == "" { + return resolvedCommitPlan{}, fail.Errorf("INVALID_PLAN", "group %d is missing review guidance", index+1) + } + normalized, normalizeErr := laneStore.Repo.NormalizePaths(group.Files) + if normalizeErr != nil || !samePlanStrings(normalized, group.Files) { + return resolvedCommitPlan{}, fail.Errorf("INVALID_PLAN", "group %d files are not canonical", index+1) + } + plannedPaths = append(plannedPaths, normalized...) + } + sort.Strings(plannedPaths) + if !samePlanStrings(plannedPaths, plan.SourcePaths) { + return resolvedCommitPlan{}, fail.New("INVALID_PLAN", "reviewed groups must cover every planned path exactly once") + } + messages := make([]string, 0, len(groups)) + for _, group := range groups { + messages = append(messages, group.Message) + } + if err := policy.ValidateMessages(plan.MessagePolicy, messages, allowWIP); err != nil { + return resolvedCommitPlan{}, err + } + digest, err := reviewPlanDigest(*plan) + if err != nil { + return resolvedCommitPlan{}, err + } + return resolvedCommitPlan{ + Groups: groups, + ReviewDigest: digest, + ExpectedSourceDigest: plan.SourceDigest, + SourceMode: plan.SourceMode, + UntrackedPolicy: plan.UntrackedPolicy, + Policy: plan.MessagePolicy, + Reviewed: true, + }, nil +} + +func reviewPlanDigest(plan planProposal) (string, error) { + body, err := json.Marshal(plan) + if err != nil { + return "", fail.Wrap("INVALID_PLAN", err) + } + sum := sha256.Sum256(body) + return "sha256:" + hex.EncodeToString(sum[:]), nil +} + +func leaseScopeDigest(leases []store.Lease, now time.Time) string { + type scope struct { + ID string `json:"id"` + Paths []string `json:"paths"` + } + values := make([]scope, 0, len(leases)) + for _, lease := range leases { + if lease.State != "active" || lease.ExpiresAt != nil && !now.Before(*lease.ExpiresAt) { + continue + } + paths := append([]string(nil), lease.Paths...) + sort.Strings(paths) + values = append(values, scope{ID: lease.ID, Paths: paths}) + } + sort.Slice(values, func(left, right int) bool { return values[left].ID < values[right].ID }) + body, _ := json.Marshal(values) + sum := sha256.Sum256(body) + return "sha256:" + hex.EncodeToString(sum[:]) +} + +func samePlanStrings(left, right []string) bool { + if len(left) != len(right) { + return false + } + for index := range left { + if left[index] != right[index] { + return false + } + } + return true +} diff --git a/cmd/wip/profile.go b/cmd/wip/profile.go index dddbef3..4c7b792 100644 --- a/cmd/wip/profile.go +++ b/cmd/wip/profile.go @@ -9,6 +9,7 @@ import ( "github.com/nstranquist/wip-commit/internal/atomicfile" "github.com/nstranquist/wip-commit/internal/fail" + "github.com/nstranquist/wip-commit/internal/policy" "github.com/nstranquist/wip-commit/internal/recordjson" "github.com/nstranquist/wip-commit/internal/safeio" "github.com/nstranquist/wip-commit/internal/store" @@ -16,17 +17,19 @@ import ( ) type profile struct { - SchemaVersion int `json:"schema_version"` - Lane string `json:"lane"` - Agent string `json:"agent"` - Session string `json:"session"` - Mode store.Mode `json:"mode"` - Worktree string `json:"worktree"` + SchemaVersion int `json:"schema_version"` + Lane string `json:"lane"` + Agent string `json:"agent"` + Session string `json:"session"` + Mode store.Mode `json:"mode"` + Worktree string `json:"worktree"` + MessagePolicy policy.Receipt `json:"message_policy,omitempty"` } const ( - profileSchemaVersion = 1 - maxProfileBytes = 64 << 10 + profileSchemaVersion = 2 + legacyProfileSchemaVersion = 1 + maxProfileBytes = 64 << 10 ) type identityFlags struct { @@ -50,8 +53,8 @@ func profilePath(laneStore store.Store, lane string) (string, error) { return filepath.Join(laneStore.Root, "profiles", lane+".json"), nil } -func writeProfile(laneStore store.Store, lane store.Lane) (string, error) { - wanted := profile{SchemaVersion: profileSchemaVersion, Lane: lane.ID, Agent: lane.Agent, Session: lane.Session, Mode: lane.Mode, Worktree: lane.Worktree} +func writeProfile(laneStore store.Store, lane store.Lane, messagePolicy policy.Receipt) (string, error) { + wanted := profile{SchemaVersion: profileSchemaVersion, Lane: lane.ID, Agent: lane.Agent, Session: lane.Session, Mode: lane.Mode, Worktree: lane.Worktree, MessagePolicy: messagePolicy} body, err := recordjson.Marshal(wanted, maxProfileBytes, "PROFILE_WRITE_FAILED", "lane profile") if err != nil { return "", err @@ -93,8 +96,8 @@ func loadProfile(laneStore store.Store, lane string) (profile, error) { if err := strictjson.Decode(body, &value); err != nil { return profile{}, fail.Wrap("PROFILE_READ_FAILED", err) } - if value.SchemaVersion != profileSchemaVersion { - return profile{}, fail.Errorf("MIGRATION_REQUIRED", "profile schema version %d is unsupported; this wip release supports version %d", value.SchemaVersion, profileSchemaVersion) + if value.SchemaVersion != legacyProfileSchemaVersion && value.SchemaVersion != profileSchemaVersion { + return profile{}, fail.Errorf("MIGRATION_REQUIRED", "profile schema version %d is unsupported; this wip release supports versions %d and %d", value.SchemaVersion, legacyProfileSchemaVersion, profileSchemaVersion) } if value.Lane != lane { return profile{}, fail.New("PROFILE_READ_FAILED", "lane profile identity is invalid") @@ -110,6 +113,12 @@ func loadProfile(laneStore store.Store, lane string) (profile, error) { if value.Worktree == "" || !filepath.IsAbs(value.Worktree) || filepath.Clean(value.Worktree) != value.Worktree { return profile{}, fail.New("PROFILE_READ_FAILED", "lane profile worktree is invalid") } + if value.SchemaVersion == legacyProfileSchemaVersion { + value.SchemaVersion = profileSchemaVersion + value.MessagePolicy = policy.Default() + } else if err := policy.ValidateReceipt(value.MessagePolicy); err != nil { + return profile{}, fail.Wrap("PROFILE_READ_FAILED", err) + } laneRecord, err := laneStore.Load(lane) if err != nil { return profile{}, err diff --git a/cmd/wip/scale_dogfood_test.go b/cmd/wip/scale_dogfood_test.go new file mode 100644 index 0000000..94d35d2 --- /dev/null +++ b/cmd/wip/scale_dogfood_test.go @@ -0,0 +1,187 @@ +package main + +import ( + "encoding/json" + "fmt" + "os" + "path/filepath" + "slices" + "strings" + "testing" +) + +func TestCaptureSixHundredTrackedPathsWithoutChangingCallerState(t *testing.T) { + const fileCount = 600 + directory := cliTestRepo(t) + paths := make([]string, 0, fileCount) + for index := range fileCount { + name := fmt.Sprintf("scale/file-%03d.txt", index) + paths = append(paths, name) + writeCLI(t, directory, name, fmt.Sprintf("base %03d\n", index)) + } + cliGit(t, directory, "add", "scale") + cliGit(t, directory, "commit", "-m", "test: add scale fixture") + + headBefore := cliGit(t, directory, "rev-parse", "HEAD") + indexBefore := cliGitRaw(t, directory, "ls-files", "-s", "-z") + for index, name := range paths { + writeCLI(t, directory, name, fmt.Sprintf("captured %03d\n", index)) + } + initializeCLI(t, directory, "scale-600", paths...) + + planPath := filepath.Join(t.TempDir(), "scale-600.plan.json") + drafted := runCLI(t, []string{ + "--json", "--repo-dir", directory, "plan", "--lane", "scale-600", + "--source", "worktree_snapshot", "--untracked", "forbid", "--out", planPath, + }, "") + if drafted.code != 0 || !drafted.envelope.OK { + t.Fatalf("draft scale plan = %#v stderr=%s", drafted.envelope, drafted.stderr) + } + var plan planProposal + decodeData(t, drafted.envelope.Data, &plan) + if len(plan.SourcePaths) != fileCount || !slices.Equal(plan.SourcePaths, paths) { + t.Fatalf("scale plan paths = %d, want %d exact paths", len(plan.SourcePaths), fileCount) + } + plan.State = "reviewed" + for index := range plan.Groups { + plan.Groups[index].Message = "test(scale): capture six hundred exact paths" + } + writeReviewedProposal(t, planPath, plan) + reviewDigest, err := reviewPlanDigest(plan) + if err != nil { + t.Fatal(err) + } + + captured := runCLI(t, []string{ + "--json", "--repo-dir", directory, "capture", "--lane", "scale-600", + "--plan", planPath, "--review-plan-digest", reviewDigest, "--final", "--lock-wait", "0", + }, "") + if captured.code != 0 || !captured.envelope.OK { + t.Fatalf("capture scale plan = %#v stderr=%s", captured.envelope, captured.stderr) + } + var result guidedCaptureResult + decodeData(t, captured.envelope.Data, &result) + if !result.LaneReleased || !result.Capture.RefUpdated || result.Capture.GateOutcome != "passed" { + t.Fatalf("scale capture result = %#v", result) + } + if len(result.Capture.SourcePaths) != fileCount || len(result.Capture.RequestedPaths) != fileCount { + t.Fatalf("scale capture path counts = source %d requested %d", len(result.Capture.SourcePaths), len(result.Capture.RequestedPaths)) + } + if !result.Handoff.CaptureOnly || result.Handoff.LandingAuthorized || !result.Handoff.ReviewEligible { + t.Fatalf("scale handoff authority = %#v", result.Handoff) + } + + changed := strings.Split(cliGit(t, directory, "diff-tree", "--no-commit-id", "--name-only", "-r", result.Capture.FinalCommit), "\n") + if len(changed) != fileCount || !slices.Equal(changed, paths) { + t.Fatalf("captured tree changed %d paths, want %d exact paths", len(changed), fileCount) + } + if got := cliGit(t, directory, "show", result.Capture.FinalCommit+":"+paths[0]); got != "captured 000" { + t.Fatalf("first captured path = %q", got) + } + if got := cliGit(t, directory, "show", result.Capture.FinalCommit+":"+paths[fileCount-1]); got != "captured 599" { + t.Fatalf("last captured path = %q", got) + } + if got := cliGit(t, directory, "rev-parse", "HEAD"); got != headBefore { + t.Fatalf("source HEAD moved: before=%s after=%s", headBefore, got) + } + if got := cliGitRaw(t, directory, "ls-files", "-s", "-z"); got != indexBefore { + t.Fatal("600-path capture changed the caller index") + } +} + +func TestThreeDedicatedWorktreesCaptureIndependently(t *testing.T) { + anchor := cliTestRepo(t) + paths := []string{"lanes/one.txt", "lanes/two.txt", "lanes/three.txt"} + for index, name := range paths { + writeCLI(t, anchor, name, fmt.Sprintf("base %d\n", index+1)) + } + cliGit(t, anchor, "add", "lanes") + cliGit(t, anchor, "commit", "-m", "test: add worktree dogfood fixture") + + headBefore := cliGit(t, anchor, "rev-parse", "HEAD") + anchorIndexBefore := cliGitRaw(t, anchor, "ls-files", "-s", "-z") + tips := make([]string, 0, len(paths)) + for index, name := range paths { + lane := fmt.Sprintf("dedicated-%d", index+1) + worktree := filepath.Join(t.TempDir(), lane) + cliGit(t, anchor, "worktree", "add", "--detach", worktree, headBefore) + worktreeIndexBefore := cliGitRaw(t, worktree, "ls-files", "-s", "-z") + writeCLI(t, worktree, name, fmt.Sprintf("captured %d\n", index+1)) + + initialized := runCLI(t, []string{ + "--json", "--repo-dir", worktree, "init", "--mode", "worktree", + "--lane", lane, "--agent", "agent", "--session", "session", + "--path", name, "--non-interactive", "--no-install", "--no-install-skill", + }, "") + if initialized.code != 0 || !initialized.envelope.OK { + t.Fatalf("initialize %s = %#v stderr=%s", lane, initialized.envelope, initialized.stderr) + } + + planPath := filepath.Join(t.TempDir(), lane+".plan.json") + drafted := runCLI(t, []string{ + "--json", "--repo-dir", worktree, "plan", "--lane", lane, + "--source", "worktree_snapshot", "--untracked", "forbid", "--out", planPath, + }, "") + if drafted.code != 0 || !drafted.envelope.OK { + t.Fatalf("draft %s = %#v stderr=%s", lane, drafted.envelope, drafted.stderr) + } + var plan planProposal + decodeData(t, drafted.envelope.Data, &plan) + plan.State = "reviewed" + for group := range plan.Groups { + plan.Groups[group].Message = fmt.Sprintf("test(worktree): capture dedicated lane %d", index+1) + } + writeReviewedProposal(t, planPath, plan) + reviewDigest, err := reviewPlanDigest(plan) + if err != nil { + t.Fatal(err) + } + + captured := runCLI(t, []string{ + "--json", "--repo-dir", worktree, "capture", "--lane", lane, + "--plan", planPath, "--review-plan-digest", reviewDigest, "--final", "--lock-wait", "0", + }, "") + if captured.code != 0 || !captured.envelope.OK { + t.Fatalf("capture %s = %#v stderr=%s", lane, captured.envelope, captured.stderr) + } + var result guidedCaptureResult + decodeData(t, captured.envelope.Data, &result) + if !result.LaneReleased || !result.Handoff.CaptureOnly || result.Handoff.LandingAuthorized { + t.Fatalf("dedicated handoff %s = %#v", lane, result) + } + if got := cliGit(t, worktree, "show", result.Capture.FinalCommit+":"+name); got != fmt.Sprintf("captured %d", index+1) { + t.Fatalf("dedicated capture %s content = %q", lane, got) + } + if got := cliGit(t, worktree, "rev-parse", "HEAD"); got != headBefore { + t.Fatalf("dedicated worktree %s HEAD moved: %s", lane, got) + } + if got := cliGitRaw(t, worktree, "ls-files", "-s", "-z"); got != worktreeIndexBefore { + t.Fatalf("dedicated worktree %s index changed", lane) + } + tips = append(tips, result.Capture.FinalCommit) + } + if tips[0] == tips[1] || tips[0] == tips[2] || tips[1] == tips[2] { + t.Fatalf("dedicated lanes did not produce distinct tips: %v", tips) + } + if got := cliGit(t, anchor, "rev-parse", "HEAD"); got != headBefore { + t.Fatalf("anchor HEAD moved: before=%s after=%s", headBefore, got) + } + if got := cliGitRaw(t, anchor, "ls-files", "-s", "-z"); got != anchorIndexBefore { + t.Fatal("dedicated worktree captures changed the anchor index") + } + doctor := runCLI(t, []string{"--json", "--repo-dir", anchor, "doctor"}, "") + if doctor.code != 0 || !doctor.envelope.OK { + t.Fatalf("post-dogfood doctor = %#v stderr=%s", doctor.envelope, doctor.stderr) + } +} + +func writeReviewedProposal(t *testing.T, path string, plan planProposal) { + t.Helper() + body, err := json.MarshalIndent(plan, "", " ") + if err != nil { + t.Fatal(err) + } + if err := os.WriteFile(path, append(body, '\n'), 0o600); err != nil { + t.Fatal(err) + } +} diff --git a/cmd/wip/schema_contract_test.go b/cmd/wip/schema_contract_test.go new file mode 100644 index 0000000..78f4858 --- /dev/null +++ b/cmd/wip/schema_contract_test.go @@ -0,0 +1,102 @@ +package main + +import ( + "bytes" + "encoding/json" + "os" + "path/filepath" + "testing" + + "github.com/santhosh-tekuri/jsonschema/v6" +) + +func TestCommandOutputsMatchPublishedJSONSchemas(t *testing.T) { + directory := cliTestRepo(t) + writeCLI(t, directory, "core.txt", "new core\n") + cliGit(t, directory, "add", "core.txt") + initializeCLI(t, directory, "schema-contract", "core.txt") + + planPath := filepath.Join(t.TempDir(), "plan.json") + drafted := runCLI(t, []string{"--json", "--repo-dir", directory, "plan", "--lane", "schema-contract", "--out", planPath}, "") + if drafted.code != 0 { + t.Fatalf("draft plan = %#v stderr=%s", drafted.envelope, drafted.stderr) + } + validateSchemaValue(t, "PLAN.schema.json", drafted.envelope.Data) + var reviewed planProposal + decodeData(t, drafted.envelope.Data, &reviewed) + reviewed.State = "reviewed" + for index := range reviewed.Groups { + reviewed.Groups[index].Message = "fix(schema): validate published command contracts" + } + validateSchemaValue(t, "PLAN.schema.json", reviewed) + body, err := json.MarshalIndent(reviewed, "", " ") + if err != nil { + t.Fatal(err) + } + if err := os.WriteFile(planPath, append(body, '\n'), 0o600); err != nil { + t.Fatal(err) + } + + status := runCLI(t, []string{"--json", "--repo-dir", directory, "status", "--lane", "schema-contract", "--observe=true"}, "") + if status.code != 0 { + t.Fatalf("status = %#v stderr=%s", status.envelope, status.stderr) + } + validateSchemaValue(t, "STATUS.schema.json", status.envelope.Data) + + captured := runCLI(t, []string{"--json", "--repo-dir", directory, "capture", "--lane", "schema-contract", "--plan", planPath}, "") + if captured.code != 0 { + t.Fatalf("capture = %#v stderr=%s", captured.envelope, captured.stderr) + } + var result guidedCaptureResult + decodeData(t, captured.envelope.Data, &result) + validateSchemaValue(t, "HANDOFF.schema.json", result.Handoff) + + legacy := []byte(`[{"message":"fix(schema): validate legacy plan","files":["core.txt"]}]`) + validateSchemaJSON(t, "PLAN.legacy-v1.schema.json", legacy) + + invalid, err := json.Marshal(map[string]any{ + "schema_version": "1.0.0", + "unexpected": true, + }) + if err != nil { + t.Fatal(err) + } + if err := schemaValidationError(t, "HANDOFF.schema.json", invalid); err == nil { + t.Fatal("handoff schema accepted an incomplete object with an unknown field") + } +} + +func validateSchemaValue(t *testing.T, schemaName string, value any) { + t.Helper() + body, err := json.Marshal(value) + if err != nil { + t.Fatal(err) + } + validateSchemaJSON(t, schemaName, body) +} + +func validateSchemaJSON(t *testing.T, schemaName string, body []byte) { + t.Helper() + if err := schemaValidationError(t, schemaName, body); err != nil { + t.Fatalf("%s rejected command data: %v\n%s", schemaName, err, body) + } +} + +func schemaValidationError(t *testing.T, schemaName string, body []byte) error { + t.Helper() + instance, err := jsonschema.UnmarshalJSON(bytes.NewReader(body)) + if err != nil { + t.Fatalf("decode schema instance: %v", err) + } + schemaPath, err := filepath.Abs(filepath.Join("..", "..", "docs", schemaName)) + if err != nil { + t.Fatal(err) + } + compiler := jsonschema.NewCompiler() + compiler.AssertFormat() + schema, err := compiler.Compile(schemaPath) + if err != nil { + t.Fatalf("compile %s: %v", schemaName, err) + } + return schema.Validate(instance) +} diff --git a/cmd/wip/status.go b/cmd/wip/status.go new file mode 100644 index 0000000..6fbdda2 --- /dev/null +++ b/cmd/wip/status.go @@ -0,0 +1,197 @@ +package main + +import ( + "context" + "sort" + "time" + + "github.com/nstranquist/wip-commit/internal/engine" + "github.com/nstranquist/wip-commit/internal/fail" + "github.com/nstranquist/wip-commit/internal/pathid" + "github.com/nstranquist/wip-commit/internal/policy" + "github.com/nstranquist/wip-commit/internal/store" +) + +type renewalStatus struct { + Attempted bool `json:"attempted"` + Succeeded bool `json:"succeeded"` + RenewedAt *time.Time `json:"renewed_at,omitempty"` +} + +type refHealth struct { + Healthy bool `json:"healthy"` + Expected string `json:"expected"` + Actual string `json:"actual,omitempty"` + Issue string `json:"issue,omitempty"` +} + +type operationalStatus struct { + SchemaVersion string `json:"schema_version"` + store.Status + MessagePolicy policy.Receipt `json:"message_policy"` + ActivePaths []string `json:"active_paths"` + LeasedButNotStaged []string `json:"leased_but_not_staged"` + EmptyLeaseScopes []string `json:"empty_lease_scopes"` + CaptureCandidates []string `json:"capture_candidates"` + CapturedButStillStaged []string `json:"captured_but_still_staged"` + StagedLeased []string `json:"staged_leased"` + ForeignStaged []string `json:"foreign_staged"` + ExpiredLeaseIDs []string `json:"expired_lease_ids"` + LeaseExpiresAt *time.Time `json:"lease_expires_at"` + LeaseRemainingMS int64 `json:"lease_remaining_ms"` + Renewal renewalStatus `json:"renewal"` + RefHealth refHealth `json:"ref_health"` + LastIntent *engine.IntentSummary `json:"last_intent,omitempty"` +} + +type laneContext struct { + Lane string `json:"lane"` + Ref string `json:"ref"` + Tip string `json:"tip"` + LeaseExpiresAt *time.Time `json:"lease_expires_at"` + LeaseRemainingMS int64 `json:"lease_remaining_ms"` + LeaseRenewed bool `json:"lease_renewed"` + MessagePolicy policy.Receipt `json:"message_policy"` + LatestIntentState string `json:"latest_intent_state,omitempty"` +} + +func (status operationalStatus) context() *laneContext { + value := &laneContext{Lane: status.Lane.ID, Ref: status.Lane.Ref, Tip: status.Lane.CurrentSHA, LeaseExpiresAt: status.LeaseExpiresAt, LeaseRemainingMS: status.LeaseRemainingMS, LeaseRenewed: status.Renewal.Succeeded, MessagePolicy: status.MessagePolicy} + if status.LastIntent != nil { + value.LatestIntentState = status.LastIntent.State + } + return value +} + +func buildOperationalStatus(ctx context.Context, laneStore store.Store, status store.Status, renewal renewalStatus) (operationalStatus, error) { + result := operationalStatus{SchemaVersion: "2.0.0", Status: status, Renewal: renewal} + now := time.Now().UTC() + var activeScopes []string + for _, lease := range status.Leases { + if lease.State == "active" && (lease.ExpiresAt == nil || now.Before(*lease.ExpiresAt)) { + activeScopes = append(activeScopes, lease.Paths...) + if lease.ExpiresAt != nil && (result.LeaseExpiresAt == nil || lease.ExpiresAt.Before(*result.LeaseExpiresAt)) { + expires := *lease.ExpiresAt + result.LeaseExpiresAt = &expires + } + } else if lease.State == "active" { + result.ExpiredLeaseIDs = append(result.ExpiredLeaseIDs, lease.ID) + } + } + result.ActivePaths = canonicalStrings(activeScopes) + if result.LeaseExpiresAt != nil { + result.LeaseRemainingMS = maxInt64(0, result.LeaseExpiresAt.Sub(now).Milliseconds()) + } + saved, err := loadProfile(laneStore, status.Lane.ID) + if err != nil { + return result, err + } + result.MessagePolicy = saved.MessagePolicy + indexEntries, err := laneStore.Repo.IndexEntries(ctx, nil) + if err != nil { + return result, fail.Wrap("GIT_FAILED", err) + } + laneEntries, err := laneStore.Repo.TreeEntries(ctx, status.Lane.CurrentSHA) + if err != nil { + return result, fail.Wrap("GIT_FAILED", err) + } + headEntries, err := laneStore.Repo.TreeEntries(ctx, status.Lane.BaseSHA) + if err != nil { + return result, fail.Wrap("GIT_FAILED", err) + } + paths := map[string]bool{} + for path := range indexEntries { + paths[path] = true + } + for path := range laneEntries { + paths[path] = true + } + for path := range headEntries { + paths[path] = true + } + for path := range paths { + leased := pathid.Covered(path, result.ActivePaths) + staged := indexEntries[path] != headEntries[path] + pending := indexEntries[path] != laneEntries[path] + if leased { + if staged { + result.StagedLeased = append(result.StagedLeased, path) + } + if pending { + result.CaptureCandidates = append(result.CaptureCandidates, path) + } else if staged { + result.CapturedButStillStaged = append(result.CapturedButStillStaged, path) + } + } else if staged { + result.ForeignStaged = append(result.ForeignStaged, path) + } + } + for _, scope := range result.ActivePaths { + populated := false + for _, path := range append(append([]string(nil), result.StagedLeased...), result.CaptureCandidates...) { + if pathid.Covered(path, []string{scope}) { + populated = true + break + } + } + if !populated { + result.LeasedButNotStaged = append(result.LeasedButNotStaged, scope) + } + } + result.LeasedButNotStaged = canonicalStrings(result.LeasedButNotStaged) + result.EmptyLeaseScopes = append([]string{}, result.LeasedButNotStaged...) + result.CaptureCandidates = canonicalStrings(result.CaptureCandidates) + result.CapturedButStillStaged = canonicalStrings(result.CapturedButStillStaged) + result.StagedLeased = canonicalStrings(result.StagedLeased) + result.ForeignStaged = canonicalStrings(result.ForeignStaged) + result.ExpiredLeaseIDs = canonicalStrings(result.ExpiredLeaseIDs) + result.RefHealth = refHealth{Expected: status.Lane.CurrentSHA} + actual, refErr := laneStore.Repo.Text(ctx, nil, "rev-parse", "--verify", status.Lane.Ref+"^{commit}") + if refErr != nil { + result.RefHealth.Issue = "ref_not_found" + } else { + result.RefHealth.Actual = actual + result.RefHealth.Healthy = actual == status.Lane.CurrentSHA + if !result.RefHealth.Healthy { + result.RefHealth.Issue = "ref_tip_mismatch" + } + } + result.LastIntent, err = engine.LatestIntent(laneStore.Repo, status.Lane.Ref) + if err != nil { + return result, err + } + return result, nil +} + +func canonicalStrings(values []string) []string { + if len(values) == 0 { + return []string{} + } + sort.Strings(values) + out := values[:0] + for _, value := range values { + if len(out) == 0 || out[len(out)-1] != value { + out = append(out, value) + } + } + return out +} + +func maxInt64(left, right int64) int64 { + if left > right { + return left + } + return right +} + +func laneContextFor(ctx context.Context, laneStore store.Store, laneID string, renewal renewalStatus) (*laneContext, error) { + status, err := laneStore.Status(laneID) + if err != nil { + return nil, err + } + operational, err := buildOperationalStatus(ctx, laneStore, status, renewal) + if err != nil { + return nil, err + } + return operational.context(), nil +} diff --git a/cmd/wip/upgrade.go b/cmd/wip/upgrade.go new file mode 100644 index 0000000..c628f8a --- /dev/null +++ b/cmd/wip/upgrade.go @@ -0,0 +1,499 @@ +package main + +import ( + "context" + "crypto/sha256" + "encoding/hex" + "encoding/json" + "errors" + "fmt" + "io/fs" + "os" + "path/filepath" + "runtime" + "strings" + + "github.com/nstranquist/wip-commit/internal/atomicfile" + "github.com/nstranquist/wip-commit/internal/fail" + "github.com/nstranquist/wip-commit/internal/filelock" + "github.com/nstranquist/wip-commit/internal/gitx" + "github.com/nstranquist/wip-commit/internal/safeio" + "github.com/nstranquist/wip-commit/internal/store" + skillbundle "github.com/nstranquist/wip-commit/skills/wip-commit" +) + +const ( + upgradeSchemaVersion = "2.0.0" + maxUpgradeBinarySize = 512 << 20 +) + +type upgradeOptions struct { + state, binary, skill bool + apply, yes bool + planDigest string + installDir string + skillDir string +} + +type upgradeResult struct { + SchemaVersion string `json:"schema_version"` + Target string `json:"target"` + Path string `json:"path"` + CurrentSHA256 string `json:"current_sha256"` + DesiredSHA256 string `json:"desired_sha256"` + RevisionStore string `json:"revision_store,omitempty"` + PreviousRevisionPath string `json:"previous_revision_path,omitempty"` + DesiredRevisionPath string `json:"desired_revision_path,omitempty"` + PlanDigest string `json:"plan_digest"` + AlreadyCurrent bool `json:"already_current"` + Applied bool `json:"applied"` +} + +type upgradeBinding struct { + SchemaVersion string `json:"schema_version"` + Target string `json:"target"` + Path string `json:"path"` + CurrentSHA256 string `json:"current_sha256"` + DesiredSHA256 string `json:"desired_sha256"` + RevisionStore string `json:"revision_store,omitempty"` + PreviousRevisionPath string `json:"previous_revision_path,omitempty"` + DesiredRevisionPath string `json:"desired_revision_path,omitempty"` +} + +type upgradeMaterial struct { + target, path, currentSHA256, desiredSHA256 string + revisionStore, previousRevisionPath, desiredRevisionPath string + alreadyCurrent bool +} + +func (application app) runUpgrade(ctx context.Context, args []string) int { + set := application.flagSet("upgrade") + options := upgradeOptions{} + set.BoolVar(&options.state, "state", false, "upgrade the coordination-domain marker") + set.BoolVar(&options.binary, "binary", false, "upgrade an existing installed binary") + set.BoolVar(&options.skill, "skill", false, "upgrade an existing portable skill") + set.BoolVar(&options.apply, "apply", false, "apply the reviewed upgrade") + set.BoolVar(&options.yes, "yes", false, "confirm the reviewed upgrade") + set.StringVar(&options.planDigest, "plan-digest", "", "exact digest from preview") + set.StringVar(&options.installDir, "install-dir", "", "binary install directory") + set.StringVar(&options.skillDir, "skill-dir", "", "agent skill directory") + if err := set.Parse(args); err != nil { + return application.failure("upgrade", fail.Wrap("INVALID_ARGS", err), nil, 2) + } + if err := noArgs(set); err != nil { + return application.failure("upgrade", err, nil, 2) + } + selected := 0 + for _, value := range []bool{options.state, options.binary, options.skill} { + if value { + selected++ + } + } + if selected != 1 { + return application.failure("upgrade", fail.New("INVALID_ARGS", "select exactly one of --state, --binary, or --skill"), nil, 2) + } + if options.apply && (!options.yes || options.planDigest == "") { + return application.failure("upgrade", fail.New("INVALID_ARGS", "--apply requires --yes and --plan-digest"), nil, 2) + } + if !options.apply && (options.yes || options.planDigest != "") { + return application.failure("upgrade", fail.New("INVALID_ARGS", "--yes and --plan-digest require --apply"), nil, 2) + } + if options.planDigest != "" && !validSHA256(options.planDigest) { + return application.failure("upgrade", fail.New("INVALID_ARGS", "--plan-digest must be sha256 followed by 64 lowercase hexadecimal characters"), nil, 2) + } + + material, repo, err := application.inspectUpgrade(ctx, options) + if err != nil { + return application.failure("upgrade", err, nil, 1) + } + result, err := bindUpgrade(material) + if err != nil { + return application.failure("upgrade", fail.Wrap("UPGRADE_FAILED", err), nil, 1) + } + if options.apply { + if options.planDigest != result.PlanDigest { + return application.failure("upgrade", fail.New("UPGRADE_PLAN_DIGEST_MISMATCH", "upgrade plan digest does not match the current byte-bound preview"), result, 1) + } + if err := application.applyUpgrade(ctx, options, repo, material); err != nil { + return application.failure("upgrade", err, result, 1) + } + result.Applied = !result.AlreadyCurrent + } + return application.success("upgrade", result, formatUpgradeResult(result)) +} + +func (application app) inspectUpgrade(ctx context.Context, options upgradeOptions) (upgradeMaterial, gitx.Repo, error) { + if options.state { + repo, err := gitx.Discover(ctx, application.repoDir) + if err != nil { + return upgradeMaterial{}, gitx.Repo{}, err + } + plan, err := store.InspectDomainUpgrade(repo) + if err != nil { + return upgradeMaterial{}, repo, err + } + if !plan.AlreadyCurrent { + if err := ensureStateUpgradeQuiescent(ctx, repo); err != nil { + return upgradeMaterial{}, repo, err + } + } + return upgradeMaterial{target: "state", path: plan.Path, currentSHA256: plan.CurrentSHA256, desiredSHA256: plan.DesiredSHA256, alreadyCurrent: plan.AlreadyCurrent}, repo, nil + } + if options.binary { + directory, err := normalizedUpgradeDirectory(options.installDir, ".local", "bin") + if err != nil { + return upgradeMaterial{}, gitx.Repo{}, err + } + material, err := inspectBinaryUpgrade(directory) + return material, gitx.Repo{}, err + } + directory, err := normalizedUpgradeDirectory(options.skillDir, ".agents", "skills") + if err != nil { + return upgradeMaterial{}, gitx.Repo{}, err + } + material, err := inspectSkillUpgrade(directory) + return material, gitx.Repo{}, err +} + +func (application app) applyUpgrade(ctx context.Context, options upgradeOptions, repo gitx.Repo, reviewed upgradeMaterial) error { + if options.state { + if err := ensureStateUpgradeQuiescent(ctx, repo); err != nil { + return err + } + applied, err := store.ApplyDomainUpgrade(repo, reviewed.currentSHA256) + if err != nil { + return err + } + if applied.CurrentSHA256 != reviewed.desiredSHA256 || !applied.AlreadyCurrent { + return fail.New("UPGRADE_FAILED", "state marker did not verify at the reviewed desired digest") + } + return nil + } + if options.binary { + return applyBinaryUpgrade(reviewed) + } + return applySkillUpgrade(reviewed) +} + +func ensureStateUpgradeQuiescent(ctx context.Context, repo gitx.Repo) error { + laneStore, initialized, err := store.Inspect(repo) + if err != nil { + return err + } + if !initialized { + return fail.New("STATE_NOT_INITIALIZED", "coordination state is not initialized") + } + report := doctorReport{Counts: map[string]int{}, ActiveLanes: []string{}, ExpiredLanes: []string{}, PendingInit: []string{}, PendingCapture: []string{}, PendingArchive: []string{}, ArchiveCandidates: []string{}, Findings: []doctorFinding{}} + auditDoctor(ctx, laneStore, &report) + if len(report.ActiveLanes) > 0 || len(report.PendingInit) > 0 || len(report.PendingCapture) > 0 || len(report.PendingArchive) > 0 { + return fail.New("UPGRADE_BLOCKED", "state upgrade requires no active lanes and no pending initialization, capture, or archive recovery") + } + for _, finding := range report.Findings { + if finding.Severity == "error" || finding.Severity == "recovery" { + return fail.New("UPGRADE_BLOCKED", "state upgrade requires a healthy doctor report: "+finding.Code) + } + } + return nil +} + +func bindUpgrade(material upgradeMaterial) (upgradeResult, error) { + binding := upgradeBinding{ + SchemaVersion: upgradeSchemaVersion, Target: material.target, Path: material.path, + CurrentSHA256: material.currentSHA256, DesiredSHA256: material.desiredSHA256, + RevisionStore: material.revisionStore, PreviousRevisionPath: material.previousRevisionPath, DesiredRevisionPath: material.desiredRevisionPath, + } + body, err := json.Marshal(binding) + if err != nil { + return upgradeResult{}, err + } + return upgradeResult{ + SchemaVersion: upgradeSchemaVersion, Target: material.target, Path: material.path, + CurrentSHA256: material.currentSHA256, DesiredSHA256: material.desiredSHA256, + RevisionStore: material.revisionStore, PreviousRevisionPath: material.previousRevisionPath, DesiredRevisionPath: material.desiredRevisionPath, + PlanDigest: digest(body), AlreadyCurrent: material.alreadyCurrent, + }, nil +} + +func inspectBinaryUpgrade(directory string) (upgradeMaterial, error) { + path := filepath.Join(directory, binaryName()) + info, err := os.Lstat(path) + if errors.Is(err, os.ErrNotExist) { + return upgradeMaterial{}, fail.New("UPGRADE_TARGET_MISSING", "installed binary does not exist; use wip init --install for first installation") + } + if err != nil { + return upgradeMaterial{}, fail.Wrap("UPGRADE_FAILED", err) + } + if !info.Mode().IsRegular() || info.Mode()&os.ModeSymlink != 0 || runtime.GOOS != "windows" && info.Mode().Perm()&0o111 == 0 { + return upgradeMaterial{}, fail.New("UPGRADE_CONFLICT", "installed binary is not a regular executable file") + } + if info.Size() > maxUpgradeBinarySize { + return upgradeMaterial{}, fail.New("UPGRADE_CONFLICT", "installed binary exceeds the upgrade read bound") + } + current, err := safeio.ReadRegular(path, maxUpgradeBinarySize) + if err != nil { + return upgradeMaterial{}, fail.Wrap("UPGRADE_FAILED", err) + } + _, desired, err := selfExecutable() + if err != nil { + return upgradeMaterial{}, err + } + currentDigest, desiredDigest := digest(current), digest(desired) + revisionStore := filepath.Join(directory, "."+binaryName()+".revisions") + return upgradeMaterial{ + target: "binary", path: path, currentSHA256: currentDigest, desiredSHA256: desiredDigest, + revisionStore: revisionStore, + previousRevisionPath: binaryRevisionPath(revisionStore, currentDigest), + desiredRevisionPath: binaryRevisionPath(revisionStore, desiredDigest), + alreadyCurrent: currentDigest == desiredDigest, + }, nil +} + +func applyBinaryUpgrade(reviewed upgradeMaterial) error { + lock, err := filelock.Acquire(reviewed.path+".upgrade.lock", filelock.DefaultWait) + if err != nil { + return fail.Wrap("LOCK_TIMEOUT", err) + } + defer func() { _ = lock.Release() }() + fresh, err := inspectBinaryUpgrade(filepath.Dir(reviewed.path)) + if err != nil { + return err + } + if fresh.path != reviewed.path || fresh.currentSHA256 != reviewed.currentSHA256 || fresh.desiredSHA256 != reviewed.desiredSHA256 { + return fail.New("UPGRADE_PLAN_MOVED", "installed binary changed after preview; review a new upgrade plan") + } + if fresh.alreadyCurrent { + return nil + } + _, body, err := selfExecutable() + if err != nil { + return err + } + previous, err := safeio.ReadRegular(reviewed.path, maxUpgradeBinarySize) + if err != nil { + return fail.Wrap("UPGRADE_FAILED", err) + } + if digest(previous) != reviewed.currentSHA256 || digest(body) != reviewed.desiredSHA256 { + return fail.New("UPGRADE_PLAN_MOVED", "upgrade bytes changed after the reviewed plan was revalidated") + } + if err := retainBinaryRevision(reviewed.revisionStore, reviewed.previousRevisionPath, previous, reviewed.currentSHA256); err != nil { + return err + } + if err := retainBinaryRevision(reviewed.revisionStore, reviewed.desiredRevisionPath, body, reviewed.desiredSHA256); err != nil { + return err + } + if err := atomicfile.Write(reviewed.path, body, 0o755); err != nil { + return fail.Wrap("UPGRADE_FAILED", err) + } + verified, err := inspectBinaryUpgrade(filepath.Dir(reviewed.path)) + if err != nil || verified.currentSHA256 != reviewed.desiredSHA256 { + if err != nil { + return err + } + return fail.New("UPGRADE_FAILED", "installed binary verification failed after atomic replacement") + } + return nil +} + +func binaryRevisionPath(store, value string) string { + return filepath.Join(store, "sha256-"+strings.TrimPrefix(value, "sha256:")) +} + +func retainBinaryRevision(store, path string, body []byte, expectedDigest string) error { + if path != binaryRevisionPath(store, expectedDigest) { + return fail.New("UPGRADE_FAILED", "binary revision path does not match its reviewed digest") + } + if err := ensureBinaryRevisionStore(store); err != nil { + return err + } + if err := atomicfile.Create(path, body, 0o555); err != nil && !errors.Is(err, atomicfile.ErrExists) { + return fail.Wrap("UPGRADE_FAILED", err) + } + retained, err := safeio.ReadRegular(path, maxUpgradeBinarySize) + if err != nil { + return fail.Wrap("UPGRADE_FAILED", err) + } + if digest(retained) != expectedDigest { + return fail.New("UPGRADE_CONFLICT", "retained binary revision does not match its content-addressed path") + } + if err := ensureBinaryRevisionStore(store); err != nil { + return err + } + return nil +} + +func ensureBinaryRevisionStore(path string) error { + if err := os.Mkdir(path, 0o700); err != nil && !errors.Is(err, os.ErrExist) { + return fail.Wrap("UPGRADE_FAILED", err) + } + info, err := os.Lstat(path) + if err != nil { + return fail.Wrap("UPGRADE_FAILED", err) + } + if !info.IsDir() || info.Mode()&os.ModeSymlink != 0 { + return fail.New("UPGRADE_CONFLICT", "binary revision store is not a regular directory") + } + return nil +} + +func inspectSkillUpgrade(directory string) (upgradeMaterial, error) { + path := portableSkillPath(directory) + files, err := readSkillSnapshot(path) + if err != nil { + return upgradeMaterial{}, err + } + currentDigest, err := skillbundle.DigestFiles(files) + if err != nil { + return upgradeMaterial{}, fail.Wrap("UPGRADE_FAILED", err) + } + desiredDigest, err := skillbundle.BundleDigest() + if err != nil { + return upgradeMaterial{}, fail.Wrap("UPGRADE_FAILED", err) + } + return upgradeMaterial{target: "skill", path: path, currentSHA256: currentDigest, desiredSHA256: desiredDigest, alreadyCurrent: currentDigest == desiredDigest}, nil +} + +func readSkillSnapshot(path string) (map[string][]byte, error) { + info, err := os.Lstat(path) + if errors.Is(err, os.ErrNotExist) { + return nil, fail.New("UPGRADE_TARGET_MISSING", "portable skill does not exist; use wip init --install-skill for first installation") + } + if err != nil || !info.IsDir() || info.Mode()&os.ModeSymlink != 0 { + if err != nil { + return nil, fail.Wrap("UPGRADE_FAILED", err) + } + return nil, fail.New("UPGRADE_CONFLICT", "portable skill target is not a regular directory") + } + allowedFiles := map[string]bool{} + allowedDirectories := map[string]bool{} + for _, name := range skillbundle.Paths { + allowedFiles[name] = true + for directory := filepath.ToSlash(filepath.Dir(filepath.FromSlash(name))); directory != "."; directory = filepath.ToSlash(filepath.Dir(filepath.FromSlash(directory))) { + allowedDirectories[directory] = true + } + } + files := map[string][]byte{} + entries := 0 + err = filepath.WalkDir(path, func(candidate string, entry fs.DirEntry, walkErr error) error { + if walkErr != nil { + return walkErr + } + if candidate == path { + return nil + } + entries++ + if entries > maxSkillEntries { + return fail.Errorf("UPGRADE_CONFLICT", "portable skill exceeds %d entries", maxSkillEntries) + } + if entry.Type()&os.ModeSymlink != 0 { + return fail.New("UPGRADE_CONFLICT", "portable skill contains a symlink") + } + relative, relErr := filepath.Rel(path, candidate) + if relErr != nil { + return relErr + } + relative = filepath.ToSlash(relative) + if entry.IsDir() { + if !allowedDirectories[relative] { + return fail.New("UPGRADE_CONFLICT", "portable skill has an unexpected directory: "+relative) + } + return nil + } + if !allowedFiles[relative] { + return fail.New("UPGRADE_CONFLICT", "portable skill has an unexpected file: "+relative) + } + body, readErr := safeio.ReadRegular(candidate, maxPortableSkillFileSize) + if readErr != nil { + return readErr + } + files[relative] = body + return nil + }) + if err != nil { + var typed *fail.Error + if errors.As(err, &typed) { + return nil, err + } + return nil, fail.Wrap("UPGRADE_FAILED", err) + } + for _, required := range skillbundle.PayloadPaths { + if _, ok := files[required]; !ok { + return nil, fail.New("UPGRADE_CONFLICT", "portable skill is missing required file: "+required) + } + } + return files, nil +} + +func applySkillUpgrade(reviewed upgradeMaterial) error { + lockPath := filepath.Join(filepath.Dir(reviewed.path), ".wip-commit-skill-upgrade.lock") + lock, err := filelock.Acquire(lockPath, filelock.DefaultWait) + if err != nil { + return fail.Wrap("LOCK_TIMEOUT", err) + } + defer func() { _ = lock.Release() }() + fresh, err := inspectSkillUpgrade(filepath.Dir(reviewed.path)) + if err != nil { + return err + } + if fresh.path != reviewed.path || fresh.currentSHA256 != reviewed.currentSHA256 || fresh.desiredSHA256 != reviewed.desiredSHA256 { + return fail.New("UPGRADE_PLAN_MOVED", "portable skill changed after preview; review a new upgrade plan") + } + if fresh.alreadyCurrent { + return nil + } + for _, name := range skillbundle.Paths { + body, err := skillbundle.FS.ReadFile(name) + if err != nil { + return fail.Wrap("UPGRADE_FAILED", err) + } + if err := atomicfile.Write(filepath.Join(reviewed.path, filepath.FromSlash(name)), body, 0o644); err != nil { + return fail.Wrap("UPGRADE_FAILED", err) + } + } + verified, err := inspectSkillUpgrade(filepath.Dir(reviewed.path)) + if err != nil || verified.currentSHA256 != reviewed.desiredSHA256 { + if err != nil { + return err + } + return fail.New("UPGRADE_FAILED", "portable skill verification failed after replacement") + } + return nil +} + +func normalizedUpgradeDirectory(value string, defaults ...string) (string, error) { + if value == "" { + home, err := os.UserHomeDir() + if err != nil { + return "", fail.Wrap("INVALID_PATH", err) + } + parts := append([]string{home}, defaults...) + value = filepath.Join(parts...) + } + absolute, err := filepath.Abs(value) + if err != nil { + return "", fail.Wrap("INVALID_PATH", err) + } + return filepath.Clean(absolute), nil +} + +func digest(body []byte) string { + value := sha256.Sum256(body) + return "sha256:" + hex.EncodeToString(value[:]) +} + +func validSHA256(value string) bool { + if !strings.HasPrefix(value, "sha256:") || len(value) != len("sha256:")+64 { + return false + } + _, err := hex.DecodeString(strings.TrimPrefix(value, "sha256:")) + return err == nil && value == strings.ToLower(value) +} + +func formatUpgradeResult(result upgradeResult) string { + state := "preview" + if result.AlreadyCurrent { + state = "already current" + } else if result.Applied { + state = "applied" + } + return fmt.Sprintf("%s upgrade %s: %s\nplan digest: %s", result.Target, state, result.Path, result.PlanDigest) +} diff --git a/cmd/wip/upgrade_test.go b/cmd/wip/upgrade_test.go new file mode 100644 index 0000000..9561804 --- /dev/null +++ b/cmd/wip/upgrade_test.go @@ -0,0 +1,226 @@ +package main + +import ( + "context" + "errors" + "fmt" + "os" + "path/filepath" + "testing" + + "github.com/nstranquist/wip-commit/internal/gitx" + "github.com/nstranquist/wip-commit/internal/store" + skillbundle "github.com/nstranquist/wip-commit/skills/wip-commit" +) + +func TestBinaryUpgradeRequiresExactReviewedDigest(t *testing.T) { + directory := t.TempDir() + path := filepath.Join(directory, binaryName()) + oldBody := []byte("old executable\n") + if err := os.WriteFile(path, oldBody, 0o755); err != nil { + t.Fatal(err) + } + preview := runCLI(t, []string{"--json", "upgrade", "--binary", "--install-dir", directory}, "") + if preview.code != 0 || !preview.envelope.OK { + t.Fatalf("binary preview = %#v stderr=%s", preview.envelope, preview.stderr) + } + var plan upgradeResult + decodeData(t, preview.envelope.Data, &plan) + if plan.Target != "binary" || plan.AlreadyCurrent || !validSHA256(plan.PlanDigest) { + t.Fatalf("binary plan = %#v", plan) + } + if plan.SchemaVersion != "2.0.0" || plan.RevisionStore == "" || plan.PreviousRevisionPath == "" || plan.DesiredRevisionPath == "" { + t.Fatalf("binary retention plan = %#v", plan) + } + if _, err := os.Lstat(plan.RevisionStore); !errors.Is(err, os.ErrNotExist) { + t.Fatalf("binary preview changed revision store: %v", err) + } + if err := os.WriteFile(path, []byte("moved executable\n"), 0o755); err != nil { + t.Fatal(err) + } + moved := runCLI(t, []string{"--json", "upgrade", "--binary", "--install-dir", directory, "--apply", "--yes", "--plan-digest", plan.PlanDigest}, "") + if moved.code == 0 || moved.envelope.Error == nil || moved.envelope.Error.Code != "UPGRADE_PLAN_DIGEST_MISMATCH" { + t.Fatalf("moved binary apply = %#v", moved.envelope) + } + preview = runCLI(t, []string{"--json", "upgrade", "--binary", "--install-dir", directory}, "") + decodeData(t, preview.envelope.Data, &plan) + applied := runCLI(t, []string{"--json", "upgrade", "--binary", "--install-dir", directory, "--apply", "--yes", "--plan-digest", plan.PlanDigest}, "") + if applied.code != 0 || !applied.envelope.OK { + t.Fatalf("binary apply = %#v stderr=%s", applied.envelope, applied.stderr) + } + var receipt upgradeResult + decodeData(t, applied.envelope.Data, &receipt) + if !receipt.Applied || receipt.DesiredSHA256 != plan.DesiredSHA256 { + t.Fatalf("binary receipt = %#v", receipt) + } + retained, err := os.ReadFile(plan.PreviousRevisionPath) + if err != nil || string(retained) != "moved executable\n" { + t.Fatalf("previous revision = %q, err=%v", retained, err) + } + desired, err := os.ReadFile(plan.DesiredRevisionPath) + if err != nil || digest(desired) != plan.DesiredSHA256 { + t.Fatalf("desired revision digest=%s, err=%v", digest(desired), err) + } + current, err := inspectBinaryUpgrade(directory) + if err != nil || !current.alreadyCurrent { + t.Fatalf("binary verification = %#v err=%v", current, err) + } +} + +func TestBinaryUpgradeRejectsConflictingRetainedRevisionWithoutReplacingTarget(t *testing.T) { + directory := t.TempDir() + path := filepath.Join(directory, binaryName()) + oldBody := []byte("old executable\n") + if err := os.WriteFile(path, oldBody, 0o755); err != nil { + t.Fatal(err) + } + preview := runCLI(t, []string{"--json", "upgrade", "--binary", "--install-dir", directory}, "") + var plan upgradeResult + decodeData(t, preview.envelope.Data, &plan) + if err := os.Mkdir(plan.RevisionStore, 0o700); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(plan.PreviousRevisionPath, []byte("conflict\n"), 0o555); err != nil { + t.Fatal(err) + } + applied := runCLI(t, []string{"--json", "upgrade", "--binary", "--install-dir", directory, "--apply", "--yes", "--plan-digest", plan.PlanDigest}, "") + if applied.code == 0 || applied.envelope.Error == nil || applied.envelope.Error.Code != "UPGRADE_CONFLICT" { + t.Fatalf("conflicting revision apply = %#v", applied.envelope) + } + current, err := os.ReadFile(path) + if err != nil || string(current) != string(oldBody) { + t.Fatalf("failed upgrade changed target: %q, err=%v", current, err) + } +} + +func TestBinaryUpgradeRejectsRevisionStoreSymlinkWithoutReplacingTarget(t *testing.T) { + directory := t.TempDir() + path := filepath.Join(directory, binaryName()) + oldBody := []byte("old executable\n") + if err := os.WriteFile(path, oldBody, 0o755); err != nil { + t.Fatal(err) + } + preview := runCLI(t, []string{"--json", "upgrade", "--binary", "--install-dir", directory}, "") + var plan upgradeResult + decodeData(t, preview.envelope.Data, &plan) + outside := t.TempDir() + if err := os.Symlink(outside, plan.RevisionStore); err != nil { + t.Skipf("symbolic links are unavailable: %v", err) + } + applied := runCLI(t, []string{"--json", "upgrade", "--binary", "--install-dir", directory, "--apply", "--yes", "--plan-digest", plan.PlanDigest}, "") + if applied.code == 0 || applied.envelope.Error == nil || applied.envelope.Error.Code != "UPGRADE_CONFLICT" { + t.Fatalf("symbolic-link revision store apply = %#v", applied.envelope) + } + current, err := os.ReadFile(path) + if err != nil || string(current) != string(oldBody) { + t.Fatalf("failed upgrade changed target: %q, err=%v", current, err) + } + if entries, err := os.ReadDir(outside); err != nil || len(entries) != 0 { + t.Fatalf("failed upgrade wrote through revision-store link: entries=%v err=%v", entries, err) + } +} + +func TestRetainBinaryRevisionNeverPrunesRollbackArtifacts(t *testing.T) { + store := filepath.Join(t.TempDir(), ".wip.revisions") + const revisions = 6 + for index := range revisions { + body := []byte(fmt.Sprintf("revision-%d\n", index)) + value := digest(body) + if err := retainBinaryRevision(store, binaryRevisionPath(store, value), body, value); err != nil { + t.Fatal(err) + } + } + entries, err := os.ReadDir(store) + if err != nil || len(entries) != revisions { + t.Fatalf("retained revisions=%d, want=%d, err=%v", len(entries), revisions, err) + } +} + +func TestPortableSkillUpgradePublishesContractLastAndVerifiesBundle(t *testing.T) { + directory := t.TempDir() + target := portableSkillPath(directory) + for _, name := range skillbundle.PayloadPaths { + body, err := skillbundle.FS.ReadFile(name) + if err != nil { + t.Fatal(err) + } + if name == "SKILL.md" { + body = append(append([]byte{}, body...), []byte("\nlegacy\n")...) + } + path := filepath.Join(target, filepath.FromSlash(name)) + if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(path, body, 0o644); err != nil { + t.Fatal(err) + } + } + preview := runCLI(t, []string{"--json", "upgrade", "--skill", "--skill-dir", directory}, "") + if preview.code != 0 || !preview.envelope.OK { + t.Fatalf("skill preview = %#v stderr=%s", preview.envelope, preview.stderr) + } + var plan upgradeResult + decodeData(t, preview.envelope.Data, &plan) + applied := runCLI(t, []string{"--json", "upgrade", "--skill", "--skill-dir", directory, "--apply", "--yes", "--plan-digest", plan.PlanDigest}, "") + if applied.code != 0 || !applied.envelope.OK { + t.Fatalf("skill apply = %#v stderr=%s", applied.envelope, applied.stderr) + } + if _, err := os.Lstat(filepath.Join(target, "contract.json")); err != nil { + t.Fatalf("contract marker missing after skill upgrade: %v", err) + } + current, err := inspectSkillUpgrade(directory) + if err != nil || !current.alreadyCurrent || current.currentSHA256 != plan.DesiredSHA256 { + t.Fatalf("skill verification = %#v err=%v", current, err) + } +} + +func TestStateUpgradeIsQuiescentAndDigestBound(t *testing.T) { + directory := cliTestRepo(t) + repo, err := gitx.Discover(context.Background(), directory) + if err != nil { + t.Fatal(err) + } + laneStore, err := store.Open(repo) + if err != nil { + t.Fatal(err) + } + marker := filepath.Join(repo.CommonDir, "wip", "domain.json") + legacy := []byte("{\n \"schema_version\": 1,\n \"domain\": \"github.com/nstranquist/wip-commit\",\n \"state_version\": 1\n}\n") + if err := os.WriteFile(marker, legacy, 0o600); err != nil { + t.Fatal(err) + } + doctor := runCLI(t, []string{"--json", "--repo-dir", directory, "doctor"}, "") + var report doctorReport + decodeData(t, doctor.envelope.Data, &report) + if doctor.code != 1 || !doctor.envelope.OK || report.Healthy || !report.UpgradeRequired || len(report.Findings) != 1 || report.Findings[0].Code != "STATE_UPGRADE_REQUIRED" || report.Findings[0].Severity != "recovery" { + t.Fatalf("legacy marker doctor = %#v report=%#v", doctor.envelope, report) + } + preview := runCLI(t, []string{"--json", "--repo-dir", directory, "upgrade", "--state"}, "") + if preview.code != 0 || !preview.envelope.OK { + t.Fatalf("state preview = %#v stderr=%s", preview.envelope, preview.stderr) + } + var plan upgradeResult + decodeData(t, preview.envelope.Data, &plan) + if plan.Target != "state" || plan.AlreadyCurrent { + t.Fatalf("state plan = %#v", plan) + } + if _, err := laneStore.Create(context.Background(), store.CreateOptions{ID: "upgrade-blocker", Agent: "agent", Session: "session", Mode: store.ModeShared}); err == nil { + blocked := runCLI(t, []string{"--json", "--repo-dir", directory, "upgrade", "--state", "--apply", "--yes", "--plan-digest", plan.PlanDigest}, "") + if blocked.code == 0 || blocked.envelope.Error == nil || blocked.envelope.Error.Code != "UPGRADE_BLOCKED" { + t.Fatalf("active-lane state apply = %#v", blocked.envelope) + } + if err := laneStore.Release("upgrade-blocker", "agent", "session", true); err != nil { + t.Fatal(err) + } + } else { + t.Fatal(err) + } + applied := runCLI(t, []string{"--json", "--repo-dir", directory, "upgrade", "--state", "--apply", "--yes", "--plan-digest", plan.PlanDigest}, "") + if applied.code != 0 || !applied.envelope.OK { + t.Fatalf("state apply = %#v stderr=%s", applied.envelope, applied.stderr) + } + opened, err := store.Open(repo) + if err != nil || opened.Domain.SchemaVersion != 2 || opened.Domain.UpgradeRequired { + t.Fatalf("upgraded domain = %#v err=%v", opened.Domain, err) + } +} diff --git a/cmd/wip/version.go b/cmd/wip/version.go new file mode 100644 index 0000000..e6525c6 --- /dev/null +++ b/cmd/wip/version.go @@ -0,0 +1,151 @@ +package main + +import ( + "crypto/sha256" + "encoding/hex" + "io" + "os" + "path/filepath" + "runtime" + "runtime/debug" + "strings" + + skillbundle "github.com/nstranquist/wip-commit/skills/wip-commit" +) + +const versionResultSchema = "2.0.0" + +const maxVersionExecutableBytes = 512 << 20 + +var ( + buildRevision string + buildSourceState string + buildVCSTime string + buildReleaseTag string +) + +type versionResult struct { + SchemaVersion string `json:"schema_version"` + Version string `json:"version"` + Channel string `json:"channel"` + ReleaseTag string `json:"release_tag,omitempty"` + SourceStamped bool `json:"source_stamped"` + Revision string `json:"revision,omitempty"` + SourceState string `json:"source_state,omitempty"` + VCSTime string `json:"vcs_time,omitempty"` + GoVersion string `json:"go_version"` + ExecutableSHA256 string `json:"executable_sha256,omitempty"` + PortableBundleSHA256 string `json:"portable_bundle_sha256,omitempty"` +} + +func currentVersionInfo() versionResult { + result := versionResult{ + SchemaVersion: versionResultSchema, + Version: version, + ReleaseTag: strings.TrimSpace(buildReleaseTag), + Revision: strings.TrimSpace(buildRevision), + SourceState: strings.TrimSpace(buildSourceState), + VCSTime: strings.TrimSpace(buildVCSTime), + GoVersion: runtime.Version(), + } + result.ExecutableSHA256 = currentExecutableDigest() + result.PortableBundleSHA256, _ = skillbundle.PayloadDigest() + build, ok := debug.ReadBuildInfo() + if !ok { + return finalizeVersionIdentity(result) + } + if build.GoVersion != "" { + result.GoVersion = build.GoVersion + } + return versionInfoFromSettings(result, build.Settings) +} + +func currentExecutableDigest() string { + path, err := os.Executable() + if err != nil { + return "" + } + path, err = filepath.EvalSymlinks(path) + if err != nil { + return "" + } + file, err := os.Open(path) + if err != nil { + return "" + } + defer func() { _ = file.Close() }() + info, err := file.Stat() + if err != nil || !info.Mode().IsRegular() || info.Size() < 1 || info.Size() > maxVersionExecutableBytes { + return "" + } + hash := sha256.New() + written, err := io.Copy(hash, io.LimitReader(file, maxVersionExecutableBytes+1)) + if err != nil || written != info.Size() { + return "" + } + return "sha256:" + hex.EncodeToString(hash.Sum(nil)) +} + +func versionInfoFromSettings(result versionResult, settings []debug.BuildSetting) versionResult { + trustedReleaseInjection := result.ReleaseTag != "" && result.ReleaseTag == "v"+result.Version && !strings.HasSuffix(result.Version, "-dev") + if !trustedReleaseInjection { + // Development builds must use Go's VCS settings. Do not let arbitrary + // linker flags turn a dirty or unrelated source build into a clean one + // or claim that a development version is a release. + result.ReleaseTag = "" + result.Revision = "" + result.SourceState = "" + result.VCSTime = "" + } + for _, setting := range settings { + switch setting.Key { + case "vcs.revision": + if result.Revision == "" { + result.Revision = strings.TrimSpace(setting.Value) + } + case "vcs.time": + if result.VCSTime == "" { + result.VCSTime = strings.TrimSpace(setting.Value) + } + case "vcs.modified": + if result.SourceState != "" { + continue + } + switch strings.TrimSpace(setting.Value) { + case "true": + result.SourceState = "modified" + case "false": + result.SourceState = "clean" + } + } + } + return finalizeVersionIdentity(result) +} + +func finalizeVersionIdentity(result versionResult) versionResult { + result.SourceStamped = result.Revision != "" + switch { + case result.ReleaseTag != "" && result.ReleaseTag == "v"+result.Version: + result.Channel = "release" + case result.ReleaseTag == "" && strings.HasSuffix(result.Version, "-dev"): + result.Channel = "development" + default: + result.Channel = "unverified" + } + return result +} + +func (result versionResult) human() string { + text := "wip " + result.Version + if result.Revision == "" { + return text + } + revision := result.Revision + if len(revision) > 12 { + revision = revision[:12] + } + if result.SourceState != "" { + return text + " (" + revision + ", " + result.SourceState + ")" + } + return text + " (" + revision + ")" +} diff --git a/cmd/wip/version_test.go b/cmd/wip/version_test.go new file mode 100644 index 0000000..ff8b7c7 --- /dev/null +++ b/cmd/wip/version_test.go @@ -0,0 +1,102 @@ +package main + +import ( + "runtime/debug" + "strings" + "testing" +) + +func TestCurrentVersionBindsExecutableAndPortableBundle(t *testing.T) { + result := currentVersionInfo() + if !strings.HasPrefix(result.ExecutableSHA256, "sha256:") || len(result.ExecutableSHA256) != 71 { + t.Fatalf("executable digest = %q", result.ExecutableSHA256) + } + if !strings.HasPrefix(result.PortableBundleSHA256, "sha256:") || len(result.PortableBundleSHA256) != 71 { + t.Fatalf("portable bundle digest = %q", result.PortableBundleSHA256) + } +} + +func TestVersionInfoReportsExactSourceProvenance(t *testing.T) { + revision := "0123456789abcdef0123456789abcdef01234567" + result := versionInfoFromSettings(versionResult{ + SchemaVersion: versionResultSchema, + Version: "0.2.0-dev", + GoVersion: "go1.26.7", + }, []debug.BuildSetting{ + {Key: "vcs.revision", Value: revision}, + {Key: "vcs.time", Value: "2026-08-21T05:00:00Z"}, + {Key: "vcs.modified", Value: "false"}, + }) + + if result.Revision != revision || result.SourceState != "clean" || result.VCSTime != "2026-08-21T05:00:00Z" { + t.Fatalf("version provenance = %#v", result) + } + if result.Channel != "development" || !result.SourceStamped { + t.Fatalf("development identity = %#v", result) + } + if got := result.human(); got != "wip 0.2.0-dev (0123456789ab, clean)" { + t.Fatalf("human version = %q", got) + } +} + +func TestVersionInfoKeepsHumanOutputWithoutVCSMetadata(t *testing.T) { + result := finalizeVersionIdentity(versionResult{SchemaVersion: versionResultSchema, Version: "0.2.0-dev", GoVersion: "go1.26.7"}) + if result.Channel != "development" || result.SourceStamped { + t.Fatalf("unstamped development identity = %#v", result) + } + if got := result.human(); got != "wip 0.2.0-dev" { + t.Fatalf("human version = %q", got) + } +} + +func TestVersionInfoRequiresMatchingInjectedReleaseTag(t *testing.T) { + release := finalizeVersionIdentity(versionResult{SchemaVersion: versionResultSchema, Version: "0.2.0-beta.1", ReleaseTag: "v0.2.0-beta.1", Revision: "abc"}) + if release.Channel != "release" || !release.SourceStamped { + t.Fatalf("release identity = %#v", release) + } + unverified := finalizeVersionIdentity(versionResult{SchemaVersion: versionResultSchema, Version: "0.2.0-beta.1", ReleaseTag: "v0.2.0-beta.2"}) + if unverified.Channel != "unverified" { + t.Fatalf("mismatched release identity = %#v", unverified) + } +} + +func TestVersionInfoPrefersLinkerProvenance(t *testing.T) { + result := versionInfoFromSettings(versionResult{ + SchemaVersion: versionResultSchema, + Version: "0.2.0-beta.1", + ReleaseTag: "v0.2.0-beta.1", + Revision: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + SourceState: "clean", + VCSTime: "2026-08-21T05:00:00Z", + GoVersion: "go1.26.7", + }, []debug.BuildSetting{ + {Key: "vcs.revision", Value: "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"}, + {Key: "vcs.time", Value: "2026-08-21T06:00:00Z"}, + {Key: "vcs.modified", Value: "true"}, + }) + if result.Revision != "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" || result.SourceState != "clean" || result.VCSTime != "2026-08-21T05:00:00Z" { + t.Fatalf("linker provenance was replaced: %#v", result) + } +} + +func TestDevelopmentVersionIgnoresLinkerProvenance(t *testing.T) { + result := versionInfoFromSettings(versionResult{ + SchemaVersion: versionResultSchema, + Version: "0.2.0-dev", + ReleaseTag: "v0.2.0-dev", + Revision: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + SourceState: "clean", + VCSTime: "2026-08-21T05:00:00Z", + GoVersion: "go1.26.7", + }, []debug.BuildSetting{ + {Key: "vcs.revision", Value: "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"}, + {Key: "vcs.time", Value: "2026-08-21T06:00:00Z"}, + {Key: "vcs.modified", Value: "true"}, + }) + if result.Revision != "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" || result.SourceState != "modified" || result.VCSTime != "2026-08-21T06:00:00Z" { + t.Fatalf("development linker provenance was trusted: %#v", result) + } + if result.ReleaseTag != "" || result.Channel != "development" { + t.Fatalf("development linker release identity was trusted: %#v", result) + } +} diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 6a27ded..e19083a 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -2,7 +2,7 @@ ## Data model -All coordination state is below the repository's Git common directory: +Capture coordination state is below the repository's Git common directory: ```text /wip/v1/ @@ -17,6 +17,22 @@ All coordination state is below the repository's Git common directory: locks/intent-.lock ``` +The separate review and landing authority uses this root: + +```text +/wip/review/v1/ + handoffs/.json + plans/.json + landing-intents/.json + archive/ + reconciliation/ + locks/ +``` + +The standalone capture command does not create a landing decision. The +coordination migration creates the required review directories and preserves +legacy review records there. + Durable record writes stage complete temporary files in `locks/`. Record directories therefore contain only canonical JSON names, even when a writer stops before publication. Temporary files are never interpreted as records. @@ -33,14 +49,23 @@ store and refs through the Git common directory. Git subprocesses remove inherited repository-local environment variables that can redirect or reinterpret the repository, common directory, worktree, -namespace, refs, shallow boundary, configuration, or object storage. Discovery -and capture therefore stay bound to the canonical checkout. An inherited -`GIT_INDEX_FILE` remains the source staged view. The capture transaction -supplies its private index explicitly to Git and prepared hooks. +namespace, refs, shallow boundary, configuration, object storage, or pathspec +mode. Discovery and capture therefore stay bound to the canonical checkout. An +inherited `GIT_INDEX_FILE` remains the caller view only for `staged_index` +source mode. The capture transaction supplies its private index explicitly to +Git and prepared hooks. Prepared hooks receive canonical capture, hook-phase, +target-ref, source-read-only, and exact post-commit object markers. The forced +read-only value is a cooperative signal; it does not sandbox repository code. +A `worktree_snapshot` uses a separate temporary source index. Candidate verification commands remove the active WIP identity, target ref, -commit object, source index, and stale candidate-tree variables. They receive +commit object, caller index, and stale candidate-tree variables. They receive only the current `WIP_CANDIDATE_TREE` value from the capture process. +Their directory is an implicit candidate-tree materialization scope. The plan +can add exact repository-relative dependencies with `materialize`. A command +with neither field requests the full tree. The kernel uses literal pathspecs, +counts immutable tree entries and blob bytes before disk writes, and supplies +selected paths to `checkout-index` as NUL-delimited input. `/wip/domain.json` owns the state version. A shared `wip-coordination.lock` serializes public and legacy domain creation. The @@ -51,38 +76,78 @@ The store checks the domain marker and version directories before it creates schema. It returns `COORDINATION_DOMAIN_CONFLICT` for another state owner. See [STATE-COMPATIBILITY.md](STATE-COMPATIBILITY.md). +Coordination migration uses a byte-for-byte read-only preview. The reviewed +poststate manifest binds every required directory and the regular +`wip/v1/locks/leases.lock` artifact. Apply uses one writer fence. It publishes +the registry lock before it publishes imported lane and lease records. It then +moves the complete legacy root into a sealed archive. The migration never +writes to both coordination roots. + +The completion receipt keeps the exact canonical manifest from cutover. Before +the journal reaches `complete`, status requires that exact manifest. After +completion, normal capture and review writers can change the live `v1` roots. +Migration status reports the current manifest and sets `canonical_advanced` +when it differs from the receipt. It still checks the immutable plan, +journal, receipt, archive, domain marker, and static migration envelope. +Transient private-index contents are outside the historical comparison. Their +`wip/indexes` root must remain a regular mode-`0700` directory. + Lane refs have this form: ```text refs/heads/wip// ``` -## Modes +## Coordination modes `shared` mode permits several active lanes in one checkout when their leases do -not overlap. Capture always reads selected staged entries and leaves the shared -index unchanged. +not overlap. Use `staged_index` as the controlled source exception in this mode. `worktree` mode requires a linked non-anchor worktree. It reserves that -worktree. Another active lane cannot bind to it. A worktree-mode lane also reads -staged entries and leaves the worktree's `HEAD` and index unchanged. +worktree. Another active lane cannot bind to it. Use `worktree_snapshot` as the +preferred source in this mode. -The mode changes the coordination boundary. It does not change the publication -algorithm. +The user interface recommends `worktree` mode for one agent per task. Use +`shared` mode only when lanes must use the same checkout and index. + +The coordination mode changes the ownership boundary. It does not change the +publication algorithm. + +## Source modes + +`staged_index` selects exact changed entries from the caller index. Its +untracked policy is `not_applicable`. Foreign staged entries remain unchanged. -A dry-run creates no commit objects. The first planned group reports the -current lane commit as its parent. A later group reports an empty parent because -its preceding commit does not exist. The ordered group list defines the planned -dependency chain. +`worktree_snapshot` selects exact tracked changes from the reviewed scopes. Its +untracked policy is `forbid` or `include`. The default `forbid` policy stops if +an untracked path exists in a selected scope. -Building candidates, including during a dry-run, can add tree objects to the -Git object database. A failed non-dry-run can also leave unreachable commit -objects because publication uses one final ref update. These objects are not -published history. Normal Git garbage collection can remove them later. `wip` -does not prune or delete Git objects as a recovery action. +Both source modes bind `source_mode`, `untracked_policy`, `source_scopes`, +`source_paths`, and `source_digest` in the version 3 plan. Capture reconstructs +that source and compares the digest before and after all gates. -The split planner compares the active source index with the lane's current -commit. It does not propose staged entries that already match the lane tree. +A direct commit dry-run creates candidate Git objects in a temporary object +directory. It removes that directory before it returns. It snapshots hook bytes +but does not execute repository hooks or verification commands. It also skips +the publication callback, commit creation, intent writes, lease renewal, and ref +updates. + +The result uses schema `3.0.0` and reports `gate_outcome: "skipped"`. Its +`execution` object reports planned, executed, and skipped counts. All executed +counts are zero. The first group reports the current lane commit as its parent. +A later group reports an empty parent because its preceding commit does not +exist. + +Guided `wip capture` does not accept `--dry-run`. It rejects that combination +before repository discovery, store access, lease renewal, or handoff creation. + +A failed non-dry-run can leave unreachable commit objects because publication +uses one final ref update. These objects are not published history. Normal Git +garbage collection can remove them later. `wip` does not prune or delete Git +objects as a recovery action. + +The split planner compares the selected source with the lane's current commit. +It does not propose source paths that already match the lane tree. Portable path identity applies NFC normalization, Unicode case folding, and a stable lowercase form. Reapplying the key produces the same bytes. Path overlap @@ -92,14 +157,25 @@ uses component boundaries after this canonicalization. Commands use this lock order: -1. coordination-domain lock during store creation; -2. archive lock during archive or restore; -3. lane locks in sorted lane order; -4. lease-registry lock. +1. initialization-intent lock during setup or a reviewed init abort. +2. coordination-domain lock during store creation. +3. archive lock during archive or restore. +4. lane locks in sorted lane order. +5. state-registry lock at `locks/leases.lock`. No command acquires those locks in the opposite order. Different lanes can run -capture work in parallel. One lane is serialized. An initialization-intent -lock is acquired by itself when a completed step is recorded. +capture work in parallel. One lane is serialized. Initialization holds its +per-intent lock from before the first setup side effect through the final +journaled step. An exact retry therefore serializes with both another retry and +`init-abort`. The abort path acquires no lower-order state lock. + +An active handoff holds the lane lock through intent selection, validation, +lease renewal, and status construction. A final guided capture keeps its lane +lock through handoff creation and lane and lease release. + +The state-registry lock fences operational lane and lease record reads. It also +fences lease replacement and the final lane commit receipt. Windows can reject +an open during atomic replacement without this shared fence. ## Lane state @@ -133,6 +209,14 @@ lifetime. The publication callback compares and refreshes the set while it holds the registry lock. Every refresh audits the complete active registry for a cross-lane path overlap. +Authenticated `status`, `env`, `claim`, `plan`, and `handoff` also renew the +complete active lease set. `status --observe`, `env --observe`, and `plan +--observe` are pure reads. An observed plan cannot write an output file. A +handoff for a released lane does not renew leases. + +`env` compares the canonical lane worktree with the current repository root. +A mismatch stops the command and leaves the lease unchanged. + A heartbeat failure remains authoritative after the ref update. The failed result includes `ref_updated`, `plan_id`, `plan_digest`, and the applied intent state. The operator must use that evidence with `wip reconcile`. @@ -141,26 +225,28 @@ state. The operator must use that evidence with `wip reconcile`. For one split plan, `wip` performs these steps: -1. Normalize and validate all groups, messages, paths, and verify commands. -2. Check that every planned path is inside the active lease set. -3. Resolve the lane ref and source `HEAD` to exact object IDs. -4. Snapshot the pre-commit and post-commit hook files. -5. Read the source index and calculate a digest for the selected paths. -6. Create a private index from the current lane commit. -7. For each group, copy only its exact source index entries into the private - index. -8. Run the copied pre-commit hook, check the changed-path scope, run `git diff - --check`, and run verify commands in a candidate-tree checkout. -9. Create each commit with `git commit-tree`. No ref points to the partial chain. -10. Recheck the lane, lease set, source `HEAD`, selected index digest, and hook - paths. -11. Write a durable `prepared` intent. -12. Update the lane ref once with the expected old object ID. -13. Mark the intent `applied`, advance the lane cursor, and mark it `complete`. -14. Run the copied post-commit hook once for each commit with that commit's +1. Validate the reviewed-plan bindings and named message policy. +2. Normalize and validate all groups, message safety, paths, and verify commands. +3. Check that every planned path is inside the active lease set. +4. Resolve the lane ref and source `HEAD` to exact object IDs. +5. Snapshot the pre-commit and post-commit hook files. +6. Rebuild the selected source and require its digest to equal the reviewed + plan. +7. Create a private index from the current lane commit. +8. For each group, copy only its exact source entries into the private index. +9. Run the copied pre-commit hook, check the changed-path scope, run `git diff + --check`, bound and materialize the reviewed candidate-tree scopes, and run + verify commands in that checkout. +10. Create each commit with `git commit-tree`. No ref points to the partial chain. +11. Recheck the lane, lease set, source `HEAD`, selected source digest, and hook + paths. This second source check detects changes during the transaction. +12. Write a durable `prepared` intent. +13. Update the lane ref once with the expected old object ID. +14. Mark the intent `applied`, advance the lane cursor, and mark it `complete`. +15. Run the copied post-commit hook once for each commit with that commit's private tree loaded. -The source `HEAD`, source index, and source worktree are not rewritten by this +The source `HEAD`, caller index, and source worktree are not rewritten by this algorithm. ## Intent state and recovery @@ -174,7 +260,7 @@ The following table describes crash recovery: | Last durable event | Ref state | Recovery | | --- | --- | --- | | No intent | old | Run the plan again | -| `prepared` intent | old | The plan was not applied; run it again | +| `prepared` intent | old | The plan was not applied. Run it again. | | `prepared` intent | new | Run `wip reconcile` | | `applied` intent | new | Run `wip reconcile` | | Lane cursor advanced | new | Run `wip reconcile` to mark complete | @@ -231,29 +317,83 @@ deterministic empty batch. Each receipt validates record placement and binds lane and released lease records to exact candidates. Extra records fail closed. Restore writes the lane manifest last. +A restored receipt is durable history. If a later receipt archives the same +records, validation follows each non-live record only to one newer, +non-restored receipt. The newer receipt must be valid and must own that exact +record. No owner, more than one owner, an invalid owner, or changed candidate +data stops validation. This rule lets repeated archive and restore cycles keep +all receipts without weakening missing-record checks. + Resume and restore first inspect the existing domain. They return `ARCHIVE_NOT_FOUND` without creating state when the domain is not initialized. -## Split-plan format - -The top-level JSON value is an array. Each item contains one message, one or -more path scopes, and optional verify commands. - -```json -[ - { - "message": "fix(storage): preserve atomic state", - "files": ["internal/storage"], - "verify": [ - { - "argv": ["go", "test", "./internal/storage"], - "directory": ".", - "timeout_ms": 120000 - } - ] - } -] -``` +## Reviewed-plan format + +`wip plan` emits one version 3 object. The object binds the lane, ref, source +`HEAD`, source mode, untracked policy, source scopes, source paths, source +digest, active leases, and message policy. + +Each group contains review guidance, an empty draft message, exact files, and +optional verify commands. A reviewer adds messages and changes `state` to +`reviewed`. Each verify command can set a working `directory` and additional +repository-relative `materialize` scopes. These paths affect only the candidate +checkout used by verification. + +`wip capture` accepts only this object. It calculates a canonical SHA-256 plan +digest. A new capture stores that digest and its private-source binding in +capture-intent schema version 3. + +`wip commit` also accepts the object. It keeps the legacy top-level array for +compatibility. Legacy arrays do not qualify for `wip capture`. + +The decoder rejects unknown fields, duplicate keys, trailing JSON, and input +larger than 1 MiB. See [PLAN.schema.json](PLAN.schema.json). + +## Operational status + +Status compares three exact trees: the caller index, source `HEAD`, and lane +tip. It classifies capture candidates, captured staged entries, foreign staged +entries, and empty lease scopes. These classes describe index state. They do +not authorize a worktree-source plan. + +Status also validates the lane ref and latest capture intent. The JSON envelope +contains a stable lease context for all successful lane commands. + +## Capture handoff + +The handoff loader builds one unique chain of completed intents from the lane +base to the current tip. It validates every intent and commit object. A gap, +branch, cycle, ambiguity, or moved ref fails closed. + +The version 2 output contains every segment, commit, source binding, and review +digest. A canonical `handoff_digest` binds the complete output. A handoff is +review-eligible only when every segment has its version 3 private-source and +review bindings. + +The completed-intent path does not skip Git-object validation. The handoff +command holds the lane lock through chain validation, active-lease renewal, and +status construction. `capture --final` keeps the same lock through handoff +validation and release. + +For a released lane, handoff acquires the existing regular lane lock without +creating state or rewriting the lock owner record. It verifies the opened file +against the path before and after lock acquisition. + +The output contains no agent ID, session ID, absolute path, remote URL, or file +content. It explicitly states that capture does not authorize landing. A +separate review authority must persist the handoff and make any landing plan. + +See [HANDOFF.schema.json](HANDOFF.schema.json) and +[KEP-0003](KEP-0003-agent-facing-capture-workflow.md). + +## Schema contract validation + +Tests validate real plan, status, legacy-plan, and handoff command data against +the published Draft 2020-12 schemas. They also require a strict schema to reject +invalid data. -The decoder rejects unknown fields, duplicate object keys, trailing JSON, and -input larger than 1 MiB. See [PLAN.schema.json](PLAN.schema.json). +The test-only validator is `github.com/santhosh-tekuri/jsonschema/v6` version +6.0.3. The dependency uses Apache-2.0 and supports Go 1.21 and newer. Version +6.0.3 was the current stable release on the 2026-08-18 review date. Tests load +only repository schema files. They do not enable remote schema loading in the +product runtime. diff --git a/docs/BETA-EXERCISE.md b/docs/BETA-EXERCISE.md index 73445b5..afb1056 100644 --- a/docs/BETA-EXERCISE.md +++ b/docs/BETA-EXERCISE.md @@ -34,7 +34,8 @@ redacted note. Validate the receipt against 4. Create a new disposable Git repository. 5. Configure a test-only Git name and email in that repository. 6. Commit two small text files as the base commit. -7. Record the source `HEAD` and index-file digest before each scenario. +7. Record the source `HEAD`, index-file digest, and Git common-directory digest + before each scenario. Do not add a remote. Do not use global Git configuration. @@ -43,13 +44,27 @@ Do not add a remote. Do not use global Git configuration. 1. Run `wip init` in shared mode. 2. Claim both test files. 3. Change and stage both files. -4. Run `wip plan`. -5. Write a reviewed two-group plan. -6. Run `wip commit --plan --dry-run`. -7. Verify that the dry-run did not move the lane ref. -8. Run `wip commit --plan `. -9. Verify that the lane contains two linear commits. -10. Verify that source `HEAD` and the complete index stayed unchanged. +4. Run `wip plan --source staged_index --untracked not_applicable --observe`. +5. Verify that the observed plan changed no repository bytes. +6. Run `wip plan --source staged_index --untracked not_applicable --out + `. +7. Add two messages and set the plan state to `reviewed`. +8. Run `wip commit --plan --dry-run`. +9. Require result schema `3.0.0` and `gate_outcome: "skipped"`. +10. Require `execution.policy: "no-exec"` and zero executed counts. +11. Verify that repository, store, ref, lease, configuration, and index bytes did + not change. +12. Add hook and verification markers. Verify that the dry-run created neither + marker. +13. Run `wip capture --plan `. +14. Verify that the non-dry capture executed the configured gates. +15. Verify that the lane contains two linear commits. +16. Verify that source `HEAD` and the complete index stayed unchanged. +17. Verify the cumulative handoff digest and complete base-to-tip chain. +18. Verify that the handoff is capture-only and does not authorize landing. + +The dry-run validates structure only. It does not prove that repository hooks +or verification commands pass. Record scenario ID `shared-split`. @@ -67,14 +82,15 @@ Record scenario ID `overlap-refusal`. ## Scenario 3: verification failure 1. Stage a later change on one leased file. -2. Add `git rev-parse --is-inside-work-tree` as a verify command. -3. Run the capture. -4. Verify that the command returns `VERIFY_FAILED`. -5. Verify that source `HEAD`, the complete index, and the lane ref stayed +2. Write a new version 3 `staged_index` draft plan. +3. Add `git rev-parse --is-inside-work-tree` as a verify command. +4. Set the plan state to `reviewed` and run `wip capture`. +5. Verify that the command returns `VERIFY_FAILED`. +6. Verify that source `HEAD`, the complete index, and the lane ref stayed unchanged. -6. Restore the exact staged bytes from Scenario 1 with explicit file writes and +7. Restore the exact staged bytes from Scenario 1 with explicit file writes and `git add`. -7. Verify that the complete index digest matches the digest recorded after +8. Verify that the complete index digest matches the digest recorded after Scenario 1. Candidate directories do not contain Git metadata. This command must fail. @@ -83,11 +99,10 @@ Record scenario ID `verify-failure`. ## Scenario 4: duplicate refusal -1. Create a new reviewed plan from the current lane ref and the restored staged - snapshot. -2. Run that plan without another staged change. -3. Verify that the command returns `EMPTY_COMMIT_GROUP` or `EMPTY_SELECTION`. -4. Verify that the lane ref stayed unchanged. +1. Run `wip plan --source staged_index --untracked not_applicable --out + ` without another staged change. +2. Verify that the command returns `EMPTY_SELECTION`. +3. Verify that the lane ref stayed unchanged. Record scenario ID `duplicate-refusal`. @@ -96,11 +111,14 @@ Record scenario ID `duplicate-refusal`. 1. Release the shared lane. 2. Run `wip init` with `--mode worktree` and `--create-worktree`. 3. Claim two files in that linked worktree. -4. Change and stage both files in the linked worktree. -5. Capture a reviewed two-group plan. -6. Verify both checkout `HEAD` values. -7. Verify both complete indexes. -8. Verify that the new lane contains the complete split chain. +4. Change both files in the linked worktree. Do not stage them. +5. Create a reviewed two-group version 3 plan with `--source + worktree_snapshot --untracked forbid`. +6. Capture the reviewed plan. +7. Verify both checkout `HEAD` values. +8. Verify both complete indexes. +9. Verify that the new lane contains the complete split chain. +10. Verify the cumulative handoff digest and `landing_authorized: false`. Record scenario ID `worktree-split`. diff --git a/docs/DOGFOOD.md b/docs/DOGFOOD.md index 1c7f145..db425d0 100644 --- a/docs/DOGFOOD.md +++ b/docs/DOGFOOD.md @@ -1,5 +1,371 @@ # Dogfood evidence +This file contains dated historical evidence. Some entries record plan version +2 and staged-index behavior. Use [ARCHITECTURE.md](ARCHITECTURE.md), +[PLAN.schema.json](PLAN.schema.json), and [HANDOFF.schema.json](HANDOFF.schema.json) +for the current protocol. + +## 2026-08-21 installed workflow and source-provenance exercise + +This exercise started with no `wip` executable on `PATH`. The complete portable +skill was available in the standalone source tree. The existing agent skill +paths remained bound to the broader Nicos-integrated workflow and were not +overwritten. + +Evidence scope: local maintainer evidence. The exercise did not land, merge, +push, tag, or publish any captured commit. + +### Disposable protocol + +The source-current beta binary installed itself at `~/.local/bin/wip`. Its +installer also wrote a complete portable skill bundle to an isolated test +directory. The installed binary and source binary were byte-equal. The three +portable skill files were byte-equal to their source files. + +A disposable repository then passed these behaviors: + +- A shared lane captured a reviewed two-commit split at + `d962bd56dfde3064392499578d5e901f3f0169cc`. +- The shared source `HEAD`, complete index digest, and staged tree stayed + unchanged. A foreign staged path stayed staged and did not enter the lane. +- An overlapping claim returned `PATH_LEASE_CONFLICT`. The exact pending + initialization receipt completed after the first owner released its lease. +- Two reconciliation calls returned the same already-complete receipt. +- A linked-worktree lane captured a reviewed two-commit split at + `2385e60e9d9acec9479ccc3a9f52fd5d87c722a5`. +- Both linked and anchor `HEAD` values and complete index digests stayed + unchanged. +- Release preserved both lane refs and commits. Final doctor output was healthy + with no active lane or pending recovery. + +The first wrong-checkout probe found that the older product-passport branch let +`wip env` return a worktree-bound identity from the anchor checkout. It did not +renew the lease. The agent-facing branch already contained the intended +`WORKTREE_MISMATCH` check. The older branch received the same fail-closed check, +a lease and Git-state regression test, and matching user and skill guidance. + +The complete gate matrix for that correction passed `go test ./...`, `go vet +./...`, `actionlint`, and `go test -race -count=3 ./...`. + +### Real self-hosted captures + +The older branch could not read the current store because its strict readers +rejected newer `message_policy` and `review_plan_digest` fields. It stopped +before staging or lane creation. The compatible agent-facing binary read the +same store as healthy with no active or pending lane. + +The first real capture used +`refs/heads/wip/codex/env-worktree-binding-fix`: + +- Tip: `b7e77a2a48c32e44ecf89c7fe188e1bcf8393e1b`. +- Plan ID: `plan-128b94b2cee8fc6ce1dcf054`. +- Capture intent digest: + `sha256:54b27961ca98ec067b85cbb010fbe74e8095bb56ba55015c5da7c5076b939335`. +- Reviewed plan digest: + `sha256:19184ab8ce0844282e38bcb12f4b01ac0ab61bce48255b5c966f2a7446658461`. +- Four commits covered the code and test, error guide, README, and portable + skill. +- Final capture set `capture_only` to true, `landing_authorized` to false, and + `lane_released` to true. + +The compatibility exercise also showed that different development revisions +reported the same plain beta version. A new typed version result now reports +the exact source revision, source state, VCS time, and Go version. The release +builder injects clean deterministic source identity even though it disables +automatic Go VCS stamping. + +The second real capture used `refs/heads/wip/codex/version-provenance`: + +- Tip: `a42693a360b1b9cc987aa0c7926fd5b9792fbe34`. +- Plan ID: `plan-578a7037a7436d366414b15a`. +- Capture intent digest: + `sha256:093284cdd0570df0d5caee50225558f9fb6edd9251cad7189bb872a12d94901f`. +- Reviewed plan digest: + `sha256:a9be503d8b60578dd899734c0f98469e7ac192aa95c4b2f06cc304f162ca2a83`. +- Four commits covered typed version output, README guidance, deterministic + release stamping, and skill policy. +- Final capture set `capture_only` to true, `landing_authorized` to false, and + `lane_released` to true. + +The complete provenance gate matrix passed `go test ./...`, `go vet ./...`, +`actionlint`, and `go test -race -count=3 ./...`. The initial source-stamped +installed binary had SHA-256 +`bd64e76d7cf7e907215ee6786f3a37064730516bad3d25a5fa9402106ec9e5cf`. +Its JSON version result identifies revision +`a42693a360b1b9cc987aa0c7926fd5b9792fbe34`, source state `clean`, VCS time +`2026-08-21T01:02:47-05:00`, and Go `1.26.7`. + +### Scoped archive replay follow-up + +A preview narrowed to three released lanes returned an exact cutoff and digest. +An apply that omitted the preview's `--lane` values failed closed with +`ARCHIVE_PLAN_MOVED`; no record or ref moved. Repeating the three filters +completed recoverable archive receipt `archive-a6eb70b719044cb82e4063b2`. + +That operator error exposed incomplete replay guidance. The follow-up capture +used `refs/heads/wip/codex/archive-filter-replay`: + +- Tip: `4b309328955996e29629fef0a9239bd151266aec`. +- Plan ID: `plan-13ef6bbf04693d466ec73705`. +- Capture intent digest: + `sha256:2136a8c13e1721560692e3540692b5eab01861237b5eb6fbf3c032232fe24ff4`. +- Reviewed plan digest: + `sha256:cceeacffd954ffaaae783f3b959a75691cc9b17b7bb3fb00858036416841b982`. +- Four commits added canonical sorted `lane_filters`, actionable help and error + text, a two-lane regression test, and matching README and skill guidance. +- The omitted-filter regression proves both eligible lanes remain unchanged; + the replayed filter archives only the reviewed lane. + +The follow-up passed `go test ./...`, `go vet ./...`, `actionlint`, and +`go test -race -count=3 ./...`. A clean build from the captured tip installed +itself through `wip init --install`. The installed and source binaries are +byte-equal with SHA-256 +`4adf75c206c5804d98d4acf4a0ca85f5f7573607f621ecaeebfd54e2a69f9dd5`. +Its JSON version result identifies revision +`4b309328955996e29629fef0a9239bd151266aec`, source state `clean`, VCS time +`2026-08-21T01:22:32-05:00`, and Go `1.26.7`. + +The installed binary then previewed `archive-filter-replay` with canonical +`lane_filters`, replayed that filter, and completed recoverable receipt +`archive-b27618aea8e554548bb6a9b5`. The lane ref and commit remained unchanged. + +The final repository doctor was healthy. Both source indexes intentionally kept +their captured entries staged. No handoff authorized landing. + +## 2026-08-18 atomic finalization and schema review + +This exercise used a source-current binary in the isolated +`feat/agent-facing-capture-v2` linked worktree. It tested the review corrections +against real repository state. + +Evidence scope: local maintainer evidence. This exercise does not prove hosted +CI, branch landing, a public release, or independent adoption. + +### Review corrections + +The final guided capture now keeps one lane lock from handoff validation through +lane release. The active handoff command also selects and validates the intent, +renews the lease, and builds status under one lane lock. Completed intents still +validate every Git parent, tree, message, path set, scope, and final tree. + +Additional corrections bind `wip env` to the lane worktree before renewal and +recognize every supported Boolean spelling of `--observe`. Initialization now +requires an interactive worktree destination and reports where to continue +after create or reuse. + +Deterministic contention tests paused after handoff validation. A competing +lane lock returned `LOCK_TIMEOUT` for both active handoff and final capture. +Wrong-worktree and observe tests proved that rejected or observing calls did +not change lease timestamps. + +The released-handoff regression compared the lane lock before and after the +command. The bytes were identical. Unit tests also proved that released +handoff locking does not create a missing lock file or parent directory. The +tests reject directories, symlinks, and replaced lock paths. They also prove +that the read-only acquisition still waits for an existing owner. + +Real plan, status, legacy-plan, and handoff command data passed the published +Draft 2020-12 schemas. A deliberately incomplete handoff with an unknown field +was rejected. + +### Race-gate correction + +The first required three-count race run found a timing defect in the existing +heartbeat test. The test slept near lease expiry. Race instrumentation +sometimes moved execution past the deadline. Its failure path also left the +test heartbeat running. + +The first correction polled the lease for a new timestamp. A later race run +correctly hit the fail-closed stable-file check during atomic lease replacement. +The final test uses an internal observer that fires only after a completed +background refresh. It does not add a retry or weaken the production reader. + +Ten targeted heartbeat race repetitions passed. After the released-handoff +lock correction, ten file-lock repetitions and five CLI contention repetitions +also passed. The final `go test -race -count=3 ./...` run passed all packages. +The CLI package completed in 157.817 seconds. + +The final local gate matrix also passed `go test ./...`, `go vet ./...`, +`actionlint`, `golangci-lint run ./...`, `go mod verify`, and +`govulncheck@v1.7.0 ./...`. The vulnerability scan found no reachable known +vulnerability. + +`git fsck --strict --no-dangling` also passed. Gitleaks scanned the complete +82-commit history and the final worktree. Both scans found no leak. + +### Protected landing review + +A read-only remote audit found `origin/main` at +`4cf003bebbfd9c6281578ea9ef1b679dae67078f`. Pull request +[#7](https://github.com/nstranquist/wip-commit/pull/7) remained open at +`bfb720d9870f9f63d4c4110f9ee84aafc6d6a361`. + +The pull request and this branch both change the architecture and store lock +model. A read-only three-tree preview found textual conflicts in +`docs/ARCHITECTURE.md` and `internal/store/store.go`. During landing, preserve +the pull request's state-registry read fence and this branch's continuous +lane-lock transaction. Run the Windows concurrency stress test and the complete +gate matrix on the combined candidate. + +No command pushed, merged, closed, or changed the pull request. + +### Reviewed repository capture + +The source `HEAD` stayed at +`1194d4564c1009f81d486000734756e787956ed1`. Status reported 21 exact capture +candidates and no foreign staged paths. The reviewed three-group plan ran a +focused gate for the boundary change and full repository tests for the schema +and documentation groups. + +The private chain was: + +1. `f47cedc0b69c46933c2872f552aa5f84f78d0177` — `fix(capture): harden agent workflow boundaries` +2. `8d3764881ebc60eefa0e96845cabd8194379a4da` — `test(schema): validate published command contracts` +3. `a6f7dee2049672baa78d61cc149e8f983ce3e033` — `docs(capture): explain atomic agent handoff workflow` + +Receipt evidence: + +- Lane: `refs/heads/wip/codex/agent-facing-v2-atomic-final`. +- Plan ID: `plan-185477327d1cc03e1e04037e`. +- Capture intent digest: + `sha256:e7edfba90386fb2a2c8b9c34f2e7844a92c92843d15b1ef8ef5f1607e412c873`. +- Reviewed plan digest: + `sha256:5f339fd8cfcbe621ab170067dfcea023a4d5e6e61827e9ae3d1de5f785c26e41`. +- Source-index digest: + `sha256:028fe1582dfea7c4609f05ca2804dd4d80ccc1dd0d973a789f3dc636b2488a39`. +- Final tree: `f3223a96009d9fed401c33bb6fd7745aec60bc61`. +- Every group-specific verification command passed. +- The handoff set `capture_only` to true and `landing_authorized` to false. + +The final reviewed capture added this evidence file and used `--final`: + +- Commit: `e356d9f489ec2ff256dfef424a762a867defe858`. +- Plan ID: `plan-1c61a7a787b31eb9d3b35560`. +- Capture intent digest: + `sha256:4fbd19cc3d180cd223dd912508002db964b2d5f849b7ced4cbac909f8a599ca1`. +- Reviewed plan digest: + `sha256:cd600afae3cd847d34b42792e39d942cecb708ca361232865689bc4b369d93ec`. +- Final tree: `d285e5e57bf9491d2067222a7e38fa280e9b8d3c`. +- `lane_released` was true, and the final context had no lease expiry. + +The source `HEAD` remained unchanged. The lane ref and all four private commits +remain available. No command landed, merged, pushed, or deleted the lane ref. + +## 2026-08-18 reviewed guided capture + +This exercise used a source-current binary in a linked worktree. It captured +the complete agent-facing workflow with the new version 2 plan and handoff +contracts. + +Evidence scope: local maintainer evidence. This exercise does not prove hosted +CI, publication, release, landing, or independent adoption. + +### Operational status and lease behavior + +The source `HEAD` was +`206fa8b6a1dde1d97081133e4d447c0881849922`. The lane was +`refs/heads/wip/codex/agent-facing-capture-v2`. + +An expired lane inspection returned `LEASE_EXPIRED` with a complete status +object. It did not renew an expired lease. After an explicit claim, ordinary +`status` and `plan` calls renewed the complete active path set. + +After exact staging, status reported 46 capture candidates and no foreign +staged paths. It also reported three empty broad lease scopes. The status +object validated against `STATUS.schema.json`. + +### Reviewed plan and safe failure + +The generated draft proposed 12 component groups. Review consolidated them +into three dependency-closed groups: + +1. `feat(capture): add reviewed agent workflow` +2. `docs(capture): define operational handoff contracts` +3. `feat(skill): teach reviewed capture workflow` + +The first capture built the first private commit. The next group failed with +`DIFF_CHECK_FAILED` because `docs/STATUS.schema.json` had one extra blank line +at EOF. The lane ref stayed at its old value. The source `HEAD` and staged +entries also stayed unchanged. + +After that byte was fixed, the old plan returned `STALE_PLAN` before hooks ran. +This result confirmed that the reviewed plan bound the selected index content. +A new generated draft received the same reviewed three-group structure. + +### Applied result + +The second capture produced this private linear chain: + +1. `6a9e14d1f83bb3c04202e4536d94578e2ca89019` — `feat(capture): add reviewed agent workflow` +2. `19a4f1c1c6463c55bbe8bf3439691e5901cf040b` — `docs(capture): define operational handoff contracts` +3. `4c27c2a6f477a33ef257a4722fc03c47d7473f0e` — `feat(skill): teach reviewed capture workflow` + +Receipt evidence: + +- Plan ID: `plan-9b2932bca63b757a5ec475b2`. +- Capture intent digest: + `sha256:8c48dad5804a213823c24447957735e61f3853bea710b278f9fcde4a833281b5`. +- Reviewed plan digest: + `sha256:d24c6a65ade6962da016d4c75d6d8141a03dc9744d980a6359e6284c3ef898c7`. +- Final tree: `fda0fab63f375d37b1fb2fd4e5f424af8724fea0`. +- Changed-path counts: 21, 22, and 3. +- Each group-specific verification command passed. +- The source `HEAD` stayed unchanged. +- The complete `git ls-files --stage -z` digest stayed + `cfb3075ba51c7b6358c5bd04c7c4abf4fd3f928815f06470dedc0b5466adc50a`. + +The guided command emitted a handoff that validated against +`HANDOFF.schema.json`. The handoff bound the named message policy and reviewed +plan digest. It set `capture_only` to true and `landing_authorized` to false. + +The later standalone handoff returned the same receipt. Status reported zero +capture candidates, 46 captured-but-still-staged paths, a complete intent, and +no foreign staged paths. The lane remained active at that checkpoint so this +evidence record could be added. A final one-file capture of this record +releases the lane only after handoff validation. No command lands, merges, or +pushes the private ref. + +### Post-capture review correction + +A later code review found a narrow interval between command validation and the +kernel's first index read. A parallel writer could replace selected entries +during that interval. Stable replacement content could then pass the kernel's +final reread. + +The kernel now requires the reviewed source-index digest. It compares that +digest with its initial source snapshot before hooks run. The final reread +still detects changes during capture. + +`TestRunRejectsReviewedIndexMismatchBeforeHooks` proves that a mismatch returns +`SOURCE_INDEX_MOVED` without running the repository hook or updating the ref. +This correction requires a new final capture and supersedes the earlier lane +tree as the release candidate. + +The corrected candidate used lane +`refs/heads/wip/codex/agent-facing-capture-v2-final`. Its reviewed capture +produced this chain: + +1. `7efa2bea4373b40b2089a6ff61b37778dcec7246` — `feat(capture): add reviewed agent workflow` +2. `5e853892f31e08e8dc73a7a4f0b4f3a6c63c4a29` — `docs(capture): define operational handoff contracts` +3. `eb9ac96215ec1033920a7569fb8961f09c3c2aed` — `feat(skill): teach reviewed capture workflow` + +Corrected receipt evidence: + +- Plan ID: `plan-16cafb8a9838ec64f7631b00`. +- Capture intent digest: + `sha256:2a8922d1d1a0bd9356b4fc4a3bf7489f8d1fab7a27304777e37c4f0b0bcb084d`. +- Reviewed plan digest: + `sha256:11d4605aa1795ab6a9b7154f7328205e2bb60abf380a84d209924389dfbda431`. +- Reviewed and kernel source-index digest: + `sha256:cb2393c80e40ccd78ba612742625a09490e81f2843cf5e85c91c25a9ae479387`. +- Final tree: `1f6bb2999e707426c67d3942e83565fb4e17b0a4`. +- The source `HEAD` and complete staged-entry listing stayed unchanged. +- A standalone active-lane handoff renewed the complete lease set only after + the receipt validated. + +The lane stayed active for this evidence edit. A final reviewed capture adds +only this changed file and releases the lane after handoff validation. + ## 2026-08-16 self-hosted shared capture This exercise used a source-current `wip` binary on the real dirty @@ -19,6 +385,10 @@ hosted CI, an independent user exercise, or an independent security review. ### Safe failure under host pressure +Historical contract note: this evidence predates the no-exec dry-run contract. +Current `wip commit --dry-run` does not execute hooks or verification commands. +Only a non-dry capture can provide current gate evidence. + The first capture dry-run ran the complete internal test set. Disposable Git tests reached the host storage limit and returned `no space left on device`. @@ -201,3 +571,44 @@ skill files were byte-equal to the source bundle. The redacted maintainer receipt is [BETA-EXERCISE.maintainer-2026-08-16.json](BETA-EXERCISE.maintainer-2026-08-16.json). It validates the protocol without closing the independent beta gate. + +## 2026-08-21 repeated archive and restore maintenance + +This exercise used the real `wip-commit` coordination store. A reviewed +preview selected 34 released lanes and excluded the active correction lane. + +The first apply used the previously installed binary. It completed as +`archive-86653415cc3e81cce70e103e`, but `wip doctor` then found that the older +restored receipt `archive-74f4b31a69187b337ed50e88` no longer had its record +live or in its own batch. The exact new receipt was restored immediately. The +store returned to a healthy state, and every WIP ref stayed unchanged. + +The failure-boundary regression now runs this sequence: + +1. archive a released lane. +2. restore the receipt. +3. archive the same records into a different receipt. +4. validate both the historical and current receipts. +5. remove one successor record and require `ARCHIVE_FAILED`. +6. restore the record and the current receipt. + +The CLI regression also requires `wip doctor` to stay healthy after the second +archive. The implementation accepts a non-live historical record only when one +newer, non-restored, fully validated receipt owns it. Missing, duplicated, +unbound, or changed records still fail closed. + +The full tests, three race-enabled test runs, `go vet`, `actionlint`, +`golangci-lint`, Linux and Windows cross-builds, and the portable behavioral +benchmark passed. The benchmark candidate passed 16 of 16 checks. The +deliberately weakened candidate passed 0 of 16. Both benchmark runs used zero +AI calls and zero AI tokens. + +The source-current binary had SHA-256 +`d57891ca834bfd06e6ccd6e9af54f074034a84bb0dd2fc3e0f35e816861889c6`. +It applied the reviewed 34-lane plan as +`archive-1b8c142d0db2e33553893714`, with receipt digest +`sha256:1b8c142d0db2e3355389371418c26e316e924629eda43cbfcafe9b5be68c568c`. +The batch contains 118 records. The complete WIP ref inventory was byte-equal +before and after apply. The final doctor read was healthy with one active lane, +no archive candidates, no pending recovery, and no findings. No ref was +deleted, landed, merged, or pushed. diff --git a/docs/ERRORS.md b/docs/ERRORS.md index a8e7416..4031ff8 100644 --- a/docs/ERRORS.md +++ b/docs/ERRORS.md @@ -1,7 +1,7 @@ # Error and recovery guide `wip --json` returns one object with `ok`, `action`, and either `data` or -`error`. The error object has a stable `code` and a human-readable `message`. +`error`. Successful lane commands also return `context` with lease state. ## Coordination errors @@ -11,11 +11,12 @@ | `LANE_AMBIGUOUS` | More than one shared lane matches | Pass `--lane` or load `wip env --lane ` | | `PATH_LEASE_CONFLICT` | Another active lane owns an overlapping path | Select disjoint paths, or wait for that owner to release or expire | | `LEASE_EXPIRED` | The lease deadline passed | Run `wip init` again or claim the paths again | -| `LEASE_HEARTBEAT_FAILED` | Capture could not refresh its exact lease set | If `ref_updated` is true, run `wip reconcile` with the returned plan evidence. Otherwise, run `wip doctor` | -| `LANE_RELEASE_RECOVERY_REQUIRED` | Lease release started before the lane manifest changed | Rerun the exact `wip release`; do not claim, renew, or capture on that lane | +| `LEASE_HEARTBEAT_FAILED` | Capture failed to refresh its exact lease set | If `ref_updated` is true, run `wip reconcile` with the returned plan evidence. Otherwise, run `wip doctor` | +| `LANE_RELEASE_RECOVERY_REQUIRED` | Lease release started before the lane manifest changed | Rerun the exact `wip release`. Do not claim, renew, or capture on that lane | | `RELEASED_LANE_ACTIVE_LEASE` | A released or aborted lane still has an active stored lease | Stop. Preserve the records and inspect with `wip doctor` | | `WORKTREE_CONFLICT` | An exclusive worktree binding conflicts | Use another linked worktree or release the active lane | -| `LOCK_TIMEOUT` | Another process held a required lock | Wait, inspect `wip status`, and retry | +| `WORKTREE_MISMATCH` | The selected lane belongs to another checkout | Change to the lane's recorded checkout; do not export or use its identity elsewhere | +| `LOCK_TIMEOUT` | Another process held a required lock | The default fails fast. Inspect `wip status` and retry later. Use an explicit bounded `--lock-wait` only when blocking is intended | | `COORDINATION_DOMAIN_CONFLICT` | Public and legacy coordination state cannot share one repository | Stop all lane processes. Preserve both state roots, then select one domain | ## Capture errors @@ -23,27 +24,43 @@ | Code | Meaning | Action | | --- | --- | --- | | `SPLIT_PLAN_REQUIRED` | Automation did not provide a split plan | Pass `--plan`, or explicitly pass `--single --message` | -| `INVALID_COMMIT_MESSAGE` | A message failed the naming policy | Use a concrete Conventional Commit subject of at most 72 characters | -| `SOURCE_INDEX_MOVED` | A selected staged entry changed during capture | Inspect the staged paths and rerun the complete plan | +| `REVIEWED_PLAN_REQUIRED` | `wip capture` did not receive one version 3 plan | Run `wip plan --out `, review that file, then pass it to `wip capture` | +| `REVIEW_PLAN_DIGEST_MISMATCH` | The reviewed plan differs from the exact digest supplied by NDev | Stop. Preserve the plan and request a new review digest | +| `PLAN_NOT_REVIEWED` | The version 3 plan still has draft state | Add every message, review every group, then set `state` to `reviewed` | +| `STALE_PLAN` | A bound lane, source, path, lease, or policy value changed | Create and review a new plan from the selected source | +| `PLAN_EXISTS` | `wip plan --out` found an existing destination | Select a new output path or review the existing file separately | +| `INVALID_SOURCE_POLICY` | The source mode and untracked policy are not compatible | Use `not_applicable` with `staged_index`. Use `forbid` or `include` with `worktree_snapshot` | +| `UNTRACKED_PATH_FORBIDDEN` | A selected worktree scope contains an untracked path under the `forbid` policy | Review the untracked paths. Use `include` only when all selected paths belong in the capture | +| `SOURCE_SNAPSHOT_FAILED` | Git or the filesystem failed to build the private source snapshot | Preserve the caller index. Fix the reported source error, then create a new plan | +| `MESSAGE_POLICY_REJECTED` | A message failed the named lane policy | Follow the policy in the JSON `message_policy` receipt | +| `INVALID_MESSAGE_POLICY` | A policy name or receipt is unsupported | Fix `.wip-commit.json` or use a supported `--message-policy` value | +| `INVALID_COMMIT_MESSAGE` | A message failed kernel byte or size safety | Remove unsafe controls, fix the subject, or reduce the message size | +| `SOURCE_MOVED` | The selected source no longer matches the reviewed digest | Inspect the selected source paths and create a new reviewed plan | | `SOURCE_HEAD_MOVED` | The checkout moved from the lane base | Stop and create a new lane from the intended base | -| `REF_MOVED` | The lane ref did not match the expected cursor | Inspect the lane and receipt; do not force-update it | +| `REF_MOVED` | The lane ref did not match the expected cursor | Inspect the lane and receipt. Do not force-update it | | `PLAN_SCOPE_MISMATCH` | A hook changed an unplanned private-index path | Fix the hook or expand the reviewed plan and lease | | `HOOK_SOURCE_MOVED` | A hook path changed during capture | Inspect the hook and rerun from a stable source | | `HOOK_TIMEOUT` | A hook exceeded its limit | Fix the hook or pass a reviewed larger timeout | | `VERIFY_FAILED` | A candidate-tree command failed | Fix the candidate change and rerun the whole plan | +| `VERIFY_MATERIALIZATION_LIMIT` | A verify command requested more than 16,384 candidate entries or 512 MiB | Set the smallest `directory`, add only required `materialize` dependencies, and review a new plan | | `VERIFY_TIMEOUT` | A verify command exceeded its limit | Fix the command or pass a reviewed larger timeout | -| `GIT_FAILED` | Git could not inspect the staged path set | Fix the reported index or repository error, then run the exact command again | -| `DIFF_CHECK_FAILED` | Git could not complete the staged whitespace check | Fix the reported Git error. Do not treat the check as passed | +| `GIT_FAILED` | Git failed to inspect the selected source or Git objects | Fix the reported repository error, then run the exact command again | +| `DIFF_CHECK_FAILED` | Git failed to complete the candidate whitespace check | Fix the reported Git error. Do not treat the check as passed | ## Recovery errors | Code | Meaning | Action | | --- | --- | --- | -| `PLAN_NOT_APPLIED` | The intent exists but the ref stayed at the old commit | Run the complete plan again from current staged state | +| `PLAN_NOT_APPLIED` | The intent exists but the ref stayed at the old commit | Create a new plan from the current selected source | | `INTENT_NOT_FOUND` | The supplied plan ID has no durable record | Use the exact JSON result from the failed capture | | `INTENT_DIGEST_MISMATCH` | The record or supplied digest differs | Stop. Do not edit the receipt or guess a digest | -| `INVALID_INTENT` | A digest-valid receipt has invalid identities, bounds, paths, or commit structure | Stop. Preserve the receipt and lane ref; do not mark or reconcile it | +| `INVALID_INTENT` | A digest-valid receipt has invalid identities, bounds, paths, or commit structure | Stop. Preserve the receipt and lane ref. Do not mark or reconcile it | | `CAPTURE_RECEIPT_MISMATCH` | Git objects do not match immutable evidence | Stop and inspect the repository. Do not force reconciliation | +| `HANDOFF_NOT_READY` | The lane has no complete validated capture intent | Reconcile an applied intent or complete a reviewed capture first | +| `HANDOFF_CHAIN_INCOMPLETE` | No continuous completed intent chain reaches the lane tip | Preserve all intents and refs. Reconcile the missing segment or inspect the gap | +| `HANDOFF_CHAIN_AMBIGUOUS` | More than one completed intent continues the same parent | Stop. Preserve all intents and refs for a separate recovery review | +| `HANDOFF_TIP_MISMATCH` | The supplied intent does not name the lane tip segment | Use no selector for the complete chain, or supply the exact tip intent evidence | +| `HANDOFF_TOO_LARGE` | The cumulative handoff exceeds a segment, commit, or byte bound | Stop. Preserve the lane and use a separately reviewed bounded handoff procedure | ## State compatibility errors @@ -51,26 +68,51 @@ | --- | --- | --- | | `MIGRATION_REQUIRED` | A state directory or record uses an unsupported schema | Stop. Use the compatible `wip` release and follow [STATE-COMPATIBILITY.md](STATE-COMPATIBILITY.md) | | `STORE_FAILED` | Version 1 lane or lease state is malformed or unsafe to read | Stop. Preserve the state and inspect the reported file condition | -| `PROFILE_READ_FAILED` | A version 1 profile is malformed or has the wrong identity | Pass the full identity only after you confirm the lane owner | -| `INTENT_READ_FAILED` | A version 1 intent is malformed or unsafe to read | Stop. Preserve the intent and lane ref; do not guess recovery data | +| `PROFILE_READ_FAILED` | A supported profile is malformed, has the wrong identity, or has an invalid policy | Preserve the profile and confirm the lane owner and policy | +| `INTENT_READ_FAILED` | A supported intent is malformed or unsafe to read | Stop. Preserve the intent and lane ref. Do not guess recovery data | | `INTENT_WRITE_FAILED` | A capture intent cannot fit or cannot be published | The lane ref did not move. Reduce the plan size or fix the reported storage error | | `INIT_INTENT_FAILED` | An initialization receipt is malformed or changed | Stop. Preserve the receipt, worktree, lane ref, lease, profile, and installed files | | `INSTALL_CONFLICT` | The binary target exists with different bytes or an unsafe type | Preserve the target. Select another `--install-dir`, or review the target separately | -| `INSTALL_FAILED` | The binary could not be published or verified | Preserve any complete target and retry the exact initialization command | +| `INSTALL_FAILED` | Binary publication or verification failed | Preserve any complete target and retry the exact initialization command | | `SKILL_INSTALL_CONFLICT` | The target skill directory contains different content | Select another `--skill-dir`, or remove the target only after a separate review | -| `SKILL_INSTALL_FAILED` | The embedded skill could not be published or verified | Preserve the matching partial bundle and retry the exact initialization command | +| `SKILL_INSTALL_FAILED` | Embedded skill publication or verification failed | Preserve the matching partial bundle and retry the exact initialization command | +| `STATE_NOT_INITIALIZED` | A state upgrade has no owned domain marker | Run `wip init`. Do not use upgrade as first initialization | +| `UPGRADE_BLOCKED` | State has an active lane, pending recovery, or unhealthy record | Stop all `wip` processes, release lanes, and make `wip doctor` healthy before a new preview | +| `UPGRADE_PLAN_DIGEST_MISMATCH` | Apply does not match the current byte-bound preview | Review a new preview. Do not reuse the old digest | +| `UPGRADE_PLAN_MOVED` | The target bytes changed after preview or while acquiring the lock | Preserve the target and review a new preview | +| `UPGRADE_TARGET_MISSING` | Binary or skill upgrade target does not exist | Use the no-overwrite first-install path in `wip init` | +| `UPGRADE_CONFLICT` | The upgrade target has an unsafe type, unexpected entry, or excessive size | Preserve and inspect the target. Do not replace it automatically | +| `UPGRADE_FAILED` | Atomic replacement or post-write verification failed | Preserve the target and rerun preview. A new reviewed upgrade can repair a partial skill bundle that fails digest validation | + +## Coordination migration errors + +| Code | Meaning | Action | +| --- | --- | --- | +| `MIGRATION_PRODUCER_INVALID`, `MIGRATION_PRODUCER_MISMATCH` | The executable identity is missing, invalid, or different from the reviewed producer | Use the exact source-stamped executable that created the reviewed plan | +| `MIGRATION_PLAN_BLOCKED`, `MIGRATION_PLAN_INVALID`, `MIGRATION_PLAN_DIGEST_MISMATCH`, `MIGRATION_PLAN_TOO_LARGE` | The migration plan is blocked, malformed, moved, or outside its bound | Preserve both roots. Create and review a new preview | +| `MIGRATION_PRESTATE_CHANGED`, `MIGRATION_SOURCE_MOVED`, `MIGRATION_REF_MOVED`, `MIGRATION_CANONICAL_MOVED`, `MIGRATION_REPOSITORY_MISMATCH` | A bound repository, source, destination, or ref changed before migration completed, or the static migration envelope changed later | Restore the writer freeze. Create and review a new preview unless a journal requires resume. A normal post-cutover live-store change is reported as `canonical_advanced` instead | +| `MIGRATION_SOURCE_INVALID`, `MIGRATION_SOURCE_UNSAFE`, `MIGRATION_SOURCE_STATE_INVALID` | The legacy source layout, file type, or record state is unsafe | Preserve the source. Repair it only through a separate reviewed recovery plan | +| `MIGRATION_DESTINATION_INVALID`, `MIGRATION_DESTINATION_UNSAFE` | The canonical destination contains an invalid or unsafe path | Preserve the destination. Do not replace or remove it automatically | +| `MIGRATION_LOCKED`, `MIGRATION_IN_PROGRESS`, `MIGRATION_FENCE_CONFLICT` | Another migration owns the lock or writer fence | Inspect migration status. Resume only the exact owning plan | +| `MIGRATION_RESUME_REQUIRED`, `MIGRATION_INTERRUPTED` | A durable migration journal requires forward recovery | Run `--resume` with the exact plan, digest, producer, and writer freeze | +| `MIGRATION_NOT_STARTED`, `MIGRATION_ROLLED_BACK` | The supplied resume or rollback action has no resumable journal | Create and review a new preview | +| `MIGRATION_ROLLBACK_REFUSED`, `MIGRATION_ROLLBACK_INVALID`, `MIGRATION_ROLLBACK_FAILED` | Rollback is unsafe, moved, or failed | Preserve all migration artifacts. Resume forward if the legacy source moved | +| `MIGRATION_ARCHIVE_CONFLICT`, `MIGRATION_ARCHIVE_INVALID`, `MIGRATION_ARCHIVE_MISSING`, `MIGRATION_ARCHIVE_MOVED`, `MIGRATION_ARCHIVE_UNSAFE` | The legacy archive is missing, changed, unsafe, or conflicts with another path | Preserve the archive. Do not reconstruct or delete it by hand | +| `MIGRATION_JOURNAL_INVALID`, `MIGRATION_JOURNAL_FAILED`, `MIGRATION_RECEIPT_INVALID`, `MIGRATION_STATUS_INVALID` | Durable migration evidence is invalid or its write failed | Stop all writers. Preserve the journal, plan, receipt, roots, and refs | +| `MIGRATION_PLAN_FAILED`, `MIGRATION_PREPARE_FAILED`, `MIGRATION_SOURCE_MOVE_FAILED`, `MIGRATION_SEAL_FAILED`, `MIGRATION_FENCE_FAILED` | A migration file or directory operation failed | Preserve all artifacts. Inspect status, then resume only the exact plan | +| `MIGRATION_SOURCE_NOT_REMOVED` | A completed migration still has an unsealed or duplicate legacy source | Stop all writers. Preserve both locations and inspect the exact migration receipt | ## Inspection and archival errors | Code | Meaning | Action | | --- | --- | --- | | `ARCHIVE_PLAN_REQUIRED` | Apply has no reviewed cutoff or digest | Run the preview, then reuse its exact `--cutoff` and `--plan-digest` | -| `ARCHIVE_PLAN_MOVED` | The eligible record set differs from the preview | Run a new preview. Do not reuse the old digest | +| `ARCHIVE_PLAN_MOVED` | The eligible record set differs from the preview | Repeat every `--lane` filter from the preview, or run a new preview. Do not reuse a digest after records change | | `ARCHIVE_EMPTY` | The reviewed plan has no exact eligible candidate | Run a new preview with an older cutoff or a valid lane | | `ARCHIVE_REFUSED` | A lane, lease, or ref is not safe to archive | Run `wip doctor` and repair the reported state first | | `ARCHIVE_CONFLICT` | Live and archived records conflict | Preserve both copies and inspect the receipt before retry | | `ARCHIVE_NOT_FOUND` | A resume or restore receipt does not exist | Use the exact receipt ID from the earlier result. The command does not initialize state | -| `ARCHIVE_FAILED` | A receipt, batch layout, record binding, or file placement is invalid | Preserve the live and archived records. Use `wip doctor` and do not move files by hand | +| `ARCHIVE_FAILED` | A receipt, batch layout, record binding, file placement, or later archive owner is invalid | Preserve the live and archived records. Use `wip doctor` and do not move files by hand | If archive apply returns a receipt with state `prepared`, preserve the state directory and run `wip archive --resume --apply --yes`. Do not run diff --git a/docs/HANDOFF.schema.json b/docs/HANDOFF.schema.json new file mode 100644 index 0000000..88f7ed0 --- /dev/null +++ b/docs/HANDOFF.schema.json @@ -0,0 +1,159 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://github.com/nstranquist/wip-commit/blob/main/docs/HANDOFF.schema.json", + "title": "wip cumulative capture-only handoff v2", + "type": "object", + "additionalProperties": false, + "required": [ + "schema_version", + "kind", + "handoff_digest", + "capture_only", + "landing_authorized", + "review_eligible", + "lane_ref", + "lane_tip", + "lane_base_commit", + "final_tree", + "tip_plan_id", + "tip_capture_intent_digest", + "segments" + ], + "properties": { + "schema_version": {"const": "2.0.0"}, + "kind": {"const": "capture_handoff"}, + "handoff_digest": {"$ref": "#/$defs/digest"}, + "capture_only": {"const": true}, + "landing_authorized": {"const": false}, + "review_eligible": {"type": "boolean"}, + "lane_ref": {"type": "string", "pattern": "^refs/heads/wip/[^/]+/[^/]+$"}, + "lane_tip": {"$ref": "#/$defs/object_id"}, + "lane_base_commit": {"$ref": "#/$defs/object_id"}, + "final_tree": {"$ref": "#/$defs/object_id"}, + "tip_plan_id": {"$ref": "#/$defs/plan_id"}, + "tip_capture_intent_digest": {"$ref": "#/$defs/digest"}, + "segments": { + "type": "array", + "minItems": 1, + "maxItems": 1000, + "items": {"$ref": "#/$defs/segment"} + } + }, + "allOf": [ + { + "if": {"properties": {"review_eligible": {"const": true}}, "required": ["review_eligible"]}, + "then": { + "properties": { + "segments": { + "items": { + "allOf": [ + {"$ref": "#/$defs/segment"}, + { + "required": [ + "reviewed_plan_digest", + "message_policy", + "source_mode", + "untracked_policy", + "source_digest", + "source_paths" + ], + "properties": {"message_policy_bound": {"const": true}} + } + ] + } + } + } + } + } + ], + "$defs": { + "object_id": {"type": "string", "pattern": "^(?:[0-9a-f]{40}|[0-9a-f]{64})$"}, + "digest": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"}, + "plan_id": {"type": "string", "pattern": "^plan-[0-9a-f]{24}$"}, + "paths": { + "type": "array", + "minItems": 1, + "maxItems": 10000, + "uniqueItems": true, + "items": {"type": "string", "minLength": 1} + }, + "message_policy": { + "type": "object", + "additionalProperties": false, + "required": ["id", "version", "digest"], + "properties": { + "id": {"enum": ["conventional-v1", "safety-only-v1"]}, + "version": {"const": "1.0.0"}, + "digest": {"$ref": "#/$defs/digest"} + } + }, + "segment": { + "type": "object", + "additionalProperties": false, + "required": [ + "index", + "plan_id", + "capture_intent_digest", + "message_policy_bound", + "intent_state", + "source_head", + "parent_commit", + "final_commit", + "final_tree", + "commits" + ], + "properties": { + "index": {"type": "integer", "minimum": 1}, + "plan_id": {"$ref": "#/$defs/plan_id"}, + "capture_intent_digest": {"$ref": "#/$defs/digest"}, + "reviewed_plan_digest": {"$ref": "#/$defs/digest"}, + "message_policy": {"$ref": "#/$defs/message_policy"}, + "message_policy_bound": {"type": "boolean"}, + "intent_state": {"const": "complete"}, + "source_head": {"$ref": "#/$defs/object_id"}, + "source_mode": {"enum": ["staged_index", "worktree_snapshot"]}, + "untracked_policy": {"enum": ["not_applicable", "forbid", "include"]}, + "source_digest": {"$ref": "#/$defs/digest"}, + "source_paths": {"$ref": "#/$defs/paths"}, + "parent_commit": {"$ref": "#/$defs/object_id"}, + "final_commit": {"$ref": "#/$defs/object_id"}, + "final_tree": {"$ref": "#/$defs/object_id"}, + "commits": { + "type": "array", + "minItems": 1, + "maxItems": 128, + "items": {"$ref": "#/$defs/commit"} + } + }, + "allOf": [ + { + "if": {"properties": {"message_policy_bound": {"const": true}}, "required": ["message_policy_bound"]}, + "then": {"required": ["reviewed_plan_digest", "message_policy"]} + }, + { + "if": {"properties": {"source_mode": {"const": "staged_index"}}, "required": ["source_mode"]}, + "then": {"properties": {"untracked_policy": {"const": "not_applicable"}}} + }, + { + "if": {"properties": {"source_mode": {"const": "worktree_snapshot"}}, "required": ["source_mode"]}, + "then": {"properties": {"untracked_policy": {"enum": ["forbid", "include"]}}} + } + ] + }, + "commit": { + "type": "object", + "additionalProperties": false, + "required": ["index", "message", "parent", "commit", "tree", "changed_paths", "verify_count", "repairs_applied"], + "properties": { + "index": {"type": "integer", "minimum": 1}, + "message": {"type": "string", "minLength": 1}, + "parent": {"$ref": "#/$defs/object_id"}, + "commit": {"$ref": "#/$defs/object_id"}, + "tree": {"$ref": "#/$defs/object_id"}, + "changed_paths": {"$ref": "#/$defs/paths"}, + "verify_count": {"type": "integer", "minimum": 0, "maximum": 64}, + "repairs_applied": {"type": "integer", "minimum": 0} + } + } + } +} diff --git a/docs/HOSTED-SETUP.md b/docs/HOSTED-SETUP.md index 1f44eeb..3653de0 100644 --- a/docs/HOSTED-SETUP.md +++ b/docs/HOSTED-SETUP.md @@ -1,5 +1,8 @@ # Hosted repository setup +Status: Executed for the first source publication. Use this file to verify or +repair controls. Do not repeat repository creation. + ## Authority boundary The owner approved the `wip-commit` name, @@ -9,8 +12,10 @@ instructions assign the first push to a human. Do not create a release tag until every public-beta gate passes. -Use [PUBLICATION-HANDOFF.md](PUBLICATION-HANDOFF.md) before this runbook. This -runbook does not authorize a release tag. +The first-publication procedure is now a historical record in +[PUBLICATION-HANDOFF.md](PUBLICATION-HANDOFF.md). Current control evidence is in +[HOSTED-STATUS-2026-08-18.md](HOSTED-STATUS-2026-08-18.md). This runbook does +not authorize a release tag. ## Source of truth diff --git a/docs/HOSTED-STATUS-2026-08-18.md b/docs/HOSTED-STATUS-2026-08-18.md new file mode 100644 index 0000000..e4fd81b --- /dev/null +++ b/docs/HOSTED-STATUS-2026-08-18.md @@ -0,0 +1,62 @@ +# Hosted source status + +Observed on: 2026-08-18 + +Evidence scope: read-only GitHub API and remote-ref checks. + +## Confirmed public state + +The source repository is public at +[github.com/nstranquist/wip-commit](https://github.com/nstranquist/wip-commit). +Its default branch is `main`. + +Live `main` was +`4cf003bebbfd9c6281578ea9ef1b679dae67078f` during this check. The latest +`main` CI run passed the Linux, macOS, Windows, race, and lint jobs. The +dependency-review job was skipped on the push event, as designed. A release +candidate must pass it on a pull-request event. + +[CI run 32183872589](https://github.com/nstranquist/wip-commit/actions/runs/32183872589) +is the live `main` run that this record checked. + +## Confirmed controls + +Ruleset +[20926881](https://github.com/nstranquist/wip-commit/rules/20926881) is active +for the default branch. It has no bypass actor. It blocks deletion and +non-fast-forward updates. It requires linear history and one approving review. +It also requires approval after the last push and resolved review threads. +Pull requests must use rebase-only updates. + +The ruleset requires these provider-bound checks: + +- `test (ubuntu-latest)` +- `test (macos-latest)` +- `test (windows-latest)` +- `race` +- `lint` +- `dependency-review` + +Workflow tokens use read-only permissions by default. They cannot approve pull +requests. + +Private vulnerability reporting, secret scanning, secret-scanning push +protection, and Dependabot security updates are enabled. + +## Lifecycle boundary + +The repository has no Git tag and no GitHub release. Public source and passing +hosted checks do not prove a release, launch, adoption, or stable support. + +The agent-facing workflow in KEP-0003 is local candidate work. It has not run on +hosted workers or landed on public `main`. Its exact final commit must pass the +required pull-request checks before a beta tag can use it. + +These human or external gates remain: + +- An independent beta exercise. +- An approved Code of Conduct and confidential reporting path. +- Maintainer security-notification verification. +- Explicit tag approval. +- Tag workflow, archive, checksum, and attestation verification. +- Clean installation from the final public tag. diff --git a/docs/KEP-0001-capture-to-landing-boundary.md b/docs/KEP-0001-capture-to-landing-boundary.md index fe5087c..3be11ca 100644 --- a/docs/KEP-0001-capture-to-landing-boundary.md +++ b/docs/KEP-0001-capture-to-landing-boundary.md @@ -1,31 +1,32 @@ # KEP-0001: Capture-to-landing boundary -Status: Proposed +Status: Superseded for standalone landing. Retained as adapter requirements. Decision owner: Repository owner -Last updated: 2026-08-16 +Last updated: 2026-08-23 Target release: Post-beta ## Summary -Keep `v0.1.0-beta.1` capture-only. The public `wip` command must not update a +Keep every public `wip` release capture-only. The command must not update a normal branch, merge commits, push refs, or resolve conflicts. -Treat landing as a separate transaction. A future landing command must use an -exact reviewed plan, a target lock, a backup ref, and one target-ref -compare-and-swap. +Treat landing as a separate product transaction. A landing authority must use +one immutable cumulative handoff, one exact review digest, a target lock, a +backup ref, and one target-ref compare-and-swap. -This KEP defines that future boundary. It does not authorize implementation or -public release. +This KEP defines the external adapter boundary. It does not authorize a +standalone landing command, implementation, or public release. ## Context Capture and landing protect different assets. -Capture protects the source checkout, source index, selected paths, lane ref, -commit chain, and recovery intent. It can run for disjoint lanes in parallel. +Capture protects the source checkout, caller index, selected source paths, lane +ref, commit chain, and recovery intent. It can run for disjoint lanes in +parallel. Landing protects a shared target branch and its review policy. It must order competing sources and stop when the target changes. @@ -40,12 +41,12 @@ The existing beta therefore publishes only an agent-owned local ref: refs/heads/wip// ``` -## Decision request +## Decision -Approve these two decisions separately: +These two decisions apply: 1. Publish the beta with capture-only scope. -2. Defer a standalone landing command until independent beta evidence exists. +2. Keep standalone landing outside this product. The second decision does not block internal landing adapters. An adapter must preserve every control in this KEP. @@ -56,7 +57,7 @@ The beta must: - capture only to an agent-owned ref. - preserve the source `HEAD`, worktree, and complete index. -- keep the source ref after release or abort. +- keep the capture ref after release or abort. - return typed capture and recovery evidence. - state that review and landing are separate operations. @@ -65,44 +66,47 @@ The beta must not: - update `main` or another normal branch. - merge, rebase, cherry-pick, or resolve conflicts. - push a ref or call a hosting API. -- delete a source or backup ref. +- delete a capture or backup ref. - infer approval from a passing local gate. -## Future landing transaction +## Separate landing transaction -This section defines a possible post-beta command. The command does not exist. +This section defines requirements for a separate landing authority. The public +`wip` command does not implement this transaction. -### Proposed interface +### Required interface shape -Preview one landing: +Preview one immutable handoff against one exact target: ```text -wip land plan \ - --source-ref refs/heads/wip/agent/lane \ +landing-authority plan \ + --handoff capture-handoff.json \ + --handoff-digest sha256: \ --target-ref refs/heads/main \ - --expected-source \ --expected-target ``` Apply only the reviewed plan: ```text -wip land apply \ - --plan-id \ - --plan-digest \ +landing-authority apply \ + --queue-id \ + --review-digest sha256: \ --yes ``` -The apply command must not accept free-form source or target overrides. +The apply command must not accept free-form handoff, source, or target +overrides. ### Required evidence The plan must bind: - the canonical Git common directory. -- the source ref and exact source commit. +- the complete immutable handoff and its exact digest. +- every handoff segment and exact source commit. - the target ref and exact target commit. -- the source capture plan ID and digest. +- one queue ID and every reviewed decision. - every source commit, parent, tree, and message. - the ancestry result. - the target worktree state. @@ -114,16 +118,16 @@ The plan must bind: The transaction must stop unless all conditions pass: -1. The source ref matches the expected source commit. -2. The source capture intent is complete and valid. +1. The stored handoff matches the exact reviewed handoff digest. +2. Every capture intent and Git object in the handoff is complete and valid. 3. The target ref matches the expected target commit. -4. The source commit is a descendant of the target commit. +4. The handoff tip is a descendant of the target commit. 5. The target has no pending landing transaction. -6. Every required gate receipt matches the source commit. +6. Every required gate receipt matches the handoff tip. 7. The repository has no unsupported state version. 8. The target branch is not checked out in any worktree. -The first standalone version must support fast-forward landing only. +The first adapter version must support fast-forward landing only. ### Publication @@ -138,16 +142,17 @@ The transaction must use this order: 7. Record the new target state. 8. Mark the intent `complete`. -The source ref and backup ref must remain after publication. +The capture ref and backup ref must remain after publication. Landing must not +move the capture ref or require it as mutable authority. ### Checked-out targets -The standalone command must return `TARGET_CHECKED_OUT` when any worktree uses +The landing authority must return `TARGET_CHECKED_OUT` when any worktree uses the target branch. It must not update that ref directly. A worktree-aware adapter can implement a separate stack transaction. That -adapter must bind the worktree, source, target, gates, ancestry, backup, intent, -and exact target compare-and-swap. +adapter must bind the worktree, immutable handoff, target, gates, ancestry, +backup, intent, and exact target compare-and-swap. ### Recovery @@ -157,12 +162,12 @@ The landing intent must support these states: prepared -> applied -> complete ``` -Recovery must use the original plan ID and digest. It must never reconstruct a -plan from the current worktree. +Recovery must use the original queue ID and review digest. It must never +reconstruct a plan from the current worktree, capture ref, or live lease state. | Intent state | Target state | Required action | | --- | --- | --- | -| `prepared` | old target | Run a new preview from current refs. | +| `prepared` | old target | Run a new preview from the stored handoff and current target. | | `prepared` | exact new target | Reconcile the original intent. | | `applied` | exact new target | Reconcile the original intent. | | `complete` | exact new target | Return the existing receipt. | @@ -174,8 +179,8 @@ Landing must not send telemetry or repository data to a network service. Receipts must not contain credentials, file contents, remote URLs, usernames, or absolute worktree paths. -Hooks and gate commands remain trusted repository code. A landing command must -not add another hook execution surface. +Hooks and gate commands remain trusted repository code. The landing authority +must not add another hook execution surface. ## Non-goals @@ -206,15 +211,15 @@ Rejected. The target worktree and index can become inconsistent with its ref. ### Keep landing outside this project forever -Valid for the beta. Revisit this option after independent users report their -handoff and reconciliation needs. +Accepted for the standalone product. A separate authority can consume the +capture-only handoff without adding landing to `wip`. -## Test plan for a future command +## Test plan for a separate authority A landing implementation must test: - exact fast-forward success. -- moved source and moved target refusal. +- changed handoff and moved target refusal. - non-fast-forward refusal. - checked-out target refusal. - concurrent plans for one target. @@ -222,7 +227,7 @@ A landing implementation must test: - gate-receipt mismatch. - interrupted intent recovery at each state. - idempotent reconciliation. -- source and backup ref preservation. +- capture and backup ref preservation. - inherited Git environment isolation. - unusual valid ref names. - Linux, macOS, and Windows runtime behavior. @@ -233,7 +238,7 @@ Do not implement the command before these gates pass: 1. Complete one independent beta exercise for both capture modes. 2. Record at least three real capture-to-integration handoffs. -3. Approve the landing policy and JSON receipt contract. +3. Approve the landing policy, queue schema, and JSON receipt contract. 4. Complete an independent security review of target locking and recovery. 5. Define the relationship with worktree-aware stack landing. @@ -243,10 +248,10 @@ Do not implement the command before these gates pass: | --- | --- | | 2026-08-16 | Recommend capture-only scope for the first public beta. | | 2026-08-16 | Require a separate KEP before standalone landing implementation. | +| 2026-08-23 | Keep standalone `wip` capture-only. Use a separate landing authority. | +| 2026-08-23 | Bind landing review to the complete cumulative handoff digest. | ## Open decisions -- Approve the capture-only public beta boundary. - Select the owner of the future target-lock namespace. - Select the gate receipt types that landing must require. -- Decide whether standalone landing remains deferred after the beta period. diff --git a/docs/KEP-0002-hosted-candidate-correction.md b/docs/KEP-0002-hosted-candidate-correction.md new file mode 100644 index 0000000..954e3ae --- /dev/null +++ b/docs/KEP-0002-hosted-candidate-correction.md @@ -0,0 +1,209 @@ +# KEP-0002: Hosted candidate correction receipt + +Status: Accepted + +Implementation: Verified on 2026-08-17 + +Decision owner: Repository owner + +Last updated: 2026-08-23 + +Target release: Before `v0.2.0-beta.1` + +## Summary + +Add a fail-closed receipt for a candidate that changes after the first public +push. Keep the pre-first-push receipt immutable. + +The correction receipt must bind the verifier, old candidate, new candidate, +local checks, remote refs, pull request, and hosted runs. It must bind the final +tree. + +This KEP does not authorize a tag or a pull-request merge. + +## Context + +The first publication used an absent repository as a privacy and identity +gate. That fact cannot stay true after repository creation. + +Hosted Windows checks then found three host assumptions. The corrected +candidate passed every required hosted check before `main` moved. + +The original receipt still proves the pre-first-push boundary. It does not bind +the corrected final commit. + +## Decision + +Use a second receipt type for post-first-push corrections. Require its +`pre-main` phase before a corrected candidate moves to `main`. + +Use the `finalized` phase only to verify an observed bootstrap sequence. This +phase does not claim that the receipt existed before `main` moved. + +## Required sequence + +If the first hosted candidate fails, use this sequence: + +1. Keep `main` at the reviewed bootstrap. +2. Keep the verification pull request open. +3. Fix the finding on the candidate branch. +4. Run every local release gate on the corrected commit. +5. Scan the complete history and worktree for secrets. +6. Check the complete author and committer identity set. +7. Fast-forward only the candidate branch. +8. Run every required hosted check on the corrected commit. +9. Create the private correction receipt. +10. Close the verification pull request without merging it. +11. Fast-forward `main` only to the receipt's candidate commit. +12. Check the remote commit and tree. + +Do not force-push a candidate branch. If a fast-forward is not possible, create +a new branch. + +The implemented command also supports a finalized verification sequence: + +1. Keep the closed pull request and every hosted run. +2. Check that the pull request closed without a merge. +3. Check that remote `main` and the candidate ref equal the corrected commit. +4. Run the complete local and hosted evidence command. +5. Record that the receipt used the `finalized` phase. + +## Receipt contract + +The command must write one new private JSON file. It must not overwrite a +file or write inside the candidate or verifier checkout. + +The receipt must bind: + +- the schema version and generation time. +- the target repository and visibility. +- the reviewed bootstrap commit and tree. +- the first receipt digest. +- the old candidate commit and tree. +- the new candidate commit and tree. +- the complete merge-free correction range. +- the verifier commit, tree, command digest, and schema digest. +- the complete reviewed delta path list. +- the local object and secret-scan results. +- the public author and committer email result. +- a digest and count for every author and committer name and email. +- the remote candidate and `main` refs. +- the pull-request number, state, head, base, and merge result. +- each required run ID, event, head commit, status, and conclusion. +- each required check context and GitHub App integration ID. + +The receipt must exclude tokens, identity values, local paths, private reports, +and raw security logs. + +## Command behavior + +The Go command is `scripts/publication-correction`. The command accepts these +explicit values: + +- candidate and verifier checkouts. +- phase, bootstrap, old candidate, and new candidate. +- candidate ref, pull request, ruleset, and hosted runs. +- path manifest, first receipt, and output. + +The command must use bounded timeouts for GitHub, Git, and secret-scan +commands. It must reject incomplete dependency injection in tests. + +The command must stop unless: + +- the candidate checkout is clean and uses complete history. +- the verifier checkout is clean and uses complete history. +- the verifier command and schema are tracked at the recorded verifier commit. +- the new candidate is the checked-out commit. +- the old candidate is an ancestor of the new candidate. +- the correction range is merge-free. +- the complete bootstrap delta matches the path manifest. +- object checks and secret scans pass. +- all history author and committer emails match the public owner email. +- the target repository exists and is public. +- the remote candidate ref equals the new candidate. +- the pull request matches the selected phase and remains unmerged. +- every required hosted run succeeded on the new candidate. +- the ruleset has no bypass actor and protects deletion, force pushes, and + linear history. +- the pull-request rule requires review, stale-review dismissal, last-push + approval, resolved threads, and rebase-only merges. +- strict status checks apply to branch creation. +- every ruleset check passed through its required GitHub App integration. + +The `pre-main` phase requires the open pull request and bootstrap `main`. The +`finalized` phase requires the closed pull request and corrected `main`. + +## Failure behavior + +If a check fails, return a typed error and write no receipt. Do not weaken the +check after repository creation. + +Preserve the old receipt, candidate refs, pull request, and hosted runs after a +failure. + +## Test plan + +Test these cases: + +- exact one-commit correction success. +- multiple linear correction commits. +- clean verifier commit, tree, command digest, and schema digest. +- dirty, wrong-module, or missing-artifact verifier checkout. +- moved candidate ref. +- changed path manifest. +- merge commit in the correction range. +- failed or pending hosted run. +- run for a different head commit. +- pull request with a different head. +- merged pull request. +- private or different target repository. +- missing ruleset protection or a ruleset bypass actor. +- failed provider-bound check or changed GitHub App integration. +- invalid or incomplete first receipt. +- changed public identity. +- secret-scan or object-check failure. +- existing output file. +- output path inside the checkout. +- open receipt directory on Unix. +- external-command timeout. +- deterministic redaction and schema validation. + +## Alternatives + +### Edit the first receipt + +Rejected. Editing an immutable receipt destroys its evidence value. + +### Rerun the pre-first-push command + +Rejected. The target repository now exists, and the checkout now has a remote. + +### Trust only the hosted check page + +Rejected. A passing page does not bind the local delta, identities, or final +tree. + +### Delete and recreate the repository + +Rejected. The public history and hosted evidence already exist. + +## Rollout gate + +The command and test matrix passed before the beta tag. The finalized run bound +the correction from `ed3f1fadfbc74eb0aa41ef8b90e41f403213d33d` to +`206fa8b6a1dde1d97081133e4d447c0881849922`. + +Verifier commit `6f36147f24f614cff0c7010533d864f8d9ad7628` produced the +source-bound private receipt. Its digest is +`sha256:77db44ba2bfa6f007186ace931f38444521d8a29cf48bd945e07a801eda36a9a`. +Only the redacted result belongs in public evidence. + +## Decision log + +| Date | Decision | +| --- | --- | +| 2026-08-17 | Propose a second immutable receipt for hosted candidate corrections. | +| 2026-08-17 | The repository owner accepted KEP-0002. | +| 2026-08-17 | Implement both phases and record the finalized correction receipt. | +| 2026-08-17 | Supersede the provisional receipt with source-bound verifier and complete ruleset evidence. | +| 2026-08-23 | Retarget prospective release gates to `v0.2.0-beta.1`. Preserve the 2026-08-17 receipt and ref evidence. | diff --git a/docs/KEP-0003-agent-facing-capture-workflow.md b/docs/KEP-0003-agent-facing-capture-workflow.md new file mode 100644 index 0000000..83238dc --- /dev/null +++ b/docs/KEP-0003-agent-facing-capture-workflow.md @@ -0,0 +1,246 @@ +# KEP-0003: Agent-facing capture workflow + +Status: Accepted and amended + +Decision owner: Repository owner + +Last updated: 2026-08-23 + +Target: Unreleased protocol 3 candidate. No tag is authorized. + +## Summary + +Keep the private-index publication transaction. Add an exact private-source +layer before that transaction. + +This change keeps one operational status object. It defines reviewed plan +version 3 and cumulative handoff version 2. It also adds a read-only plan +preview and explicit source modes. + +The change does not add landing, staging, merging, pushing, or index cleanup. + +## Decision + +Implement these contracts: + +1. `wip status` reports exact staged and lease classifications. +2. `wip plan` writes a bound draft that `wip capture` reads directly. +3. A lane profile binds a named commit-message policy. +4. Successful ordinary lane use renews the complete active lease set. +5. `wip handoff` returns a validated, capture-only receipt. +6. Interactive initialization recommends `worktree` mode. +7. `wip capture` requires a reviewed version 3 plan and returns its cumulative + handoff. +8. `worktree_snapshot` is the preferred agent source. +9. `staged_index` is the controlled shared-checkout exception. +10. `wip plan --observe` is byte-for-byte read-only. + +`wip commit` keeps legacy plan-array and explicit `--single` support. This +compatibility path does not weaken the reviewed `wip capture` contract. + +## Operational status + +The status object reports these disjoint or related sets: + +- `capture_candidates`: leased index entries that differ from the lane tree. +- `captured_but_still_staged`: leased staged entries that match the lane tree. +- `foreign_staged`: source staged entries outside all active leases. +- `leased_but_not_staged`: active claim scopes with no staged or pending entry. + +The object also reports lease time, renewal state, ref health, message policy, +and the latest capture-intent state. + +Status reports caller-index classes. It does not select or authorize a +`worktree_snapshot` source. + +`wip status` renews the lane by default. Use `wip status --observe` for a pure +read that does not renew a lease. + +## Reviewed plan + +`wip plan --out ` creates the file without replacement. The version 3 +draft binds: + +- lane ID, lane ref, and lane tip. +- source `HEAD`, source mode, and untracked policy. +- selected source scopes and exact source paths. +- selected private-source digest. +- active lease-scope digest. +- named message-policy receipt. +- ordered groups and optional verification commands. + +The draft contains empty `message` fields. A reviewer must add each message and +change `state` from `draft` to `reviewed`. + +`wip capture` recalculates every binding before hooks run. It passes the +reviewed source digest into the capture kernel. The kernel checks that digest +again before publication. `STALE_PLAN` reports a moved input before the +transaction. `SOURCE_MOVED` reports a source race in the kernel. + +The capture intent stores the reviewed-plan digest and policy receipt. The +version 3 intent also stores the private-source binding. The intent digest +covers all of those fields. + +`wip plan --observe` returns the same draft data without an output file. It +does not renew leases or change the Git common directory, checkout, or caller +index. + +## Message policy + +The capture kernel validates message safety only. It rejects empty subjects, +invalid UTF-8, NUL, carriage returns, unsupported controls, and oversized text. + +The default `conventional-v1` policy keeps the existing naming rules. The +optional `safety-only-v1` policy permits any message that passes kernel safety. + +A repository can select the policy in `.wip-commit.json`: + +```json +{ + "schema_version": "1.0.0", + "message_policy": "safety-only-v1" +} +``` + +`wip init --message-policy ` is an explicit override. Initialization binds +the resolved policy to the lane profile and initialization intent. + +All policy checks finish before pre-commit hooks and verification commands. + +## Lease renewal + +Authenticated `status`, `env`, `claim`, `plan`, `commit`, `capture`, and +`handoff` use the complete active lane lease set. They renew that set after +identity validation. + +`status --observe`, `env --observe`, `plan --observe`, `doctor`, and archive +preview do not renew leases. A handoff for a released lane also remains a pure +read. Expired active leases remain fail-closed and require a new claim. + +The released-lane read acquires the existing regular lane lock without +creating a directory or rewriting lock metadata. A missing or replaced lock +fails closed. + +The equivalent `--observe=true` and `-observe` forms also select pure reads. +An explicit `--observe=false` keeps normal renewal. `env` checks the lane's +canonical worktree before renewal and returns `WORKTREE_MISMATCH` from another +checkout without changing a lease. + +Every successful lane JSON envelope contains a `context` object. The context +includes the earliest expiry, remaining milliseconds, and renewal result. + +## Handoff + +The version 2 handoff validates one unique completed intent chain from the lane +base to its tip. It contains every segment, source binding, commit, message, +path set, and final tree. + +`handoff_digest` binds the complete canonical output. `review_eligible` is true +only when every segment has a reviewed-plan, message-policy, and version 3 +private-source binding. + +Chain validation, active-lease renewal, and status construction use one lane +lock. Completed intents do not bypass Git-object validation. A supplied intent +selector must name the tip segment. + +The handoff omits agent IDs, session IDs, absolute paths, remote URLs, and file +contents. It sets `capture_only` to `true` and `landing_authorized` to `false`. + +The handoff is evidence for a separate policy system. It cannot authorize a +merge, push, or target-ref update. + +## Guided capture + +Use this workflow: + +```text +wip --json status +wip --json plan \ + --source worktree_snapshot \ + --untracked forbid \ + --path \ + --out plan.json +# Review groups. Add messages. Set state to reviewed. +wip --json capture --plan plan.json +``` + +Use `--final` to release the lane after handoff validation. The command keeps +the lane lock through validation and release. It still does not land or delete +a ref. + +## Compatibility + +The state directory remains `/wip/v1/`. Lane, lease, and archive +records stay at schema version 1. + +New profiles and initialization intents use schema version 2. Readers accept +version 1 and apply the historical `conventional-v1` policy in memory. + +New captures use intent schema version 3. Readers accept intent schema versions +1 and 2 without changing their historical digest forms. + +Readers calculate a version 1 digest before they infer any new default. This +rule preserves immutable historical receipts. + +## Security review basis + +The design uses negative tests for stale and malformed inputs. It keeps stable +compatibility paths and records all security-sensitive bindings. + +These choices follow the reviewed OpenSSF secure-development guidance and NIST +SSDF practices. The Git environment review also keeps repository selection and +index behavior explicit. + +See [SECURITY-REVIEW-2026-08-18.md](SECURITY-REVIEW-2026-08-18.md). + +## Rejected alternatives + +### Add landing to capture + +Rejected. Landing owns a different ref, lock, policy, and recovery transaction. + +### Clear captured staged entries + +Rejected. An uncoordinated Git process can update the shared index concurrently. + +### Replace `git add` + +Rejected. This feature does not own source worktree staging. + +### Renew only with `wip renew` + +Rejected. Ordinary authenticated use already proves current lane ownership. + +### Make legacy arrays valid for `wip capture` + +Rejected. A legacy array does not bind source, lease, lane, or policy state. + +## Acceptance evidence + +- Focused CLI tests cover reviewed success, draft refusal, and stale refusal. +- Handoff tests verify cumulative chains, stable digests, privacy fields, and + capture-only markers. +- Status tests cover pending, captured, foreign, empty-lease, and observe states. +- Policy tests cover default, override, strict configuration, and safety-only use. +- Compatibility tests preserve version 1 profile and intent digests. +- Deterministic contention tests prove that final release and active handoff + keep the lane lock after receipt validation. +- Released-handoff tests prove that lock acquisition preserves the existing + lock bytes and does not create a missing lock or parent directory. +- Source tests prove that worktree capture preserves the caller index and + source `HEAD`. They also prove explicit untracked-file policy. +- Observe tests compare repository state before and after `plan --observe`. +- Real command fixtures validate against every published capture schema. +- Worktree tests prove that `env` fails before renewal in another checkout. +- Full race, vet, workflow, and dogfood evidence belongs in `docs/DOGFOOD.md`. + +## Decision log + +| Date | Decision | +| --- | --- | +| 2026-08-18 | Preserve the private-index and one-CAS capture kernel. | +| 2026-08-18 | Adopt original plan schema version 2 for `wip capture`. | +| 2026-08-18 | Keep landing outside the capture product. | +| 2026-08-23 | Supersede plan version 2 with private-source plan version 3. | +| 2026-08-23 | Make handoff version 2 cumulative from the lane base to its tip. | +| 2026-08-23 | Keep every handoff capture-only and require separate review authority. | diff --git a/docs/OSS-PRACTICE-GUIDE.md b/docs/OSS-PRACTICE-GUIDE.md index b68b194..037b10b 100644 --- a/docs/OSS-PRACTICE-GUIDE.md +++ b/docs/OSS-PRACTICE-GUIDE.md @@ -118,9 +118,9 @@ After a fix, add a regression test and review the same failure class elsewhere. Treat Git environment variables as part of the command input. Bind discovery, refs, worktrees, object storage, and hooks to the selected repository. -Keep the active source index explicit. Give capture hooks the private candidate -index. Verify the source `HEAD`, complete index, selected tree, and expected old -ref at the publication boundary. +Keep the source mode, untracked policy, source scopes, and source digest +explicit. Give capture hooks the private candidate index. Verify the source +`HEAD`, caller index, selected source, and expected old ref at publication. Do not use stash, reset, clean, force-update, merge, or push as a capture recovery action. diff --git a/docs/OSS-PUBLIC-BETA.md b/docs/OSS-PUBLIC-BETA.md index 19f5b1d..7d505fc 100644 --- a/docs/OSS-PUBLIC-BETA.md +++ b/docs/OSS-PUBLIC-BETA.md @@ -4,15 +4,17 @@ Plan ID: `wip-oss-public-beta` Status: Accepted -Target: `v0.1.0-beta.1` +Target: `v0.2.0-beta.1` Owner: Repository owner -Last review: 2026-08-16 +Last review: 2026-08-18 Approval: `owner-session-2026-08-16` -Local preparation: Extended safety pass complete on 2026-08-16 +Local preparation: Extended safety pass complete on 2026-08-18 + +Public source: Confirmed on 2026-08-18. No tag or GitHub release exists. ## Approved decision @@ -24,12 +26,26 @@ The owner approved a capture-only public beta with these boundaries: - Support shared checkouts and linked worktrees through the same capture transaction. - Keep branch landing, merging, pushing, and remote coordination out of scope. -- Use `v0.1.0-beta.1` only after all public-beta gates pass. +- Use `v0.2.0-beta.1` only after all public-beta gates pass. + +## Hosted state on 2026-08-17 + +The public source repository now exists at +[`nstranquist/wip-commit`](https://github.com/nstranquist/wip-commit). +Commit `206fa8b6a1dde1d97081133e4d447c0881849922` passed the hosted candidate and +final `main` checks. + +The active `main` ruleset and security settings passed the hosted setup audit. +[PUBLICATION-EVIDENCE.md](PUBLICATION-EVIDENCE.md) contains the public record. + +No beta tag or GitHub release exists. The independent beta, conduct, +security-notification, tag-approval, and tagged-install gates remain. This approval fixes the repository name, module path, and capture-only scope. -It does not approve a release tag. The project instructions require a human to -perform the first push. Follow -[PUBLICATION-HANDOFF.md](PUBLICATION-HANDOFF.md) for that exact boundary. +It does not approve a release tag. The owner separately completed the first +source publication through the first-push handoff on 2026-08-17. The historical +authority boundary remains in +[PUBLICATION-HANDOFF.md](PUBLICATION-HANDOFF.md). Do not run it again. ## Why this plan exists @@ -43,7 +59,7 @@ adding a YAML dependency. Use these status values: -- `verified`: Local evidence passed on the recorded source. +- `verified`: Recorded local or hosted evidence passed on the exact source. - `prepared`: The repository artifact exists, but hosted evidence is absent. - `planned`: Owner-controlled implementation work remains. - `human-gated`: An owner decision or external mutation is required. @@ -65,7 +81,12 @@ The owner-controlled repository work is complete. The checkout now contains: values. - no-clobber lease creation, a capture heartbeat, a final exact-set publication fence, and refusal of partially released lanes. -- read-only split proposals and a split-plan default for automation. +- one bound version 3 draft/reviewed plan schema with private-source bindings + and fail-closed stale-plan checks. +- operational status with staged-state classes and ordinary-use lease renewal. +- named message policy outside the capture kernel. +- a typed version 2 cumulative capture-only handoff and guided `wip capture` + command. - bounded `wip doctor` inspection, structural capture-receipt validation, and exact recoverable state archival. - receipt-bound archive records and recovery of a deterministic empty batch @@ -84,24 +105,29 @@ The owner-controlled repository work is complete. The checkout now contains: versions. - an exact minimum Go 1.25.12 gate that excludes reachable standard-library vulnerabilities found in Go 1.25.0. +- a source-bound, fail-closed hosted-correction command, schema, negative test + matrix, and finalized private receipt for the first corrected candidate. Two clean six-target rehearsals produced equal directory trees. Every recorded archive checksum passed, and the native archive reported the target version. -This local proof does not satisfy hosted CI, attestation, independent testing, -public installation, or publication gates. +The public base includes hosted CI evidence and active controls. This local +feature candidate lacks hosted evidence. It does not satisfy attestation, +independent testing, tagged installation, or release gates. ## Product boundary -The public beta captures exact staged subsets into agent-owned local refs. It -does not land those refs onto a shared branch. +The public beta captures exact staged-index or worktree-snapshot sources into +agent-owned local refs. It does not land those refs onto a shared branch. + +`wip init` is the onboarding entry point. It recommends one linked worktree per +task. Shared mode remains available for lanes that require one checkout. -`wip init` is the onboarding entry point. It configures a shared lane or a -linked-worktree lane. It can install the current binary only after explicit -consent, and it does not overwrite different bytes. +The wizard can install the current binary only after explicit consent. It does +not overwrite different bytes. -Both modes use path leases, private indexes, bounded hooks, durable intents, -and an exact ref compare-and-swap. Worktree mode adds worktree ownership. It -does not use a different publication algorithm. +Both modes use path leases, private sources, private indexes, bounded hooks, +durable intents, and an exact ref compare-and-swap. Worktree mode adds worktree +ownership. It does not use a different publication algorithm. The portable agent skill must use only public `wip` commands and standard Git inspection. It must not require private helpers, private paths, or an internal @@ -113,8 +139,8 @@ command. The public beta must retain these properties: 1. A successful capture leaves the source `HEAD` unchanged. -2. A successful capture leaves the complete source index unchanged. -3. An unselected staged path cannot enter an agent commit. +2. A successful capture leaves the complete caller index unchanged. +3. An unselected source path cannot enter an agent commit. 4. A failed group, hook, gate, or ref race publishes none of a split chain. 5. Reconciliation accepts only the original immutable plan evidence. 6. Two disjoint shared lanes can capture at the same time. @@ -131,7 +157,8 @@ The public beta must retain these properties: 14. Archive apply rechecks every reviewed candidate under lock and preserves all lane refs and commits. 15. A prepared archive can resume or restore by immutable receipt ID. -16. Commands other than `wip init` cannot claim an uninitialized repository. +16. Only `wip init` and an exact reviewed migration apply can claim an + uninitialized repository. 17. New lease publication cannot replace an existing lease record. A partial release blocks claim, renewal, and capture until release resumes. 18. Every durable record writer rejects bytes that its corresponding reader @@ -148,6 +175,16 @@ The public beta must retain these properties: symmetric across Unicode case pairs and component boundaries. 24. Inherited Git variables cannot redirect repository discovery, refs, object storage, or prepared hooks away from the selected canonical checkout. +25. Operational lane and lease reads use the record-replacement registry + fence, including the final durable commit receipt. +26. `wip plan --observe` changes no repository bytes and writes no plan file. +27. A handoff binds the complete base-to-tip capture chain. It never authorizes + landing. +28. Coordination migration uses one writer fence and never dual-writes both + state roots. +29. The migration manifest binds the regular lease-registry lock. Apply + publishes that lock and the review-plan and handoff directories before it + publishes imported lane and lease records. The threat model remains part of the release contract. Cooperating processes must honor leases. Hooks and `verify` commands remain trusted repository code. @@ -182,19 +219,21 @@ records the same approval reference. ### Phase 3: create the hosted candidate -Follow [PUBLICATION-HANDOFF.md](PUBLICATION-HANDOFF.md), then -[HOSTED-SETUP.md](HOSTED-SETUP.md), and retain their redacted evidence. -The exact required CI check names come from the first hosted pull request. -Do not guess them from workflow job labels. - -1. Create the public repository only after the owner authorizes it. -2. Push `main` without a release tag. -3. Enable private vulnerability reporting and security notifications. -4. Enable dependency alerts and secret scanning. -5. Protect `main` with pull requests, review, and required CI jobs. -6. Block force pushes and branch deletion. -7. Run Linux, macOS, and Windows jobs on hosted workers. -8. Approve a Code of Conduct, assign enforcement responsibility, and configure +The first source publication ran on 2026-08-17. Do not repeat its bootstrap +steps. See [PUBLICATION-HANDOFF.md](PUBLICATION-HANDOFF.md) for the historical +boundary and +[HOSTED-STATUS-2026-08-18.md](HOSTED-STATUS-2026-08-18.md) for the live check. + +Every new candidate must use the active protected pull-request path. Use the +required check names from the live ruleset. + +1. Open a reviewed candidate pull request without merging it. +2. Run Linux, macOS, Windows, race, lint, and dependency-review jobs. +3. Close the verification pull request without merging it. +4. Use a separately authorized, policy-compliant update for public `main`. +5. Verify the final public commit, tree, and hosted checks. +6. Verify the maintainer's personal security-alert notifications. +7. Approve a Code of Conduct, assign enforcement responsibility, and configure a confidential conduct-reporting path before soliciting contributions. Hosted Windows execution is mandatory. A Windows cross-build does not exercise @@ -213,7 +252,7 @@ Windows locks, process cleanup, or atomic replacement. ### Phase 5: publish the beta -1. Create an approved, signed `v0.1.0-beta.1` tag. +1. Create an approved, signed `v0.2.0-beta.1` tag. 2. Build release archives from that exact tag. 3. Publish checksums and provenance attestations with the archives. 4. Test one archive on each operating system. @@ -244,8 +283,8 @@ CGO_ENABLED=0 GOOS=darwin GOARCH=arm64 GOTOOLCHAIN=go1.25.12 GOWORK=off go test CGO_ENABLED=0 GOOS=windows GOARCH=amd64 GOTOOLCHAIN=go1.25.12 GOWORK=off go test -exec=/usr/bin/true ./... CGO_ENABLED=0 GOOS=windows GOARCH=arm64 GOTOOLCHAIN=go1.25.12 GOWORK=off go test -exec=/usr/bin/true ./... actionlint -GOTOOLCHAIN=go1.25.12 GOWORK=off go run ./scripts/release --version v0.1.0-beta.1 --out -GOTOOLCHAIN=go1.25.12 GOWORK=off go run ./scripts/release --version v0.1.0-beta.1 --out +GOTOOLCHAIN=go1.25.12 GOWORK=off go run ./scripts/release --version v0.2.0-beta.1 --out +GOTOOLCHAIN=go1.25.12 GOWORK=off go run ./scripts/release --version v0.2.0-beta.1 --out diff -rq gitleaks git --redact --exit-code 1 . gitleaks dir --redact --exit-code 1 . @@ -288,8 +327,10 @@ tag, hosted attestation, and verification sequence. for project, governance, release, and succession practices. - Use the [GitHub Open Source Guides](https://opensource.guide/) for community health and maintainer practices. -- Review the OpenSSF [Concise Guide for Developing More Secure Software](https://github.com/ossf/wg-best-practices-os-developers/blob/main/docs/Concise-Guide-for-Developing-More-Secure-Software.md) - and [Concise Guide for Evaluating Open Source Software](https://github.com/ossf/wg-best-practices-os-developers/blob/main/docs/Concise-Guide-for-Evaluating-Open-Source-Software.md). +- Review the OpenSSF [Concise Guide for Developing More Secure + Software][ossf-secure-development]. +- Review the OpenSSF [Concise Guide for Evaluating Open Source + Software][ossf-evaluation]. - Map the secure-development lifecycle to the NIST [Secure Software Development Framework](https://csrc.nist.gov/pubs/sp/800/218/final). @@ -326,3 +367,6 @@ data-loss or foreign-staged-content defect can remain. Landing remains a separate product decision. If the public contract states the boundary clearly, capture-only behavior can remain the stable scope. + +[ossf-secure-development]: https://github.com/ossf/wg-best-practices-os-developers/blob/main/docs/Concise-Guide-for-Developing-More-Secure-Software.md +[ossf-evaluation]: https://github.com/ossf/wg-best-practices-os-developers/blob/main/docs/Concise-Guide-for-Evaluating-Open-Source-Software.md diff --git a/docs/OSS-PUBLIC-BETA.requirements.yaml b/docs/OSS-PUBLIC-BETA.requirements.yaml index 64e691e..22cc30e 100644 --- a/docs/OSS-PUBLIC-BETA.requirements.yaml +++ b/docs/OSS-PUBLIC-BETA.requirements.yaml @@ -1,11 +1,11 @@ { "schema_version": 1, "plan_id": "wip-oss-public-beta", - "plan_status": "proposed", - "target_version": "v0.1.0-beta.1", - "last_reviewed": "2026-08-16", + "plan_status": "accepted", + "target_version": "v0.2.0-beta.1", + "last_reviewed": "2026-08-23", "status_definitions": { - "verified": "Local evidence passed on the recorded source.", + "verified": "Recorded local or hosted evidence passed on the exact source.", "prepared": "The repository artifact exists, but hosted evidence is absent.", "planned": "Owner-controlled implementation work remains.", "human-gated": "An owner decision or external mutation is required.", @@ -119,20 +119,24 @@ "human_gate": true, "acceptance": "The exact candidate passes Linux, macOS, Windows, race, vet, lint, module, and dependency-review jobs.", "evidence": [ - {"kind": "workflow", "value": ".github/workflows/ci.yml", "observed_on": "2026-08-14"} + {"kind": "workflow", "value": ".github/workflows/ci.yml", "observed_on": "2026-08-14"}, + {"kind": "hosted-run", "value": "https://github.com/nstranquist/wip-commit/actions/runs/31996057770 passed Linux, macOS, Windows, race, lint, and dependency review on commit 206fa8b6a1dde1d97081133e4d447c0881849922.", "observed_on": "2026-08-17"}, + {"kind": "hosted-run", "value": "https://github.com/nstranquist/wip-commit/actions/runs/31996220707 passed every main-push job that applies to commit 206fa8b6a1dde1d97081133e4d447c0881849922.", "observed_on": "2026-08-17"}, + {"kind": "hosted-run", "value": "Public main CI run 32183872589 passed Linux, macOS, Windows, race, and lint at 4cf003bebbfd9c6281578ea9ef1b679dae67078f.", "observed_on": "2026-08-18"}, + {"kind": "gap", "value": "The integrated agent-facing candidate still needs its own complete protected pull-request check set, including dependency-review.", "observed_on": "2026-08-18"} ] }, { "id": "OSS-009", "gate": "public-beta", "title": "Configure hosted repository protections", - "status": "human-gated", + "status": "verified", "owner": "repository-owner", - "human_gate": true, + "human_gate": false, "acceptance": "main requires pull requests, review, required CI, and blocks force pushes and deletion.", "evidence": [ {"kind": "prepared-runbook", "value": "docs/HOSTED-SETUP.md defines the authority boundary, ruleset sequence, observed-check-name rule, and evidence receipt.", "observed_on": "2026-08-16"}, - {"kind": "gap", "value": "No remote is configured in the local checkout.", "observed_on": "2026-08-14"} + {"kind": "hosted-setting", "value": "https://github.com/nstranquist/wip-commit/rules/20926881 is active on main with no bypass actor, rebase-only pull requests, one approval, last-push approval, six provider-bound checks, linear history, and ref protections.", "observed_on": "2026-08-17"} ] }, { @@ -145,7 +149,9 @@ "acceptance": "Private vulnerability reporting, dependency alerts, secret scanning, and security notifications are enabled.", "evidence": [ {"kind": "prepared-policy", "value": "SECURITY.md and .github/ISSUE_TEMPLATE/config.yml", "observed_on": "2026-08-14"}, - {"kind": "prepared-runbook", "value": "docs/HOSTED-SETUP.md defines the current GitHub security-setting sequence and evidence receipt.", "observed_on": "2026-08-16"} + {"kind": "prepared-runbook", "value": "docs/HOSTED-SETUP.md defines the current GitHub security-setting sequence and evidence receipt.", "observed_on": "2026-08-16"}, + {"kind": "hosted-setting", "value": "Dependency graph, Dependabot alerts, Dependabot security updates, secret scanning, push protection, and private vulnerability reporting are enabled. GitHub serves SECURITY.md on the security policy page.", "observed_on": "2026-08-17"}, + {"kind": "gap", "value": "The maintainer's personal security-alert notification setting remains unverified.", "observed_on": "2026-08-18"} ] }, { @@ -186,7 +192,9 @@ "human_gate": true, "acceptance": "A clean environment installs the tagged command through the public Go module path and runs wip version.", "evidence": [ - {"kind": "gap", "value": "The module path is not public.", "observed_on": "2026-08-14"} + {"kind": "command", "value": "A clean GOBIN installed github.com/nstranquist/wip-commit/cmd/wip@4cf003bebbfd9c6281578ea9ef1b679dae67078f through proxy.golang.org and returned wip 0.1.0-beta.1.", "observed_on": "2026-08-18"}, + {"kind": "public-install", "value": "A clean unauthenticated clone resolved commit 206fa8b6a1dde1d97081133e4d447c0881849922 and tree c0dd6638adcdc231840ad06406dc9f0caa38e45d. go install at that commit resolved the public pseudo-version and returned wip 0.1.0-beta.1.", "observed_on": "2026-08-17"}, + {"kind": "gap", "value": "No public beta tag exists, so tagged installation remains unproved.", "observed_on": "2026-08-18"} ] }, { @@ -196,9 +204,9 @@ "status": "human-gated", "owner": "repository-owner", "human_gate": true, - "acceptance": "The owner creates a signed v0.1.0-beta.1 tag only after every public-beta gate passes.", + "acceptance": "The owner creates a signed v0.2.0-beta.1 tag only after every public-beta gate passes.", "evidence": [ - {"kind": "gap", "value": "No remote or tag exists.", "observed_on": "2026-08-14"} + {"kind": "gap", "value": "The public repository exists, but no tag, GitHub release, or explicit tag approval exists.", "observed_on": "2026-08-18"} ] }, { @@ -208,10 +216,13 @@ "status": "verified", "owner": "maintainer", "human_gate": false, - "acceptance": "The project documents schema support, upgrade behavior, downgrade behavior, and fail-closed migration errors.", + "acceptance": "The project documents schema support, upgrade behavior, downgrade behavior, and fail-closed migration errors. Coordination migration uses a byte-pure preview and one digest-bound plan. It uses one writer fence and a manifest-bound registry lock. It also creates immutable review-plan and handoff directories and a sealed legacy archive. Completed migration status preserves the exact cutover receipt while reporting later live-store movement separately.", "evidence": [ {"kind": "artifact", "value": "docs/STATE-COMPATIBILITY.md and docs/ERRORS.md", "observed_on": "2026-08-14"}, - {"kind": "test", "value": "TestFutureStateDirectoryFailsBeforeV1Creation, TestUnknownVersionedStateEntryRequiresMigrationBeforeMutation, TestCoordinationDomainMarkerAndForeignDomainFailClosed, TestFutureLaneAndLeaseSchemasRequireMigration, TestFutureIntentSchemaRequiresMigration, TestFutureInitIntentSchemaRequiresMigration, and TestFutureProfileSchemaRequiresMigration", "observed_on": "2026-08-16"} + {"kind": "test", "value": "TestFutureStateDirectoryFailsBeforeV1Creation, TestUnknownVersionedStateEntryRequiresMigrationBeforeMutation, TestCoordinationDomainMarkerAndForeignDomainFailClosed, TestFutureLaneAndLeaseSchemasRequireMigration, TestFutureIntentSchemaRequiresMigration, TestFutureInitIntentSchemaRequiresMigration, and TestFutureProfileSchemaRequiresMigration", "observed_on": "2026-08-16"}, + {"kind": "test", "value": "TestPreviewIsByteForByteReadOnly, TestRegistryLockPublishesBeforeImportedRecords, TestEmptyAndPublicOnlyMigrations, TestIncompatibleTerminalHistoryIsArchiveOnlyAndCanonicalStoreReads, and the complete internal/coordmigration test package", "observed_on": "2026-08-23"}, + {"kind": "artifact", "value": "docs/OSS-SOURCE-REVIEW-2026-08-27.md", "observed_on": "2026-08-27"}, + {"kind": "test", "value": "TestCompletedMigrationStatusReportsPostCutoverAdvance, TestCompletedMigrationStatusRejectsUnsafePrivateIndexRoot, TestCompletedMigrationStatusStillRejectsEnvelopeDrift, the complete internal/coordmigration package, and its race suite", "observed_on": "2026-08-27"} ] }, { @@ -283,9 +294,10 @@ "status": "verified", "owner": "maintainer", "human_gate": false, - "acceptance": "Automation needs a reviewed split plan unless it explicitly selects one commit. The read-only planner proposes deterministic component groups and conservative Conventional Commit prefixes for staged paths that differ from the lane's current commit, without moving HEAD or the index.", + "acceptance": "Automation uses one version 3 plan from draft through capture. The plan binds the lane, ref, tip, source HEAD, source mode, and untracked policy. It also binds source scopes, exact source paths, source digest, active lease scope, and named message policy. Capture rejects draft or stale plans before hooks run. Legacy arrays remain available only through the compatibility commit command.", "evidence": [ - {"kind": "test", "value": "TestCommitRequiresSplitPlanUnlessSingleIsExplicit, TestPlanPreviewUsesComponentBoundariesWithoutMutation, and TestPlanPreviewExcludesAlreadyCapturedStagedPaths", "observed_on": "2026-08-16"} + {"kind": "test", "value": "TestCommitRequiresSplitPlanUnlessSingleIsExplicit, TestPlanPreviewUsesComponentBoundariesWithoutMutation, TestPlanPreviewExcludesAlreadyCapturedStagedPaths, TestReviewedPlanCaptureProducesBoundPrivateHandoff, and TestCaptureRejectsDraftAndStaleReviewedPlans", "observed_on": "2026-08-18"}, + {"kind": "test", "value": "TestPlanObserveIsRepositoryByteForByteReadOnly, TestWorktreePlanAndCapturePreserveCallerIndex, TestWorktreePlanRejectsUntrackedUnderForbidPolicy, and TestCaptureRejectsMovedReviewedSource", "observed_on": "2026-08-23"} ] }, { @@ -321,7 +333,8 @@ "human_gate": true, "acceptance": "Before public contributions are solicited, the owner approves a Code of Conduct, names its enforcement responsibility, and configures a confidential conduct-reporting path.", "evidence": [ - {"kind": "gap", "value": "No approved Code of Conduct or confidential conduct-reporting channel exists in this local checkout.", "observed_on": "2026-08-16"} + {"kind": "configuration", "value": "GitHub private vulnerability reporting is enabled and supplies the confidential repository channel named in SUPPORT.md and the proposed Code of Conduct.", "observed_on": "2026-08-17"}, + {"kind": "human-gate", "value": "CODE_OF_CONDUCT.md names the repository owner as moderator and adapts Contributor Covenant 3.0. Owner review and merge remain required before contributions are solicited.", "observed_on": "2026-08-17"} ] }, { @@ -345,7 +358,7 @@ "human_gate": true, "acceptance": "After a beta period, the project reviews issue and pull-request response, maintainer load, unresolved security and safety defects, real concurrent use, and a tested backup-administrator, transfer, or archival path.", "evidence": [ - {"kind": "gap", "value": "A local unpublished project has no honest community-health or succession evidence.", "observed_on": "2026-08-16"} + {"kind": "gap", "value": "A new public source candidate has no beta-period community-health or succession evidence.", "observed_on": "2026-08-17"} ] }, { @@ -355,7 +368,7 @@ "status": "verified", "owner": "maintainer", "human_gate": false, - "acceptance": "Git discovery, capture, and prepared hooks ignore inherited repository-local variables that can redirect or reinterpret the repository, worktree, common directory, configuration, namespace, replacement refs, shallow boundary, or object storage. The caller's active source index remains explicit, and hooks receive the private candidate index.", + "acceptance": "Git discovery, private-source capture, and prepared hooks ignore inherited repository-local variables. These variables cannot redirect or reinterpret the repository, worktree, common directory, configuration, namespace, refs, or object storage. The caller index is an explicit input only for staged-index mode. Worktree-source mode uses an isolated temporary source index. Hooks receive only the private candidate index.", "evidence": [ {"kind": "test", "value": "TestDiscoverIgnoresInheritedRepositoryRoutingEnvironment", "observed_on": "2026-08-16"} ] @@ -369,7 +382,7 @@ "human_gate": false, "acceptance": "The repository records authoritative open source, secure-development, evaluation, SSDF, and Git sources with reviewed revisions. A maintainer guide maps those sources to project rules, review triggers, evidence types, and accepted gaps.", "evidence": [ - {"kind": "artifact", "value": "docs/OSS-PRACTICE-GUIDE.md, docs/OSS-SOURCES.json, AGENTS.md, CONTRIBUTING.md, GOVERNANCE.md, and docs/RELEASE.md", "observed_on": "2026-08-16"} + {"kind": "artifact", "value": "docs/OSS-PRACTICE-GUIDE.md, docs/OSS-SOURCES.json, docs/SECURITY-REVIEW-2026-08-18.md, AGENTS.md, CONTRIBUTING.md, GOVERNANCE.md, and docs/RELEASE.md", "observed_on": "2026-08-18"} ] }, { @@ -391,7 +404,7 @@ "status": "verified", "owner": "maintainer", "human_gate": false, - "acceptance": "A candidate verification command does not inherit the host WIP lane, agent, session, target ref, commit object, source index, or stale candidate-tree value. It receives only the current WIP_CANDIDATE_TREE value from wip.", + "acceptance": "A candidate verification command does not inherit the host WIP lane, agent, session, target ref, commit object, caller-index selector, or stale candidate-tree value. It receives only the current WIP_CANDIDATE_TREE value from wip.", "evidence": [ {"kind": "test", "value": "TestVerificationEnvironmentDoesNotInheritCaptureIdentity and the self-hosted VERIFY_FAILED isolation receipt in docs/DOGFOOD.md", "observed_on": "2026-08-16"} ] @@ -403,9 +416,10 @@ "status": "verified", "owner": "maintainer", "human_gate": false, - "acceptance": "The beta remains capture-only. A KEP defines future exact fast-forward landing for unchecked targets, refuses checked-out targets unless a worktree-aware adapter owns them, and requires recovery, privacy, lock, backup-ref, and receipt gates before implementation.", + "acceptance": "The beta remains capture-only. The standalone command does not implement landing. A KEP requires a separate landing authority. That authority binds one immutable cumulative handoff, one queue entry, and one exact review digest. It also binds a target lock, a backup ref, and one target compare-and-swap.", "evidence": [ - {"kind": "artifact", "value": "docs/KEP-0001-capture-to-landing-boundary.md", "observed_on": "2026-08-16"} + {"kind": "artifact", "value": "docs/KEP-0001-capture-to-landing-boundary.md", "observed_on": "2026-08-16"}, + {"kind": "artifact", "value": "The 2026-08-23 KEP amendment supersedes standalone landing and retains only the external adapter requirements.", "observed_on": "2026-08-23"} ] }, { @@ -415,10 +429,11 @@ "status": "verified", "owner": "repository-owner", "human_gate": false, - "acceptance": "A source-current, fail-closed preflight binds a clean final candidate to the reviewed bootstrap, a merge-free linear split-commit range, the complete reviewed path delta, zero remotes and tags, owner approval, public author and committer identities, absent target repository, complete non-replaced history, passing object integrity, and passing history and worktree secret scans. It writes a no-overwrite private receipt outside the checkout. A human-only runbook preserves the exact candidate while obtaining hosted checks without merging a pull request.", + "acceptance": "A source-current, fail-closed preflight binds a clean pre-first-push candidate to the reviewed bootstrap, a merge-free linear split-commit range, the complete reviewed path delta, zero remotes and tags, owner approval, public author and committer identities, absent target repository, complete non-replaced history, passing object integrity, and passing history and worktree secret scans. It writes a no-overwrite private receipt outside the checkout. A human-only runbook preserves the exact candidate while obtaining hosted checks without merging a pull request.", "evidence": [ {"kind": "artifact", "value": "scripts/publication-handoff, docs/PUBLICATION-HANDOFF.md, docs/PUBLICATION-HANDOFF.paths, and docs/PUBLICATION-HANDOFF.schema.json", "observed_on": "2026-08-16"}, - {"kind": "gap", "value": "The project instructions prohibit an agent push. Human execution and hosted evidence remain required.", "observed_on": "2026-08-16"} + {"kind": "receipt", "value": "The validated private pre-first-push receipt bound commit ed3f1fadfbc74eb0aa41ef8b90e41f403213d33d, tree 674a65c74d55a08b3f8d560700de1430ade99942, the reviewed bootstrap, and the then-current 17-path manifest before repository creation.", "observed_on": "2026-08-17"}, + {"kind": "hosted-state", "value": "The first source publication completed without a pull-request merge; the public repository and protected main now exist.", "observed_on": "2026-08-18"} ] }, { @@ -434,6 +449,35 @@ {"kind": "artifact", "value": "go.mod requires Go 1.25.12; docs/RELEASE.md and docs/OSS-PRACTICE-GUIDE.md require exact-minimum verification.", "observed_on": "2026-08-16"}, {"kind": "command", "value": "GOTOOLCHAIN=go1.25.12 GOWORK=off go run golang.org/x/vuln/cmd/govulncheck@v1.7.0 ./...", "observed_on": "2026-08-16"} ] + }, + { + "id": "OSS-034", + "gate": "public-beta", + "title": "Bind hosted candidate corrections", + "status": "verified", + "owner": "maintainer", + "human_gate": false, + "acceptance": "A fail-closed Go command binds each post-first-push correction to the old and new candidates, exact verifier source, complete path manifest, local checks, remote candidate and main refs, unmerged pull request, required hosted runs, provider-bound checks, complete no-bypass ruleset controls, and final tree in one immutable private receipt. The pre-main phase verifies the state before main moves. The finalized phase records an observed completed bootstrap sequence without claiming earlier receipt creation.", + "evidence": [ + {"kind": "artifact", "value": "scripts/publication-correction, docs/PUBLICATION-CORRECTION.md, docs/PUBLICATION-CORRECTION.schema.json, and accepted KEP-0002 implement the typed no-overwrite correction contract.", "observed_on": "2026-08-17"}, + {"kind": "test", "value": "The correction matrix covers both success phases, exact clean verifier provenance, multiple linear commits, manifest drift, merge commits, object corruption, identity drift, remote and pull-request mismatch, run and check failure, each required ruleset control, secret scans, timeouts, unsafe output, no-overwrite behavior, redaction, deterministic encoding, and schema shape.", "observed_on": "2026-08-17"}, + {"kind": "receipt", "value": "The validated finalized private receipt bound verifier commit 6f36147f24f614cff0c7010533d864f8d9ad7628, candidate correction ed3f1fadfbc74eb0aa41ef8b90e41f403213d33d to 206fa8b6a1dde1d97081133e4d447c0881849922, tree c0dd6638adcdc231840ad06406dc9f0caa38e45d, 20 bootstrap paths, 5 correction paths, 4 hosted runs, 6 required checks, the complete no-bypass ruleset contract, and GitHub Actions integration 15368. Its SHA-256 digest is 77db44ba2bfa6f007186ace931f38444521d8a29cf48bd945e07a801eda36a9a.", "observed_on": "2026-08-17"} + ] + }, + { + "id": "OSS-035", + "gate": "public-beta", + "title": "Complete the agent-facing capture workflow", + "status": "verified", + "owner": "maintainer", + "human_gate": false, + "acceptance": "Status classifies leased, captured, pending, and foreign staged entries. Worktree snapshots are the default agent source, and staged-index capture is the controlled shared-checkout exception. Plan version 3 binds the complete private source. Plan observe is byte-pure. Guided capture returns a digest-bound, cumulative version 2 handoff that never authorizes landing. Final capture can release only after handoff validation.", + "evidence": [ + {"kind": "artifact", "value": "docs/KEP-0003-agent-facing-capture-workflow.md, docs/PLAN.schema.json, docs/HANDOFF.schema.json, and docs/SECURITY-REVIEW-2026-08-18.md", "observed_on": "2026-08-18"}, + {"kind": "test", "value": "TestStatusClassifiesCaptureStateAndForeignIndexEntries, TestMessagePolicyIsBoundOutsideCaptureKernel, TestReviewedPlanCaptureProducesBoundPrivateHandoff, TestCaptureRejectsDraftAndStaleReviewedPlans, and TestGuidedCaptureFinalReleasesAfterHandoffValidation", "observed_on": "2026-08-18"}, + {"kind": "artifact", "value": "The 2026-08-23 KEP-0003 amendment, PLAN.schema.json, HANDOFF.schema.json, ARCHITECTURE.md, and THREAT-MODEL.md define protocol 3 private sources and cumulative handoff version 2.", "observed_on": "2026-08-23"}, + {"kind": "test", "value": "TestCumulativeHandoffCoversEveryReviewedCaptureFromLaneBaseToTip, TestPlanObserveIsRepositoryByteForByteReadOnly, TestWorktreePlanAndCapturePreserveCallerIndex, and TestCaptureRejectsDraftAndStaleReviewedPlans", "observed_on": "2026-08-23"} + ] } ] } diff --git a/docs/OSS-READINESS.md b/docs/OSS-READINESS.md index e84a4cb..892c1c5 100644 --- a/docs/OSS-READINESS.md +++ b/docs/OSS-READINESS.md @@ -2,15 +2,22 @@ ## Current decision -The project is a strong candidate for its own public repository. It is locally -publish-ready for a `v0.1.0-beta.1` candidate. It is not publicly launched, and -the local evidence does not support a stable `v1.0.0` claim. +The project has a public source repository with active hosted controls. This +repository's historical source candidates have passing hosted checks. The +agent-facing candidate is locally publish-ready, but it has not passed its own +protected hosted checks. No public beta tag or GitHub release exists. The +evidence does not support a released, launched, adopted, or stable claim. The detailed release decision and current evidence are in [OSS-PUBLIC-BETA.md](OSS-PUBLIC-BETA.md) and -[OSS-PUBLIC-BETA.requirements.yaml](OSS-PUBLIC-BETA.requirements.yaml). The plan -is accepted. The approval fixes the name, module path, and capture-only scope. -It does not authorize an agent push or a release tag. +[OSS-PUBLIC-BETA.requirements.yaml](OSS-PUBLIC-BETA.requirements.yaml). Public +execution evidence is in [PUBLICATION-EVIDENCE.md](PUBLICATION-EVIDENCE.md). + +The plan is accepted. The approval fixes the name, module path, and +capture-only scope. It does not authorize a release tag. + +The live public-source and hosted-control check is in +[HOSTED-STATUS-2026-08-18.md](HOSTED-STATUS-2026-08-18.md). ## Ready in this checkout @@ -25,8 +32,16 @@ It does not authorize an agent push or a release tag. - One coordination-domain interlock for standalone and legacy installations. - Explicit initialization ownership. Probes and other lane commands cannot claim an uninitialized repository. -- Exact staged-subset and all-or-nothing split capture. -- Read-only component split proposals and split-plan automation defaults. +- Exact staged-index and worktree-source capture with all-or-nothing split + publication. +- One bound version 3 draft/reviewed capture-plan schema with no-overwrite + output. +- Stale-plan checks for source mode, source digest, lane, paths, leases, and + message policy. +- Operational status with capture, captured-staged, foreign, and empty-lease + classes and a strict public JSON Schema. +- Ordinary-use lease renewal with pure `--observe` status, environment, and + plan reads. - Automatic lease heartbeat and an exact final publication fence. - Random no-clobber lease creation and fail-closed partial-release recovery. - Exact init-claim repair and complete-registry renewal and release checks. @@ -34,7 +49,13 @@ It does not authorize an agent push or a release tag. - Bounded read-only state diagnosis. - Exact-plan, receipt-based archive, resume, and restore operations that preserve refs and commits. -- Strict JSON and Conventional Commit policy. +- Strict JSON and named message policies outside the capture kernel. +- A privacy-bounded version 2 cumulative handoff with an exact digest and + explicit non-authorization. +- A guided `wip capture` path that requires a reviewed version 3 plan. +- A digest-bound coordination migration with a single-writer cutover, a + manifest-bound registry lock, a sealed legacy archive, and immutable + review-plan and handoff directories. - Threat model, architecture, error guide, security policy, and contribution guide. - Honest single-maintainer governance, succession expectations, and beta @@ -58,12 +79,23 @@ It does not authorize an agent push or a release tag. - Deterministic six-target archives, checksums, and release receipt. - Tag-only artifact-attestation workflow with immutable action references. - State compatibility, upgrade, and downgrade policy. -- A proposed capture-to-landing KEP that keeps the beta capture-only and - defines fail-closed requirements for any future landing command. +- An amended capture-to-landing KEP that keeps the beta capture-only and + defines fail-closed requirements for a separate landing authority. +- An accepted and amended agent-facing workflow KEP with plan version 3, + cumulative handoff version 2, and historical receipt compatibility. - A redacted independent beta exercise protocol and machine-checkable receipt schema. - A human-gated hosted-repository setup and evidence runbook. - A fail-closed pre-first-push receipt and exact human publication handoff. +- Passing hosted Linux, macOS, Windows, race, lint, and dependency-review + checks on the exact public source candidate. +- An active no-bypass `main` ruleset with rebase-only pull requests, review, + provider-bound checks, linear history, and ref protections. +- Enabled dependency alerts, security updates, secret scanning, push + protection, and private vulnerability reporting. +- A clean public-module installation smoke test for the exact untagged commit. +- An accepted hosted-correction KEP, source-bound fail-closed command, schema, + test matrix, and finalized private receipt for the first hosted correction. - Fail-closed tests for unsupported state directories and record schemas. - Symlink-escape and dual-domain creation-race tests. - Concurrent first-use directory and no-clobber publication tests. @@ -73,25 +105,22 @@ It does not authorize an agent push or a release tag. - Canonical Git repository and object-store binding despite inherited routing environment variables. -## Required before public beta publication +## Required before the public beta tag -1. Follow [PUBLICATION-HANDOFF.md](PUBLICATION-HANDOFF.md). Create the public - repository and add a remote. The reviewed candidate checkout currently - has no remote. -2. Run the prepared CI on hosted Linux, macOS, and Windows workers. Local cross - compilation is not a substitute for Windows runtime tests. -3. Follow [HOSTED-SETUP.md](HOSTED-SETUP.md) to require pull-request review and - the observed passing CI checks on the default branch. -4. Enable private vulnerability reporting, dependency alerts, and secret - scanning as described in the hosted setup runbook. -5. Approve a Code of Conduct and configure confidential conduct reporting +1. Run the exact agent-facing candidate through the protected pull-request + path. Require hosted Linux, macOS, Windows, race, lint, and dependency-review + checks. Local cross-compilation is not a Windows runtime test. +2. Verify the maintainer's personal security-alert notifications. +3. Approve a Code of Conduct and configure confidential conduct reporting before soliciting public contributions. -6. Ask at least one independent user to follow +4. Ask at least one independent user to follow [BETA-EXERCISE.md](BETA-EXERCISE.md) for shared and worktree flows. Retain a redacted receipt that passes [BETA-EXERCISE.schema.json](BETA-EXERCISE.schema.json). -7. Run a clean public-module installation smoke test. -8. Create and push `v0.1.0-beta.1` only after every tracked public-beta gate +5. Obtain explicit owner approval for `v0.2.0-beta.1`. +6. Create and push the signed tag only after every tracked public-beta gate passes. Check that the hosted release attestation succeeds. +7. Verify the published archives and checksums. Install the final tag through + the public Go module path. ## Required before a stable release @@ -110,7 +139,8 @@ It does not authorize an agent push or a release tag. ## Publication boundary -The owner approved the public target and capture-only scope. A remote, history -push, repository setting, and release are still external changes. The project -instructions assign the first push to a human. Preparing this checkout does not -perform those actions. +The source repository, history, ruleset, and hosted security settings are +public, and the active ruleset requires reviewed pull requests for later `main` +updates. No tag, release, announcement, or adoption evidence exists. Do not +infer those states from public source availability. This local candidate does +not authorize a push or any hosted-state change. diff --git a/docs/OSS-SOURCE-REVIEW-2026-08-27.md b/docs/OSS-SOURCE-REVIEW-2026-08-27.md new file mode 100644 index 0000000..847034b --- /dev/null +++ b/docs/OSS-SOURCE-REVIEW-2026-08-27.md @@ -0,0 +1,45 @@ +# Official source review: completed migration status + +Date: 2026-08-27 + +## Decision + +A completed coordination migration is historical cutover evidence. It must not +freeze the two live coordination stores. Migration status must report a later +live-store manifest without weakening exact checks before completion or exact +checks for immutable migration evidence. + +## Sources + +- OpenSSF Concise Guide for Developing More Secure Software, main revision + `eb54fd9f4264bebab64586d92dffc914fbe8c896`. The applicable rule requires + automated negative tests and review before a change is accepted. +- NIST SP 800-218 version 1.1, February 2022. Practices PW.8.2, PS.3.1, and + PS.3.2 require repeatable security testing and protected integrity and + provenance evidence. +- Pro Git, second edition, environment variables chapter, reviewed with Git + 2.55.0. `GIT_DIR`, `GIT_WORK_TREE`, `GIT_INDEX_FILE`, and object-directory + variables can change repository behavior. The selected Git common directory + and private-index root must remain explicit. + +## Requirements and evidence + +- A status read before migration completion still requires the exact reviewed + canonical manifest. +- A completed status checks the immutable plan, journal, receipt, sealed + archive, domain marker, and static migration envelope. +- A completed status reports the current canonical manifest separately from + the cutover receipt. +- The status reader does not enumerate transient private-index contents. It + rejects an unsafe private-index root. +- `OSS-015` tracks the affected stable gate. +- The full `internal/coordmigration` package, its race suite, and `go vet + ./...` passed on 2026-08-27. + +## Accepted gaps + +- The completed status does not check every current lane, lease, intent, or + queue record. `wip --json doctor` remains the bounded current-state + validator. Owner: maintainer. +- This local review does not replace the independent security review required + by `OSS-016`. Owner: independent reviewer. diff --git a/docs/OSS-SOURCES.json b/docs/OSS-SOURCES.json index 6950c54..ce0e809 100644 --- a/docs/OSS-SOURCES.json +++ b/docs/OSS-SOURCES.json @@ -1,6 +1,6 @@ { "schema_version": 1, - "reviewed_on": "2026-08-16", + "reviewed_on": "2026-08-27", "sources": [ { "id": "producing-open-source-software", @@ -35,7 +35,7 @@ "authority": "official-guide", "url": "https://github.com/ossf/wg-best-practices-os-developers/blob/main/docs/Concise-Guide-for-Developing-More-Secure-Software.md", "repository_url": "https://github.com/ossf/wg-best-practices-os-developers", - "reviewed_revision": "429544ce24fa3351c193190ef563377f61ce8aa3", + "reviewed_revision": "eb54fd9f4264bebab64586d92dffc914fbe8c896, reviewed 2026-08-27", "use_for": [ "secure development controls", "dependency and vulnerability practices", @@ -62,7 +62,7 @@ "title": "NIST Secure Software Development Framework", "authority": "government-standard", "url": "https://csrc.nist.gov/pubs/sp/800/218/final", - "reviewed_revision": "NIST SP 800-218", + "reviewed_revision": "NIST SP 800-218 v1.1, February 2022, reviewed 2026-08-27", "use_for": [ "security requirements", "toolchain and provenance protection", @@ -75,7 +75,7 @@ "title": "Pro Git: Environment Variables", "authority": "official-git-book", "url": "https://git-scm.com/book/en/v2/Git-Internals-Environment-Variables", - "reviewed_revision": "online second edition, reviewed 2026-08-16", + "reviewed_revision": "online second edition, reviewed 2026-08-27 with Git 2.55.0", "use_for": [ "repository and worktree selection", "index and object-store behavior", diff --git a/docs/PLAN.legacy-v1.schema.json b/docs/PLAN.legacy-v1.schema.json new file mode 100644 index 0000000..3b2f287 --- /dev/null +++ b/docs/PLAN.legacy-v1.schema.json @@ -0,0 +1,37 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://github.com/nstranquist/wip-commit/blob/main/docs/PLAN.legacy-v1.schema.json", + "title": "wip legacy commit plan", + "type": "array", + "minItems": 1, + "maxItems": 128, + "items": { + "type": "object", + "additionalProperties": false, + "required": ["message", "files"], + "properties": { + "message": {"type": "string", "minLength": 1}, + "files": { + "type": "array", + "minItems": 1, + "maxItems": 10000, + "uniqueItems": true, + "items": {"type": "string", "minLength": 1} + }, + "verify": { + "type": "array", + "maxItems": 64, + "items": { + "type": "object", + "additionalProperties": false, + "required": ["argv"], + "properties": { + "argv": {"type": "array", "minItems": 1, "maxItems": 256, "items": {"type": "string"}}, + "directory": {"type": "string"}, + "timeout_ms": {"type": "integer", "minimum": 0, "maximum": 86400000} + } + } + } + } + } +} diff --git a/docs/PLAN.schema.json b/docs/PLAN.schema.json index 64ccad6..eeed92c 100644 --- a/docs/PLAN.schema.json +++ b/docs/PLAN.schema.json @@ -1,52 +1,137 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://github.com/nstranquist/wip-commit/blob/main/docs/PLAN.schema.json", - "title": "wip split commit plan", - "type": "array", - "minItems": 1, - "maxItems": 128, - "items": { - "type": "object", - "additionalProperties": false, - "required": ["message", "files"], - "properties": { - "message": { - "type": "string", - "minLength": 1 - }, - "files": { - "type": "array", - "minItems": 1, - "maxItems": 10000, - "uniqueItems": true, - "items": { - "type": "string", - "minLength": 1 - } - }, - "verify": { - "type": "array", - "maxItems": 64, - "items": { - "type": "object", - "additionalProperties": false, - "required": ["argv"], - "properties": { - "argv": { - "type": "array", - "minItems": 1, - "maxItems": 256, - "items": {"type": "string"} - }, - "directory": {"type": "string"}, - "timeout_ms": { - "type": "integer", - "minimum": 0, - "maximum": 86400000 + "title": "wip reviewed private-source capture plan v3", + "type": "object", + "additionalProperties": false, + "required": [ + "schema_version", + "state", + "lane", + "agent", + "session", + "target_ref", + "lane_tip", + "source_head", + "source_mode", + "untracked_policy", + "source_digest", + "source_scopes", + "lease_digest", + "message_policy", + "source_paths", + "groups", + "instruction" + ], + "properties": { + "schema_version": {"const": "3.0.0"}, + "state": {"enum": ["draft", "reviewed"]}, + "lane": {"$ref": "#/$defs/identifier"}, + "agent": {"$ref": "#/$defs/identifier"}, + "session": {"$ref": "#/$defs/identifier"}, + "target_ref": {"type": "string", "pattern": "^refs/heads/wip/[^/]+/[^/]+$"}, + "lane_tip": {"$ref": "#/$defs/object_id"}, + "source_head": {"$ref": "#/$defs/object_id"}, + "source_mode": {"enum": ["staged_index", "worktree_snapshot"]}, + "untracked_policy": {"enum": ["not_applicable", "forbid", "include"]}, + "source_digest": {"$ref": "#/$defs/digest"}, + "source_scopes": {"$ref": "#/$defs/paths"}, + "lease_digest": {"$ref": "#/$defs/digest"}, + "message_policy": {"$ref": "#/$defs/message_policy"}, + "source_paths": {"$ref": "#/$defs/paths"}, + "groups": { + "type": "array", + "minItems": 1, + "maxItems": 128, + "items": {"$ref": "#/$defs/group"} + }, + "instruction": {"type": "string", "minLength": 1} + }, + "allOf": [ + { + "if": {"properties": {"state": {"const": "reviewed"}}, "required": ["state"]}, + "then": { + "properties": { + "groups": { + "items": { + "allOf": [ + {"$ref": "#/$defs/group"}, + {"properties": {"message": {"minLength": 1}}} + ] } } } } + }, + { + "if": {"properties": {"source_mode": {"const": "staged_index"}}, "required": ["source_mode"]}, + "then": {"properties": {"untracked_policy": {"const": "not_applicable"}}} + }, + { + "if": {"properties": {"source_mode": {"const": "worktree_snapshot"}}, "required": ["source_mode"]}, + "then": {"properties": {"untracked_policy": {"enum": ["forbid", "include"]}}} + } + ], + "$defs": { + "identifier": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$"}, + "object_id": {"type": "string", "pattern": "^(?:[0-9a-f]{40}|[0-9a-f]{64})$"}, + "digest": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"}, + "paths": { + "type": "array", + "minItems": 1, + "maxItems": 10000, + "uniqueItems": true, + "items": {"type": "string", "minLength": 1} + }, + "message_policy": { + "type": "object", + "additionalProperties": false, + "required": ["id", "version", "digest"], + "properties": { + "id": {"enum": ["conventional-v1", "safety-only-v1"]}, + "version": {"const": "1.0.0"}, + "digest": {"$ref": "#/$defs/digest"} + } + }, + "group": { + "type": "object", + "additionalProperties": false, + "required": ["key", "suggested_scope", "suggested_prefix", "rationale", "message", "files"], + "properties": { + "key": {"type": "string", "minLength": 1}, + "suggested_scope": {"type": "string", "minLength": 1}, + "suggested_prefix": {"type": "string", "minLength": 1}, + "rationale": {"type": "string", "minLength": 1}, + "message": {"type": "string"}, + "files": {"$ref": "#/$defs/paths"}, + "verify": { + "type": "array", + "maxItems": 64, + "items": {"$ref": "#/$defs/verify"} + } + } + }, + "verify": { + "type": "object", + "additionalProperties": false, + "required": ["argv"], + "properties": { + "argv": { + "type": "array", + "minItems": 1, + "maxItems": 256, + "items": {"type": "string"} + }, + "directory": {"type": "string"}, + "materialize": { + "type": "array", + "minItems": 1, + "maxItems": 256, + "uniqueItems": true, + "items": {"type": "string", "minLength": 1} + }, + "timeout_ms": {"type": "integer", "minimum": 0, "maximum": 86400000} + } } } } diff --git a/docs/PUBLICATION-CORRECTION.md b/docs/PUBLICATION-CORRECTION.md new file mode 100644 index 0000000..e2c1a38 --- /dev/null +++ b/docs/PUBLICATION-CORRECTION.md @@ -0,0 +1,178 @@ +# Hosted candidate correction receipt + +When hosted checks require a candidate change after the first public push, +use this procedure. + +The command reads local and GitHub evidence. It writes one new private receipt. +It does not change a repository, ref, pull request, run, tag, or release. + +This procedure does not authorize a tag or a pull-request merge. + +## Receipt phases + +Before `main` moves, use `--phase pre-main`. This phase requires these states: + +- Remote `main` equals the reviewed bootstrap. +- The verification pull request is open and unmerged. +- The run list contains a successful candidate push. +- The run list contains one successful candidate pull-request run. + +Use `--phase finalized` to verify a completed bootstrap sequence. This phase +requires these states: + +- Remote `main` equals the corrected candidate. +- The verification pull request is closed and unmerged. +- The run list contains a successful candidate push. +- The run list contains one successful candidate pull-request run. +- The run list contains a successful `main` push. + +The finalized phase records observed history. It does not claim that the +receipt existed before `main` moved. + +## Evidence contract + +The command verifies these local facts: + +- The verifier checkout is clean, complete, and free of replacement refs. +- The receipt binds the verifier commit, tree, command digest, and schema digest. +- The candidate checkout is clean and uses complete history. +- The checked-out commit equals `--candidate`. +- No Git replacement ref changes the history. +- `git fsck --strict --no-dangling` passes. +- The old candidate is an ancestor of the new candidate. +- Every correction commit has one exact parent. +- The complete bootstrap delta matches `--paths-file`. +- Full-history and worktree secret scans pass. +- Every author and committer email matches the public owner email. + +The receipt binds a digest of every distinct author and committer name and +email. It does not include those values. + +GitHub display names are not identity credentials. The receipt records the +display-name match as a separate Boolean result. + +The command verifies these hosted facts: + +- The authenticated GitHub viewer is the repository owner. +- The target repository is public and uses `main` as its default branch. +- The remote candidate and `main` refs match the selected phase. +- The pull request has the required head, base, state, and merge result. +- Every declared hosted run completed successfully on the candidate commit. +- The selected ruleset has no bypass actor and protects the default branch. +- The ruleset blocks deletion and force pushes, and it requires linear history. +- Pull requests require review, last-push approval, and resolved review threads. +- The ruleset dismisses stale reviews and permits rebase merges only. +- Strict required checks apply to branch creation. +- Every ruleset check passed in the declared pull-request run. +- Every check came from the ruleset's GitHub App integration. + +## Private output preparation + +Create a private directory outside the candidate and verifier checkouts. On +Unix, set mode `0700` on the directory. + +```text +mkdir -p ../wip-commit-private-receipts +chmod 700 ../wip-commit-private-receipts +``` + +Make sure that the output file does not exist. The command never overwrites a +file. + +## Finalized verification command + +Run the command source from a clean, reviewed verifier checkout. Set +`--repo-dir` to a clean checkout of the exact candidate. + +The command below records the 2026-08-17 correction. Its +`candidate/v0.1.0-beta.1` ref is historical evidence. The current release +target is `v0.2.0-beta.1`. + +```text +go run ./scripts/publication-correction \ + --verifier-dir . \ + --repo-dir ../wip-commit-correction-source \ + --target nstranquist/wip-commit \ + --phase finalized \ + --bootstrap b276204385636c5a8ac338491565bd4894255217 \ + --old-candidate ed3f1fadfbc74eb0aa41ef8b90e41f403213d33d \ + --candidate 206fa8b6a1dde1d97081133e4d447c0881849922 \ + --candidate-ref candidate/v0.1.0-beta.1 \ + --first-receipt ../wip-commit-private-receipts/pre-first-push-ed3f1fa-authorized.json \ + --paths-file docs/PUBLICATION-HANDOFF.paths \ + --pull-request 1 \ + --ruleset 20926881 \ + --run candidate-push:push:candidate/v0.1.0-beta.1:31996054315 \ + --run verification-pr:pull_request:candidate/v0.1.0-beta.1:31996057770 \ + --run main-push:push:main:31996220707 \ + --run dependency-graph:dynamic:main:31996222126 \ + --out ../wip-commit-private-receipts/hosted-correction-206fa8b-v2.json +``` + +Each `--run` value uses `LABEL:EVENT:BRANCH:ID`. Labels and run IDs must be +unique. + +## Schema validation + +Verify the private receipt against +[PUBLICATION-CORRECTION.schema.json](PUBLICATION-CORRECTION.schema.json). + +```text +python3 -c 'import json,jsonschema; schema=json.load(open("docs/PUBLICATION-CORRECTION.schema.json")); receipt=json.load(open("../wip-commit-private-receipts/hosted-correction-206fa8b-v2.json")); jsonschema.Draft202012Validator.check_schema(schema); jsonschema.Draft202012Validator(schema,format_checker=jsonschema.FormatChecker()).validate(receipt)' +``` + +Keep the receipt outside the repository. Do not publish the receipt, email +addresses, local paths, private reports, tokens, or raw scan output. + +## Failure recovery + +If the command fails, preserve every input and fix the typed finding. Use a new +output path for the next complete run. + +| Code | Required recovery | +| --- | --- | +| `VERIFIER_INVALID` | Use a clean, complete checkout that contains the tracked command and schema. | +| `CHECKOUT_NOT_CLEAN` | Use a clean checkout of the exact candidate. | +| `CANDIDATE_MISMATCH` | Check `HEAD` and all three explicit commit IDs. | +| `CORRECTION_NOT_LINEAR` | Use a merge-free descendant or create a new candidate branch. | +| `PATH_MANIFEST_MISMATCH` | Review the complete bootstrap delta and update the manifest through review. | +| `OBJECT_CHECK_FAILED` | Preserve the checkout and repair the Git object store. | +| `SECRET_SCAN_FAILED` | Remove the finding from the complete history and worktree. | +| `IDENTITY_MISMATCH` | Correct the public email or rebuild the candidate with the approved identity. | +| `REMOTE_REF_MISMATCH` | Check the candidate phase and remote refs. Do not force-push. | +| `PULL_REQUEST_MISMATCH` | Restore the required unmerged pull-request state or select the correct phase. | +| `HOSTED_RUN_FAILED` | Run every required workflow on the exact candidate. | +| `HOSTED_RUN_INCOMPLETE` | Add the missing candidate, pull-request, or `main` run. | +| `RULESET_MISMATCH` | Restore active default-branch protection before another run. | +| `REQUIRED_CHECK_FAILED` | Run the provider-bound check on the exact pull-request head. | +| `COMMAND_TIMEOUT` | Inspect the external service, then rerun the complete command. | +| `OUTPUT_UNSAFE` | Select a private `0700` directory outside both checkouts. | +| `OUTPUT_EXISTS` | Preserve the existing file and select a new output name. | + +The command writes no receipt after a failed check. + +## Recorded correction + +The finalized run on 2026-08-17 bound these public facts: + +- Old candidate: `ed3f1fadfbc74eb0aa41ef8b90e41f403213d33d`. +- New candidate: `206fa8b6a1dde1d97081133e4d447c0881849922`. +- New tree: `c0dd6638adcdc231840ad06406dc9f0caa38e45d`. +- Verifier commit: `6f36147f24f614cff0c7010533d864f8d9ad7628`. +- Verifier tree: `e9559e5fc7fa7083e471acb7d9e72e10b9c3110a`. +- Verifier command digest: + `sha256:85a645b26c37a0033de22d3e3b6731d0d953e8ba0a2e7f634f1f8820f843087d`. +- Verifier schema digest: + `sha256:f8873f01997118f7d6d57bfa9f95b68ce0febab64c79dbd727de9ddb0649c7ac`. +- Correction commits: `1`. +- Complete bootstrap delta paths: `20`. +- Correction delta paths: `5`. +- Hosted runs: `4`. +- Provider-bound checks: `6`. +- GitHub Actions integration: `15368`. +- The active ruleset had no bypass actor and matched every required control. +- Private receipt digest: + `sha256:77db44ba2bfa6f007186ace931f38444521d8a29cf48bd945e07a801eda36a9a`. + +The private receipt passed the Draft 2020-12 schema. It contains no email +address, local path, token, private report, or raw security log. diff --git a/docs/PUBLICATION-CORRECTION.schema.json b/docs/PUBLICATION-CORRECTION.schema.json new file mode 100644 index 0000000..59a295a --- /dev/null +++ b/docs/PUBLICATION-CORRECTION.schema.json @@ -0,0 +1,323 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://github.com/nstranquist/wip-commit/blob/main/docs/PUBLICATION-CORRECTION.schema.json", + "title": "wip-commit hosted candidate correction receipt", + "type": "object", + "additionalProperties": false, + "required": [ + "schema_version", + "generated_at", + "target_repository", + "phase", + "verifier", + "bootstrap", + "first_receipt", + "correction", + "local", + "identity", + "repository", + "remote", + "pull_request", + "hosted_runs", + "ruleset", + "required_checks" + ], + "properties": { + "schema_version": {"const": "1.0.0"}, + "generated_at": {"$ref": "#/$defs/timestamp"}, + "target_repository": {"$ref": "#/$defs/repository_name"}, + "phase": {"enum": ["pre-main", "finalized"]}, + "verifier": { + "type": "object", + "additionalProperties": false, + "required": [ + "commit", + "tree", + "command_path", + "command_digest", + "schema_path", + "schema_digest", + "clean", + "complete_history", + "replacement_ref_count", + "object_integrity_check" + ], + "properties": { + "commit": {"$ref": "#/$defs/object_id"}, + "tree": {"$ref": "#/$defs/object_id"}, + "command_path": {"const": "scripts/publication-correction/main.go"}, + "command_digest": {"$ref": "#/$defs/digest"}, + "schema_path": {"const": "docs/PUBLICATION-CORRECTION.schema.json"}, + "schema_digest": {"$ref": "#/$defs/digest"}, + "clean": {"const": true}, + "complete_history": {"const": true}, + "replacement_ref_count": {"const": 0}, + "object_integrity_check": {"const": "passed"} + } + }, + "bootstrap": {"$ref": "#/$defs/object"}, + "first_receipt": { + "type": "object", + "additionalProperties": false, + "required": [ + "schema_version", + "digest", + "bootstrap_commit", + "bootstrap_tree", + "candidate_commit", + "candidate_tree" + ], + "properties": { + "schema_version": {"const": "1.0.0"}, + "digest": {"$ref": "#/$defs/digest"}, + "bootstrap_commit": {"$ref": "#/$defs/object_id"}, + "bootstrap_tree": {"$ref": "#/$defs/object_id"}, + "candidate_commit": {"$ref": "#/$defs/object_id"}, + "candidate_tree": {"$ref": "#/$defs/object_id"} + } + }, + "correction": { + "type": "object", + "additionalProperties": false, + "required": [ + "old_candidate", + "new_candidate", + "commits", + "bootstrap_delta_paths", + "correction_delta_paths", + "merge_free", + "old_is_ancestor", + "bootstrap_is_ancestor" + ], + "properties": { + "old_candidate": {"$ref": "#/$defs/object"}, + "new_candidate": {"$ref": "#/$defs/object"}, + "commits": { + "type": "array", + "minItems": 1, + "items": {"$ref": "#/$defs/correction_commit"} + }, + "bootstrap_delta_paths": {"$ref": "#/$defs/path_list"}, + "correction_delta_paths": {"$ref": "#/$defs/path_list"}, + "merge_free": {"const": true}, + "old_is_ancestor": {"const": true}, + "bootstrap_is_ancestor": {"const": true} + } + }, + "local": { + "type": "object", + "additionalProperties": false, + "required": [ + "clean", + "complete_history", + "replacement_ref_count", + "object_integrity_check", + "history_secret_scan", + "worktree_secret_scan", + "path_manifest_matched", + "checked_out_candidate" + ], + "properties": { + "clean": {"const": true}, + "complete_history": {"const": true}, + "replacement_ref_count": {"const": 0}, + "object_integrity_check": {"const": "passed"}, + "history_secret_scan": {"const": "passed"}, + "worktree_secret_scan": {"const": "passed"}, + "path_manifest_matched": {"const": true}, + "checked_out_candidate": {"const": true} + } + }, + "identity": { + "type": "object", + "additionalProperties": false, + "required": [ + "history_commit_count", + "unique_author_names", + "unique_author_emails", + "unique_committer_names", + "unique_committer_emails", + "identity_set_digest", + "public_email_match", + "public_name_match" + ], + "properties": { + "history_commit_count": {"type": "integer", "minimum": 1}, + "unique_author_names": {"type": "integer", "minimum": 1}, + "unique_author_emails": {"type": "integer", "minimum": 1}, + "unique_committer_names": {"type": "integer", "minimum": 1}, + "unique_committer_emails": {"type": "integer", "minimum": 1}, + "identity_set_digest": {"$ref": "#/$defs/digest"}, + "public_email_match": {"const": true}, + "public_name_match": {"type": "boolean"} + } + }, + "repository": { + "type": "object", + "additionalProperties": false, + "required": ["full_name", "visibility", "default_branch", "authenticated_owner"], + "properties": { + "full_name": {"$ref": "#/$defs/repository_name"}, + "visibility": {"const": "public"}, + "default_branch": {"const": "main"}, + "authenticated_owner": {"const": true} + } + }, + "remote": { + "type": "object", + "additionalProperties": false, + "required": ["candidate_ref", "candidate_commit", "main_ref", "main_commit"], + "properties": { + "candidate_ref": {"type": "string", "minLength": 1}, + "candidate_commit": {"$ref": "#/$defs/object_id"}, + "main_ref": {"const": "main"}, + "main_commit": {"$ref": "#/$defs/object_id"} + } + }, + "pull_request": { + "type": "object", + "additionalProperties": false, + "required": ["number", "state", "head_ref", "head_commit", "base_ref", "base_commit", "merged"], + "properties": { + "number": {"type": "integer", "minimum": 1}, + "state": {"enum": ["open", "closed"]}, + "head_ref": {"type": "string", "minLength": 1}, + "head_commit": {"$ref": "#/$defs/object_id"}, + "base_ref": {"const": "main"}, + "base_commit": {"$ref": "#/$defs/object_id"}, + "merged": {"const": false}, + "merge_commit": {"$ref": "#/$defs/object_id"} + } + }, + "hosted_runs": { + "type": "array", + "minItems": 2, + "items": {"$ref": "#/$defs/hosted_run"} + }, + "ruleset": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "name", + "enforcement", + "no_bypass_actors", + "deletion_blocked", + "non_fast_forward_blocked", + "linear_history_required", + "pull_request_required", + "required_approving_review_count", + "dismiss_stale_reviews", + "last_push_approval_required", + "review_threads_resolved", + "allowed_merge_methods", + "strict_required_checks", + "required_checks_on_create" + ], + "properties": { + "id": {"type": "integer", "minimum": 1}, + "name": {"type": "string", "minLength": 1}, + "enforcement": {"const": "active"}, + "no_bypass_actors": {"const": true}, + "deletion_blocked": {"const": true}, + "non_fast_forward_blocked": {"const": true}, + "linear_history_required": {"const": true}, + "pull_request_required": {"const": true}, + "required_approving_review_count": {"type": "integer", "minimum": 1}, + "dismiss_stale_reviews": {"const": true}, + "last_push_approval_required": {"const": true}, + "review_threads_resolved": {"const": true}, + "allowed_merge_methods": { + "type": "array", + "prefixItems": [{"const": "rebase"}], + "items": false, + "minItems": 1, + "maxItems": 1 + }, + "strict_required_checks": {"const": true}, + "required_checks_on_create": {"const": true} + } + }, + "required_checks": { + "type": "array", + "minItems": 1, + "items": {"$ref": "#/$defs/required_check"} + } + }, + "$defs": { + "object_id": { + "type": "string", + "pattern": "^(?:[0-9a-f]{40}|[0-9a-f]{64})$" + }, + "digest": { + "type": "string", + "pattern": "^sha256:[0-9a-f]{64}$" + }, + "timestamp": { + "type": "string", + "format": "date-time", + "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}([.][0-9]{1,9})?Z$" + }, + "repository_name": { + "type": "string", + "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$" + }, + "path_list": { + "type": "array", + "minItems": 1, + "uniqueItems": true, + "items": { + "type": "string", + "minLength": 1, + "pattern": "^[^/]" + } + }, + "object": { + "type": "object", + "additionalProperties": false, + "required": ["commit", "tree"], + "properties": { + "commit": {"$ref": "#/$defs/object_id"}, + "tree": {"$ref": "#/$defs/object_id"} + } + }, + "correction_commit": { + "type": "object", + "additionalProperties": false, + "required": ["commit", "tree", "parent"], + "properties": { + "commit": {"$ref": "#/$defs/object_id"}, + "tree": {"$ref": "#/$defs/object_id"}, + "parent": {"$ref": "#/$defs/object_id"} + } + }, + "hosted_run": { + "type": "object", + "additionalProperties": false, + "required": ["label", "id", "event", "head_branch", "head_commit", "status", "conclusion", "attempt", "workflow"], + "properties": { + "label": {"type": "string", "pattern": "^[a-z][a-z0-9-]{0,62}$"}, + "id": {"type": "integer", "minimum": 1}, + "event": {"type": "string", "pattern": "^[a-z][a-z0-9_]{0,62}$"}, + "head_branch": {"type": "string", "minLength": 1}, + "head_commit": {"$ref": "#/$defs/object_id"}, + "status": {"const": "completed"}, + "conclusion": {"const": "success"}, + "attempt": {"type": "integer", "minimum": 1}, + "workflow": {"type": "string", "minLength": 1} + } + }, + "required_check": { + "type": "object", + "additionalProperties": false, + "required": ["context", "integration_id", "check_run_id", "status", "conclusion"], + "properties": { + "context": {"type": "string", "minLength": 1}, + "integration_id": {"type": "integer", "minimum": 1}, + "check_run_id": {"type": "integer", "minimum": 1}, + "status": {"const": "completed"}, + "conclusion": {"const": "success"} + } + } + } +} diff --git a/docs/PUBLICATION-EVIDENCE.md b/docs/PUBLICATION-EVIDENCE.md new file mode 100644 index 0000000..f3386f0 --- /dev/null +++ b/docs/PUBLICATION-EVIDENCE.md @@ -0,0 +1,146 @@ +# Public source publication evidence + +Status: Public source candidate. No tag or GitHub release exists. + +Current release target: `v0.2.0-beta.1` + +Observed on: 2026-08-17 + +Repository: [nstranquist/wip-commit](https://github.com/nstranquist/wip-commit) + +Final commit: `206fa8b6a1dde1d97081133e4d447c0881849922` + +Final tree: `c0dd6638adcdc231840ad06406dc9f0caa38e45d` + +This record contains public or redacted evidence. It contains no token, email +address, private report, local path, or raw security log. + +## Hosted discovery and correction + +The pre-first-push receipt bound candidate `ed3f1fadfbc74eb0aa41ef8b90e41f403213d33d` +and its 17-path manifest. The first hosted run found three Windows host +assumptions and one repository setting gap. + +- [The first run](https://github.com/nstranquist/wip-commit/actions/runs/31995610617) + found CRLF-sensitive checks and a POSIX-only mode assertion. +- Dependency review also required the dependency graph. +- Commit `206fa8b6a1dde1d97081133e4d447c0881849922` fixed the three Windows findings. +- The correction expanded the complete bootstrap delta to 20 reviewed paths. +- The repository owner enabled dependency alerts and the dependency graph. + +[Pull request 1](https://github.com/nstranquist/wip-commit/pull/1) verified the +corrected commit. The pull request closed without a merge commit. + +The corrected commit passed these runs: + +- [candidate push](https://github.com/nstranquist/wip-commit/actions/runs/31996054315). +- [candidate pull request](https://github.com/nstranquist/wip-commit/actions/runs/31996057770). +- [final `main` push](https://github.com/nstranquist/wip-commit/actions/runs/31996220707). +- [dependency graph](https://github.com/nstranquist/wip-commit/actions/runs/31996222126). + +## Source-current correction receipt + +The command in +[PUBLICATION-CORRECTION.md](PUBLICATION-CORRECTION.md) verified the completed +bootstrap sequence. It used the explicit `finalized` phase. + +The private receipt bound: + +- the immutable first receipt digest. +- bootstrap `b276204385636c5a8ac338491565bd4894255217`. +- old candidate `ed3f1fadfbc74eb0aa41ef8b90e41f403213d33d`. +- final candidate `206fa8b6a1dde1d97081133e4d447c0881849922`. +- final tree `c0dd6638adcdc231840ad06406dc9f0caa38e45d`. +- verifier commit `6f36147f24f614cff0c7010533d864f8d9ad7628` and tree + `e9559e5fc7fa7083e471acb7d9e72e10b9c3110a`. +- verifier command and schema SHA-256 digests. +- one merge-free correction commit. +- the complete 20-path bootstrap delta. +- the complete 5-path correction delta. +- four successful hosted runs. +- six successful checks from GitHub Actions integration `15368`. +- closed pull request 1 with `merged: false`. +- final candidate and `main` refs at the same commit. +- the active no-bypass ruleset and all review, history, and update controls. + +The receipt passed +[PUBLICATION-CORRECTION.schema.json](PUBLICATION-CORRECTION.schema.json). Its +SHA-256 digest is +`77db44ba2bfa6f007186ace931f38444521d8a29cf48bd945e07a801eda36a9a`. + +The private file remains outside the repository. The public record contains no +identity value, local path, token, private report, or raw security log. + +## Required checks + +All required checks came from GitHub Actions integration `15368`. + +| Required context | Passing pull-request job | +| --- | --- | +| `test (ubuntu-latest)` | [job 95287787614](https://github.com/nstranquist/wip-commit/actions/runs/31996057770/job/95287787614) | +| `test (macos-latest)` | [job 95287787690](https://github.com/nstranquist/wip-commit/actions/runs/31996057770/job/95287787690) | +| `test (windows-latest)` | [job 95287787600](https://github.com/nstranquist/wip-commit/actions/runs/31996057770/job/95287787600) | +| `race` | [job 95287787629](https://github.com/nstranquist/wip-commit/actions/runs/31996057770/job/95287787629) | +| `lint` | [job 95287787563](https://github.com/nstranquist/wip-commit/actions/runs/31996057770/job/95287787563) | +| `dependency-review` | [job 95287787528](https://github.com/nstranquist/wip-commit/actions/runs/31996057770/job/95287787528) | + +## Hosted controls + +[Ruleset 20926881](https://github.com/nstranquist/wip-commit/rules/20926881) +is active on `main`. It has no bypass actor. + +The ruleset requires: + +- a pull request. +- one approval. +- approval after the last push. +- dismissal of stale approvals. +- resolution of review conversations. +- linear history. +- the six provider-bound checks above. +- blocked force pushes and branch deletion. + +The repository permits rebase merges only. Workflow tokens use read-only +permissions by default and cannot approve pull requests. + +The owner enabled and verified: + +- the dependency graph. +- Dependabot alerts. +- Dependabot security updates. +- secret scanning. +- secret-scanning push protection. +- private vulnerability reporting. + +GitHub serves [the security policy](https://github.com/nstranquist/wip-commit/security/policy). +The maintainer's personal security-notification setting remains unverified. + +## Public source smoke test + +A clean test used an empty Git credential helper and cloned the public HTTPS +URL. The clone resolved the final commit and tree above. + +This command installed the exact untagged commit through the public Go module +path and Go proxy: + +```text +go install github.com/nstranquist/wip-commit/cmd/wip@206fa8b6a1dde1d97081133e4d447c0881849922 +``` + +The module resolved to +`v0.0.0-20260817045403-206fa8b6a1dd`. The installed command returned +`wip 0.1.0-beta.1`. + +This result proves public source installation at one commit. It does not prove +the tagged-install gate. + +## Remaining public-beta gates + +Do not create `v0.2.0-beta.1` until all these gates pass: + +- Obtain a valid receipt from one independent beta tester. +- Approve a Code of Conduct and a confidential conduct-reporting path. +- Verify the maintainer's security-alert notifications. +- Obtain explicit owner approval for the tag. +- Run and verify the tag-only archive and attestation workflow. +- Install the final tag through the public Go module path. diff --git a/docs/PUBLICATION-HANDOFF.md b/docs/PUBLICATION-HANDOFF.md index e032a87..adff399 100644 --- a/docs/PUBLICATION-HANDOFF.md +++ b/docs/PUBLICATION-HANDOFF.md @@ -1,6 +1,6 @@ -# First publication handoff +# First publication handoff (historical) -Status: Ready for human execution +Status: Executed on 2026-08-17. Do not run this handoff again. Target: `github.com/nstranquist/wip-commit` @@ -8,14 +8,48 @@ Reviewed bootstrap: `b276204385636c5a8ac338491565bd4894255217` Owner approval: `owner-session-2026-08-16` +First corrected public `main` on 2026-08-17: +`206fa8b6a1dde1d97081133e4d447c0881849922` + +Current release target: `v0.2.0-beta.1` + +The historical commands retain the `candidate/v0.1.0-beta.1` ref name. That +ref name records the completed publication event. It is not the current +release target. + +The source repository now exists and has an active ruleset. The procedure below +is the retained first-publication record. It is not a current mutation runbook. +See [HOSTED-STATUS-2026-08-18.md](HOSTED-STATUS-2026-08-18.md). + +Public evidence: [PUBLICATION-EVIDENCE.md](PUBLICATION-EVIDENCE.md) + +## Execution note + +The pre-first-push receipt bound +`ed3f1fadfbc74eb0aa41ef8b90e41f403213d33d` and its 17-path manifest. The first +hosted run found three Windows host assumptions and a disabled dependency +graph. + +Commit `206fa8b6a1dde1d97081133e4d447c0881849922` fixed the Windows findings and +expanded the complete bootstrap delta to 20 reviewed paths. The corrected +commit passed every required hosted check. + +Pull request 1 closed without a merge commit. Then `main` moved by a direct +fast-forward. + +The pre-first-push command cannot validate this correction because the target +now exists. The `finalized` procedure in +[PUBLICATION-CORRECTION.md](PUBLICATION-CORRECTION.md) verified the completed +sequence and produced the required private correction receipt. + ## Boundary The owner approved the repository name, module path, and capture-only public beta scope. The owner has not approved a release tag. -The repository instructions prohibit an agent push. A human must execute every -command in the **Human-only first push** section. Do not merge the bootstrap -pull request. Do not create a tag during this handoff. +The repository instructions prohibited an agent push without an owner +override. The owner gave one-time approval for this exact handoff. That +approval did not authorize a pull-request merge or tag. The preflight command is read-only except for one new private receipt outside the checkout. It does not create a repository, remote, tag, branch, or Git ref, @@ -80,10 +114,13 @@ Stop if any preflight check fails. Do not weaken a check or edit the receipt. Fix the candidate, capture a new reviewed commit series, and rerun the preflight to a new output path. -## Human-only first push +## Human-only first push (historical record) + +This section is an execution record. Do not run these commands again. In this section, `` means the exact `candidate.commit` from -the validated receipt. A human repository owner must run these commands. +the validated receipt. A human repository owner ran these commands during the +historical handoff. 1. Create an empty public repository. Do not add a README, license, or `.gitignore` from GitHub. @@ -173,7 +210,7 @@ exists. All later changes must follow the active protected-branch policy. ## Gates that remain after the handoff -Do not create `v0.1.0-beta.1` until the requirement tracker has evidence for: +Do not create `v0.2.0-beta.1` until the requirement tracker has evidence for: - hosted Linux, macOS, and Windows execution on the final tag candidate. - repository rules and security settings. diff --git a/docs/RELEASE.md b/docs/RELEASE.md index 1c4f85b..1af80a7 100644 --- a/docs/RELEASE.md +++ b/docs/RELEASE.md @@ -10,8 +10,13 @@ name and capture-only scope is not tag approval. The local release command creates files only. It does not create a tag, push a ref, create a remote repository, or publish a release. +Committed source keeps `cmd/wip` at the matching `X.Y.Z-dev` identity. The +release builder accepts only a `vX.Y.Z...` tag on that development line. It +injects both the artifact SemVer and the exact tag. A binary reports +`channel: release` only when those injected values match. + The hosted workflow runs only for a tag name that contains a prerelease -suffix, such as `v0.1.0-beta.1`. It builds six archives: +suffix, such as `v0.2.0-beta.1`. It builds six archives: - Linux on AMD64 and ARM64. - macOS on AMD64 and ARM64. @@ -52,7 +57,7 @@ checkout. ```text GOTOOLCHAIN=go1.25.12 GOWORK=off go run ./scripts/release \ - --version v0.1.0-beta.1 \ + --version v0.2.0-beta.1 \ --out dist ``` @@ -78,18 +83,21 @@ Use [PUBLICATION-HANDOFF.md](PUBLICATION-HANDOFF.md) for the first push and [HOSTED-SETUP.md](HOSTED-SETUP.md) for the hosted controls. Require a non-author receipt produced with [BETA-EXERCISE.md](BETA-EXERCISE.md) and validated against [BETA-EXERCISE.schema.json](BETA-EXERCISE.schema.json). +If hosted checks require a candidate change, use +[PUBLICATION-CORRECTION.md](PUBLICATION-CORRECTION.md) from a clean verifier +checkout before another `main` update. Before the tag, move the release notes from `Unreleased` to a -`0.1.0-beta.1` section with the actual tag date. Add the release comparison +`0.2.0-beta.1` section with the actual tag date. Add the release comparison links. Treat that edit as a source change: rerun every local and hosted gate on the new commit before tag approval. Create one signed tag at the approved commit: ```text -git tag -s v0.1.0-beta.1 -m "wip-commit v0.1.0-beta.1" -git tag -v v0.1.0-beta.1 -git push origin refs/tags/v0.1.0-beta.1 +git tag -s v0.2.0-beta.1 -m "wip-commit v0.2.0-beta.1" +git tag -v v0.2.0-beta.1 +git push origin refs/tags/v0.2.0-beta.1 ``` The tag push starts `.github/workflows/release-beta.yml`. The workflow repeats @@ -105,7 +113,7 @@ After the workflow succeeds, download the release files in a clean directory. Check `checksums.txt`, then check the attestations: ```text -gh attestation verify wip-commit_0.1.0-beta.1_linux_amd64.tar.gz \ +gh attestation verify wip-commit_0.2.0-beta.1_linux_amd64.tar.gz \ --repo nstranquist/wip-commit ``` diff --git a/docs/SECURITY-REVIEW-2026-08-18.md b/docs/SECURITY-REVIEW-2026-08-18.md new file mode 100644 index 0000000..b06b026 --- /dev/null +++ b/docs/SECURITY-REVIEW-2026-08-18.md @@ -0,0 +1,72 @@ +# Agent-facing workflow security review + +This review is historical evidence for plan version 2. It does not review +private-source plan version 3, cumulative handoff version 2, or coordination +migration. Use the current threat model and a new dated review for those +contracts. + +Review date: 2026-08-18 + +Scope: KEP-0003, capture plan v2, policy binding, lease renewal, status, and +handoff output. + +## Sources + +The review used these primary sources: + +- OpenSSF Concise Guide for Developing More Secure Software, revision + `429544ce24fa3351c193190ef563377f61ce8aa3`. +- NIST SP 800-218 version 1.1, February 2022. +- Pro Git, second edition, Environment Variables chapter. +- Local Git `2.55.0` behavior tests. + +The source registry is [OSS-SOURCES.json](OSS-SOURCES.json). + +## Applied findings + +### Negative tests + +The reviewed workflow rejects draft plans, moved lane tips, moved source +indexes, changed candidate paths, changed leases, and changed policies. + +The tests also reject malformed policy receipts, unknown configuration fields, +unsafe message bytes, and handoffs without a complete validated intent. + +### Stable compatibility + +Version 1 records remain readable. The readers reconstruct each old digest +before they infer a historical default. + +The command keeps legacy plan arrays under `wip commit`. It does not accept +those arrays under the stronger `wip capture` contract. + +### Review evidence + +The plan records each security-sensitive input before capture. The v2 intent +stores the reviewed-plan digest and message-policy receipt. + +The command checks the selected index digest before it starts the transaction. +The kernel receives the same expected digest and checks its initial source +snapshot before hooks run. It checks the selected entries again before the +single ref update. + +The handoff validates the ref and complete commit chain before output. It marks +the result as capture-only and non-authorizing. + +### Git environment boundary + +Repository discovery still removes inherited variables that can redirect the +repository, refs, config, worktree, namespace, or object store. + +The caller's `GIT_INDEX_FILE` remains the explicit source index. The private +capture index remains a separate `GIT_INDEX_FILE` value. + +## Residual boundaries + +- Cooperating processes must honor leases. +- Hooks and verification commands remain trusted repository code. +- A same-user malicious process can alter local files and refs. +- The handoff does not prove review approval, landing, push, release, or adoption. +- Network filesystems remain unsupported. + +These boundaries do not change the capture-only beta contract. diff --git a/docs/SECURITY-REVIEW-2026-08-27.md b/docs/SECURITY-REVIEW-2026-08-27.md new file mode 100644 index 0000000..e404c51 --- /dev/null +++ b/docs/SECURITY-REVIEW-2026-08-27.md @@ -0,0 +1,68 @@ +# Capture boundary security review + +Review date: 2026-08-27 + +Scope: linked-worktree initialization recovery, copied-hook environment, +candidate-tree verifier materialization, and inherited Git pathspec variables. + +## Sources + +This review refreshed three primary sources in +[OSS-SOURCES.json](OSS-SOURCES.json): + +- Pro Git, second edition, Environment Variables chapter, reviewed with Git + 2.55.0. +- OpenSSF Concise Guide for Developing More Secure Software, revision + `eb54fd9f4264bebab64586d92dffc914fbe8c896`. +- NIST SP 800-218 version 1.1, February 2022. + +Pro Git identifies repository, worktree, index, object-directory, and pathspec +environment variables as inputs to Git behavior. The capture kernel now removes +the inherited pathspec mode variables in addition to its existing repository +routing controls. + +OpenSSF requires automated negative tests for security requirements. NIST SSDF +requires root-cause correction and tests that prevent recurrence. Each repaired +boundary has a negative or failure-boundary test. + +## Applied findings + +### Initialization recovery + +When `wip init --create-worktree` starts inside that existing linked worktree, +the command finds the primary checkout that owns the shared Git directory. It +uses and reports that checkout as the immutable recovery anchor. A test reruns +the same completed initialization from the linked worktree and proves that the +command does not reject its own target. + +### Copied hooks + +The hook runner removes inherited copies of `WIP_CAPTURE`, +`WIP_HOOK_PHASE`, `WIP_SOURCE_READ_ONLY`, `WIP_TARGET_REF`, and +`WIP_COMMIT_OBJECT`. It then supplies one canonical value for the active hook +phase. A negative test supplies mixed-case spoofed values and proves that no +spoofed or duplicate value reaches the hook environment. + +### Verifier materialization + +The plan schema adds an optional `materialize` list. A command directory is an +implicit scope. The kernel lists the immutable candidate tree with literal +top-level pathspecs, rejects more than 16,384 entries or 512 MiB, and only then +creates a scratch checkout. It sends selected paths to `checkout-index` through +NUL-delimited standard input. + +Tests prove that a scoped verifier sees its candidate directory and one +declared dependency but cannot see an unrelated candidate file. Parser tests +prove that entry, byte, and malformed-listing boundaries fail closed. A retained +real-tree overlay test materializes and verifies the NDev subtree with more than +10,000 files, then proves that an undeclared full nicos-tools tree returns +`VERIFY_MATERIALIZATION_LIMIT`. + +## Residual boundaries + +- Hooks and verify commands are trusted repository code. The read-only marker + is a contract for cooperating hooks, not an operating-system sandbox. +- The materialization byte limit counts Git object content. Filesystem metadata + and allocation can use additional space. +- External Git commands can ignore WIP leases and environment contracts. +- The capture handoff does not authorize landing, merge, push, tag, or release. diff --git a/docs/STATE-COMPATIBILITY.md b/docs/STATE-COMPATIBILITY.md index 5f6d91d..d9dec6a 100644 --- a/docs/STATE-COMPATIBILITY.md +++ b/docs/STATE-COMPATIBILITY.md @@ -2,12 +2,21 @@ ## Supported state -`v0.1.0-beta.1` reads and writes state directory version 1. Lane, lease, -capture-intent, initialization-intent, profile, and archive-receipt records also -use JSON schema version 1. +The current development command reads and writes state directory version 1. +Lane, lease, and archive-receipt records use JSON schema version 1. + +New profiles and initialization intents use record schema version 2. Their +readers also accept version 1. + +New captures use capture-intent schema version 3. This schema binds +`source_mode`, `untracked_policy`, `source_digest`, and `source_paths`. Readers +also accept capture-intent schema versions 1 and 2 without changing their +historical digest fields. Archive receipt state values are `prepared`, `complete`, `restoring`, and -`restored`. +`restored`. A restored receipt remains valid history after a newer receipt +archives the same records. Each record must remain live or have exactly one +validated newer archive owner. The state is in the Git common directory: @@ -15,8 +24,26 @@ The state is in the Git common directory: /wip/v1/ ``` -The owner marker is `/wip/domain.json`. It binds the state -owner and writable version before a command creates record directories. +The separate review authority uses this root: + +```text +/wip/review/v1/ +``` + +Its required directories are `archive`, `handoffs`, `landing-intents`, `locks`, +`plans`, and `reconciliation`. The standalone capture path does not convert a +handoff into landing authority. + +The owner marker is `/wip/domain.json`. Marker schema version 2 +binds the owner, writable state version, minimum reader protocol, and sorted +required reader capabilities. New repositories write marker version 2. + +The command reads marker version 1 without changing it. Read-only doctor, +handoff, status-observe, and environment-observe operations remain available. +Every mutation stops with `MIGRATION_REQUIRED` until the operator applies the +digest-bound marker upgrade. An old binary rejects marker version 2 because it +does not recognize the reader-floor fields. This is the required fail-closed +behavior. Legacy Nicos Tools state uses `/ndev-wip/v1/`. Both implementations acquire `/wip-coordination.lock` before domain @@ -33,9 +60,12 @@ When the command finds either of these items, it returns - a state directory with a version other than the exact name `v1`. - an unknown top-level entry inside the `v1` directory. -- a domain marker schema version other than 1. -- a lane, lease, capture intent, initialization intent, profile, or archive - receipt with a schema version other than 1. +- a domain marker schema version other than 1 or 2. +- a marker version 2 reader floor above `wip.command/3.0.0`, a different + protocol major, or a required capability that the binary does not advertise. +- a lane, lease, or archive receipt with a schema version other than 1. +- a capture intent with a schema version other than 1, 2, or 3. +- an initialization intent or profile with a schema version other than 1 or 2. The command checks state-directory versions before it creates `v1`. This check prevents an old binary from starting a second coordination domain beside newer @@ -45,9 +75,18 @@ The domain marker closes the concurrent initialization gap. A future writer must acquire the same domain lock before it changes the marker or creates a new version directory. -`wip` does not migrate, rename, delete, or rewrite unsupported state. It does -not guess how a future schema works. Malformed version 1 data continues to use -its specific read, identity, or digest error. +`wip` does not migrate, rename, delete, or rewrite an unknown state directory or +record. It does not guess how a future schema works. The state-marker upgrade +changes only the validated owner marker from schema 1 to schema 2. + +The separate `wip migrate` command handles only the reviewed legacy NDev +coordination layout. It does not act as a general repair for unknown schemas. + +A version 1 profile implies the historical `conventional-v1` policy. Version 1 +initialization and capture intents keep their original digest form. + +Readers calculate each version 1 digest before they infer any current default. +They do not rewrite an old record during a read. `init-intents` and `archive` are additive version 1 directories. A read-only inspection accepts their absence as an empty older version 1 store and does not @@ -55,11 +94,11 @@ create them. The next mutating command creates the missing directories after it validates the domain and layout. Other missing required record directories are reported by `wip doctor`. -Only a non-dry-run `wip init` claims an uninitialized repository. Other lane -commands inspect the domain first and return `LANE_NOT_ACTIVE` without creating -the marker, version directory, or shared coordination lock. Once version 1 -state exists, a mutating command can create only the additive directories that -are missing from that same validated domain. +Only a non-dry-run `wip init` or an exact reviewed migration apply can claim an +uninitialized repository. Other lane commands inspect the domain first and +return `LANE_NOT_ACTIVE` without creating the marker, version directory, or +shared coordination lock. Once marker version 2 owns version 1 state, a +mutating command can create only additive directories in that validated domain. Archive resume and restore also inspect before mutation. They return `ARCHIVE_NOT_FOUND` without creating a domain when no state exists. Legacy @@ -70,26 +109,115 @@ Every version 1 writer bounds the complete encoded record before publication. The bound includes the final newline. This rule keeps each new record readable by the same release. -## Upgrade procedure +## Marker upgrade procedure -Before an upgrade that changes the state version: +Before a marker upgrade: 1. Stop all `wip` processes for the repository. 2. Use the current compatible binary to inspect every active lane. 3. Reconcile any capture that moved a lane ref but did not complete its intent. 4. Record each lane ref and commit ID. 5. Release each finished lane. Preserve every lane ref. -6. Make a filesystem backup of `/wip/v1/`. -7. Read the new release notes and use only its documented migration command. +6. Make a filesystem backup of `/wip/`, including + `domain.json`. +7. Require a healthy `wip --json doctor` result with no active lanes or pending + initialization, capture, or archive recovery. +8. Run the read-only preview: + + ```text + wip --json upgrade --state + ``` + +9. Review `path`, `current_sha256`, `desired_sha256`, and `plan_digest`. Apply + only that plan: + + ```text + wip --json upgrade --state --apply --yes \ + --plan-digest sha256: + ``` + +10. Run `wip --json doctor` again. Require marker schema 2, the expected reader + floor, no pending recovery, and `healthy: true`. + +Preview does not write. Apply acquires the coordination lock, compares the +exact old marker digest again, atomically replaces only `domain.json`, and +verifies the desired digest. A repeated apply to the current marker is +idempotent. Any byte change requires a new preview. -The beta has no migration command because it has no earlier public schema. A -future migration must be explicit, idempotent, bounded, and recoverable. It -must preserve the original state until the new state and its receipt are -durable. +A future state-directory or record migration must also be explicit, +idempotent, bounded, and recoverable. It must preserve the original state until +the new state and its receipt are durable. Do not change JSON records by hand. Do not rename `v2` to `v1`. Do not copy a partial state directory between repositories. +## Coordination-domain migration + +Use this procedure only for the legacy NDev root at +`/ndev-wip/v1`. + +1. Stop all capture, queue, landing, and reconciliation writers. +2. Back up every ref and both coordination roots. +3. Record the exact executable, source revision, and portable-skill digest. +4. Run the byte-for-byte read-only preview: + + ```text + wip --json migrate --preview + ``` + +5. Save the exact `data.plan` object as a plan file. +6. Review all manifests, refs, dispositions, conflicts, and producer fields. +7. Apply only a ready plan with its exact digest: + + ```text + wip --json migrate \ + --apply \ + --plan migration-plan.json \ + --plan-digest sha256: \ + --yes + ``` + +8. Run `wip --json migrate --status --migration-id `. +9. Require a complete receipt and a sealed legacy archive. +10. Run `wip --json doctor` with the source-matched command. + +Migration status schema `wip.coordination-migration-status/1.1.0` separates the +historical cutover manifest from the current live-store manifest. A complete +status keeps the cutover digest in `receipt.canonical_manifest_digest`. It +reports the current digest in `current_canonical_manifest_digest`. The +`canonical_advanced` field is true when those digests differ after a valid +post-cutover writer changes the live store. This difference is not a migration +failure. Completed status also excludes transient `wip/indexes` content from +the historical comparison. It still requires the private-index root to be a +regular mode-0700 directory. Run `wip --json doctor` to validate the current +records. + +Before the completion receipt and final journal phase exist, migration status +still requires the exact reviewed canonical manifest. It also rejects a change +to the static migration envelope after completion. + +Apply writes a plan-bound writer fence before it publishes canonical records. +All capture-store writers stop while that fence is active. The migration +publishes the exact regular `wip/v1/locks/leases.lock` artifact before imported +lane or lease records become readable. It imports valid capture records and +copies review records. It creates the `handoffs` and `plans` review directories +before record publication. + +The migration then moves the complete legacy root into a sealed archive. It +does not dual-write the legacy and canonical roots. It does not authorize +landing. + +The preview does not import an active lane that has no live path lease. It +marks the stale lane and its expired leases `archive-only`. The plan binds the +exact lane ref SHA, including a descendant SHA that advanced from the stored +cursor. Apply verifies that SHA before it changes coordination state. A missing +or diverged ref blocks migration. A moved ref also blocks migration when the +lane has a live lease. The migration does not delete or move the lane ref. + +If apply stops, use `--resume` with the same plan and digest. Use `--rollback` +only before the migration moves the legacy source. After that move, preserve +the archive and resume forward. + ## Downgrade procedure When the target release lists the current state version as readable, a @@ -115,9 +243,18 @@ release can read and write. A state-version change requires all of these items: No state migration can be a hidden side effect of `wip init`, `wip status`, or `wip commit`. -`wip doctor`, `wip status`, `wip env`, `wip plan`, and archive preview are -read-only. They do not create a domain marker or version directory. A marker -without its version directory is reported as initialized but unhealthy state; -it is not misreported as an unclaimed domain. `wip archive` moves only released -records after an exact reviewed preview. It rechecks the exact records under -lock, preserves all lane refs, and supports receipt-based resume and restore. +`wip doctor`, `wip status --observe`, `wip env --observe`, `wip plan +--observe`, migration preview, migration status, and archive preview are +read-only. They do not create a domain marker or version directory. A +released-lane handoff is also read-only. An active-lane handoff renews leases. + +Authenticated `status`, `env`, and `plan` renew active leases unless +`--observe` is set. This renewal replaces only existing lease records after +complete identity validation. + +A marker without its version directory is initialized but unhealthy state. It +is not an unclaimed domain. + +`wip archive` moves only released records after an exact reviewed preview. It +rechecks records under lock, preserves refs, and supports receipt-based resume +and restore. diff --git a/docs/STATUS.schema.json b/docs/STATUS.schema.json new file mode 100644 index 0000000..9e0d6ec --- /dev/null +++ b/docs/STATUS.schema.json @@ -0,0 +1,191 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://github.com/nstranquist/wip-commit/blob/main/docs/STATUS.schema.json", + "title": "wip operational lane status", + "type": "object", + "additionalProperties": false, + "required": [ + "schema_version", + "lane", + "leases", + "message_policy", + "active_paths", + "leased_but_not_staged", + "empty_lease_scopes", + "capture_candidates", + "captured_but_still_staged", + "staged_leased", + "foreign_staged", + "expired_lease_ids", + "lease_expires_at", + "lease_remaining_ms", + "renewal", + "ref_health" + ], + "properties": { + "schema_version": {"const": "2.0.0"}, + "lane": {"$ref": "#/$defs/lane"}, + "leases": { + "type": "array", + "maxItems": 10000, + "items": {"$ref": "#/$defs/lease"} + }, + "message_policy": {"$ref": "#/$defs/message_policy"}, + "active_paths": {"$ref": "#/$defs/paths"}, + "leased_but_not_staged": {"$ref": "#/$defs/paths"}, + "empty_lease_scopes": {"$ref": "#/$defs/paths"}, + "capture_candidates": {"$ref": "#/$defs/paths"}, + "captured_but_still_staged": {"$ref": "#/$defs/paths"}, + "staged_leased": {"$ref": "#/$defs/paths"}, + "foreign_staged": {"$ref": "#/$defs/paths"}, + "expired_lease_ids": { + "type": "array", + "maxItems": 10000, + "uniqueItems": true, + "items": {"type": "string", "pattern": "^lease-[0-9a-f]{32}$"} + }, + "lease_expires_at": { + "oneOf": [ + {"type": "string", "format": "date-time"}, + {"type": "null"} + ] + }, + "lease_remaining_ms": {"type": "integer", "minimum": 0}, + "renewal": {"$ref": "#/$defs/renewal"}, + "ref_health": {"$ref": "#/$defs/ref_health"}, + "last_intent": {"$ref": "#/$defs/intent_summary"} + }, + "$defs": { + "object_id": {"type": "string", "pattern": "^(?:[0-9a-f]{40}|[0-9a-f]{64})$"}, + "digest": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"}, + "identifier": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$"}, + "paths": { + "type": "array", + "maxItems": 10000, + "uniqueItems": true, + "items": {"type": "string", "minLength": 1} + }, + "message_policy": { + "type": "object", + "additionalProperties": false, + "required": ["id", "version", "digest"], + "properties": { + "id": {"enum": ["conventional-v1", "safety-only-v1"]}, + "version": {"const": "1.0.0"}, + "digest": {"$ref": "#/$defs/digest"} + } + }, + "lane": { + "type": "object", + "additionalProperties": false, + "required": [ + "schema_version", + "id", + "agent", + "session", + "mode", + "ref", + "base_ref", + "base_sha", + "current_sha", + "worktree", + "state", + "created_at", + "updated_at" + ], + "properties": { + "schema_version": {"const": 1}, + "id": {"$ref": "#/$defs/identifier"}, + "agent": {"$ref": "#/$defs/identifier"}, + "session": {"$ref": "#/$defs/identifier"}, + "mode": {"enum": ["shared", "worktree"]}, + "ref": {"type": "string", "pattern": "^refs/heads/wip/[^/]+/[^/]+$"}, + "base_ref": {"type": "string", "minLength": 1}, + "base_sha": {"$ref": "#/$defs/object_id"}, + "current_sha": {"$ref": "#/$defs/object_id"}, + "worktree": {"type": "string", "minLength": 1}, + "lease_ids": { + "type": "array", + "maxItems": 10000, + "uniqueItems": true, + "items": {"type": "string", "pattern": "^lease-[0-9a-f]{32}$"} + }, + "state": {"enum": ["active", "released", "aborted"]}, + "created_at": {"type": "string", "format": "date-time"}, + "updated_at": {"type": "string", "format": "date-time"}, + "last_commit": {"$ref": "#/$defs/object_id"} + } + }, + "lease": { + "type": "object", + "additionalProperties": false, + "required": [ + "schema_version", + "id", + "lane_id", + "agent", + "session", + "paths", + "state", + "created_at", + "updated_at" + ], + "properties": { + "schema_version": {"const": 1}, + "id": {"type": "string", "pattern": "^lease-[0-9a-f]{32}$"}, + "lane_id": {"$ref": "#/$defs/identifier"}, + "agent": {"$ref": "#/$defs/identifier"}, + "session": {"$ref": "#/$defs/identifier"}, + "paths": {"$ref": "#/$defs/paths"}, + "state": {"enum": ["active", "released"]}, + "created_at": {"type": "string", "format": "date-time"}, + "updated_at": {"type": "string", "format": "date-time"}, + "expires_at": {"type": "string", "format": "date-time"}, + "released_at": {"type": "string", "format": "date-time"} + } + }, + "renewal": { + "type": "object", + "additionalProperties": false, + "required": ["attempted", "succeeded"], + "properties": { + "attempted": {"type": "boolean"}, + "succeeded": {"type": "boolean"}, + "renewed_at": {"type": "string", "format": "date-time"} + } + }, + "ref_health": { + "type": "object", + "additionalProperties": false, + "required": ["healthy", "expected"], + "properties": { + "healthy": {"type": "boolean"}, + "expected": {"$ref": "#/$defs/object_id"}, + "actual": {"$ref": "#/$defs/object_id"}, + "issue": {"enum": ["ref_not_found", "ref_tip_mismatch"]} + } + }, + "intent_summary": { + "type": "object", + "additionalProperties": false, + "required": [ + "plan_id", + "plan_digest", + "state", + "expected_new", + "created_at", + "updated_at" + ], + "properties": { + "plan_id": {"type": "string", "pattern": "^plan-[0-9a-f]{24}$"}, + "plan_digest": {"$ref": "#/$defs/digest"}, + "review_plan_digest": {"$ref": "#/$defs/digest"}, + "state": {"enum": ["prepared", "applied", "complete"]}, + "expected_new": {"$ref": "#/$defs/object_id"}, + "message_policy": {"$ref": "#/$defs/message_policy"}, + "created_at": {"type": "string", "format": "date-time"}, + "updated_at": {"type": "string", "format": "date-time"} + } + } + } +} diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..7bfbfea --- /dev/null +++ b/examples/README.md @@ -0,0 +1,24 @@ +# Legacy commit plan example + +`shared-split-plan.json` shows the legacy commit-only plan array. Pass an edited +file only to `wip commit --plan `. `wip capture` rejects this format. + +For guided capture, generate a bound version 3 plan with `wip plan --out +`. Do not construct that plan from a template. Its source, lane, lease, +and policy digests must come from the current repository state. + +Before you use an example: + +1. Use this legacy format only for a controlled staged-index compatibility + capture. +2. Replace every path with a staged path in the active lane's lease. +3. Replace every message with a concrete Conventional Commit subject. +4. Replace each verification command with a bounded command for the candidate + tree. +5. Run `wip plan --source staged_index --untracked not_applicable`. +6. Compare its source paths with the edited legacy file. +7. Run `wip commit --plan `. + +The command rejects paths outside the lease, duplicate files, vague messages, +and verification commands that fail or time out. It leaves the source `HEAD` +and complete index unchanged. diff --git a/examples/shared-split-plan.json b/examples/shared-split-plan.json new file mode 100644 index 0000000..41da09d --- /dev/null +++ b/examples/shared-split-plan.json @@ -0,0 +1,24 @@ +[ + { + "message": "fix(parser): preserve source error locations", + "files": [ + "internal/parser" + ], + "verify": [ + { + "argv": [ + "go", + "test", + "./internal/parser" + ], + "timeout_ms": 120000 + } + ] + }, + { + "message": "docs(parser): explain source error locations", + "files": [ + "docs/parser.md" + ] + } +] diff --git a/go.mod b/go.mod index 5964127..7aabccf 100644 --- a/go.mod +++ b/go.mod @@ -3,6 +3,7 @@ module github.com/nstranquist/wip-commit go 1.25.12 require ( + github.com/santhosh-tekuri/jsonschema/v6 v6.0.3 golang.org/x/sys v0.47.0 golang.org/x/text v0.41.0 ) diff --git a/go.sum b/go.sum index 2893487..5fed906 100644 --- a/go.sum +++ b/go.sum @@ -1,3 +1,7 @@ +github.com/dlclark/regexp2 v1.11.0 h1:G/nrcoOa7ZXlpoa/91N3X7mM3r8eIlMBBJZvsz/mxKI= +github.com/dlclark/regexp2 v1.11.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8= +github.com/santhosh-tekuri/jsonschema/v6 v6.0.3 h1:1EYB5IzjZawrrnELUi78f9fPu57HuXjmddZPjrls/28= +github.com/santhosh-tekuri/jsonschema/v6 v6.0.3/go.mod h1:JXeL+ps8p7/KNMjDQk3TCwPpBy0wYklyWTfbkIzdIFU= golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs= golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw= golang.org/x/text v0.41.0 h1:vz/seA0lnX87Othu2f/0L24RcgrXD9/YFTSuGjj3rH8= diff --git a/internal/atomicfile/atomicfile.go b/internal/atomicfile/atomicfile.go index 60d5541..c4cbefb 100644 --- a/internal/atomicfile/atomicfile.go +++ b/internal/atomicfile/atomicfile.go @@ -36,7 +36,7 @@ func CreateWithTempDir(path, temporaryDirectory string, body []byte, mode os.Fil _ = file.Close() _ = os.Remove(temporary) }() - if err = file.Chmod(mode); err != nil { + if err = file.Chmod(createSourceMode(mode)); err != nil { return err } if written, writeErr := file.Write(body); writeErr != nil { @@ -55,10 +55,13 @@ func CreateWithTempDir(path, temporaryDirectory string, body []byte, mode os.Fil } else if err != nil { return err } - if err = syncDirectory(destinationDirectory); err != nil { + if err = os.Remove(temporary); err != nil { return err } - if err = os.Remove(temporary); err != nil { + if err = finalizeCreatedFile(path, mode); err != nil { + return err + } + if err = syncDirectory(destinationDirectory); err != nil { return err } return syncDirectory(temporaryDirectory) diff --git a/internal/atomicfile/atomicfile_test.go b/internal/atomicfile/atomicfile_test.go index c592a52..0cfa66d 100644 --- a/internal/atomicfile/atomicfile_test.go +++ b/internal/atomicfile/atomicfile_test.go @@ -76,6 +76,30 @@ func TestConcurrentCreatePublishesOneCompleteWinner(t *testing.T) { } } +func TestCreatePreservesReadOnlyModeAfterTemporaryRemoval(t *testing.T) { + root := t.TempDir() + staging := filepath.Join(root, "staging") + target := filepath.Join(root, "state", "plan.json") + if err := CreateWithTempDir(target, staging, []byte("immutable plan\n"), 0o400); err != nil { + t.Fatal(err) + } + info, err := os.Lstat(target) + if err != nil { + t.Fatal(err) + } + if info.Mode().Perm()&0o200 != 0 { + t.Fatalf("published file remains owner-writable: %v", info.Mode()) + } + body, err := os.ReadFile(target) + if err != nil || string(body) != "immutable plan\n" { + t.Fatalf("body = %q, err=%v", body, err) + } + entries, err := os.ReadDir(staging) + if err != nil || len(entries) != 0 { + t.Fatalf("staging entries = %#v, err=%v", entries, err) + } +} + func TestCreateWithExternalTempDirectoryKeepsDestinationCanonical(t *testing.T) { root := t.TempDir() staging := filepath.Join(root, "staging") diff --git a/internal/atomicfile/create_mode_default.go b/internal/atomicfile/create_mode_default.go new file mode 100644 index 0000000..c60a0eb --- /dev/null +++ b/internal/atomicfile/create_mode_default.go @@ -0,0 +1,9 @@ +//go:build !windows + +package atomicfile + +import "os" + +func createSourceMode(mode os.FileMode) os.FileMode { return mode } + +func finalizeCreatedFile(_ string, _ os.FileMode) error { return nil } diff --git a/internal/atomicfile/create_mode_windows.go b/internal/atomicfile/create_mode_windows.go new file mode 100644 index 0000000..f09a7a8 --- /dev/null +++ b/internal/atomicfile/create_mode_windows.go @@ -0,0 +1,14 @@ +//go:build windows + +package atomicfile + +import "os" + +// Removing one read-only Windows hard-link name can clear the shared read-only +// attribute from the surviving name. Keep the temporary source writable, remove +// it after publication, and then apply the reviewed final mode to the target. +func createSourceMode(mode os.FileMode) os.FileMode { return mode | 0o200 } + +func finalizeCreatedFile(path string, mode os.FileMode) error { + return os.Chmod(path, mode) +} diff --git a/internal/contract/contract.go b/internal/contract/contract.go new file mode 100644 index 0000000..befce19 --- /dev/null +++ b/internal/contract/contract.go @@ -0,0 +1,131 @@ +// Package contract defines the public command and durable-reader capability +// contract. The values are data, not feature detection by prose or version +// string. +package contract + +import ( + "fmt" + "slices" + "strconv" + "strings" +) + +const ( + SchemaVersion = "1.0.0" + Protocol = "wip.command/3.0.0" + PortableSkillContract = "wip.portable-skill/2.0.0" +) + +var capabilities = []string{ + "capture.v3.private-source-cas", + "capture.v3.review-digest", + "commit.dry-run.no-exec.v1", + "coordination.migration.v1", + "doctor.v1", + "handoff.v2.cumulative-capture-only", + "hook.environment.v1", + "install.digest-upgrade.v1", + "lane.init.anchor-recovery.v1", + "lane.init.v1", + "lease.claim.v1", + "plan.v3.observe", + "plan.v3.private-source-no-overwrite", + "source.worktree-snapshot.v1", + "state.archive-history.v1", + "state.capture-intent.v2", + "state.capture-intent.v3", + "state.init-intent.v2", + "state.profile.v2", + "state.reader-floor.v1", + "status.v2.observe", + "verify.materialization.v1", + "version.v2.provenance", +} + +var stateReaderCapabilities = []string{ + "state.archive-history.v1", + "state.capture-intent.v2", + "state.capture-intent.v3", + "state.init-intent.v2", + "state.profile.v2", + "state.reader-floor.v1", +} + +type Document struct { + SchemaVersion string `json:"schema_version"` + Protocol string `json:"protocol"` + Capabilities []string `json:"capabilities"` + PortableSkillContract string `json:"portable_skill_contract"` +} + +func Current() Document { + return Document{ + SchemaVersion: SchemaVersion, + Protocol: Protocol, + Capabilities: slices.Clone(capabilities), + PortableSkillContract: PortableSkillContract, + } +} + +func StateReaderCapabilities() []string { + return slices.Clone(stateReaderCapabilities) +} + +func Supports(required []string) error { + for _, capability := range required { + if !slices.Contains(capabilities, capability) { + return fmt.Errorf("unsupported required capability %q", capability) + } + } + return nil +} + +// MeetsProtocolFloor reports whether current is in the same command-protocol +// family and is at least the requested semantic version. Protocol-major +// changes are deliberately incompatible even when their numeric value is +// greater. +func MeetsProtocolFloor(current, floor string) error { + currentVersion, err := parseProtocol(current) + if err != nil { + return fmt.Errorf("current protocol: %w", err) + } + floorVersion, err := parseProtocol(floor) + if err != nil { + return fmt.Errorf("reader floor: %w", err) + } + if currentVersion[0] != floorVersion[0] { + return fmt.Errorf("protocol major %d cannot read protocol major %d state", currentVersion[0], floorVersion[0]) + } + for index := range currentVersion { + if currentVersion[index] > floorVersion[index] { + return nil + } + if currentVersion[index] < floorVersion[index] { + return fmt.Errorf("protocol %s is below required floor %s", current, floor) + } + } + return nil +} + +func parseProtocol(value string) ([3]uint64, error) { + var version [3]uint64 + const prefix = "wip.command/" + if !strings.HasPrefix(value, prefix) { + return version, fmt.Errorf("invalid protocol %q", value) + } + parts := strings.Split(strings.TrimPrefix(value, prefix), ".") + if len(parts) != len(version) { + return version, fmt.Errorf("invalid protocol %q", value) + } + for index, part := range parts { + if part == "" || len(part) > 1 && part[0] == '0' { + return version, fmt.Errorf("invalid protocol %q", value) + } + parsed, err := strconv.ParseUint(part, 10, 31) + if err != nil { + return version, fmt.Errorf("invalid protocol %q", value) + } + version[index] = parsed + } + return version, nil +} diff --git a/internal/contract/contract_test.go b/internal/contract/contract_test.go new file mode 100644 index 0000000..e49f88b --- /dev/null +++ b/internal/contract/contract_test.go @@ -0,0 +1,41 @@ +package contract + +import ( + "slices" + "testing" +) + +func TestCurrentContractIsCanonical(t *testing.T) { + document := Current() + if document.SchemaVersion != SchemaVersion || document.Protocol != Protocol || document.PortableSkillContract != PortableSkillContract { + t.Fatalf("contract identity = %#v", document) + } + if !slices.IsSorted(document.Capabilities) { + t.Fatalf("capabilities are not sorted: %v", document.Capabilities) + } + if len(document.Capabilities) != len(slices.Compact(slices.Clone(document.Capabilities))) { + t.Fatalf("capabilities contain duplicates: %v", document.Capabilities) + } + if err := Supports(StateReaderCapabilities()); err != nil { + t.Fatal(err) + } +} + +func TestProtocolFloorIsMajorBoundedSemver(t *testing.T) { + for _, test := range []struct { + current, floor string + allowed bool + }{ + {Protocol, Protocol, true}, + {"wip.command/3.1.0", Protocol, true}, + {"wip.command/3.0.0", "wip.command/3.1.0", false}, + {"wip.command/2.9.0", Protocol, false}, + {"wip.command/4.0.0", Protocol, false}, + {"wip.command/03.0.0", Protocol, false}, + {"other/2.0.0", Protocol, false}, + } { + if allowed := MeetsProtocolFloor(test.current, test.floor) == nil; allowed != test.allowed { + t.Errorf("MeetsProtocolFloor(%q, %q) = %v, want %v", test.current, test.floor, allowed, test.allowed) + } + } +} diff --git a/internal/coordmigration/apply.go b/internal/coordmigration/apply.go new file mode 100644 index 0000000..2fa5eb6 --- /dev/null +++ b/internal/coordmigration/apply.go @@ -0,0 +1,1010 @@ +package coordmigration + +import ( + "bytes" + "context" + "errors" + "fmt" + "os" + "path/filepath" + "slices" + "sort" + "time" + + "github.com/nstranquist/wip-commit/internal/contract" + "github.com/nstranquist/wip-commit/internal/fail" + "github.com/nstranquist/wip-commit/internal/filelock" + "github.com/nstranquist/wip-commit/internal/gitx" + "github.com/nstranquist/wip-commit/internal/safeio" +) + +const ( + phaseJournalCreated = "journal-created" + phaseCanonicalPrepared = "canonical-prepared" + phaseRecordsPublished = "records-published" + phaseSourceMoved = "source-moved" + phaseArchiveSealed = "archive-sealed" + phaseComplete = "complete" + phaseRollbackStarted = "rollback-started" + phaseRolledBack = "rolled-back" +) + +var phaseOrder = map[string]int{ + phaseJournalCreated: 0, + phaseCanonicalPrepared: 1, + phaseRecordsPublished: 2, + phaseSourceMoved: 3, + phaseArchiveSealed: 4, + phaseComplete: 5, + phaseRollbackStarted: 6, + phaseRolledBack: 7, +} + +// ApplyOptions contains only recovery and test-control settings. Apply always +// requires a separate exact reviewed plan digest. +type ApplyOptions struct { + Resume bool + Rollback bool + LockWait time.Duration + AfterPhase func(string) error + // AfterOperation is a package-level fault-injection seam used to prove + // recovery between durable operations. The command never exposes it. + AfterOperation func(string) error + // Producer is recomputed by command dispatch from the running executable. + // It must equal the identity embedded in the reviewed plan on every apply, + // resume, and rollback invocation. + Producer ProducerIdentity +} + +type domainRecord struct { + SchemaVersion int `json:"schema_version"` + Domain string `json:"domain"` + StateVersion int `json:"state_version"` + MinimumReaderProtocol string `json:"minimum_reader_protocol"` + RequiredCapabilities []string `json:"required_capabilities"` +} + +func Apply(ctx context.Context, repo gitx.Repo, plan Plan, expectedDigest string, options ApplyOptions) (Result, error) { + if err := validateApplyRequest(repo, plan, expectedDigest, options); err != nil { + return Result{}, err + } + lock, err := filelock.Acquire(filepath.Join(repo.CommonDir, "wip-coordination.lock"), options.LockWait) + if err != nil { + return Result{}, fail.Wrap("MIGRATION_LOCKED", err) + } + defer func() { _ = lock.Release() }() + + journalPath := migrationJournalPath(repo.CommonDir) + journal, journalExists, err := readJournal(journalPath) + if err != nil { + return Result{}, err + } + if journalExists && journal.Phase == phaseRolledBack { + rolledBackPlan, loadErr := loadPersistedPlan(repo.CommonDir, journal.MigrationID) + if loadErr != nil { + return Result{}, fail.Wrap("MIGRATION_PLAN_INVALID", loadErr) + } + if bindingErr := verifyJournalPlanBinding(repo, rolledBackPlan, journal); bindingErr != nil { + return Result{}, bindingErr + } + status, statusErr := InspectStatus(repo, journal.MigrationID) + if statusErr != nil { + return Result{}, statusErr + } + if status.State != "rolled-back" || status.Rollback == nil { + return Result{}, fail.New("MIGRATION_ROLLBACK_INVALID", "rolled-back journal has no exact rollback marker") + } + if err := deactivateWriterFence(repo.CommonDir, rolledBackPlan); err != nil { + return Result{}, err + } + if journal.MigrationID == plan.MigrationID && journal.PlanDigest == plan.PlanDigest { + if options.Rollback { + return Result{SchemaVersion: StatusSchemaVersion, Mode: "rollback", RolledBack: true, Plan: plan, Status: status}, nil + } + return Result{}, fail.New("MIGRATION_ROLLED_BACK", "this exact migration was rolled back; create and review a new preview") + } + if err := retireRolledBackJournal(repo.CommonDir, journal); err != nil { + return Result{}, err + } + journal, journalExists = Journal{}, false + } + if journalExists && (journal.MigrationID != plan.MigrationID || journal.PlanDigest != plan.PlanDigest) { + return Result{}, fail.New("MIGRATION_IN_PROGRESS", "a different coordination migration journal already exists") + } + if !journalExists { + if options.Resume || options.Rollback { + return Result{}, fail.New("MIGRATION_NOT_STARTED", "no migration journal exists for resume or rollback") + } + current, previewErr := Preview(ctx, repo, PreviewOptions{Producer: options.Producer}) + if previewErr != nil { + return Result{}, previewErr + } + if current.PlanDigest != plan.PlanDigest { + return Result{}, fail.Errorf("MIGRATION_PRESTATE_CHANGED", "current preview is %s, reviewed plan is %s", current.PlanDigest, plan.PlanDigest) + } + if err := verifyExactCanonicalPrestate(repo.CommonDir, plan); err != nil { + return Result{}, fail.Wrap("MIGRATION_PRESTATE_CHANGED", err) + } + } + if err := activateWriterFence(repo.CommonDir, plan); err != nil { + return Result{}, err + } + if err := persistBootstrapPlan(repo.CommonDir, plan); err != nil { + return Result{}, err + } + if journalExists { + if journal.Phase == phaseComplete { + status, statusErr := InspectStatus(repo, plan.MigrationID) + if statusErr == nil { + statusErr = deactivateWriterFence(repo.CommonDir, plan) + } + return Result{SchemaVersion: StatusSchemaVersion, Mode: mutationMode(options), Applied: true, Resumed: options.Resume, Plan: plan, Status: status, Receipt: status.Receipt}, statusErr + } + if !options.Resume { + if options.Rollback { + // The exact plan, journal, and canonical prefix are verified below + // before rollback removes any published migration output. + } else { + return Result{}, fail.New("MIGRATION_RESUME_REQUIRED", "an incomplete migration journal exists; use the exact plan and --resume or --rollback") + } + } + } else { + journal = Journal{ + SchemaVersion: JournalSchemaVersion, MigrationID: plan.MigrationID, PlanDigest: plan.PlanDigest, + ExpectedCanonicalDigest: plan.ExpectedCanonicalData.Digest, PlannedCanonicalDigest: plan.PlannedCanonicalData.Digest, + PublishedPaths: []string{}, Phase: phaseJournalCreated, UpdatedAt: time.Now().UTC(), + } + if err := writeJSON(journalPath, journal, 0o600, false); err != nil { + return Result{}, fail.Wrap("MIGRATION_JOURNAL_FAILED", err) + } + if err := afterPhase(journalPath, &journal, options, phaseJournalCreated); err != nil { + return Result{}, err + } + } + if err := verifyJournalPlanBinding(repo, plan, journal); err != nil { + return Result{}, recordJournalError(journalPath, &journal, err) + } + if err := verifyExistingMigrationArtifacts(repo, plan); err != nil { + return Result{}, recordJournalError(journalPath, &journal, err) + } + if err := verifyCanonicalTransition(repo.CommonDir, plan, journal, phaseRequiresCanonicalPost(journal.Phase)); err != nil { + return Result{}, recordJournalError(journalPath, &journal, fail.Wrap("MIGRATION_CANONICAL_MOVED", err)) + } + if journal.Phase == phaseRollbackStarted && !options.Rollback { + return Result{}, fail.New("MIGRATION_ROLLBACK_REQUIRED", "rollback has started; retry rollback with the exact reviewed plan") + } + if options.Rollback { + return rollback(ctx, repo, plan, journal, options) + } + + if phaseBefore(journal.Phase, phaseCanonicalPrepared) { + if err := verifySourcePrestate(repo, plan, false); err != nil { + return Result{}, recordJournalError(journalPath, &journal, err) + } + if err := prepareCanonical(repo, plan, func(path string) error { + return authorizePublishedPath(journalPath, &journal, path) + }); err != nil { + return Result{}, recordJournalError(journalPath, &journal, fail.Wrap("MIGRATION_PREPARE_FAILED", err)) + } + if err := advanceJournal(journalPath, &journal, phaseCanonicalPrepared); err != nil { + return Result{}, err + } + if err := afterPhase(journalPath, &journal, options, phaseCanonicalPrepared); err != nil { + return Result{}, err + } + } + if phaseBefore(journal.Phase, phaseRecordsPublished) { + if err := verifySourcePrestate(repo, plan, false); err != nil { + return Result{}, recordJournalError(journalPath, &journal, err) + } + if err := verifyExpectedRefs(ctx, repo, plan.ExpectedRefs); err != nil { + return Result{}, recordJournalError(journalPath, &journal, err) + } + if err := publishRecords(repo, plan, false, func(path string) error { + return authorizePublishedPath(journalPath, &journal, path) + }, func(operation string) error { + return afterOperation(journalPath, &journal, options, operation) + }); err != nil { + return Result{}, recordJournalError(journalPath, &journal, err) + } + if err := verifyPublished(repo, plan); err != nil { + return Result{}, recordJournalError(journalPath, &journal, err) + } + if err := verifyCanonicalTransition(repo.CommonDir, plan, journal, true); err != nil { + return Result{}, recordJournalError(journalPath, &journal, fail.Wrap("MIGRATION_CANONICAL_MOVED", err)) + } + if err := advanceJournal(journalPath, &journal, phaseRecordsPublished); err != nil { + return Result{}, err + } + if err := afterPhase(journalPath, &journal, options, phaseRecordsPublished); err != nil { + return Result{}, err + } + } + if phaseBefore(journal.Phase, phaseSourceMoved) { + moved, err := sourceAlreadyMoved(repo, plan) + if err != nil { + return Result{}, recordJournalError(journalPath, &journal, err) + } + if !moved { + if err := verifySourcePrestate(repo, plan, false); err != nil { + return Result{}, recordJournalError(journalPath, &journal, err) + } + if err := verifyPublished(repo, plan); err != nil { + return Result{}, recordJournalError(journalPath, &journal, err) + } + if err := moveLegacySource(repo, plan, func(path string) error { + return authorizePublishedPath(journalPath, &journal, path) + }); err != nil { + return Result{}, recordJournalError(journalPath, &journal, err) + } + if err := afterOperation(journalPath, &journal, options, "source-renamed"); err != nil { + return Result{}, err + } + } + if err := advanceJournal(journalPath, &journal, phaseSourceMoved); err != nil { + return Result{}, err + } + if err := afterPhase(journalPath, &journal, options, phaseSourceMoved); err != nil { + return Result{}, err + } + } + if phaseBefore(journal.Phase, phaseArchiveSealed) { + if err := verifyArchivedSource(repo, plan); err != nil { + return Result{}, recordJournalError(journalPath, &journal, err) + } + if err := sealLegacyArchive(repo, plan, func(path string) error { + return authorizePublishedPath(journalPath, &journal, path) + }); err != nil { + return Result{}, recordJournalError(journalPath, &journal, err) + } + if err := afterOperation(journalPath, &journal, options, "archive-seal-written"); err != nil { + return Result{}, err + } + if err := advanceJournal(journalPath, &journal, phaseArchiveSealed); err != nil { + return Result{}, err + } + if err := afterPhase(journalPath, &journal, options, phaseArchiveSealed); err != nil { + return Result{}, err + } + } + if phaseBefore(journal.Phase, phaseComplete) { + if err := verifyExpectedRefs(ctx, repo, plan.ExpectedRefs); err != nil { + return Result{}, recordJournalError(journalPath, &journal, err) + } + if err := verifyPublished(repo, plan); err != nil { + return Result{}, recordJournalError(journalPath, &journal, err) + } + if err := verifyCanonicalTransition(repo.CommonDir, plan, journal, true); err != nil { + return Result{}, recordJournalError(journalPath, &journal, fail.Wrap("MIGRATION_CANONICAL_MOVED", err)) + } + if err := verifyArchivedSource(repo, plan); err != nil { + return Result{}, recordJournalError(journalPath, &journal, err) + } + receiptPath := migrationReceiptRelativePath(plan.MigrationID) + if err := authorizePublishedPath(journalPath, &journal, receiptPath); err != nil { + return Result{}, err + } + receipt, err := completeReceipt(repo, plan) + if err != nil { + return Result{}, recordJournalError(journalPath, &journal, err) + } + if err := afterOperation(journalPath, &journal, options, "receipt-written"); err != nil { + return Result{}, err + } + if err := advanceJournal(journalPath, &journal, phaseComplete); err != nil { + return Result{}, err + } + if err := afterPhase(journalPath, &journal, options, phaseComplete); err != nil { + return Result{}, err + } + status, statusErr := InspectStatus(repo, plan.MigrationID) + if statusErr == nil { + statusErr = deactivateWriterFence(repo.CommonDir, plan) + } + return Result{SchemaVersion: StatusSchemaVersion, Mode: mutationMode(options), Applied: true, Resumed: options.Resume, Plan: plan, Status: status, Receipt: &receipt}, statusErr + } + return Result{}, fail.New("MIGRATION_JOURNAL_INVALID", "migration journal has an unsupported phase") +} + +func verifyExistingMigrationArtifacts(repo gitx.Repo, plan Plan) error { + if plan.SourceLegacy.Exists { + moved, err := sourceAlreadyMoved(repo, plan) + if err != nil { + return err + } + if moved { + if err := verifyArchivedSource(repo, plan); err != nil { + return err + } + } + } + checks := []struct { + path string + code string + run func() error + }{ + {filepath.Join(archiveMigrationRoot(repo.CommonDir, plan.MigrationID), "seal.json"), "MIGRATION_ARCHIVE_INVALID", func() error { return validateTransitionSeal(repo.CommonDir, plan) }}, + {migrationReceiptPath(repo.CommonDir, plan.MigrationID), "MIGRATION_RECEIPT_INVALID", func() error { return validateTransitionReceipt(repo.CommonDir, plan) }}, + {filepath.Join(repo.CommonDir, "wip", "migration", "v1", plan.MigrationID, "rollback.json"), "MIGRATION_ROLLBACK_INVALID", func() error { return validateTransitionRollback(repo.CommonDir, plan) }}, + } + for _, check := range checks { + if _, err := os.Lstat(check.path); errors.Is(err, os.ErrNotExist) { + continue + } else if err != nil { + return fail.Wrap(check.code, err) + } + if err := check.run(); err != nil { + return fail.Wrap(check.code, err) + } + } + return nil +} + +func mutationMode(options ApplyOptions) string { + if options.Resume { + return "resume" + } + if options.Rollback { + return "rollback" + } + return "apply" +} + +func validateApplyRequest(repo gitx.Repo, plan Plan, expectedDigest string, options ApplyOptions) error { + if plan.SchemaVersion != PlanSchemaVersion || plan.State != "ready" || len(plan.Conflicts) != 0 { + return fail.New("MIGRATION_PLAN_BLOCKED", "only a ready, conflict-free migration plan can be applied") + } + if filepath.Clean(plan.RepositoryCommonDir) != filepath.Clean(repo.CommonDir) { + return fail.New("MIGRATION_REPOSITORY_MISMATCH", "the plan belongs to a different Git common directory") + } + if err := plan.ValidateDigest(expectedDigest); err != nil { + return fail.Wrap("MIGRATION_PLAN_DIGEST_MISMATCH", err) + } + if err := options.Producer.Validate(); err != nil { + return fail.Wrap("MIGRATION_PRODUCER_INVALID", err) + } + if options.Producer != plan.Producer { + return fail.New("MIGRATION_PRODUCER_MISMATCH", "the running executable, source, protocol, or portable bundle differs from the reviewed plan producer") + } + if !digestPattern.MatchString(plan.ExpectedCanonicalData.Digest) || !digestPattern.MatchString(plan.PlannedCanonicalData.Digest) { + return fail.New("MIGRATION_PLAN_BLOCKED", "migration plan has invalid canonical manifest bindings") + } + wantPlanned, err := planCanonicalData(plan.ExpectedCanonicalData, plan) + if err != nil || wantPlanned.Digest != plan.PlannedCanonicalData.Digest { + return fail.New("MIGRATION_PLAN_BLOCKED", "migration plan post-publication manifest is invalid") + } + if options.Resume && options.Rollback { + return fail.New("INVALID_ARGUMENT", "resume and rollback are mutually exclusive") + } + if options.LockWait < 0 || options.LockWait > filelock.MaxWait { + return fail.New("INVALID_ARGUMENT", "migration lock wait is outside the supported range") + } + return nil +} + +func migrationJournalPath(commonDir string) string { + return filepath.Join(commonDir, "wip-coordination-migration-v1.journal.json") +} + +func readJournal(path string) (Journal, bool, error) { + var journal Journal + _, err := readJSONFileLimit(path, &journal, MaxPlanBytes) + if errors.Is(err, os.ErrNotExist) { + return Journal{}, false, nil + } + if err != nil { + return Journal{}, false, fail.Wrap("MIGRATION_JOURNAL_INVALID", err) + } + if journal.SchemaVersion != JournalSchemaVersion || phaseOrder[journal.Phase] < 0 || !migrationIDPattern.MatchString(journal.MigrationID) || !digestPattern.MatchString(journal.PlanDigest) || !digestPattern.MatchString(journal.ExpectedCanonicalDigest) || !digestPattern.MatchString(journal.PlannedCanonicalDigest) { + return Journal{}, false, fail.New("MIGRATION_JOURNAL_INVALID", "migration journal schema or phase is invalid") + } + if _, ok := phaseOrder[journal.Phase]; !ok { + return Journal{}, false, fail.New("MIGRATION_JOURNAL_INVALID", "migration journal phase is invalid") + } + seen := map[string]bool{} + for _, path := range journal.PublishedPaths { + clean := filepath.ToSlash(filepath.Clean(filepath.FromSlash(path))) + if clean != path || filepath.IsAbs(path) || path == "." || path == ".." || lenPrefix(path, "../") || seen[path] { + return Journal{}, false, fail.New("MIGRATION_JOURNAL_INVALID", "migration journal contains an invalid or duplicate published path") + } + seen[path] = true + } + return journal, true, nil +} + +func authorizePublishedPath(path string, journal *Journal, published string) error { + published = filepath.ToSlash(filepath.Clean(filepath.FromSlash(published))) + for _, existing := range journal.PublishedPaths { + if existing == published { + return nil + } + } + journal.PublishedPaths = append(journal.PublishedPaths, published) + journal.UpdatedAt = time.Now().UTC() + if err := writeJSON(path, journal, 0o600, true); err != nil { + return fail.Wrap("MIGRATION_JOURNAL_FAILED", err) + } + return nil +} + +func phaseBefore(current, target string) bool { return phaseOrder[current] < phaseOrder[target] } + +func phaseRequiresCanonicalPost(phase string) bool { + return !phaseBefore(phase, phaseRecordsPublished) && phase != phaseRollbackStarted && phase != phaseRolledBack +} + +func advanceJournal(path string, journal *Journal, phase string) error { + journal.Phase = phase + journal.UpdatedAt = time.Now().UTC() + journal.LastError = "" + if err := writeJSON(path, journal, 0o600, true); err != nil { + return fail.Wrap("MIGRATION_JOURNAL_FAILED", err) + } + return nil +} + +func recordJournalError(path string, journal *Journal, cause error) error { + journal.UpdatedAt = time.Now().UTC() + journal.LastError = cause.Error() + if err := writeJSON(path, journal, 0o600, true); err != nil { + return fail.Wrap("MIGRATION_JOURNAL_FAILED", errors.Join(cause, err)) + } + return cause +} + +func afterPhase(path string, journal *Journal, options ApplyOptions, phase string) error { + if options.AfterPhase == nil { + return nil + } + if err := options.AfterPhase(phase); err != nil { + return recordJournalError(path, journal, fail.Wrap("MIGRATION_INTERRUPTED", err)) + } + return nil +} + +func afterOperation(path string, journal *Journal, options ApplyOptions, operation string) error { + if options.AfterOperation == nil { + return nil + } + if err := options.AfterOperation(operation); err != nil { + return recordJournalError(path, journal, fail.Wrap("MIGRATION_INTERRUPTED", err)) + } + return nil +} + +func prepareCanonical(repo gitx.Repo, plan Plan, authorize func(string) error) error { + paths := []string{ + "wip", "wip/v1", "wip/v1/lanes", "wip/v1/leases", "wip/v1/locks", "wip/v1/intents", "wip/v1/profiles", "wip/v1/init-intents", "wip/v1/archive", + "wip/review", "wip/review/v1", "wip/review/v1/locks", "wip/review/v1/handoffs", "wip/review/v1/landing-intents", "wip/review/v1/archive", "wip/review/v1/capture-aborts", "wip/review/v1/capture-completions", "wip/review/v1/capture-reservations", "wip/review/v1/plans", "wip/review/v1/reconciliation", + "wip/archive", "wip/archive/legacy-ndev-wip", "wip/migration", "wip/migration/v1", filepath.ToSlash(filepath.Join("wip", "migration", "v1", plan.MigrationID)), + } + for _, path := range paths { + if authorize != nil { + if err := authorize(path); err != nil { + return err + } + } + if err := ensureDirectoryPath(repo.CommonDir, path, 0o700); err != nil { + return err + } + } + if !manifestContainsPath(plan.ExpectedCanonicalData.Capture, captureRegistryLock) { + lockRelative := "wip/v1/" + captureRegistryLock + if authorize != nil { + if err := authorize(lockRelative); err != nil { + return err + } + } + if err := createConfinedExact(repo.CommonDir, lockRelative, nil, 0o600); err != nil { + return err + } + } + reviewMarker, err := ndevReviewDomainBody() + if err != nil { + return err + } + if authorize != nil { + if err := authorize("wip/review/v1/domain.json"); err != nil { + return err + } + } + if err := createConfinedExact(repo.CommonDir, "wip/review/v1/domain.json", reviewMarker, 0o600); err != nil { + return err + } + marker := domainRecord{SchemaVersion: 2, Domain: DomainID, StateVersion: 1, MinimumReaderProtocol: contract.Protocol, RequiredCapabilities: contract.StateReaderCapabilities()} + markerBody, err := normalizedJSON(marker) + if err != nil { + return err + } + markerPath := filepath.Join(repo.CommonDir, "wip", "domain.json") + if plan.ExpectedCanonical.Exists { + existing, readErr := safeio.ReadRegular(markerPath, maxRecordBytes) + if readErr != nil || !bytes.Equal(existing, markerBody) { + return fmt.Errorf("canonical domain marker changed after preview") + } + } else { + if authorize != nil { + if err := authorize("wip/domain.json"); err != nil { + return err + } + } + if err := createConfinedExact(repo.CommonDir, "wip/domain.json", markerBody, 0o600); err != nil { + return err + } + } + planBody, err := normalizedJSON(plan) + if err != nil { + return err + } + planRelative := filepath.ToSlash(filepath.Join("wip", "migration", "v1", plan.MigrationID, "plan.json")) + if authorize != nil { + if err := authorize(planRelative); err != nil { + return err + } + } + return createConfinedExact(repo.CommonDir, planRelative, planBody, 0o400) +} + +func manifestContainsPath(manifest TreeManifest, path string) bool { + for _, entry := range manifest.Entries { + if entry.Path == path { + return true + } + } + return false +} + +func ensureDirectoryPath(commonDir, relative string, mode os.FileMode) error { + clean := filepath.Clean(filepath.FromSlash(relative)) + current := commonDir + for _, component := range splitPath(clean) { + current = filepath.Join(current, component) + info, err := os.Lstat(current) + if errors.Is(err, os.ErrNotExist) { + if err := os.Mkdir(current, mode); err != nil && !errors.Is(err, os.ErrExist) { + return err + } + info, err = os.Lstat(current) + } + if err != nil || !info.IsDir() || info.Mode()&os.ModeSymlink != 0 { + if err != nil { + return err + } + return fmt.Errorf("state directory is unsafe: %s", current) + } + } + return nil +} + +func splitPath(path string) []string { + var parts []string + for path != "." && path != string(filepath.Separator) && path != "" { + directory, base := filepath.Split(path) + parts = append(parts, base) + path = filepath.Clean(directory) + } + slices.Reverse(parts) + return parts +} + +func migrationPlanPath(commonDir, migrationID string) string { + return filepath.Join(commonDir, "wip", "migration", "v1", migrationID, "plan.json") +} + +func migrationReceiptPath(commonDir, migrationID string) string { + return filepath.Join(commonDir, "wip", "migration", "v1", migrationID, "receipt.json") +} + +func archiveMigrationRoot(commonDir, migrationID string) string { + return filepath.Join(commonDir, "wip", "archive", "legacy-ndev-wip", migrationID) +} + +func publishRecords(repo gitx.Repo, plan Plan, archived bool, authorize func(string) error, onPublished func(string) error) error { + legacyRoot := filepath.Join(repo.CommonDir, "ndev-wip") + if archived { + legacyRoot = filepath.Join(archiveMigrationRoot(repo.CommonDir, plan.MigrationID), "source") + } + for _, record := range append(slices.Clone(plan.LaneImports), plan.LeaseImports...) { + if record.Action == "match" || record.Action == "archive-only" { + continue + } + if record.Action != "import" { + return fmt.Errorf("unsupported import action %s", record.Action) + } + var value any + source := filepath.Join(legacyRoot, filepath.FromSlash(stringsTrimLegacy(record.Source))) + if record.Kind == "lane" { + value = &legacyLane{} + } else { + value = &legacyLease{} + } + if _, err := readJSONFile(source, value); err != nil { + return err + } + body, err := normalizedJSON(value) + if err != nil || digest(body) != record.SourceSHA256 { + return fmt.Errorf("normalized source changed for %s %s", record.Kind, record.ID) + } + if authorize != nil { + if err := ensureAuthorizedParents(repo.CommonDir, record.Destination, authorize); err != nil { + return err + } + if err := authorize(record.Destination); err != nil { + return err + } + } + if err := createConfinedExact(repo.CommonDir, record.Destination, body, 0o600); err != nil { + return err + } + if onPublished != nil { + if err := onPublished("record-published:" + record.Destination); err != nil { + return err + } + } + } + for _, record := range append(slices.Clone(plan.ReviewCopies), plan.ReconciliationCopies...) { + if record.Action == "match" { + continue + } + mode, err := parseMode(record.Mode) + if err != nil { + return err + } + source := filepath.Join(repo.CommonDir, filepath.FromSlash(record.Source)) + if archived && record.Kind == "legacy-review" { + source = filepath.Join(legacyRoot, filepath.FromSlash(stringsTrimLegacy(record.Source))) + } + if authorize != nil { + if err := ensureAuthorizedParents(repo.CommonDir, record.Destination, authorize); err != nil { + return err + } + if err := authorize(record.Destination); err != nil { + return err + } + } + if err := copyConfinedExact(source, repo.CommonDir, record.Destination, record.SourceSHA256, mode); err != nil { + return err + } + if onPublished != nil { + if err := onPublished("record-published:" + record.Destination); err != nil { + return err + } + } + } + return nil +} + +func ensureAuthorizedParents(commonDir, destination string, authorize func(string) error) error { + clean := filepath.ToSlash(filepath.Clean(filepath.FromSlash(destination))) + parent := filepath.ToSlash(filepath.Dir(clean)) + var parents []string + for parent != "." && parent != "" { + parents = append(parents, parent) + next := filepath.ToSlash(filepath.Dir(parent)) + if next == parent { + break + } + parent = next + } + slices.Reverse(parents) + for _, path := range parents { + if err := authorize(path); err != nil { + return err + } + if err := ensureDirectoryPath(commonDir, path, 0o700); err != nil { + return err + } + } + return nil +} + +func stringsTrimLegacy(path string) string { + prefix := "ndev-wip/" + if len(path) >= len(prefix) && filepath.ToSlash(path[:len(prefix)]) == prefix { + return path[len(prefix):] + } + return path +} + +func verifyPublished(repo gitx.Repo, plan Plan) error { + for _, record := range append(slices.Clone(plan.LaneImports), plan.LeaseImports...) { + if record.Action == "archive-only" { + continue + } + body, err := safeio.ReadRegular(filepath.Join(repo.CommonDir, filepath.FromSlash(record.Destination)), maxRecordBytes) + if err != nil || digest(body) != record.SourceSHA256 { + return fmt.Errorf("published %s %s does not match the reviewed normalized record", record.Kind, record.ID) + } + } + for _, record := range append(slices.Clone(plan.ReviewCopies), plan.ReconciliationCopies...) { + path := filepath.Join(repo.CommonDir, filepath.FromSlash(record.Destination)) + body, err := safeio.ReadRegular(path, maxManifestBytes) + if err != nil || digest(body) != record.SourceSHA256 { + return fmt.Errorf("published review record does not match %s", record.Destination) + } + info, err := os.Lstat(path) + if err != nil || modeString(info.Mode().Perm()) != record.Mode { + return fmt.Errorf("published review mode does not match %s", record.Destination) + } + } + return nil +} + +func verifyExpectedRefs(ctx context.Context, repo gitx.Repo, refs []RefExpectation) error { + for _, expected := range refs { + actual, err := repo.Text(ctx, nil, "rev-parse", "--verify", expected.Ref+"^{commit}") + if err != nil || actual != expected.SHA { + return fail.Errorf("MIGRATION_REF_MOVED", "ref %s no longer equals reviewed SHA %s", expected.Ref, expected.SHA) + } + } + return nil +} + +func verifySourcePrestate(repo gitx.Repo, plan Plan, archived bool) error { + logical := "ndev-wip" + if archived { + logical = filepath.ToSlash(filepath.Join("wip", "archive", "legacy-ndev-wip", plan.MigrationID, "source")) + } + current, err := manifestTree(repo.CommonDir, logical) + if err != nil { + return fail.Wrap("MIGRATION_SOURCE_UNSAFE", err) + } + if !archived && current.Digest != plan.SourceLegacy.Digest { + return fail.New("MIGRATION_SOURCE_MOVED", "legacy source changed after the reviewed preview") + } + if archived { + return compareArchivedSource(plan.SourceLegacy, current) + } + return nil +} + +func verifyArchivedSource(repo gitx.Repo, plan Plan) error { + if !plan.SourceLegacy.Exists { + return nil + } + current, err := manifestTree(repo.CommonDir, filepath.ToSlash(filepath.Join("wip", "archive", "legacy-ndev-wip", plan.MigrationID, "source"))) + if err != nil { + return fail.Wrap("MIGRATION_ARCHIVE_UNSAFE", err) + } + return compareArchivedSource(plan.SourceLegacy, current) +} + +// Sealing intentionally changes permissions. Compare the exact topology and +// file bytes while allowing only that reviewed permission transformation. +func compareArchivedSource(expected, current TreeManifest) error { + if !current.Exists && expected.Exists { + return fail.New("MIGRATION_ARCHIVE_MISSING", "moved legacy source is absent from the expected archive") + } + if expected.Exists != current.Exists || len(expected.Entries) != len(current.Entries) { + return fail.New("MIGRATION_ARCHIVE_MOVED", "moved legacy archive topology differs from the reviewed source") + } + want := sortedEntries(expected.Entries) + got := sortedEntries(current.Entries) + for index := range want { + if want[index].Path != got[index].Path || want[index].Type != got[index].Type || want[index].Size != got[index].Size || want[index].SHA256 != got[index].SHA256 { + return fail.New("MIGRATION_ARCHIVE_MOVED", "moved legacy archive paths or bytes differ from the reviewed source") + } + if got[index].Type == "file" && got[index].Mode != want[index].Mode && got[index].Mode != "0400" { + return fail.New("MIGRATION_ARCHIVE_MOVED", "moved legacy archive has an unexpected file mode") + } + if got[index].Type == "directory" && got[index].Mode != want[index].Mode && got[index].Mode != "0500" { + return fail.New("MIGRATION_ARCHIVE_MOVED", "moved legacy archive has an unexpected directory mode") + } + } + return nil +} + +func moveLegacySource(repo gitx.Repo, plan Plan, authorize func(string) error) error { + if !plan.SourceLegacy.Exists { + return nil + } + archiveRoot := archiveMigrationRoot(repo.CommonDir, plan.MigrationID) + archiveRelative := filepath.ToSlash(filepath.Join("wip", "archive", "legacy-ndev-wip", plan.MigrationID)) + if err := ensureAuthorizedParents(repo.CommonDir, filepath.ToSlash(filepath.Join(archiveRelative, "source")), authorize); err != nil { + return err + } + for _, entry := range plan.SourceLegacy.Entries { + path := filepath.ToSlash(filepath.Join(archiveRelative, "source")) + if entry.Path != "." { + path = filepath.ToSlash(filepath.Join(path, filepath.FromSlash(entry.Path))) + } + if err := authorize(path); err != nil { + return err + } + } + destination := filepath.Join(archiveRoot, "source") + if _, err := os.Lstat(destination); err == nil { + return fail.New("MIGRATION_ARCHIVE_CONFLICT", "archive source already exists before the legacy move") + } else if !errors.Is(err, os.ErrNotExist) { + return err + } + if err := os.Rename(filepath.Join(repo.CommonDir, "ndev-wip"), destination); err != nil { + return fail.Wrap("MIGRATION_SOURCE_MOVE_FAILED", err) + } + if err := syncDirectory(repo.CommonDir); err != nil { + return err + } + return syncDirectory(archiveRoot) +} + +func sourceAlreadyMoved(repo gitx.Repo, plan Plan) (bool, error) { + if !plan.SourceLegacy.Exists { + return true, nil + } + sourceInfo, sourceErr := os.Lstat(filepath.Join(repo.CommonDir, "ndev-wip")) + archiveInfo, archiveErr := os.Lstat(filepath.Join(archiveMigrationRoot(repo.CommonDir, plan.MigrationID), "source")) + sourceExists := sourceErr == nil && sourceInfo.IsDir() && sourceInfo.Mode()&os.ModeSymlink == 0 + archiveExists := archiveErr == nil && archiveInfo.IsDir() && archiveInfo.Mode()&os.ModeSymlink == 0 + if sourceExists && !archiveExists { + return false, nil + } + if !sourceExists && archiveExists { + return true, nil + } + if sourceErr != nil && !errors.Is(sourceErr, os.ErrNotExist) { + return false, sourceErr + } + if archiveErr != nil && !errors.Is(archiveErr, os.ErrNotExist) { + return false, archiveErr + } + return false, fail.New("MIGRATION_SOURCE_STATE_INVALID", "legacy source and archive source are both present or both absent") +} + +func sealLegacyArchive(repo gitx.Repo, plan Plan, authorize func(string) error) error { + if !plan.SourceLegacy.Exists { + return nil + } + archiveRoot := archiveMigrationRoot(repo.CommonDir, plan.MigrationID) + sourceRoot := filepath.Join(archiveRoot, "source") + sealRelative := filepath.ToSlash(filepath.Join("wip", "archive", "legacy-ndev-wip", plan.MigrationID, "seal.json")) + if err := authorize(sealRelative); err != nil { + return err + } + if err := verifyArchivedSource(repo, plan); err != nil { + return err + } + if err := sealArchiveTree(sourceRoot); err != nil { + return fail.Wrap("MIGRATION_SEAL_FAILED", err) + } + if err := verifyArchivedSource(repo, plan); err != nil { + return err + } + archiveManifest, err := manifestTree(repo.CommonDir, filepath.ToSlash(filepath.Join("wip", "archive", "legacy-ndev-wip", plan.MigrationID, "source"))) + if err != nil { + return err + } + seal := Seal{SchemaVersion: SealSchemaVersion, MigrationID: plan.MigrationID, PlanDigest: plan.PlanDigest, SourceManifest: plan.SourceLegacy.Digest, ArchiveManifest: archiveManifest.Digest, ArchiveRelativeDir: filepath.ToSlash(filepath.Join("wip", "archive", "legacy-ndev-wip", plan.MigrationID, "source")), SealedAt: time.Now().UTC()} + if err := writeJSON(filepath.Join(archiveRoot, "seal.json"), seal, 0o400, false); err != nil { + if !isExactSeal(filepath.Join(archiveRoot, "seal.json"), seal) { + return err + } + } + return syncDirectory(archiveRoot) +} + +func isExactSeal(path string, expected Seal) bool { + var actual Seal + if _, err := readJSONFile(path, &actual); err != nil { + return false + } + return actual.SchemaVersion == expected.SchemaVersion && actual.MigrationID == expected.MigrationID && actual.PlanDigest == expected.PlanDigest && actual.SourceManifest == expected.SourceManifest && actual.ArchiveManifest == expected.ArchiveManifest && actual.ArchiveRelativeDir == expected.ArchiveRelativeDir +} + +func completeReceipt(repo gitx.Repo, plan Plan) (Receipt, error) { + path := migrationReceiptPath(repo.CommonDir, plan.MigrationID) + var existing Receipt + if _, err := readJSONFile(path, &existing); err == nil { + if validateErr := validateReceipt(existing, plan.MigrationID); validateErr != nil || existing.PlanDigest != plan.PlanDigest || existing.SourceManifest != plan.SourceLegacy.Digest || existing.ReconciliationHistory != plan.ReconciliationHistory.Digest { + if validateErr != nil { + return Receipt{}, validateErr + } + return Receipt{}, errors.New("existing migration receipt does not match the reviewed plan") + } + return existing, nil + } else if !errors.Is(err, os.ErrNotExist) { + return Receipt{}, err + } + if plan.SourceLegacy.Exists { + if _, err := os.Lstat(filepath.Join(repo.CommonDir, "ndev-wip")); !errors.Is(err, os.ErrNotExist) { + return Receipt{}, fail.New("MIGRATION_SOURCE_NOT_REMOVED", "legacy source remains present after archive publication") + } + if err := verifyArchivedSource(repo, plan); err != nil { + return Receipt{}, err + } + } + canonical, err := manifestCanonicalData(repo.CommonDir) + if err != nil { + return Receipt{}, err + } + if canonical.Digest != plan.PlannedCanonicalData.Digest { + return Receipt{}, fail.New("MIGRATION_CANONICAL_MOVED", "canonical data does not match the reviewed post-publication manifest: "+canonicalManifestDifference(plan.PlannedCanonicalData, canonical)) + } + canonicalDigest := canonical.Digest + archiveDigest := "" + if plan.SourceLegacy.Exists { + archive, manifestErr := manifestTree(repo.CommonDir, filepath.ToSlash(filepath.Join("wip", "archive", "legacy-ndev-wip", plan.MigrationID, "source"))) + if manifestErr != nil { + return Receipt{}, manifestErr + } + archiveDigest = archive.Digest + } + receipt := Receipt{SchemaVersion: ReceiptSchemaVersion, MigrationID: plan.MigrationID, PlanDigest: plan.PlanDigest, SourceManifest: plan.SourceLegacy.Digest, CanonicalManifest: canonicalDigest, ArchiveManifest: archiveDigest, ReconciliationHistory: plan.ReconciliationHistory.Digest, CompletedAt: time.Now().UTC()} + body, err := normalizedJSON(receipt) + if err != nil { + return Receipt{}, err + } + receipt.ReceiptDigest = digest(body) + if err := writeJSON(path, receipt, 0o400, false); err != nil { + var existing Receipt + if _, readErr := readJSONFile(path, &existing); readErr != nil || existing.PlanDigest != receipt.PlanDigest || existing.CanonicalManifest != receipt.CanonicalManifest || existing.ArchiveManifest != receipt.ArchiveManifest || existing.ReceiptDigest != receipt.ReceiptDigest { + return Receipt{}, err + } + return existing, nil + } + return receipt, nil +} + +func rollback(ctx context.Context, repo gitx.Repo, plan Plan, journal Journal, options ApplyOptions) (Result, error) { + moved, err := sourceAlreadyMoved(repo, plan) + if err != nil && plan.SourceLegacy.Exists { + return Result{}, err + } + if moved && plan.SourceLegacy.Exists { + return Result{}, fail.New("MIGRATION_ROLLBACK_REFUSED", "legacy source has moved; resume forward to preserve the verified archive") + } + if err := verifyExpectedRefs(ctx, repo, plan.ExpectedRefs); err != nil { + return Result{}, err + } + journalPath := migrationJournalPath(repo.CommonDir) + if journal.Phase != phaseRollbackStarted { + if err := advanceJournal(journalPath, &journal, phaseRollbackStarted); err != nil { + return Result{}, err + } + if err := afterPhase(journalPath, &journal, options, phaseRollbackStarted); err != nil { + return Result{}, err + } + } + for _, record := range append(slices.Clone(plan.ReconciliationCopies), plan.ReviewCopies...) { + if record.Action == "copy" { + if err := removeExactFile(filepath.Join(repo.CommonDir, filepath.FromSlash(record.Destination)), record.SourceSHA256); err != nil { + return Result{}, fail.Wrap("MIGRATION_ROLLBACK_FAILED", err) + } + if err := afterOperation(journalPath, &journal, options, "rollback-removed:"+record.Destination); err != nil { + return Result{}, err + } + } + } + for _, record := range append(slices.Clone(plan.LeaseImports), plan.LaneImports...) { + if record.Action == "import" { + if err := removeExactFile(filepath.Join(repo.CommonDir, filepath.FromSlash(record.Destination)), record.SourceSHA256); err != nil { + return Result{}, fail.Wrap("MIGRATION_ROLLBACK_FAILED", err) + } + if err := afterOperation(journalPath, &journal, options, "rollback-removed:"+record.Destination); err != nil { + return Result{}, err + } + } + } + marker := RollbackMarker{SchemaVersion: RollbackSchemaVersion, MigrationID: plan.MigrationID, PlanDigest: plan.PlanDigest, State: "rolled-back", Reason: "operator requested rollback before the legacy source move", UpdatedAt: time.Now().UTC()} + markerPath := filepath.Join(repo.CommonDir, "wip", "migration", "v1", plan.MigrationID, "rollback.json") + markerRelative := filepath.ToSlash(filepath.Join("wip", "migration", "v1", plan.MigrationID, "rollback.json")) + if err := authorizePublishedPath(journalPath, &journal, markerRelative); err != nil { + return Result{}, err + } + if err := writeJSON(markerPath, marker, 0o400, true); err != nil { + return Result{}, fail.Wrap("MIGRATION_ROLLBACK_FAILED", err) + } + if err := advanceJournal(journalPath, &journal, phaseRolledBack); err != nil { + return Result{}, err + } + status, statusErr := InspectStatus(repo, plan.MigrationID) + if statusErr == nil { + statusErr = deactivateWriterFence(repo.CommonDir, plan) + } + return Result{SchemaVersion: StatusSchemaVersion, Mode: "rollback", RolledBack: true, Plan: plan, Status: status}, statusErr +} + +func sortedEntries(entries []ManifestEntry) []ManifestEntry { + result := slices.Clone(entries) + sort.Slice(result, func(i, j int) bool { return result[i].Path < result[j].Path }) + return result +} diff --git a/internal/coordmigration/canonical.go b/internal/coordmigration/canonical.go new file mode 100644 index 0000000..a0c154a --- /dev/null +++ b/internal/coordmigration/canonical.go @@ -0,0 +1,587 @@ +package coordmigration + +import ( + "encoding/json" + "errors" + "fmt" + "os" + "path/filepath" + "sort" + + "github.com/nstranquist/wip-commit/internal/contract" +) + +var ( + captureDirectories = []string{".", "archive", "init-intents", "intents", "lanes", "leases", "locks", "profiles"} + reviewDirectories = []string{".", "archive", "capture-aborts", "capture-completions", "capture-reservations", "handoffs", "landing-intents", "locks", "plans", "reconciliation"} +) + +const captureRegistryLock = "locks/leases.lock" + +// ndevReviewDomainRecord is the exact NDev 0.5.0 review authority marker. +// The paired beta migration publishes this marker and every required empty +// directory in the same reviewed canonical manifest as imported records. +type ndevReviewDomainRecord struct { + SchemaVersion int `json:"schema_version"` + Domain string `json:"domain"` + StateVersion int `json:"state_version"` + Authority string `json:"authority"` + QueueEntrySchemaVersion int `json:"queue_entry_schema_version"` + HandoffSchemaVersion string `json:"handoff_schema_version"` + AutomaticLanding bool `json:"automatic_landing"` + HandoffLandingAuthorized bool `json:"handoff_landing_authorized"` + ReviewDigestRequired bool `json:"review_digest_required"` +} + +func ndevReviewDomainBody() ([]byte, error) { + body, err := json.Marshal(ndevReviewDomainRecord{ + SchemaVersion: 1, Domain: "nicos.tools/ndev/wip-review", StateVersion: 2, + Authority: "ndev", QueueEntrySchemaVersion: 2, HandoffSchemaVersion: "2.0.0", + AutomaticLanding: false, HandoffLandingAuthorized: false, ReviewDigestRequired: true, + }) + if err != nil { + return nil, err + } + return append(body, '\n'), nil +} + +func manifestCanonicalData(commonDir string) (CanonicalManifest, error) { + capture, err := manifestTree(commonDir, filepath.ToSlash(filepath.Join("wip", "v1"))) + if err != nil { + return CanonicalManifest{}, err + } + review, err := manifestTree(commonDir, filepath.ToSlash(filepath.Join("wip", "review", "v1"))) + if err != nil { + return CanonicalManifest{}, err + } + return combineCanonical(capture, review), nil +} + +func combineCanonical(capture, review TreeManifest) CanonicalManifest { + return CanonicalManifest{ + Capture: capture, + Review: review, + Digest: digest([]byte(capture.Digest + "\x00" + review.Digest)), + } +} + +func planCanonicalData(expected CanonicalManifest, plan Plan) (CanonicalManifest, error) { + capture, err := plannedTree(expected.Capture, captureDirectories) + if err != nil { + return CanonicalManifest{}, err + } + if err := planCaptureRegistryLock(&capture); err != nil { + return CanonicalManifest{}, err + } + review, err := plannedTree(expected.Review, reviewDirectories) + if err != nil { + return CanonicalManifest{}, err + } + reviewMarker, err := ndevReviewDomainBody() + if err != nil { + return CanonicalManifest{}, err + } + if err := putPlannedFile(&review, "wip/review/v1/domain.json", "wip/review/v1", int64(len(reviewMarker)), digest(reviewMarker), "0600"); err != nil { + return CanonicalManifest{}, err + } + for _, record := range append(append([]ImportRecord{}, plan.LaneImports...), plan.LeaseImports...) { + if record.Action != "import" && record.Action != "match" { + continue + } + if err := putPlannedFile(&capture, record.Destination, "wip/v1", record.Size, record.SourceSHA256, "0600"); err != nil { + return CanonicalManifest{}, err + } + } + for _, record := range append(append([]CopyRecord{}, plan.ReviewCopies...), plan.ReconciliationCopies...) { + if record.Action != "copy" && record.Action != "match" { + continue + } + if err := putPlannedFile(&review, record.Destination, "wip/review/v1", record.Size, record.SourceSHA256, record.Mode); err != nil { + return CanonicalManifest{}, err + } + } + if err := finishManifest(&capture); err != nil { + return CanonicalManifest{}, err + } + if err := finishManifest(&review); err != nil { + return CanonicalManifest{}, err + } + return combineCanonical(capture, review), nil +} + +// planCaptureRegistryLock adds the stable empty lock artifact when the +// canonical prestate has no registry lock. Existing lock bytes remain exact. +func planCaptureRegistryLock(manifest *TreeManifest) error { + for _, entry := range manifest.Entries { + if entry.Path != captureRegistryLock { + continue + } + if entry.Type != "file" { + return fmt.Errorf("canonical path %s is not a file", captureRegistryLock) + } + return nil + } + return putPlannedFile(manifest, "wip/v1/"+captureRegistryLock, "wip/v1", 0, digest(nil), "0600") +} + +func plannedTree(expected TreeManifest, required []string) (TreeManifest, error) { + result := expected + result.Entries = append([]ManifestEntry{}, expected.Entries...) + result.Exists = true + entries := make(map[string]ManifestEntry, len(result.Entries)+len(required)) + for _, entry := range result.Entries { + entries[entry.Path] = entry + } + for _, path := range required { + if entry, found := entries[path]; found { + if entry.Type != "directory" { + return TreeManifest{}, fmt.Errorf("canonical path %s is not a directory", path) + } + continue + } + entries[path] = ManifestEntry{Path: path, Type: "directory", Mode: "0700"} + } + result.Entries = result.Entries[:0] + for _, entry := range entries { + result.Entries = append(result.Entries, entry) + } + return result, nil +} + +func putPlannedFile(manifest *TreeManifest, destination, prefix string, size int64, sha, mode string) error { + relative, err := destinationUnder(destination, prefix) + if err != nil { + return err + } + entries := make(map[string]ManifestEntry, len(manifest.Entries)+4) + for _, entry := range manifest.Entries { + entries[entry.Path] = entry + } + for parent := filepath.ToSlash(filepath.Dir(relative)); parent != "."; parent = filepath.ToSlash(filepath.Dir(parent)) { + if existing, found := entries[parent]; found && existing.Type != "directory" { + return fmt.Errorf("planned parent %s is not a directory", parent) + } + if _, found := entries[parent]; !found { + entries[parent] = ManifestEntry{Path: parent, Type: "directory", Mode: "0700"} + } + } + entry := ManifestEntry{Path: relative, Type: "file", Mode: mode, Size: size, SHA256: sha} + if existing, found := entries[relative]; found && existing != entry { + return fmt.Errorf("planned destination collision at %s", destination) + } + entries[relative] = entry + manifest.Entries = manifest.Entries[:0] + for _, item := range entries { + manifest.Entries = append(manifest.Entries, item) + } + return nil +} + +func finishManifest(manifest *TreeManifest) error { + sort.Slice(manifest.Entries, func(i, j int) bool { return manifest.Entries[i].Path < manifest.Entries[j].Path }) + var err error + manifest.Digest, err = manifestDigest(*manifest) + return err +} + +func destinationUnder(destination, prefix string) (string, error) { + clean := filepath.ToSlash(filepath.Clean(filepath.FromSlash(destination))) + prefix = filepath.ToSlash(filepath.Clean(filepath.FromSlash(prefix))) + if clean == prefix || !lenPrefix(clean, prefix+"/") { + return "", fmt.Errorf("destination %s is outside %s", destination, prefix) + } + relative := clean[len(prefix)+1:] + if relative == "" || relative == "." || filepath.IsAbs(relative) || relative == ".." || lenPrefix(relative, "../") { + return "", fmt.Errorf("destination %s is not a confined file path", destination) + } + return relative, nil +} + +func lenPrefix(value, prefix string) bool { + return len(value) >= len(prefix) && value[:len(prefix)] == prefix +} + +func verifyCanonicalTransition(repoCommon string, plan Plan, journal Journal, requirePost bool) error { + current, err := manifestCanonicalData(repoCommon) + if err != nil { + return failCanonical(err) + } + if requirePost { + if current.Digest != plan.PlannedCanonicalData.Digest { + return failCanonical(fmt.Errorf("canonical data does not match the reviewed post-publication manifest: %s", canonicalManifestDifference(plan.PlannedCanonicalData, current))) + } + } else { + authorized := publishedPathSet(journal) + if err := verifyTreeTransition(plan.ExpectedCanonicalData.Capture, plan.PlannedCanonicalData.Capture, current.Capture, "wip/v1", authorized); err != nil { + return failCanonical(err) + } + if err := verifyTreeTransition(plan.ExpectedCanonicalData.Review, plan.PlannedCanonicalData.Review, current.Review, "wip/review/v1", authorized); err != nil { + return failCanonical(err) + } + } + if err := verifyCanonicalEnvelope(repoCommon, plan, journal); err != nil { + return failCanonical(err) + } + return nil +} + +func canonicalManifestDifference(want, got CanonicalManifest) string { + if difference := treeManifestDifference("capture", want.Capture, got.Capture); difference != "" { + return difference + } + if difference := treeManifestDifference("review", want.Review, got.Review); difference != "" { + return difference + } + return fmt.Sprintf("combined digest is %s, want %s", got.Digest, want.Digest) +} + +func treeManifestDifference(label string, want, got TreeManifest) string { + if got.LogicalRoot != want.LogicalRoot { + return fmt.Sprintf("%s logical root is %q, want %q", label, got.LogicalRoot, want.LogicalRoot) + } + if got.Exists != want.Exists { + return fmt.Sprintf("%s exists is %t, want %t", label, got.Exists, want.Exists) + } + wantEntries := make(map[string]ManifestEntry, len(want.Entries)) + gotEntries := make(map[string]ManifestEntry, len(got.Entries)) + paths := make(map[string]struct{}, len(want.Entries)+len(got.Entries)) + for _, entry := range want.Entries { + wantEntries[entry.Path] = entry + paths[entry.Path] = struct{}{} + } + for _, entry := range got.Entries { + gotEntries[entry.Path] = entry + paths[entry.Path] = struct{}{} + } + ordered := make([]string, 0, len(paths)) + for path := range paths { + ordered = append(ordered, path) + } + sort.Strings(ordered) + for _, path := range ordered { + wantEntry, wantFound := wantEntries[path] + gotEntry, gotFound := gotEntries[path] + switch { + case !gotFound: + return fmt.Sprintf("%s path %q is missing", label, path) + case !wantFound: + return fmt.Sprintf("%s path %q is unexpected", label, path) + case gotEntry != wantEntry: + return fmt.Sprintf("%s path %q is %#v, want %#v", label, path, gotEntry, wantEntry) + } + } + if got.Digest != want.Digest { + return fmt.Sprintf("%s digest is %s, want %s", label, got.Digest, want.Digest) + } + return "" +} + +func publishedPathSet(journal Journal) map[string]bool { + authorized := make(map[string]bool, len(journal.PublishedPaths)) + for _, path := range journal.PublishedPaths { + authorized[filepath.ToSlash(path)] = true + } + return authorized +} + +// verifyCanonicalEnvelope protects everything under .git/wip, not only the +// two writable data roots. A resume accepts the exact reviewed prestate plus +// journal-authorized outputs whose bytes and modes are known from the plan. +// This rejects an extra file even when a stopped writer adds it outside v1. +func verifyCanonicalEnvelope(commonDir string, plan Plan, journal Journal) error { + current, err := manifestTree(commonDir, "wip") + if err != nil { + return err + } + return verifyCanonicalEnvelopeManifest(commonDir, plan, journal, current, false) +} + +// verifyCompletedCanonicalEnvelope protects immutable migration evidence while +// excluding the live data roots and transient private-index contents. The +// excluded roots must remain regular mode-0700 directories. Their record-level +// health belongs to the current-state doctor, not the historical migration. +func verifyCompletedCanonicalEnvelope(commonDir string, plan Plan, journal Journal) error { + current, err := manifestTreeFiltered(commonDir, "wip", func(relative string, info os.FileInfo) (bool, error) { + relative = filepath.ToSlash(relative) + switch relative { + case "v1", "review/v1", "indexes": + if info.Mode()&os.ModeSymlink != 0 || !info.IsDir() || modeString(info.Mode()) != "0700" { + return false, fmt.Errorf("post-cutover runtime root %s is not a regular mode-0700 directory", relative) + } + return true, nil + default: + return false, nil + } + }) + if err != nil { + return err + } + return verifyCanonicalEnvelopeManifest(commonDir, plan, journal, current, true) +} + +func verifyCanonicalEnvelopeManifest(commonDir string, plan Plan, journal Journal, current TreeManifest, allowPostCutoverRuntime bool) error { + before := fullManifestEntries(plan.ExpectedCanonical, "wip") + got := fullManifestEntries(current, "wip") + allowed, err := migrationOutputEntries(commonDir, plan, current) + if err != nil { + return err + } + authorized := publishedPathSet(journal) + for path := range authorized { + if _, ok := allowed[path]; !ok { + return fmt.Errorf("journal authorizes an output that is not in the reviewed migration: %s", path) + } + } + for path, entry := range got { + if expected, ok := before[path]; ok && equivalentManifestEntry(expected, entry) { + continue + } + // The exact data-root transition was verified separately above. Keep + // the envelope check responsible for every parent and sibling path. + if canonicalDataPath(path) || allowPostCutoverRuntime && postCutoverRuntimePath(path) { + continue + } + variants, ok := allowed[path] + if !ok || !authorized[path] { + return fmt.Errorf("canonical path changed without journal authority: %s", path) + } + matched := false + for _, expected := range variants { + if equivalentManifestEntry(expected, entry) { + matched = true + break + } + } + if !matched { + return fmt.Errorf("canonical path does not match an exact migration output: %s", path) + } + } + for path, expected := range before { + if allowPostCutoverRuntime && (canonicalDataPath(path) || postCutoverRuntimePath(path)) { + continue + } + if actual, ok := got[path]; !ok || !equivalentManifestEntry(expected, actual) && !canonicalDataPath(path) { + return fmt.Errorf("canonical prestate path disappeared or changed: %s", path) + } + } + return nil +} + +func migrationOutputEntries(commonDir string, plan Plan, current TreeManifest) (map[string][]ManifestEntry, error) { + allowed := make(map[string][]ManifestEntry) + addDirectory := func(path string, mode string) { + allowed[path] = append(allowed[path], ManifestEntry{Type: "directory", Mode: mode}) + } + for _, path := range []string{ + "wip", "wip/v1", "wip/v1/archive", "wip/v1/init-intents", "wip/v1/intents", "wip/v1/lanes", "wip/v1/leases", "wip/v1/locks", "wip/v1/profiles", + "wip/review", "wip/review/v1", "wip/review/v1/archive", "wip/review/v1/capture-aborts", "wip/review/v1/capture-completions", "wip/review/v1/capture-reservations", "wip/review/v1/handoffs", "wip/review/v1/landing-intents", "wip/review/v1/locks", "wip/review/v1/plans", "wip/review/v1/reconciliation", + "wip/archive", "wip/archive/legacy-ndev-wip", + "wip/migration", "wip/migration/v1", filepath.ToSlash(filepath.Join("wip", "migration", "v1", plan.MigrationID)), + } { + addDirectory(path, "0700") + } + addManifestOutputs(allowed, plan.PlannedCanonicalData.Capture, "wip/v1") + addManifestOutputs(allowed, plan.PlannedCanonicalData.Review, "wip/review/v1") + + domain := domainRecord{SchemaVersion: 2, Domain: DomainID, StateVersion: 1, MinimumReaderProtocol: contract.Protocol, RequiredCapabilities: contract.StateReaderCapabilities()} + domainBody, err := normalizedJSON(domain) + if err != nil { + return nil, err + } + addFileOutput(allowed, "wip/domain.json", domainBody, "0600") + planBody, err := normalizedJSON(plan) + if err != nil { + return nil, err + } + planPath := filepath.ToSlash(filepath.Join("wip", "migration", "v1", plan.MigrationID, "plan.json")) + addFileOutput(allowed, planPath, planBody, "0400") + + if plan.SourceLegacy.Exists { + archiveBase := filepath.ToSlash(filepath.Join("wip", "archive", "legacy-ndev-wip", plan.MigrationID)) + addDirectory("wip/archive", "0700") + addDirectory("wip/archive/legacy-ndev-wip", "0700") + addDirectory(archiveBase, "0700") + for _, entry := range plan.SourceLegacy.Entries { + path := archiveBase + "/source" + if entry.Path != "." { + path += "/" + entry.Path + } + allowed[path] = append(allowed[path], entry) + sealed := entry + if entry.Type == "directory" { + sealed.Mode = modeString(os.ModeDir | 0o500) + } else { + sealed.Mode = "0400" + } + allowed[path] = append(allowed[path], sealed) + } + // The seal is a valid journal output, but its exact bytes are known + // only after the archive is complete. Keep an explicit empty variant + // set until a present seal is validated below. + allowed[archiveBase+"/seal.json"] = nil + } + receiptPath := migrationReceiptRelativePath(plan.MigrationID) + rollbackPath := filepath.ToSlash(filepath.Join("wip", "migration", "v1", plan.MigrationID, "rollback.json")) + allowed[receiptPath] = nil + allowed[rollbackPath] = nil + currentEntries := fullManifestEntries(current, "wip") + for _, dynamic := range []struct { + path string + validate func() error + }{ + {filepath.ToSlash(filepath.Join("wip", "archive", "legacy-ndev-wip", plan.MigrationID, "seal.json")), func() error { return validateTransitionSeal(commonDir, plan) }}, + {receiptPath, func() error { return validateTransitionReceipt(commonDir, plan) }}, + {rollbackPath, func() error { return validateTransitionRollback(commonDir, plan) }}, + } { + if entry, exists := currentEntries[dynamic.path]; exists { + if err := dynamic.validate(); err != nil { + return nil, err + } + allowed[dynamic.path] = append(allowed[dynamic.path], entry) + } + } + return allowed, nil +} + +func addManifestOutputs(allowed map[string][]ManifestEntry, manifest TreeManifest, prefix string) { + for _, entry := range manifest.Entries { + path := prefix + if entry.Path != "." { + path += "/" + entry.Path + } + allowed[path] = append(allowed[path], entry) + } +} + +func addFileOutput(allowed map[string][]ManifestEntry, path string, body []byte, mode string) { + allowed[path] = append(allowed[path], ManifestEntry{Type: "file", Mode: mode, Size: int64(len(body)), SHA256: digest(body)}) +} + +func fullManifestEntries(manifest TreeManifest, prefix string) map[string]ManifestEntry { + result := make(map[string]ManifestEntry, len(manifest.Entries)) + for _, entry := range manifest.Entries { + path := prefix + if entry.Path != "." { + path += "/" + entry.Path + } + result[path] = entry + } + return result +} + +func equivalentManifestEntry(left, right ManifestEntry) bool { + return left.Type == right.Type && left.Mode == right.Mode && left.Size == right.Size && left.SHA256 == right.SHA256 +} + +func canonicalDataPath(path string) bool { + return path == "wip/v1" || lenPrefix(path, "wip/v1/") || path == "wip/review/v1" || lenPrefix(path, "wip/review/v1/") +} + +func postCutoverRuntimePath(path string) bool { + return path == "wip/indexes" || lenPrefix(path, "wip/indexes/") +} + +func migrationReceiptRelativePath(migrationID string) string { + return filepath.ToSlash(filepath.Join("wip", "migration", "v1", migrationID, "receipt.json")) +} + +func validateTransitionSeal(commonDir string, plan Plan) error { + path := filepath.Join(archiveMigrationRoot(commonDir, plan.MigrationID), "seal.json") + var seal Seal + if _, err := readJSONFile(path, &seal); err != nil { + return err + } + archive, err := manifestTree(commonDir, filepath.ToSlash(filepath.Join("wip", "archive", "legacy-ndev-wip", plan.MigrationID, "source"))) + if err != nil { + return err + } + if seal.SchemaVersion != SealSchemaVersion || seal.MigrationID != plan.MigrationID || seal.PlanDigest != plan.PlanDigest || seal.SourceManifest != plan.SourceLegacy.Digest || seal.ArchiveManifest != archive.Digest || seal.ArchiveRelativeDir != filepath.ToSlash(filepath.Join("wip", "archive", "legacy-ndev-wip", plan.MigrationID, "source")) || seal.SealedAt.IsZero() { + return errors.New("archive seal is not an exact output of the reviewed migration") + } + return nil +} + +func validateTransitionReceipt(commonDir string, plan Plan) error { + var receipt Receipt + if _, err := readJSONFile(migrationReceiptPath(commonDir, plan.MigrationID), &receipt); err != nil { + return err + } + if err := validateReceipt(receipt, plan.MigrationID); err != nil { + return err + } + if receipt.PlanDigest != plan.PlanDigest || receipt.SourceManifest != plan.SourceLegacy.Digest || receipt.CanonicalManifest != plan.PlannedCanonicalData.Digest || receipt.ReconciliationHistory != plan.ReconciliationHistory.Digest || receipt.CompletedAt.IsZero() { + return errors.New("completion receipt is not an exact output of the reviewed migration") + } + if plan.SourceLegacy.Exists { + archive, err := manifestTree(commonDir, filepath.ToSlash(filepath.Join("wip", "archive", "legacy-ndev-wip", plan.MigrationID, "source"))) + if err != nil || receipt.ArchiveManifest != archive.Digest { + return errors.New("completion receipt does not bind the exact legacy archive") + } + } else if receipt.ArchiveManifest != "" { + return errors.New("completion receipt unexpectedly names a legacy archive") + } + return nil +} + +func validateTransitionRollback(commonDir string, plan Plan) error { + path := filepath.Join(commonDir, "wip", "migration", "v1", plan.MigrationID, "rollback.json") + var marker RollbackMarker + if _, err := readJSONFile(path, &marker); err != nil { + return err + } + if marker.SchemaVersion != RollbackSchemaVersion || marker.MigrationID != plan.MigrationID || marker.PlanDigest != plan.PlanDigest || marker.State != "rolled-back" || marker.UpdatedAt.IsZero() { + return errors.New("rollback marker is not an exact output of the reviewed migration") + } + return nil +} + +func verifyTreeTransition(expected, planned, current TreeManifest, prefix string, authorized map[string]bool) error { + wantPre := entriesByPath(expected.Entries) + wantPost := entriesByPath(planned.Entries) + got := entriesByPath(current.Entries) + for path, actual := range got { + if before, ok := wantPre[path]; ok && before == actual { + continue + } + full := filepath.ToSlash(filepath.Join(prefix, filepath.FromSlash(path))) + if !authorized[full] { + return fmt.Errorf("canonical path changed without journal authority: %s", full) + } + if after, ok := wantPost[path]; !ok || after != actual { + return fmt.Errorf("canonical path does not match its planned output: %s", full) + } + } + for path, before := range wantPre { + if _, ok := got[path]; ok { + continue + } + full := filepath.ToSlash(filepath.Join(prefix, filepath.FromSlash(path))) + if !authorized[full] || wantPost[path] == before { + return fmt.Errorf("canonical prestate path disappeared: %s", full) + } + } + return nil +} + +func entriesByPath(entries []ManifestEntry) map[string]ManifestEntry { + result := make(map[string]ManifestEntry, len(entries)) + for _, entry := range entries { + result[entry.Path] = entry + } + return result +} + +func failCanonical(err error) error { + return fmt.Errorf("canonical manifest verification failed: %w", err) +} + +func verifyExactCanonicalPrestate(commonDir string, plan Plan) error { + current, err := manifestTree(commonDir, "wip") + if err != nil { + return err + } + if current.Digest != plan.ExpectedCanonical.Digest { + return errors.New("canonical store changed after the reviewed preview") + } + return nil +} diff --git a/internal/coordmigration/fence.go b/internal/coordmigration/fence.go new file mode 100644 index 0000000..9d9514b --- /dev/null +++ b/internal/coordmigration/fence.go @@ -0,0 +1,156 @@ +package coordmigration + +import ( + "bytes" + "errors" + "os" + "path/filepath" + "time" + + "github.com/nstranquist/wip-commit/internal/fail" + "github.com/nstranquist/wip-commit/internal/gitx" + "github.com/nstranquist/wip-commit/internal/safeio" +) + +const writerFenceSchemaVersion = "wip.coordination-migration-writer-fence/1.0.0" + +func writerFencePath(commonDir string) string { + return filepath.Join(commonDir, "wip-coordination-migration-v1.fence.json") +} + +func bootstrapPlanPath(commonDir, migrationID string) string { + return filepath.Join(commonDir, "wip-coordination-migration-v1."+migrationID+".plan.json") +} + +func retiredJournalPath(commonDir, migrationID string) string { + return filepath.Join(commonDir, "wip-coordination-migration-v1."+migrationID+".rolled-back.journal.json") +} + +// retireRolledBackJournal keeps the exact terminal journal as immutable +// history, then frees the single active-journal slot for a newly reviewed +// migration. The caller holds the repository-wide coordination lock. +func retireRolledBackJournal(commonDir string, journal Journal) error { + if journal.Phase != phaseRolledBack || !migrationIDPattern.MatchString(journal.MigrationID) { + return fail.New("MIGRATION_JOURNAL_INVALID", "only an exact rolled-back journal can be retired") + } + path := migrationJournalPath(commonDir) + body, err := safeio.ReadRegular(path, MaxPlanBytes) + if err != nil { + return fail.Wrap("MIGRATION_JOURNAL_INVALID", err) + } + current, exists, err := readJournal(path) + if err != nil || !exists { + if err != nil { + return err + } + return fail.New("MIGRATION_JOURNAL_INVALID", "rolled-back journal disappeared before retirement") + } + currentBody, err := normalizedJSON(current) + if err != nil || !bytes.Equal(body, currentBody) || current.MigrationID != journal.MigrationID || current.PlanDigest != journal.PlanDigest || current.Phase != journal.Phase { + return fail.New("MIGRATION_JOURNAL_INVALID", "rolled-back journal changed before retirement") + } + if err := createExact(retiredJournalPath(commonDir, journal.MigrationID), body, 0o400); err != nil { + return fail.Wrap("MIGRATION_JOURNAL_FAILED", err) + } + if err := removeExactFile(path, digest(body)); err != nil { + return fail.Wrap("MIGRATION_JOURNAL_FAILED", err) + } + return nil +} + +func persistBootstrapPlan(commonDir string, plan Plan) error { + body, err := normalizedJSON(plan) + if err != nil { + return err + } + if len(body) > MaxPlanBytes { + return fail.Errorf("MIGRATION_PLAN_TOO_LARGE", "migration plan is %d bytes; maximum is %d", len(body), MaxPlanBytes) + } + if err := createExact(bootstrapPlanPath(commonDir, plan.MigrationID), body, 0o400); err != nil { + return fail.Wrap("MIGRATION_PLAN_FAILED", err) + } + return nil +} + +func loadPersistedPlan(commonDir, migrationID string) (Plan, error) { + canonical, canonicalErr := loadPlan(migrationPlanPath(commonDir, migrationID)) + bootstrap, bootstrapErr := loadPlan(bootstrapPlanPath(commonDir, migrationID)) + if canonicalErr == nil && bootstrapErr == nil { + left, leftErr := normalizedJSON(canonical) + right, rightErr := normalizedJSON(bootstrap) + if leftErr != nil || rightErr != nil || !bytes.Equal(left, right) { + return Plan{}, fail.New("MIGRATION_PLAN_INVALID", "canonical and bootstrap migration plans differ") + } + return canonical, nil + } + if canonicalErr == nil { + if bootstrapErr != nil && !errors.Is(bootstrapErr, os.ErrNotExist) { + return Plan{}, bootstrapErr + } + return canonical, nil + } + if bootstrapErr == nil { + if canonicalErr != nil && !errors.Is(canonicalErr, os.ErrNotExist) { + return Plan{}, canonicalErr + } + return bootstrap, nil + } + if !errors.Is(canonicalErr, os.ErrNotExist) { + return Plan{}, canonicalErr + } + return Plan{}, bootstrapErr +} + +func activateWriterFence(commonDir string, plan Plan) error { + path := writerFencePath(commonDir) + var existing WriterFence + if _, err := readJSONFile(path, &existing); err == nil { + if existing.SchemaVersion != writerFenceSchemaVersion || existing.MigrationID != plan.MigrationID || existing.PlanDigest != plan.PlanDigest { + return fail.New("MIGRATION_FENCE_CONFLICT", "a different or invalid migration writer fence exists") + } + return nil + } else if !errors.Is(err, os.ErrNotExist) { + return fail.Wrap("MIGRATION_FENCE_CONFLICT", err) + } + fence := WriterFence{SchemaVersion: writerFenceSchemaVersion, MigrationID: plan.MigrationID, PlanDigest: plan.PlanDigest, CreatedAt: time.Now().UTC()} + if err := writeJSON(path, fence, 0o600, false); err != nil { + return fail.Wrap("MIGRATION_FENCE_FAILED", err) + } + return nil +} + +func deactivateWriterFence(commonDir string, plan Plan) error { + path := writerFencePath(commonDir) + var fence WriterFence + if _, err := readJSONFile(path, &fence); errors.Is(err, os.ErrNotExist) { + return nil + } else if err != nil { + return fail.Wrap("MIGRATION_FENCE_CONFLICT", err) + } + if fence.SchemaVersion != writerFenceSchemaVersion || fence.MigrationID != plan.MigrationID || fence.PlanDigest != plan.PlanDigest { + return fail.New("MIGRATION_FENCE_CONFLICT", "writer fence does not bind the completed migration") + } + if err := os.Remove(path); err != nil { + return fail.Wrap("MIGRATION_FENCE_FAILED", err) + } + return syncDirectory(commonDir) +} + +func verifyJournalPlanBinding(repo gitx.Repo, plan Plan, journal Journal) error { + if journal.MigrationID != plan.MigrationID || journal.PlanDigest != plan.PlanDigest || journal.ExpectedCanonicalDigest != plan.ExpectedCanonicalData.Digest || journal.PlannedCanonicalDigest != plan.PlannedCanonicalData.Digest { + return fail.New("MIGRATION_JOURNAL_INVALID", "migration journal does not bind the reviewed canonical prestate and poststate") + } + persisted, err := loadPersistedPlan(repo.CommonDir, plan.MigrationID) + if err != nil { + return fail.Wrap("MIGRATION_PLAN_INVALID", err) + } + if err := persisted.ValidateDigest(plan.PlanDigest); err != nil { + return fail.Wrap("MIGRATION_PLAN_INVALID", err) + } + leftBody, leftErr := normalizedJSON(persisted) + rightBody, rightErr := normalizedJSON(plan) + if persisted.PlanDigest != plan.PlanDigest || persisted.MigrationID != plan.MigrationID || leftErr != nil || rightErr != nil || !bytes.Equal(leftBody, rightBody) { + return fail.New("MIGRATION_PLAN_INVALID", "persisted migration plan differs from the exact reviewed plan") + } + return nil +} diff --git a/internal/coordmigration/fs.go b/internal/coordmigration/fs.go new file mode 100644 index 0000000..421135b --- /dev/null +++ b/internal/coordmigration/fs.go @@ -0,0 +1,417 @@ +package coordmigration + +import ( + "bytes" + "crypto/rand" + "encoding/json" + "errors" + "fmt" + "io" + "io/fs" + "os" + "path/filepath" + "sort" + "strconv" + "strings" + + "github.com/nstranquist/wip-commit/internal/atomicfile" + "github.com/nstranquist/wip-commit/internal/safeio" +) + +type manifestTreeFilter func(relative string, info os.FileInfo) (skipDirectory bool, err error) + +func manifestTree(commonDir, logicalRoot string) (TreeManifest, error) { + return manifestTreeFiltered(commonDir, logicalRoot, nil) +} + +func manifestTreeFiltered(commonDir, logicalRoot string, filter manifestTreeFilter) (TreeManifest, error) { + manifest := TreeManifest{LogicalRoot: filepath.ToSlash(logicalRoot), Entries: []ManifestEntry{}} + root, err := confinedPath(commonDir, logicalRoot) + if err != nil { + return manifest, err + } + rootInfo, err := os.Lstat(root) + if errors.Is(err, os.ErrNotExist) { + manifest.Digest, err = manifestDigest(manifest) + return manifest, err + } + if err != nil { + return manifest, err + } + if rootInfo.Mode()&os.ModeSymlink != 0 || !rootInfo.IsDir() { + return manifest, fmt.Errorf("%s is not a regular directory", logicalRoot) + } + manifest.Exists = true + var totalBytes int64 + err = filepath.WalkDir(root, func(path string, entry fs.DirEntry, walkErr error) error { + if walkErr != nil { + return walkErr + } + if len(manifest.Entries) >= maxManifestEntries { + return fmt.Errorf("manifest exceeds %d entries", maxManifestEntries) + } + info, err := os.Lstat(path) + if err != nil { + return err + } + relative, err := filepath.Rel(root, path) + if err != nil { + return err + } + relative = filepath.ToSlash(relative) + skipDirectory := false + if filter != nil { + skipDirectory, err = filter(relative, info) + if err != nil { + return err + } + if skipDirectory && !info.IsDir() { + return fmt.Errorf("manifest filter cannot skip non-directory path %s", filepath.ToSlash(filepath.Join(logicalRoot, relative))) + } + } + item := ManifestEntry{Path: relative, Mode: modeString(info.Mode())} + switch { + case info.Mode()&os.ModeSymlink != 0: + return fmt.Errorf("manifest rejects symlink %s", filepath.ToSlash(filepath.Join(logicalRoot, relative))) + case info.IsDir(): + item.Type = "directory" + case info.Mode().IsRegular(): + item.Type = "file" + item.Size = info.Size() + totalBytes += info.Size() + if totalBytes > maxManifestBytes { + return fmt.Errorf("manifest exceeds %d bytes", maxManifestBytes) + } + body, err := safeio.ReadRegular(path, maxManifestBytes) + if err != nil { + return err + } + item.SHA256 = digest(body) + default: + return fmt.Errorf("manifest rejects non-regular path %s", filepath.ToSlash(filepath.Join(logicalRoot, relative))) + } + manifest.Entries = append(manifest.Entries, item) + if skipDirectory && relative != "." { + return filepath.SkipDir + } + return nil + }) + if err != nil { + return manifest, err + } + sort.Slice(manifest.Entries, func(i, j int) bool { return manifest.Entries[i].Path < manifest.Entries[j].Path }) + manifest.Digest, err = manifestDigest(manifest) + return manifest, err +} + +func manifestDigest(manifest TreeManifest) (string, error) { + manifest.Digest = "" + body, err := json.Marshal(manifest) + if err != nil { + return "", err + } + return digest(body), nil +} + +func confinedPath(commonDir, relative string) (string, error) { + if filepath.IsAbs(relative) { + return "", fmt.Errorf("state path must be relative: %s", relative) + } + clean := filepath.Clean(relative) + if clean == ".." || strings.HasPrefix(clean, ".."+string(filepath.Separator)) { + return "", fmt.Errorf("state path escapes Git common directory: %s", relative) + } + return filepath.Join(commonDir, clean), nil +} + +func modeString(mode os.FileMode) string { return fmt.Sprintf("%04o", canonicalMode(mode)) } + +func parseMode(value string) (os.FileMode, error) { + parsed, err := strconv.ParseUint(value, 8, 32) + if err != nil || parsed > 0o777 { + return 0, fmt.Errorf("invalid file mode %q", value) + } + return os.FileMode(parsed), nil +} + +func readJSONFile(path string, target any) ([]byte, error) { + return readJSONFileLimit(path, target, maxRecordBytes) +} + +func readJSONFileLimit(path string, target any, limit int64) ([]byte, error) { + body, err := safeio.ReadRegular(path, limit) + if err != nil { + return nil, err + } + decoder := json.NewDecoder(bytes.NewReader(body)) + decoder.DisallowUnknownFields() + if err := decoder.Decode(target); err != nil { + return nil, err + } + var trailing any + if err := decoder.Decode(&trailing); !errors.Is(err, io.EOF) { + if err == nil { + return nil, errors.New("record contains multiple JSON values") + } + return nil, err + } + return body, nil +} + +func normalizedJSON(value any) ([]byte, error) { + body, err := json.MarshalIndent(value, "", " ") + if err != nil { + return nil, err + } + return append(body, '\n'), nil +} + +func createExact(path string, body []byte, mode os.FileMode) error { + if err := atomicfile.Create(path, body, mode); err == nil { + return nil + } else if !errors.Is(err, atomicfile.ErrExists) { + return err + } + existing, err := safeio.ReadRegular(path, int64(len(body))) + if err != nil || !bytes.Equal(existing, body) { + return fmt.Errorf("destination conflict: %s", path) + } + info, err := os.Lstat(path) + if err != nil { + return fmt.Errorf("inspect destination mode %s: %w", path, err) + } + if actual, want := modeString(info.Mode()), modeString(mode); actual != want { + repaired, repairErr := repairExactMode(path, info.Mode(), mode) + if repairErr != nil { + return fmt.Errorf("finalize destination mode %s: %w", path, repairErr) + } + if !repaired { + return fmt.Errorf("destination mode conflict: %s has %s (%s), want %s", path, actual, info.Mode(), want) + } + info, err = os.Lstat(path) + if err != nil || modeString(info.Mode()) != want { + return fmt.Errorf("destination mode repair failed: %s", path) + } + return syncDirectory(filepath.Dir(path)) + } + return nil +} + +func copyConfinedExact(source, commonDir, destination, expectedDigest string, mode os.FileMode) error { + body, err := safeio.ReadRegular(source, maxManifestBytes) + if err != nil { + return err + } + if digest(body) != expectedDigest { + return fmt.Errorf("source moved while copying %s", source) + } + return createConfinedExact(commonDir, destination, body, mode) +} + +// createConfinedExact publishes one immutable file through an opened root. +// Every parent is inspected without following a symlink before it becomes the +// next opened root. Publication uses a same-directory hard link, so readers +// can see only the complete file or no file. +func createConfinedExact(commonDir, relative string, body []byte, mode os.FileMode) error { + clean := filepath.Clean(filepath.FromSlash(relative)) + if filepath.IsAbs(clean) || clean == "." || clean == ".." || strings.HasPrefix(clean, ".."+string(filepath.Separator)) { + return fmt.Errorf("destination is outside the Git common directory: %s", relative) + } + parts := splitPath(clean) + if len(parts) < 2 { + return fmt.Errorf("destination has no confined parent: %s", relative) + } + root, err := os.OpenRoot(commonDir) + if err != nil { + return err + } + defer func() { _ = root.Close() }() + for _, component := range parts[:len(parts)-1] { + info, statErr := root.Lstat(component) + if statErr != nil { + return fmt.Errorf("destination parent %s is unavailable: %w", component, statErr) + } + if !info.IsDir() || info.Mode()&os.ModeSymlink != 0 { + return fmt.Errorf("destination parent is not a regular directory: %s", component) + } + next, openErr := root.OpenRoot(component) + if openErr != nil { + return openErr + } + _ = root.Close() + root = next + } + base := parts[len(parts)-1] + if info, statErr := root.Lstat(base); statErr == nil { + if err := verifyConfinedContent(root, base, info, body); err != nil { + return fmt.Errorf("destination conflict: %s", relative) + } + if actual, want := modeString(info.Mode()), modeString(mode); actual != want { + repaired, repairErr := repairConfinedMode(root, base, info.Mode(), mode) + if repairErr != nil { + return fmt.Errorf("finalize destination mode %s: %w", relative, repairErr) + } + if !repaired { + return fmt.Errorf("destination mode conflict: %s has %s (%s), want %s", relative, actual, info.Mode(), want) + } + info, statErr = root.Lstat(base) + if statErr != nil || modeString(info.Mode()) != want { + return fmt.Errorf("destination mode repair failed: %s", relative) + } + return syncDirectory(filepath.Join(commonDir, filepath.Dir(clean))) + } + return nil + } else if !errors.Is(statErr, os.ErrNotExist) { + return statErr + } + var nonce [16]byte + if _, err := rand.Read(nonce[:]); err != nil { + return err + } + temporary := fmt.Sprintf(".~%s.%x", base, nonce[:]) + file, err := root.OpenFile(temporary, os.O_WRONLY|os.O_CREATE|os.O_EXCL, confinedLinkSourceMode(mode)) + if err != nil { + return err + } + removeTemporary := true + defer func() { + _ = file.Close() + if removeTemporary { + _ = root.Remove(temporary) + } + }() + if written, writeErr := file.Write(body); writeErr != nil { + return writeErr + } else if written != len(body) { + return io.ErrShortWrite + } + if err := file.Sync(); err != nil { + return err + } + if err := file.Close(); err != nil { + return err + } + if err := root.Link(temporary, base); errors.Is(err, os.ErrExist) { + return createConfinedExact(commonDir, relative, body, mode) + } else if err != nil { + return err + } + if err := root.Remove(temporary); err != nil { + return err + } + removeTemporary = false + if err := finalizeConfinedLink(root, base, mode); err != nil { + return err + } + info, err := root.Lstat(base) + if err != nil { + return err + } + if err := verifyConfinedFile(root, base, info, body, mode); err != nil { + return err + } + return syncDirectory(filepath.Join(commonDir, filepath.Dir(clean))) +} + +func verifyConfinedFile(root *os.Root, base string, info os.FileInfo, body []byte, mode os.FileMode) error { + if err := verifyConfinedContent(root, base, info, body); err != nil { + return err + } + if modeString(info.Mode()) != modeString(mode) { + return fmt.Errorf("file mode is %s, want %s", modeString(info.Mode()), modeString(mode)) + } + return nil +} + +func verifyConfinedContent(root *os.Root, base string, info os.FileInfo, body []byte) error { + if !info.Mode().IsRegular() || info.Mode()&os.ModeSymlink != 0 { + return errors.New("path is not a regular file") + } + file, err := root.Open(base) + if err != nil { + return err + } + existing, readErr := io.ReadAll(io.LimitReader(file, int64(len(body))+1)) + closeErr := file.Close() + if readErr != nil { + return readErr + } + if closeErr != nil { + return closeErr + } + if !bytes.Equal(existing, body) { + return errors.New("file content does not match") + } + return nil +} + +func loadPlan(path string) (Plan, error) { + var plan Plan + _, err := readJSONFileLimit(path, &plan, MaxPlanBytes) + return plan, err +} + +func writeJSON(path string, value any, mode os.FileMode, replace bool) error { + body, err := normalizedJSON(value) + if err != nil { + return err + } + if replace { + return atomicfile.Write(path, body, mode) + } + return createExact(path, body, mode) +} + +func removeExactFile(path, expectedDigest string) error { + body, err := safeio.ReadRegular(path, maxManifestBytes) + if errors.Is(err, os.ErrNotExist) { + return nil + } + if err != nil { + return err + } + if digest(body) != expectedDigest { + return fmt.Errorf("refusing to remove changed migration output %s", path) + } + if err := os.Remove(path); err != nil { + return err + } + return syncDirectory(filepath.Dir(path)) +} + +func sealArchiveTree(root string) error { + var directories []string + err := filepath.WalkDir(root, func(path string, entry fs.DirEntry, walkErr error) error { + if walkErr != nil { + return walkErr + } + info, err := os.Lstat(path) + if err != nil { + return err + } + if info.Mode()&os.ModeSymlink != 0 { + return fmt.Errorf("archive contains symlink %s", path) + } + if info.IsDir() { + directories = append(directories, path) + return nil + } + if !info.Mode().IsRegular() { + return fmt.Errorf("archive contains non-regular path %s", path) + } + return os.Chmod(path, 0o400) + }) + if err != nil { + return err + } + sort.Slice(directories, func(i, j int) bool { return len(directories[i]) > len(directories[j]) }) + for _, directory := range directories { + if err := os.Chmod(directory, 0o500); err != nil { + return err + } + if err := syncDirectory(directory); err != nil { + return err + } + } + return nil +} diff --git a/internal/coordmigration/migration_test.go b/internal/coordmigration/migration_test.go new file mode 100644 index 0000000..cac6a6f --- /dev/null +++ b/internal/coordmigration/migration_test.go @@ -0,0 +1,1638 @@ +package coordmigration + +import ( + "bytes" + "context" + "errors" + "os" + "os/exec" + "path/filepath" + "runtime" + "strings" + "testing" + "time" + + "github.com/nstranquist/wip-commit/internal/contract" + "github.com/nstranquist/wip-commit/internal/fail" + "github.com/nstranquist/wip-commit/internal/filelock" + "github.com/nstranquist/wip-commit/internal/gitx" + "github.com/nstranquist/wip-commit/internal/store" +) + +func TestPreviewIsByteForByteReadOnly(t *testing.T) { + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + before := testTreeDigest(t, repo.CommonDir) + plan, err := previewForTest(context.Background(), repo, PreviewOptions{}) + if err != nil { + t.Fatal(err) + } + after := testTreeDigest(t, repo.CommonDir) + if before != after { + t.Fatalf("preview changed Git common directory: before=%s after=%s", before, after) + } + if plan.State != "ready" || !plan.SourceLegacy.Exists || len(plan.LaneImports) != 1 || len(plan.LeaseImports) != 1 { + t.Fatalf("unexpected preview: %#v", plan) + } + if _, err := os.Lstat(filepath.Join(repo.CommonDir, "wip-coordination.lock")); !errors.Is(err, os.ErrNotExist) { + t.Fatalf("preview created a coordination lock: %v", err) + } +} + +func TestPreviewArchivesExactEmptyLegacyV2Scaffold(t *testing.T) { + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + for _, directory := range []string{"lanes", "leases", "receipts"} { + if err := os.MkdirAll(filepath.Join(repo.CommonDir, "ndev-wip", "v2", directory), 0o700); err != nil { + t.Fatal(err) + } + } + + before := testTreeDigest(t, repo.CommonDir) + plan := mustPreview(t, repo) + after := testTreeDigest(t, repo.CommonDir) + if before != after { + t.Fatalf("preview changed Git common directory: before=%s after=%s", before, after) + } + for _, path := range []string{"v2", "v2/lanes", "v2/leases", "v2/receipts"} { + entry, found := testManifestEntry(plan.SourceLegacy, path) + if !found || entry.Type != "directory" { + t.Fatalf("source manifest does not bind empty scaffold directory %s: %#v", path, entry) + } + } + + if _, err := applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{}); err != nil { + t.Fatal(err) + } + archive := filepath.Join(archiveMigrationRoot(repo.CommonDir, plan.MigrationID), "source") + for _, path := range []string{"v2", "v2/lanes", "v2/leases", "v2/receipts"} { + info, err := os.Stat(filepath.Join(archive, filepath.FromSlash(path))) + if err != nil || !info.IsDir() { + t.Fatalf("sealed archive lost v2 scaffold directory %s: mode=%v err=%v", path, infoMode(info), err) + } + } +} + +func TestPreviewRejectsNonEmptyOrPartialLegacyV2Scaffold(t *testing.T) { + t.Run("non-empty", func(t *testing.T) { + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + for _, directory := range []string{"lanes", "leases", "receipts"} { + if err := os.MkdirAll(filepath.Join(repo.CommonDir, "ndev-wip", "v2", directory), 0o700); err != nil { + t.Fatal(err) + } + } + writeTestFile(t, filepath.Join(repo.CommonDir, "ndev-wip", "v2", "lanes", "lane.json"), []byte("{}\n"), 0o600) + if _, err := previewForTest(context.Background(), repo, PreviewOptions{}); fail.Code(err) != "MIGRATION_SOURCE_INVALID" { + t.Fatalf("non-empty legacy v2 scaffold was accepted: %v (%s)", err, fail.Code(err)) + } + }) + + t.Run("partial", func(t *testing.T) { + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + if err := os.MkdirAll(filepath.Join(repo.CommonDir, "ndev-wip", "v2", "lanes"), 0o700); err != nil { + t.Fatal(err) + } + if _, err := previewForTest(context.Background(), repo, PreviewOptions{}); fail.Code(err) != "MIGRATION_SOURCE_INVALID" { + t.Fatalf("partial legacy v2 scaffold was accepted: %v (%s)", err, fail.Code(err)) + } + }) +} + +func TestPreviewDigestIsDeterministicForRepeatedConflictKeys(t *testing.T) { + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + + var lease legacyLease + if _, err := readJSONFile(filepath.Join(repo.CommonDir, "ndev-wip", "v1", "leases", "lease1.json"), &lease); err != nil { + t.Fatal(err) + } + lease.ExpiresAt = timePointer(time.Date(2025, 1, 1, 0, 0, 0, 0, time.UTC)) + writeTestJSON(t, filepath.Join(repo.CommonDir, "ndev-wip", "v1", "leases", "lease1.json"), lease, 0o600) + + for _, id := range []string{"orphan-a", "orphan-b"} { + orphan := lease + orphan.ID = id + orphan.LaneID = "missing-" + id + writeTestJSON(t, filepath.Join(repo.CommonDir, "ndev-wip", "v1", "leases", id+".json"), orphan, 0o600) + } + + now := func() time.Time { return time.Date(2026, 8, 26, 0, 0, 0, 0, time.UTC) } + first, err := previewForTest(context.Background(), repo, PreviewOptions{Now: now}) + if err != nil { + t.Fatal(err) + } + if first.State != "blocked" || len(first.Conflicts) < 2 { + t.Fatalf("fixture did not create repeated conflict keys: %#v", first.Conflicts) + } + firstBody, err := normalizedJSON(first) + if err != nil { + t.Fatal(err) + } + for attempt := 0; attempt < 100; attempt++ { + got, err := previewForTest(context.Background(), repo, PreviewOptions{Now: now}) + if err != nil { + t.Fatal(err) + } + gotBody, err := normalizedJSON(got) + if err != nil { + t.Fatal(err) + } + if got.PlanDigest != first.PlanDigest || !bytes.Equal(gotBody, firstBody) { + t.Fatalf("preview %d moved without state change: first=%s got=%s", attempt+1, first.PlanDigest, got.PlanDigest) + } + } +} + +func TestApplyLegacyOnlyImportsAndSeals(t *testing.T) { + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + writeTestFile(t, filepath.Join(repo.CommonDir, "ndev-commit-lane", "reconcile", "history.json"), []byte("{\"result\":\"ok\"}\n"), 0o640) + plan := mustPreview(t, repo) + result, err := applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{}) + if err != nil { + t.Fatal(err) + } + if !result.Applied || result.Receipt == nil || result.Status.State != "complete" { + t.Fatalf("unexpected result: %#v", result) + } + if _, err := os.Lstat(filepath.Join(repo.CommonDir, "ndev-wip")); !errors.Is(err, os.ErrNotExist) { + t.Fatalf("legacy source remains: %v", err) + } + assertDigest(t, filepath.Join(repo.CommonDir, "wip", "v1", "lanes", "lane1.json"), plan.LaneImports[0].SourceSHA256) + assertDigest(t, filepath.Join(repo.CommonDir, "wip", "v1", "leases", "lease1.json"), plan.LeaseImports[0].SourceSHA256) + assertDigest(t, filepath.Join(repo.CommonDir, "wip", "review", "v1", "queue.json"), findCopy(t, plan.ReviewCopies, "queue.json").SourceSHA256) + assertDigest(t, filepath.Join(repo.CommonDir, "wip", "review", "v1", "reconciliation", "history.json"), plan.ReconciliationCopies[0].SourceSHA256) + archive := filepath.Join(archiveMigrationRoot(repo.CommonDir, plan.MigrationID), "source") + info, err := os.Stat(archive) + if err != nil || modeString(info.Mode()) != modeString(os.ModeDir|0o500) { + t.Fatalf("archive is not sealed: mode=%v err=%v", infoMode(info), err) + } + status, err := InspectStatus(repo, plan.MigrationID) + if err != nil || !status.Archive || status.Receipt == nil { + t.Fatalf("invalid final status: %#v err=%v", status, err) + } +} + +func TestEmptyAndPublicOnlyMigrations(t *testing.T) { + t.Run("empty", func(t *testing.T) { + repo, _ := migrationTestRepo(t) + plan := mustPreview(t, repo) + if plan.SourceLegacy.Exists || plan.ExpectedCanonical.Exists { + t.Fatalf("unexpected input manifests: %#v", plan) + } + lockEntry, found := testManifestEntry(plan.PlannedCanonicalData.Capture, captureRegistryLock) + if !found || lockEntry.Type != "file" || lockEntry.Mode != "0600" || lockEntry.Size != 0 || lockEntry.SHA256 != digest(nil) { + t.Fatalf("planned registry lock is not exact: %#v", lockEntry) + } + if _, err := applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{}); err != nil { + t.Fatal(err) + } + lockPath := filepath.Join(repo.CommonDir, "wip", "v1", "locks", "leases.lock") + info, err := os.Lstat(lockPath) + if err != nil || !info.Mode().IsRegular() || modeString(info.Mode()) != "0600" { + t.Fatalf("registry lock is unavailable after apply: mode=%v err=%v", infoMode(info), err) + } + if body, err := os.ReadFile(lockPath); err != nil || len(body) != 0 { + t.Fatalf("registry lock bytes changed during apply: %q err=%v", body, err) + } + if exists, err := regularDirectoryState(filepath.Join(repo.CommonDir, "wip", "review", "v1")); err != nil || !exists { + t.Fatalf("review store missing: %v", err) + } + for _, directory := range []string{"archive", "capture-aborts", "capture-completions", "capture-reservations", "handoffs", "landing-intents", "locks", "plans", "reconciliation"} { + path := filepath.Join(repo.CommonDir, "wip", "review", "v1", directory) + if exists, err := regularDirectoryState(path); err != nil || !exists { + t.Fatalf("required review store directory %s missing: %v", directory, err) + } + } + marker, err := os.ReadFile(filepath.Join(repo.CommonDir, "wip", "review", "v1", "domain.json")) + if err != nil { + t.Fatal(err) + } + wantMarker := []byte(`{"schema_version":1,"domain":"nicos.tools/ndev/wip-review","state_version":2,"authority":"ndev","queue_entry_schema_version":2,"handoff_schema_version":"2.0.0","automatic_landing":false,"handoff_landing_authorized":false,"review_digest_required":true}` + "\n") + if !bytes.Equal(marker, wantMarker) { + t.Fatalf("review authority marker mismatch:\n%s", marker) + } + }) + t.Run("public-only", func(t *testing.T) { + repo, _ := migrationTestRepo(t) + if _, err := store.Open(repo); err != nil { + t.Fatal(err) + } + lockPath := filepath.Join(repo.CommonDir, "wip", "v1", "locks", "leases.lock") + writeTestFile(t, lockPath, []byte("existing registry lock\n"), 0o600) + lockBefore, err := os.ReadFile(lockPath) + if err != nil { + t.Fatal(err) + } + plan := mustPreview(t, repo) + if plan.SourceLegacy.Exists || !plan.ExpectedCanonical.Exists { + t.Fatalf("unexpected input manifests: %#v", plan) + } + lockEntry, found := testManifestEntry(plan.PlannedCanonicalData.Capture, captureRegistryLock) + if !found || lockEntry.Size != int64(len(lockBefore)) || lockEntry.SHA256 != digest(lockBefore) { + t.Fatalf("existing registry lock is not bound exactly: %#v", lockEntry) + } + if _, err := applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{}); err != nil { + t.Fatal(err) + } + lockAfter, err := os.ReadFile(lockPath) + if err != nil || !bytes.Equal(lockBefore, lockAfter) { + t.Fatalf("migration changed the existing registry lock: before=%q after=%q err=%v", lockBefore, lockAfter, err) + } + }) + t.Run("nonregular registry lock", func(t *testing.T) { + repo, _ := migrationTestRepo(t) + if _, err := store.Open(repo); err != nil { + t.Fatal(err) + } + lockPath := filepath.Join(repo.CommonDir, "wip", "v1", "locks", "leases.lock") + if err := os.Mkdir(lockPath, 0o700); err != nil { + t.Fatal(err) + } + if _, err := previewForTest(context.Background(), repo, PreviewOptions{}); fail.Code(err) != "MIGRATION_PLAN_FAILED" { + t.Fatalf("nonregular registry lock was accepted: %v (%s)", err, fail.Code(err)) + } + }) +} + +func TestRegistryLockPublishesBeforeImportedRecords(t *testing.T) { + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + plan := mustPreview(t, repo) + + _, err := applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{AfterPhase: func(phase string) error { + if phase == phaseCanonicalPrepared { + return errors.New("stop before record publication") + } + return nil + }}) + if fail.Code(err) != "MIGRATION_INTERRUPTED" { + t.Fatalf("apply did not stop after canonical preparation: %v (%s)", err, fail.Code(err)) + } + + lockRelative := "wip/v1/" + captureRegistryLock + lockPath := filepath.Join(repo.CommonDir, filepath.FromSlash(lockRelative)) + info, err := os.Lstat(lockPath) + if err != nil || !info.Mode().IsRegular() || modeString(info.Mode()) != "0600" { + t.Fatalf("registry lock is unavailable before record publication: mode=%v err=%v", infoMode(info), err) + } + if body, err := os.ReadFile(lockPath); err != nil || len(body) != 0 { + t.Fatalf("registry lock is not the reviewed empty artifact: %q err=%v", body, err) + } + for _, relative := range []string{"wip/v1/lanes/lane1.json", "wip/v1/leases/lease1.json"} { + if _, err := os.Lstat(filepath.Join(repo.CommonDir, filepath.FromSlash(relative))); !errors.Is(err, os.ErrNotExist) { + t.Fatalf("imported record became readable before registry lock publication completed: %s: %v", relative, err) + } + } + journal, exists, err := readJournal(migrationJournalPath(repo.CommonDir)) + if err != nil || !exists { + t.Fatalf("migration journal is unavailable: exists=%v err=%v", exists, err) + } + lockAuthorized := false + for _, path := range journal.PublishedPaths { + if path == lockRelative { + lockAuthorized = true + break + } + } + if !lockAuthorized { + t.Fatalf("registry lock is not bound in the migration journal: %#v", journal.PublishedPaths) + } + + if _, err := applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{Resume: true}); err != nil { + t.Fatal(err) + } + opened, initialized, err := store.Inspect(repo) + if err != nil || !initialized { + t.Fatalf("canonical store cannot open after resume: initialized=%v err=%v", initialized, err) + } + if _, err := opened.Load("lane1"); err != nil { + t.Fatalf("imported lane is unreadable after resume: %v", err) + } + if _, err := opened.LoadLease("lease1"); err != nil { + t.Fatalf("imported lease is unreadable after resume: %v", err) + } +} + +func TestPreviewRejectsShadowByteConflict(t *testing.T) { + repo, head := migrationTestRepo(t) + if _, err := store.Open(repo); err != nil { + t.Fatal(err) + } + writeLegacyFixture(t, repo, head) + destination := filepath.Join(repo.CommonDir, "wip", "v1", "lanes", "lane1.json") + var lane legacyLane + if _, err := readJSONFile(filepath.Join(repo.CommonDir, "ndev-wip", "v1", "lanes", "lane1.json"), &lane); err != nil { + t.Fatal(err) + } + lane.UpdatedAt = lane.UpdatedAt.Add(time.Second) + writeTestJSON(t, destination, lane, 0o600) + var lease legacyLease + if _, err := readJSONFile(filepath.Join(repo.CommonDir, "ndev-wip", "v1", "leases", "lease1.json"), &lease); err != nil { + t.Fatal(err) + } + writeTestJSON(t, filepath.Join(repo.CommonDir, "wip", "v1", "leases", "lease1.json"), lease, 0o600) + plan := mustPreview(t, repo) + if plan.State != "blocked" || len(plan.Conflicts) == 0 || plan.Conflicts[0].Code != "SHADOW_MISMATCH" { + t.Fatalf("expected shadow mismatch, got %#v", plan.Conflicts) + } + _, err := applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{}) + if fail.Code(err) != "MIGRATION_PLAN_BLOCKED" { + t.Fatalf("expected blocked apply, got %v (%s)", err, fail.Code(err)) + } +} + +func TestIncompatibleTerminalHistoryIsArchiveOnlyAndCanonicalStoreReads(t *testing.T) { + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + now := time.Date(2026, 8, 23, 12, 0, 0, 0, time.UTC) + released := now + releasedLane := legacyLane{SchemaVersion: 1, ID: "released-lane", Agent: "agent1", Session: "session1", Mode: store.ModeWorktree, Ref: "refs/heads/wip/agent1/released-lane", BaseRef: "HEAD", BaseSHA: head, CurrentSHA: head, Worktree: repo.Root, LeaseIDs: []string{"released-lease"}, State: "released", CreatedAt: now, UpdatedAt: now} + legacyNullExpiry := []byte(`{"schema_version":1,"id":"released-lease","lane_id":"released-lane","agent":"agent1","session":"session1","paths":["README.md"],"state":"released","created_at":"2026-08-23T12:00:00Z","updated_at":"2026-08-23T12:00:00Z","expires_at":null,"released_at":"2026-08-23T12:00:00Z"}` + "\n") + aborted := legacyLane{SchemaVersion: 1, ID: "mcp-broker-9dx-019fcec6", Agent: "agent1", Session: "session1", Mode: store.ModeWorktree, Ref: "refs/heads/wip/agent1/mcp-broker-9dx-019fcec6", BaseRef: "HEAD", BaseSHA: head, CurrentSHA: head, Worktree: "", State: "aborted", CreatedAt: now, UpdatedAt: now} + _ = released + writeTestJSON(t, filepath.Join(repo.CommonDir, "ndev-wip", "v1", "lanes", releasedLane.ID+".json"), releasedLane, 0o600) + writeTestFile(t, filepath.Join(repo.CommonDir, "ndev-wip", "v1", "leases", "released-lease.json"), legacyNullExpiry, 0o600) + writeTestJSON(t, filepath.Join(repo.CommonDir, "ndev-wip", "v1", "lanes", aborted.ID+".json"), aborted, 0o600) + + plan := mustPreview(t, repo) + if plan.State != "ready" || importAction(plan.LaneImports, releasedLane.ID) != "archive-only" || importAction(plan.LeaseImports, "released-lease") != "archive-only" || importAction(plan.LaneImports, aborted.ID) != "archive-only" { + t.Fatalf("terminal dispositions were not archive-only: lanes=%#v leases=%#v conflicts=%#v", plan.LaneImports, plan.LeaseImports, plan.Conflicts) + } + if len(plan.Dispositions) < 3 { + t.Fatalf("missing typed archive-only dispositions: %#v", plan.Dispositions) + } + if _, err := applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{}); err != nil { + t.Fatal(err) + } + opened, initialized, err := store.Inspect(repo) + if err != nil || !initialized { + t.Fatalf("canonical store cannot open after apply: initialized=%v err=%v", initialized, err) + } + if _, err := opened.Load("lane1"); err != nil { + t.Fatalf("imported lane is unreadable: %v", err) + } + if _, err := opened.LoadLease("lease1"); err != nil { + t.Fatalf("imported lease is unreadable: %v", err) + } + imported, err := opened.Load("lane1") + if err != nil { + t.Fatal(err) + } + if err := opened.ValidateCapture(context.Background(), imported, []string{"README.md"}); err != nil { + t.Fatalf("post-apply canonical relationship read failed: %v", err) + } + if _, err := opened.Load(releasedLane.ID); fail.Code(err) != "LANE_NOT_FOUND" { + t.Fatalf("archive-only lane leaked into canonical state: %v", err) + } + archive := filepath.Join(archiveMigrationRoot(repo.CommonDir, plan.MigrationID), "source", "v1") + if _, err := os.Stat(filepath.Join(archive, "leases", "released-lease.json")); err != nil { + t.Fatalf("archive-only lease is missing from sealed source: %v", err) + } +} + +func TestIncompatibleActiveRecordsBlockMigration(t *testing.T) { + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + var lease legacyLease + if _, err := readJSONFile(filepath.Join(repo.CommonDir, "ndev-wip", "v1", "leases", "lease1.json"), &lease); err != nil { + t.Fatal(err) + } + lease.ExpiresAt = nil + writeTestJSON(t, filepath.Join(repo.CommonDir, "ndev-wip", "v1", "leases", "lease1.json"), lease, 0o600) + plan := mustPreview(t, repo) + if plan.State != "blocked" || importAction(plan.LeaseImports, "lease1") != "conflict" || !hasConflict(plan, "DESTINATION_READER_REJECTED") { + t.Fatalf("incompatible active lease did not block: %#v %#v", plan.LeaseImports, plan.Conflicts) + } + + // A reader-valid active lease must also have the exact lane reverse link. + lease.ExpiresAt = timePointer(time.Date(2030, 1, 1, 0, 0, 0, 0, time.UTC)) + writeTestJSON(t, filepath.Join(repo.CommonDir, "ndev-wip", "v1", "leases", "lease1.json"), lease, 0o600) + var lane legacyLane + if _, err := readJSONFile(filepath.Join(repo.CommonDir, "ndev-wip", "v1", "lanes", "lane1.json"), &lane); err != nil { + t.Fatal(err) + } + lane.LeaseIDs = nil + writeTestJSON(t, filepath.Join(repo.CommonDir, "ndev-wip", "v1", "lanes", "lane1.json"), lane, 0o600) + plan = mustPreview(t, repo) + if plan.State != "blocked" || !hasConflict(plan, "ACTIVE_LEASE_RELATION_INVALID") { + t.Fatalf("missing reverse relation did not block: %#v", plan.Conflicts) + } +} + +func TestCrossStoreRelationshipAndScopeConflictsBlockMigration(t *testing.T) { + t.Run("cross-lane portable lease", func(t *testing.T) { + repo, head := migrationTestRepo(t) + if _, err := store.Open(repo); err != nil { + t.Fatal(err) + } + writeLegacyFixture(t, repo, head) + now := time.Date(2026, 8, 23, 12, 0, 0, 0, time.UTC) + expires := time.Date(2030, 8, 24, 12, 0, 0, 0, time.UTC) + portableLane := legacyLane{SchemaVersion: 1, ID: "portable", Agent: "agent2", Session: "session2", Mode: store.ModeWorktree, Ref: "refs/heads/wip/agent2/portable", BaseRef: "HEAD", BaseSHA: head, CurrentSHA: head, Worktree: filepath.Join(repo.Root, "portable"), LeaseIDs: []string{"shared"}, State: "active", CreatedAt: now, UpdatedAt: now} + portableLease := legacyLease{SchemaVersion: 1, ID: "shared", LaneID: portableLane.ID, Agent: portableLane.Agent, Session: portableLane.Session, Paths: []string{"portable.txt"}, State: "active", CreatedAt: now, UpdatedAt: now, ExpiresAt: &expires} + writeTestJSON(t, filepath.Join(repo.CommonDir, "wip", "v1", "lanes", portableLane.ID+".json"), portableLane, 0o600) + writeTestJSON(t, filepath.Join(repo.CommonDir, "wip", "v1", "leases", portableLease.ID+".json"), portableLease, 0o600) + runGit(t, repo.Root, "update-ref", portableLane.Ref, head) + var lane legacyLane + if _, err := readJSONFile(filepath.Join(repo.CommonDir, "ndev-wip", "v1", "lanes", "lane1.json"), &lane); err != nil { + t.Fatal(err) + } + lane.LeaseIDs = []string{"shared"} + writeTestJSON(t, filepath.Join(repo.CommonDir, "ndev-wip", "v1", "lanes", "lane1.json"), lane, 0o600) + if err := os.Remove(filepath.Join(repo.CommonDir, "ndev-wip", "v1", "leases", "lease1.json")); err != nil { + t.Fatal(err) + } + plan := mustPreview(t, repo) + if plan.State != "blocked" || !hasConflict(plan, "ACTIVE_LANE_LEASE_INVALID") { + t.Fatalf("cross-lane portable lease did not block: %#v", plan.Conflicts) + } + }) + + t.Run("merged active scope overlap", func(t *testing.T) { + repo, head := migrationTestRepo(t) + if _, err := store.Open(repo); err != nil { + t.Fatal(err) + } + writeLegacyFixture(t, repo, head) + now := time.Date(2026, 8, 23, 12, 0, 0, 0, time.UTC) + expires := time.Date(2030, 8, 24, 12, 0, 0, 0, time.UTC) + portableLane := legacyLane{SchemaVersion: 1, ID: "portable", Agent: "agent2", Session: "session2", Mode: store.ModeWorktree, Ref: "refs/heads/wip/agent2/portable", BaseRef: "HEAD", BaseSHA: head, CurrentSHA: head, Worktree: filepath.Join(repo.Root, "portable"), LeaseIDs: []string{"portable-lease"}, State: "active", CreatedAt: now, UpdatedAt: now} + portableLease := legacyLease{SchemaVersion: 1, ID: "portable-lease", LaneID: portableLane.ID, Agent: portableLane.Agent, Session: portableLane.Session, Paths: []string{"README.md"}, State: "active", CreatedAt: now, UpdatedAt: now, ExpiresAt: &expires} + writeTestJSON(t, filepath.Join(repo.CommonDir, "wip", "v1", "lanes", portableLane.ID+".json"), portableLane, 0o600) + writeTestJSON(t, filepath.Join(repo.CommonDir, "wip", "v1", "leases", portableLease.ID+".json"), portableLease, 0o600) + runGit(t, repo.Root, "update-ref", portableLane.Ref, head) + plan := mustPreview(t, repo) + if plan.State != "blocked" || !hasConflict(plan, "PATH_LEASE_CONFLICT") { + t.Fatalf("merged active path overlap did not block: %#v", plan.Conflicts) + } + }) +} + +func TestExpiredActiveLeaseArchivesStaleLaneAndPreservesRef(t *testing.T) { + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + var lease legacyLease + if _, err := readJSONFile(filepath.Join(repo.CommonDir, "ndev-wip", "v1", "leases", "lease1.json"), &lease); err != nil { + t.Fatal(err) + } + lease.ExpiresAt = timePointer(time.Date(2025, 1, 1, 0, 0, 0, 0, time.UTC)) + writeTestJSON(t, filepath.Join(repo.CommonDir, "ndev-wip", "v1", "leases", "lease1.json"), lease, 0o600) + plan := mustPreview(t, repo) + if plan.State != "ready" || importAction(plan.LaneImports, "lane1") != "archive-only" || importAction(plan.LeaseImports, "lease1") != "archive-only" || !hasDisposition(plan, "STALE_ACTIVE_LANE") { + t.Fatalf("stale lane plan: lanes=%#v leases=%#v dispositions=%#v", plan.LaneImports, plan.LeaseImports, plan.Dispositions) + } + if got := expectedRefSHA(plan, "refs/heads/wip/agent1/lane1"); got != head { + t.Fatalf("expected ref SHA = %q, want %q", got, head) + } + if _, err := applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{}); err != nil { + t.Fatal(err) + } + opened, _, err := store.Inspect(repo) + if err != nil { + t.Fatal(err) + } + if _, err := opened.Load("lane1"); fail.Code(err) != "LANE_NOT_FOUND" { + t.Fatalf("archive-only stale lane leaked into canonical state: %v", err) + } + if _, err := opened.LoadLease("lease1"); fail.Code(err) != "LEASE_NOT_FOUND" { + t.Fatalf("archive-only stale lease leaked into canonical state: %v", err) + } + if got := strings.TrimSpace(runGit(t, repo.Root, "rev-parse", "refs/heads/wip/agent1/lane1")); got != head { + t.Fatalf("stale lane ref moved: got %s want %s", got, head) + } + archive := filepath.Join(archiveMigrationRoot(repo.CommonDir, plan.MigrationID), "source", "v1") + for _, path := range []string{"lanes/lane1.json", "leases/lease1.json"} { + if _, err := os.Stat(filepath.Join(archive, filepath.FromSlash(path))); err != nil { + t.Fatalf("archive-only stale record %s is missing from sealed source: %v", path, err) + } + } +} + +func TestExpiredActiveLeaseArchivesDescendantAdvancedRef(t *testing.T) { + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + expireLegacyLease(t, repo, "lease1") + tree := strings.TrimSpace(runGit(t, repo.Root, "rev-parse", head+"^{tree}")) + advanced := strings.TrimSpace(runGit(t, repo.Root, "commit-tree", tree, "-p", head, "-m", "advance stale lane ref")) + ref := "refs/heads/wip/agent1/lane1" + runGit(t, repo.Root, "update-ref", ref, advanced) + + plan := mustPreview(t, repo) + if plan.State != "ready" || importAction(plan.LaneImports, "lane1") != "archive-only" || importAction(plan.LeaseImports, "lease1") != "archive-only" || !hasDisposition(plan, "STALE_ACTIVE_REF_ADVANCED") { + t.Fatalf("advanced stale lane plan: lanes=%#v leases=%#v conflicts=%#v dispositions=%#v", plan.LaneImports, plan.LeaseImports, plan.Conflicts, plan.Dispositions) + } + if got := expectedRefSHA(plan, ref); got != advanced { + t.Fatalf("expected advanced ref SHA = %q, want %q", got, advanced) + } + if _, err := applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{}); err != nil { + t.Fatal(err) + } + if got := strings.TrimSpace(runGit(t, repo.Root, "rev-parse", ref)); got != advanced { + t.Fatalf("advanced stale lane ref moved: got %s want %s", got, advanced) + } +} + +func TestStaleActiveLaneRefSafetyBoundaries(t *testing.T) { + tests := []struct { + name string + expire bool + move func(*testing.T, gitx.Repo, string) + }{ + { + name: "live lease with advanced ref", + move: func(t *testing.T, repo gitx.Repo, head string) { + tree := strings.TrimSpace(runGit(t, repo.Root, "rev-parse", head+"^{tree}")) + advanced := strings.TrimSpace(runGit(t, repo.Root, "commit-tree", tree, "-p", head, "-m", "advance live lane ref")) + runGit(t, repo.Root, "update-ref", "refs/heads/wip/agent1/lane1", advanced) + }, + }, + { + name: "expired lease with missing ref", + expire: true, + move: func(t *testing.T, repo gitx.Repo, _ string) { + runGit(t, repo.Root, "update-ref", "-d", "refs/heads/wip/agent1/lane1") + }, + }, + { + name: "expired lease with diverged ref", + expire: true, + move: func(t *testing.T, repo gitx.Repo, head string) { + tree := strings.TrimSpace(runGit(t, repo.Root, "rev-parse", head+"^{tree}")) + diverged := strings.TrimSpace(runGit(t, repo.Root, "commit-tree", tree, "-m", "diverged stale lane ref")) + runGit(t, repo.Root, "update-ref", "refs/heads/wip/agent1/lane1", diverged) + }, + }, + } + for _, test := range tests { + t.Run(test.name, func(t *testing.T) { + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + if test.expire { + expireLegacyLease(t, repo, "lease1") + } + test.move(t, repo, head) + plan := mustPreview(t, repo) + if plan.State != "blocked" || importAction(plan.LaneImports, "lane1") != "conflict" || !hasConflict(plan, "REF_MISMATCH") { + t.Fatalf("unsafe stale ref did not block: lanes=%#v conflicts=%#v", plan.LaneImports, plan.Conflicts) + } + }) + } +} + +func TestActiveLaneWithoutLeasesArchivesAsStale(t *testing.T) { + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + var lane legacyLane + if _, err := readJSONFile(filepath.Join(repo.CommonDir, "ndev-wip", "v1", "lanes", "lane1.json"), &lane); err != nil { + t.Fatal(err) + } + lane.LeaseIDs = nil + writeTestJSON(t, filepath.Join(repo.CommonDir, "ndev-wip", "v1", "lanes", "lane1.json"), lane, 0o600) + if err := os.Remove(filepath.Join(repo.CommonDir, "ndev-wip", "v1", "leases", "lease1.json")); err != nil { + t.Fatal(err) + } + plan := mustPreview(t, repo) + if plan.State != "ready" || importAction(plan.LaneImports, "lane1") != "archive-only" || !hasDisposition(plan, "STALE_ACTIVE_LANE") { + t.Fatalf("zero-lease stale lane plan: lanes=%#v conflicts=%#v dispositions=%#v", plan.LaneImports, plan.Conflicts, plan.Dispositions) + } +} + +func TestActiveLaneWithLiveAndExpiredLeasesRemainsCanonical(t *testing.T) { + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + expireLegacyLease(t, repo, "lease1") + var lane legacyLane + if _, err := readJSONFile(filepath.Join(repo.CommonDir, "ndev-wip", "v1", "lanes", "lane1.json"), &lane); err != nil { + t.Fatal(err) + } + var live legacyLease + if _, err := readJSONFile(filepath.Join(repo.CommonDir, "ndev-wip", "v1", "leases", "lease1.json"), &live); err != nil { + t.Fatal(err) + } + live.ID = "lease2" + live.Paths = []string{"SECOND.md"} + live.ExpiresAt = timePointer(time.Date(2030, 8, 24, 12, 0, 0, 0, time.UTC)) + lane.LeaseIDs = []string{"lease1", "lease2"} + writeTestJSON(t, filepath.Join(repo.CommonDir, "ndev-wip", "v1", "lanes", "lane1.json"), lane, 0o600) + writeTestJSON(t, filepath.Join(repo.CommonDir, "ndev-wip", "v1", "leases", "lease2.json"), live, 0o600) + + plan := mustPreview(t, repo) + if plan.State != "ready" || importAction(plan.LaneImports, "lane1") != "import" || importAction(plan.LeaseImports, "lease1") != "import" || importAction(plan.LeaseImports, "lease2") != "import" || !hasDisposition(plan, "EXPIRED_ACTIVE_LEASE") { + t.Fatalf("mixed-live lane plan: lanes=%#v leases=%#v conflicts=%#v dispositions=%#v", plan.LaneImports, plan.LeaseImports, plan.Conflicts, plan.Dispositions) + } +} + +func TestPreviewRejectsUnsafeAndMovingSources(t *testing.T) { + t.Run("symlink", func(t *testing.T) { + repo, _ := migrationTestRepo(t) + if err := os.Symlink(repo.Root, filepath.Join(repo.CommonDir, "ndev-wip")); err != nil { + t.Fatal(err) + } + _, err := previewForTest(context.Background(), repo, PreviewOptions{}) + if fail.Code(err) != "MIGRATION_SOURCE_UNSAFE" { + t.Fatalf("expected unsafe source, got %v (%s)", err, fail.Code(err)) + } + }) + t.Run("nonregular", func(t *testing.T) { + if runtime.GOOS == "windows" { + t.Skip("named pipes are not portable to Windows") + } + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + fifo := filepath.Join(repo.CommonDir, "ndev-wip", "v1", "queue.pipe") + if err := exec.Command("mkfifo", fifo).Run(); err != nil { + t.Fatal(err) + } + _, err := previewForTest(context.Background(), repo, PreviewOptions{}) + if fail.Code(err) != "MIGRATION_SOURCE_UNSAFE" { + t.Fatalf("expected unsafe source, got %v (%s)", err, fail.Code(err)) + } + }) + t.Run("moving", func(t *testing.T) { + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + _, err := previewForTest(context.Background(), repo, PreviewOptions{AfterFirstSnapshot: func() error { + return os.WriteFile(filepath.Join(repo.CommonDir, "ndev-wip", "v1", "queue.json"), []byte("{\"changed\":true}\n"), 0o600) + }}) + if fail.Code(err) != "MIGRATION_SOURCE_MOVED" { + t.Fatalf("expected moving source, got %v (%s)", err, fail.Code(err)) + } + }) +} + +func TestApplyRequiresExactDigestPrestateAndCommonLock(t *testing.T) { + t.Run("digest", func(t *testing.T) { + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + plan := mustPreview(t, repo) + before := testTreeDigest(t, repo.CommonDir) + _, err := applyForTest(context.Background(), repo, plan, "sha256:"+strings.Repeat("0", 64), ApplyOptions{}) + if fail.Code(err) != "MIGRATION_PLAN_DIGEST_MISMATCH" || testTreeDigest(t, repo.CommonDir) != before { + t.Fatalf("digest refusal mutated state or returned wrong code: %v (%s)", err, fail.Code(err)) + } + }) + t.Run("prestate", func(t *testing.T) { + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + plan := mustPreview(t, repo) + writeTestFile(t, filepath.Join(repo.CommonDir, "ndev-wip", "v1", "queue.json"), []byte("{\"moved\":true}\n"), 0o600) + _, err := applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{}) + if fail.Code(err) != "MIGRATION_PRESTATE_CHANGED" { + t.Fatalf("expected prestate refusal, got %v (%s)", err, fail.Code(err)) + } + for _, path := range []string{writerFencePath(repo.CommonDir), bootstrapPlanPath(repo.CommonDir, plan.MigrationID), migrationJournalPath(repo.CommonDir)} { + if _, statErr := os.Lstat(path); !errors.Is(statErr, os.ErrNotExist) { + t.Fatalf("prestate refusal published recovery state at %s: %v", path, statErr) + } + } + }) + t.Run("lock", func(t *testing.T) { + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + plan := mustPreview(t, repo) + lock, err := filelock.Acquire(filepath.Join(repo.CommonDir, "wip-coordination.lock"), 0) + if err != nil { + t.Fatal(err) + } + defer func() { _ = lock.Release() }() + _, err = applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{}) + if fail.Code(err) != "MIGRATION_LOCKED" { + t.Fatalf("expected common-lock refusal, got %v (%s)", err, fail.Code(err)) + } + }) +} + +func TestEveryDurablePhaseResumesForward(t *testing.T) { + phases := []string{phaseJournalCreated, phaseCanonicalPrepared, phaseRecordsPublished, phaseSourceMoved, phaseArchiveSealed, phaseComplete} + for _, phase := range phases { + t.Run(phase, func(t *testing.T) { + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + plan := mustPreview(t, repo) + _, err := applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{AfterPhase: func(actual string) error { + if actual == phase { + return errors.New("injected crash") + } + return nil + }}) + if fail.Code(err) != "MIGRATION_INTERRUPTED" { + t.Fatalf("expected injected interruption, got %v (%s)", err, fail.Code(err)) + } + result, err := applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{Resume: true}) + if err != nil { + t.Fatal(err) + } + if !result.Applied || result.Status.State != "complete" { + t.Fatalf("resume did not complete: %#v", result) + } + }) + } +} + +func TestCrashWindowsInsideDurablePhasesResumeForward(t *testing.T) { + operations := []string{ + "record-published:wip/v1/lanes/lane1.json", + "source-renamed", + "archive-seal-written", + "receipt-written", + } + for _, operation := range operations { + t.Run(strings.ReplaceAll(operation, "/", "_"), func(t *testing.T) { + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + plan := mustPreview(t, repo) + _, err := applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{AfterOperation: func(actual string) error { + if actual == operation { + return errors.New("injected operation crash") + } + return nil + }}) + if fail.Code(err) != "MIGRATION_INTERRUPTED" { + t.Fatalf("expected interruption after %s, got %v (%s)", operation, err, fail.Code(err)) + } + result, err := applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{Resume: true}) + if err != nil { + t.Fatal(err) + } + if !result.Applied || result.Status.State != "complete" { + t.Fatalf("resume after %s did not complete: %#v", operation, result) + } + }) + } +} + +func TestChangedMovedSourceBlocksResumeAndPreservesArchive(t *testing.T) { + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + plan := mustPreview(t, repo) + _, err := applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{AfterOperation: func(operation string) error { + if operation != "source-renamed" { + return nil + } + queue := filepath.Join(archiveMigrationRoot(repo.CommonDir, plan.MigrationID), "source", "v1", "queue.json") + if writeErr := os.WriteFile(queue, []byte("{\"changed_after_move\":true}\n"), 0o600); writeErr != nil { + return writeErr + } + return errors.New("injected writer after source move") + }}) + if fail.Code(err) != "MIGRATION_INTERRUPTED" { + t.Fatalf("expected interruption after source move, got %v (%s)", err, fail.Code(err)) + } + _, err = applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{Resume: true}) + if fail.Code(err) != "MIGRATION_ARCHIVE_MOVED" { + t.Fatalf("changed moved source was not rejected: %v (%s)", err, fail.Code(err)) + } + if _, err := os.Lstat(filepath.Join(repo.CommonDir, "ndev-wip")); !errors.Is(err, os.ErrNotExist) { + t.Fatalf("legacy source unexpectedly reappeared: %v", err) + } + if _, err := os.Stat(filepath.Join(archiveMigrationRoot(repo.CommonDir, plan.MigrationID), "source", "v1", "queue.json")); err != nil { + t.Fatalf("changed source was not preserved for recovery: %v", err) + } +} + +func TestStatusKeepsReceiptCrashInProgressAndBindsArchiveSeal(t *testing.T) { + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + plan := mustPreview(t, repo) + _, err := applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{AfterOperation: func(operation string) error { + if operation == "receipt-written" { + return errors.New("injected receipt crash") + } + return nil + }}) + if fail.Code(err) != "MIGRATION_INTERRUPTED" { + t.Fatalf("expected receipt interruption, got %v (%s)", err, fail.Code(err)) + } + status, err := InspectStatus(repo, plan.MigrationID) + if err != nil || status.State != "in-progress" || status.Receipt == nil || status.Phase != phaseArchiveSealed { + t.Fatalf("receipt crash status=%#v err=%v", status, err) + } + if _, err := applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{Resume: true}); err != nil { + t.Fatal(err) + } + sealPath := filepath.Join(archiveMigrationRoot(repo.CommonDir, plan.MigrationID), "seal.json") + var seal Seal + if _, err := readJSONFile(sealPath, &seal); err != nil { + t.Fatal(err) + } + seal.PlanDigest = "sha256:" + strings.Repeat("0", 64) + // The completed seal is intentionally read-only. Simulate an external + // attacker that first makes the file writable before changing its bytes. + // Windows does not replace a file while its read-only attribute is set. + if err := os.Chmod(sealPath, 0o600); err != nil { + t.Fatal(err) + } + if err := writeJSON(sealPath, seal, 0o400, true); err != nil { + t.Fatal(err) + } + if _, err := InspectStatus(repo, plan.MigrationID); fail.Code(err) != "MIGRATION_ARCHIVE_INVALID" { + t.Fatalf("tampered archive seal was accepted: %v (%s)", err, fail.Code(err)) + } +} + +func TestRollbackBeforeMoveLeavesMarkerAndSource(t *testing.T) { + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + plan := mustPreview(t, repo) + _, err := applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{AfterPhase: func(phase string) error { + if phase == phaseRecordsPublished { + return errors.New("stop before move") + } + return nil + }}) + if fail.Code(err) != "MIGRATION_INTERRUPTED" { + t.Fatal(err) + } + result, err := applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{Rollback: true}) + if err != nil { + t.Fatal(err) + } + if !result.RolledBack || result.Status.Rollback == nil || !result.Status.LegacyExists { + t.Fatalf("unexpected rollback: %#v", result) + } + if _, err := os.Lstat(filepath.Join(repo.CommonDir, "wip", "v1", "lanes", "lane1.json")); !errors.Is(err, os.ErrNotExist) { + t.Fatalf("import survived rollback: %v", err) + } + if err := activateWriterFence(repo.CommonDir, plan); err != nil { + t.Fatal(err) + } + idempotent, err := applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{Rollback: true}) + if err != nil || !idempotent.RolledBack || idempotent.Status.State != "rolled-back" { + t.Fatalf("idempotent rollback = %#v err=%v", idempotent, err) + } + if _, err := os.Lstat(writerFencePath(repo.CommonDir)); !errors.Is(err, os.ErrNotExist) { + t.Fatalf("idempotent rollback left the recovery fence active: %v", err) + } + + fresh := mustPreview(t, repo) + if fresh.MigrationID == plan.MigrationID || fresh.PlanDigest == plan.PlanDigest { + t.Fatalf("fresh preview reused rolled-back identity: old=%s/%s new=%s/%s", plan.MigrationID, plan.PlanDigest, fresh.MigrationID, fresh.PlanDigest) + } + completed, err := applyForTest(context.Background(), repo, fresh, fresh.PlanDigest, ApplyOptions{}) + if err != nil || !completed.Applied || completed.Status.State != "complete" { + t.Fatalf("fresh migration after rollback = %#v err=%v", completed, err) + } + retired := retiredJournalPath(repo.CommonDir, plan.MigrationID) + if info, err := os.Lstat(retired); err != nil || !info.Mode().IsRegular() || modeString(info.Mode()) != "0400" { + t.Fatalf("retired rollback journal mode=%v err=%v", infoMode(info), err) + } + current, exists, err := readJournal(migrationJournalPath(repo.CommonDir)) + if err != nil || !exists || current.MigrationID != fresh.MigrationID || current.Phase != phaseComplete { + t.Fatalf("active journal after fresh migration = %#v exists=%v err=%v", current, exists, err) + } + oldStatus, err := InspectStatus(repo, plan.MigrationID) + if err != nil || oldStatus.State != "rolled-back" || oldStatus.Rollback == nil { + t.Fatalf("historical rollback status = %#v err=%v", oldStatus, err) + } +} + +func TestInterruptedRollbackResumesOnlyRollback(t *testing.T) { + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + plan := mustPreview(t, repo) + _, err := applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{AfterPhase: func(phase string) error { + if phase == phaseRecordsPublished { + return errors.New("stop before move") + } + return nil + }}) + if fail.Code(err) != "MIGRATION_INTERRUPTED" { + t.Fatal(err) + } + + interrupted := false + _, err = applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{Rollback: true, AfterOperation: func(operation string) error { + if !interrupted && strings.HasPrefix(operation, "rollback-removed:") { + interrupted = true + return errors.New("stop after exact rollback removal") + } + return nil + }}) + if fail.Code(err) != "MIGRATION_INTERRUPTED" || !interrupted { + t.Fatalf("rollback interruption = %v (%s), interrupted=%v", err, fail.Code(err), interrupted) + } + journal, exists, err := readJournal(migrationJournalPath(repo.CommonDir)) + if err != nil || !exists || journal.Phase != phaseRollbackStarted { + t.Fatalf("rollback journal = %#v exists=%v err=%v", journal, exists, err) + } + if _, err := applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{Resume: true}); fail.Code(err) != "MIGRATION_ROLLBACK_REQUIRED" { + t.Fatalf("forward resume after rollback start was accepted: %v (%s)", err, fail.Code(err)) + } + + result, err := applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{Rollback: true}) + if err != nil || !result.RolledBack || result.Status.State != "rolled-back" { + t.Fatalf("rollback retry = %#v err=%v", result, err) + } + if _, err := os.Lstat(filepath.Join(repo.CommonDir, "wip", "v1", "lanes", "lane1.json")); !errors.Is(err, os.ErrNotExist) { + t.Fatalf("import survived rollback retry: %v", err) + } + if _, err := os.Lstat(filepath.Join(repo.CommonDir, "ndev-wip")); err != nil { + t.Fatalf("legacy source did not survive rollback retry: %v", err) + } +} + +func TestMigrationIdentityIsDeterministicAndConfined(t *testing.T) { + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + plan := mustPreview(t, repo) + + for _, invalid := range []string{"../../config", "migration-aaaaaaaaaaaaaaaaaaaaaaa", "migration-AAAAAAAAAAAAAAAAAAAAAAAA"} { + t.Run(invalid, func(t *testing.T) { + tampered := plan + tampered.MigrationID = invalid + var err error + tampered.PlanDigest, err = planDigest(tampered) + if err != nil { + t.Fatal(err) + } + _, err = applyForTest(context.Background(), repo, tampered, tampered.PlanDigest, ApplyOptions{}) + if fail.Code(err) != "MIGRATION_PLAN_DIGEST_MISMATCH" { + t.Fatalf("tampered migration identity was accepted: %v (%s)", err, fail.Code(err)) + } + if _, err := InspectStatus(repo, invalid); fail.Code(err) != "MIGRATION_STATUS_INVALID" { + t.Fatalf("status accepted migration identity %q: %v (%s)", invalid, err, fail.Code(err)) + } + }) + } + + tampered := plan + tampered.MigrationID = "migration-aaaaaaaaaaaaaaaaaaaaaaaa" + var err error + tampered.PlanDigest, err = planDigest(tampered) + if err != nil { + t.Fatal(err) + } + if _, err := applyForTest(context.Background(), repo, tampered, tampered.PlanDigest, ApplyOptions{}); fail.Code(err) != "MIGRATION_PLAN_DIGEST_MISMATCH" { + t.Fatalf("well-formed but non-deterministic migration identity was accepted: %v (%s)", err, fail.Code(err)) + } +} + +func TestResumeModeAndCanonicalBindings(t *testing.T) { + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + plan := mustPreview(t, repo) + _, err := applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{AfterPhase: func(phase string) error { + if phase == phaseRecordsPublished { + return errors.New("stop after records") + } + return nil + }}) + if fail.Code(err) != "MIGRATION_INTERRUPTED" { + t.Fatalf("expected interruption, got %v", err) + } + result, err := applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{Resume: true}) + if err != nil { + t.Fatal(err) + } + if result.Mode != "resume" || !result.Resumed || !result.Applied || result.Receipt == nil || result.Receipt.CanonicalManifest != plan.PlannedCanonicalData.Digest { + t.Fatalf("resume protocol or manifest binding is invalid: %#v", result) + } +} + +func TestProducerIdentityIsDigestBoundAndRevalidated(t *testing.T) { + t.Run("preview requires complete identity", func(t *testing.T) { + repo, _ := migrationTestRepo(t) + if _, err := Preview(context.Background(), repo, PreviewOptions{}); fail.Code(err) != "MIGRATION_PRODUCER_INVALID" { + t.Fatalf("preview accepted an absent producer: %v (%s)", err, fail.Code(err)) + } + }) + t.Run("identity is part of plan digest", func(t *testing.T) { + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + plan := mustPreview(t, repo) + changed := plan + changed.Producer.ExecutableSHA256 = "sha256:" + strings.Repeat("d", 64) + if err := changed.ValidateDigest(plan.PlanDigest); err == nil { + t.Fatal("producer change did not invalidate the reviewed plan digest") + } + }) + t.Run("apply rejects different running executable", func(t *testing.T) { + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + plan := mustPreview(t, repo) + producer := plan.Producer + producer.ExecutableSHA256 = "sha256:" + strings.Repeat("d", 64) + _, err := Apply(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{Producer: producer}) + if fail.Code(err) != "MIGRATION_PRODUCER_MISMATCH" { + t.Fatalf("apply accepted a different executable: %v (%s)", err, fail.Code(err)) + } + }) + t.Run("resume rejects different portable bundle", func(t *testing.T) { + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + plan := mustPreview(t, repo) + _, err := applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{AfterPhase: func(phase string) error { + if phase == phaseJournalCreated { + return errors.New("stop after journal") + } + return nil + }}) + if fail.Code(err) != "MIGRATION_INTERRUPTED" { + t.Fatal(err) + } + producer := plan.Producer + producer.PortableBundleSHA256 = "sha256:" + strings.Repeat("d", 64) + _, err = Apply(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{Resume: true, Producer: producer}) + if fail.Code(err) != "MIGRATION_PRODUCER_MISMATCH" { + t.Fatalf("resume accepted a different portable bundle: %v (%s)", err, fail.Code(err)) + } + }) + t.Run("forged producer cannot name an invalid tag", func(t *testing.T) { + producer := testProducerIdentity() + producer.ReleaseTagged = true + producer.ReleaseTag = "v9.9.9" + if err := producer.Validate(); err == nil { + t.Fatal("producer accepted a tag that does not match its version") + } + }) +} + +func TestResumeAndStatusRejectCanonicalDrift(t *testing.T) { + t.Run("resume", func(t *testing.T) { + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + plan := mustPreview(t, repo) + _, err := applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{AfterPhase: func(phase string) error { + if phase == phaseRecordsPublished { + return errors.New("stop after records") + } + return nil + }}) + if fail.Code(err) != "MIGRATION_INTERRUPTED" { + t.Fatal(err) + } + writeTestFile(t, filepath.Join(repo.CommonDir, "wip", "v1", "lanes", "lane1.json"), []byte("{}\n"), 0o600) + _, err = applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{Resume: true}) + if fail.Code(err) != "MIGRATION_CANONICAL_MOVED" { + t.Fatalf("canonical drift was accepted on resume: %v (%s)", err, fail.Code(err)) + } + }) + t.Run("incomplete status", func(t *testing.T) { + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + plan := mustPreview(t, repo) + _, err := applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{AfterPhase: func(phase string) error { + if phase == phaseRecordsPublished { + return errors.New("stop after records") + } + return nil + }}) + if fail.Code(err) != "MIGRATION_INTERRUPTED" { + t.Fatal(err) + } + writeTestFile(t, filepath.Join(repo.CommonDir, "wip", "v1", "lanes", "lane1.json"), []byte("{}\n"), 0o600) + if _, err := InspectStatus(repo, plan.MigrationID); fail.Code(err) != "MIGRATION_CANONICAL_MOVED" { + t.Fatalf("incomplete status accepted canonical drift: %v (%s)", err, fail.Code(err)) + } + }) + t.Run("resume rejects envelope sibling", func(t *testing.T) { + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + plan := mustPreview(t, repo) + _, err := applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{AfterPhase: func(phase string) error { + if phase == phaseCanonicalPrepared { + return errors.New("stop after canonical preparation") + } + return nil + }}) + if fail.Code(err) != "MIGRATION_INTERRUPTED" { + t.Fatal(err) + } + writeTestFile(t, filepath.Join(repo.CommonDir, "wip", "unexpected.json"), []byte("{}\n"), 0o600) + _, err = applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{Resume: true}) + if fail.Code(err) != "MIGRATION_CANONICAL_MOVED" { + t.Fatalf("canonical envelope drift was accepted on resume: %v (%s)", err, fail.Code(err)) + } + }) + t.Run("journal cannot authorize an unplanned sibling", func(t *testing.T) { + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + plan := mustPreview(t, repo) + _, err := applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{AfterPhase: func(phase string) error { + if phase == phaseCanonicalPrepared { + return errors.New("stop after canonical preparation") + } + return nil + }}) + if fail.Code(err) != "MIGRATION_INTERRUPTED" { + t.Fatal(err) + } + journalPath := migrationJournalPath(repo.CommonDir) + journal, exists, err := readJournal(journalPath) + if err != nil || !exists { + t.Fatal(err) + } + journal.PublishedPaths = append(journal.PublishedPaths, "wip/unexpected.json") + if err := writeJSON(journalPath, journal, 0o600, true); err != nil { + t.Fatal(err) + } + writeTestFile(t, filepath.Join(repo.CommonDir, "wip", "unexpected.json"), []byte("{}\n"), 0o600) + _, err = applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{Resume: true}) + if fail.Code(err) != "MIGRATION_CANONICAL_MOVED" { + t.Fatalf("unplanned journal path was accepted: %v (%s)", err, fail.Code(err)) + } + }) + t.Run("rollback verifies prefix before removal", func(t *testing.T) { + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + plan := mustPreview(t, repo) + _, err := applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{AfterPhase: func(phase string) error { + if phase == phaseRecordsPublished { + return errors.New("stop after records") + } + return nil + }}) + if fail.Code(err) != "MIGRATION_INTERRUPTED" { + t.Fatal(err) + } + writeTestFile(t, filepath.Join(repo.CommonDir, "wip", "unexpected.json"), []byte("{}\n"), 0o600) + _, err = applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{Rollback: true}) + if fail.Code(err) != "MIGRATION_CANONICAL_MOVED" { + t.Fatalf("rollback accepted an unverified canonical prefix: %v (%s)", err, fail.Code(err)) + } + if _, statErr := os.Lstat(filepath.Join(repo.CommonDir, "wip", "v1", "lanes", "lane1.json")); statErr != nil { + t.Fatalf("rollback mutated outputs before verification: %v", statErr) + } + }) +} + +func TestCompletedMigrationStatusReportsPostCutoverAdvance(t *testing.T) { + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + plan := mustPreview(t, repo) + if _, err := applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{}); err != nil { + t.Fatal(err) + } + + initial, err := InspectStatus(repo, plan.MigrationID) + if err != nil { + t.Fatal(err) + } + if initial.State != "complete" || initial.Receipt == nil || initial.CanonicalAdvanced || initial.CurrentCanonicalManifestDigest != initial.Receipt.CanonicalManifest { + t.Fatalf("unexpected initial completed status: %#v", initial) + } + + laneStore, err := store.Open(repo) + if err != nil { + t.Fatal(err) + } + if _, err := laneStore.Renew("lane1", "agent1", "session1"); err != nil { + t.Fatal(err) + } + privateIndex := filepath.Join(repo.CommonDir, "wip", "indexes", "capture", "index") + writeTestFile(t, privateIndex, []byte("transient private index\n"), 0o600) + + advanced, err := InspectStatus(repo, plan.MigrationID) + if err != nil { + t.Fatal(err) + } + current, err := manifestCanonicalData(repo.CommonDir) + if err != nil { + t.Fatal(err) + } + if advanced.State != "complete" || advanced.Receipt == nil || !advanced.CanonicalAdvanced { + t.Fatalf("post-cutover writer did not produce advanced completed status: %#v", advanced) + } + if advanced.CurrentCanonicalManifestDigest != current.Digest || advanced.CurrentCanonicalManifestDigest == advanced.Receipt.CanonicalManifest { + t.Fatalf("post-cutover manifest was not reported exactly: status=%#v current=%s", advanced, current.Digest) + } +} + +func TestCompletedMigrationStatusRejectsUnsafePrivateIndexRoot(t *testing.T) { + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + plan := mustPreview(t, repo) + if _, err := applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{}); err != nil { + t.Fatal(err) + } + writeTestFile(t, filepath.Join(repo.CommonDir, "wip", "indexes"), []byte("not a directory\n"), 0o600) + if _, err := InspectStatus(repo, plan.MigrationID); fail.Code(err) != "MIGRATION_CANONICAL_MOVED" { + t.Fatalf("completed status accepted an unsafe private-index root: %v (%s)", err, fail.Code(err)) + } +} + +func TestCompletedMigrationStatusStillRejectsEnvelopeDrift(t *testing.T) { + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + plan := mustPreview(t, repo) + if _, err := applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{}); err != nil { + t.Fatal(err) + } + writeTestFile(t, filepath.Join(repo.CommonDir, "wip", "unexpected.json"), []byte("{}\n"), 0o600) + if _, err := InspectStatus(repo, plan.MigrationID); fail.Code(err) != "MIGRATION_CANONICAL_MOVED" { + t.Fatalf("completed status accepted migration-envelope drift: %v (%s)", err, fail.Code(err)) + } +} + +func TestInterruptedMigrationFenceBlocksCurrentWriters(t *testing.T) { + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + plan := mustPreview(t, repo) + _, err := applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{AfterPhase: func(phase string) error { + if phase == phaseJournalCreated { + return errors.New("stop with durable fence") + } + return nil + }}) + if fail.Code(err) != "MIGRATION_INTERRUPTED" { + t.Fatal(err) + } + if _, err := store.AcquireWriterFence(repo, 0); fail.Code(err) != "MIGRATION_IN_PROGRESS" { + t.Fatalf("current writer ignored migration fence: %v (%s)", err, fail.Code(err)) + } + if _, err := applyForTest(context.Background(), repo, plan, plan.PlanDigest, ApplyOptions{Resume: true}); err != nil { + t.Fatal(err) + } + fence, err := store.AcquireWriterFence(repo, 0) + if err != nil { + t.Fatalf("completed migration left writer fence active: %v", err) + } + _ = fence.Release() +} + +func TestPreviewRejectsNestedLegacyRecordAndPlanBound(t *testing.T) { + repo, head := migrationTestRepo(t) + writeLegacyFixture(t, repo, head) + if err := os.MkdirAll(filepath.Join(repo.CommonDir, "ndev-wip", "v1", "lanes", "nested"), 0o700); err != nil { + t.Fatal(err) + } + writeTestFile(t, filepath.Join(repo.CommonDir, "ndev-wip", "v1", "lanes", "nested", "lane1.json"), []byte("{}\n"), 0o600) + if _, err := previewForTest(context.Background(), repo, PreviewOptions{}); fail.Code(err) != "MIGRATION_SOURCE_INVALID" { + t.Fatalf("nested legacy record was accepted: %v (%s)", err, fail.Code(err)) + } + if _, err := DecodePlan(make([]byte, MaxPlanBytes+1)); err == nil { + t.Fatal("oversized plan was accepted") + } +} + +func TestConfinedPublicationRejectsNestedSymlinkParent(t *testing.T) { + common := t.TempDir() + outside := t.TempDir() + if err := os.MkdirAll(filepath.Join(common, "wip", "review", "v1"), 0o700); err != nil { + t.Fatal(err) + } + if err := os.Symlink(outside, filepath.Join(common, "wip", "review", "v1", "archive")); err != nil { + t.Fatal(err) + } + err := createConfinedExact(common, "wip/review/v1/archive/receipt.json", []byte("protected\n"), 0o600) + if err == nil { + t.Fatal("nested symlink parent was accepted") + } + if _, err := os.Lstat(filepath.Join(outside, "receipt.json")); !errors.Is(err, os.ErrNotExist) { + t.Fatalf("publication escaped through symlink: %v", err) + } +} + +func TestConfinedPublicationCreatesExactReadOnlyFile(t *testing.T) { + common := t.TempDir() + relative := "wip/migration/v1/migration-0123456789abcdef01234567/plan.json" + destination := filepath.Join(common, filepath.FromSlash(relative)) + if err := os.MkdirAll(filepath.Dir(destination), 0o700); err != nil { + t.Fatal(err) + } + body := []byte("reviewed immutable plan\n") + for attempt := 0; attempt < 2; attempt++ { + if err := createConfinedExact(common, relative, body, 0o400); err != nil { + t.Fatalf("attempt %d: %v", attempt+1, err) + } + } + got, err := os.ReadFile(destination) + if err != nil { + t.Fatal(err) + } + if !bytes.Equal(got, body) { + t.Fatalf("body = %q, want %q", got, body) + } + info, err := os.Lstat(destination) + if err != nil { + t.Fatal(err) + } + if gotMode := modeString(info.Mode()); gotMode != "0400" { + t.Fatalf("canonical mode = %s, want 0400", gotMode) + } + entries, err := os.ReadDir(filepath.Dir(destination)) + if err != nil { + t.Fatal(err) + } + for _, entry := range entries { + if strings.HasPrefix(entry.Name(), ".~plan.json.") { + t.Fatalf("temporary publication entry remains: %s", entry.Name()) + } + } +} + +func TestExactPublicationCreatesIdempotentReadOnlyFile(t *testing.T) { + path := filepath.Join(t.TempDir(), "plan.json") + body := []byte("reviewed bootstrap plan\n") + for attempt := 0; attempt < 2; attempt++ { + if err := createExact(path, body, 0o400); err != nil { + t.Fatalf("attempt %d: %v", attempt+1, err) + } + } + got, err := os.ReadFile(path) + if err != nil { + t.Fatal(err) + } + if !bytes.Equal(got, body) { + t.Fatalf("body = %q, want %q", got, body) + } + info, err := os.Lstat(path) + if err != nil { + t.Fatal(err) + } + if gotMode := modeString(info.Mode()); gotMode != "0400" { + t.Fatalf("canonical mode = %s, want 0400", gotMode) + } +} + +func TestWindowsReadOnlyFinalizeWindowResumesExactPublications(t *testing.T) { + if runtime.GOOS != "windows" { + t.Skip("Windows mode finalization has a platform-specific crash window") + } + common := t.TempDir() + body := []byte("reviewed immutable plan\n") + + bootstrap := filepath.Join(common, "bootstrap-plan.json") + writeTestFile(t, bootstrap, body, 0o600) + if err := createExact(bootstrap, body, 0o400); err != nil { + t.Fatalf("resume bootstrap publication: %v", err) + } + if info, err := os.Lstat(bootstrap); err != nil || modeString(info.Mode()) != "0400" { + t.Fatalf("bootstrap mode=%v err=%v", infoMode(info), err) + } + + relative := "wip/migration/v1/migration-0123456789abcdef01234567/plan.json" + destination := filepath.Join(common, filepath.FromSlash(relative)) + writeTestFile(t, destination, body, 0o600) + if err := createConfinedExact(common, relative, body, 0o400); err != nil { + t.Fatalf("resume confined publication: %v", err) + } + if info, err := os.Lstat(destination); err != nil || modeString(info.Mode()) != "0400" { + t.Fatalf("confined mode=%v err=%v", infoMode(info), err) + } + + conflict := filepath.Join(common, "conflict-plan.json") + writeTestFile(t, conflict, []byte("foreign bytes\n"), 0o600) + if err := createExact(conflict, body, 0o400); err == nil { + t.Fatal("mode repair accepted foreign bytes") + } +} + +func TestMigrationGitFixtureIgnoresInheritedRepositoryEnvironment(t *testing.T) { + decoy := t.TempDir() + runGit(t, decoy, "init", "-q") + decoyConfig := filepath.Join(decoy, ".git", "config") + before, err := os.ReadFile(decoyConfig) + if err != nil { + t.Fatal(err) + } + t.Setenv("GIT_DIR", filepath.Join(decoy, ".git")) + t.Setenv("GIT_WORK_TREE", decoy) + t.Setenv("GIT_INDEX_FILE", filepath.Join(decoy, ".git", "foreign-index")) + fixture := t.TempDir() + runGit(t, fixture, "init", "-q") + runGit(t, fixture, "config", "user.name", "Confined Fixture") + after, err := os.ReadFile(decoyConfig) + if err != nil { + t.Fatal(err) + } + if !bytes.Equal(before, after) { + t.Fatal("fixture Git command mutated the inherited repository") + } +} + +func migrationTestRepo(t *testing.T) (gitx.Repo, string) { + t.Helper() + root := t.TempDir() + runGit(t, root, "init", "-q") + runGit(t, root, "config", "user.name", "Migration Test") + runGit(t, root, "config", "user.email", "migration@example.invalid") + writeTestFile(t, filepath.Join(root, "README.md"), []byte("test\n"), 0o600) + runGit(t, root, "add", "README.md") + runGit(t, root, "commit", "-qm", "initial") + repo, err := gitx.Discover(context.Background(), root) + if err != nil { + t.Fatal(err) + } + head := strings.TrimSpace(runGit(t, root, "rev-parse", "HEAD")) + t.Cleanup(func() { + archive := filepath.Join(repo.CommonDir, "wip", "archive") + _ = filepath.Walk(archive, func(path string, info os.FileInfo, err error) error { + if err != nil { + return nil + } + if info.IsDir() { + _ = os.Chmod(path, 0o700) + } else { + _ = os.Chmod(path, 0o600) + } + return nil + }) + }) + return repo, head +} + +func writeLegacyFixture(t *testing.T, repo gitx.Repo, head string) { + t.Helper() + for _, directory := range []string{"lanes", "leases", "locks", "landing-intents", "archive"} { + if err := os.MkdirAll(filepath.Join(repo.CommonDir, "ndev-wip", "v1", directory), 0o700); err != nil { + t.Fatal(err) + } + } + now := time.Date(2026, 8, 23, 12, 0, 0, 0, time.UTC) + expires := time.Date(2030, 8, 24, 12, 0, 0, 0, time.UTC) + lane := legacyLane{SchemaVersion: 1, ID: "lane1", Agent: "agent1", Session: "session1", Mode: "worktree", Ref: "refs/heads/wip/agent1/lane1", BaseRef: "HEAD", BaseSHA: head, CurrentSHA: head, Worktree: repo.Root, LeaseIDs: []string{"lease1"}, State: "active", CreatedAt: now, UpdatedAt: now} + lease := legacyLease{SchemaVersion: 1, ID: "lease1", LaneID: "lane1", Agent: "agent1", Session: "session1", Paths: []string{"README.md"}, State: "active", CreatedAt: now, UpdatedAt: now, ExpiresAt: &expires} + writeTestJSON(t, filepath.Join(repo.CommonDir, "ndev-wip", "v1", "lanes", "lane1.json"), lane, 0o600) + writeTestJSON(t, filepath.Join(repo.CommonDir, "ndev-wip", "v1", "leases", "lease1.json"), lease, 0o600) + writeTestFile(t, filepath.Join(repo.CommonDir, "ndev-wip", "v1", "queue.json"), []byte("{\"schema_version\":1,\"entries\":[]}\n"), 0o600) + writeTestFile(t, filepath.Join(repo.CommonDir, "ndev-wip", "v1", "landing-intents", "intent.json"), []byte("{\"id\":\"intent\"}\n"), 0o600) + runGit(t, repo.Root, "update-ref", lane.Ref, head) +} + +func testManifestEntry(manifest TreeManifest, path string) (ManifestEntry, bool) { + for _, entry := range manifest.Entries { + if entry.Path == path { + return entry, true + } + } + return ManifestEntry{}, false +} + +func writeTestJSON(t *testing.T, path string, value any, mode os.FileMode) { + t.Helper() + body, err := normalizedJSON(value) + if err != nil { + t.Fatal(err) + } + writeTestFile(t, path, body, mode) +} + +func writeTestFile(t *testing.T, path string, body []byte, mode os.FileMode) { + t.Helper() + if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(path, body, mode); err != nil { + t.Fatal(err) + } +} + +func runGit(t *testing.T, directory string, args ...string) string { + t.Helper() + command := exec.Command("git", args...) + command.Dir = directory + command.Env = confinedGitEnvironment(os.Environ()) + output, err := command.CombinedOutput() + if err != nil { + t.Fatalf("git %v: %v\n%s", args, err, output) + } + return string(output) +} + +func testProducerIdentity() ProducerIdentity { + return ProducerIdentity{ + CommandProtocol: contract.Protocol, + Product: "github.com/nstranquist/wip-commit", + Version: "0.2.0-beta.1", + SourceRevision: strings.Repeat("a", 40), + SourceState: "clean", + PortableBundleSHA256: "sha256:" + strings.Repeat("b", 64), + ExecutableSHA256: "sha256:" + strings.Repeat("c", 64), + } +} + +func previewForTest(ctx context.Context, repo gitx.Repo, options PreviewOptions) (Plan, error) { + options.Producer = testProducerIdentity() + return Preview(ctx, repo, options) +} + +func applyForTest(ctx context.Context, repo gitx.Repo, plan Plan, expectedDigest string, options ApplyOptions) (Result, error) { + options.Producer = plan.Producer + return Apply(ctx, repo, plan, expectedDigest, options) +} + +func confinedGitEnvironment(environment []string) []string { + blocked := map[string]bool{ + "GIT_ALTERNATE_OBJECT_DIRECTORIES": true, + "GIT_CEILING_DIRECTORIES": true, + "GIT_COMMON_DIR": true, + "GIT_CONFIG": true, + "GIT_CONFIG_COUNT": true, + "GIT_CONFIG_GLOBAL": true, + "GIT_CONFIG_NOSYSTEM": true, + "GIT_CONFIG_SYSTEM": true, + "GIT_DIR": true, + "GIT_INDEX_FILE": true, + "GIT_OBJECT_DIRECTORY": true, + "GIT_WORK_TREE": true, + } + result := make([]string, 0, len(environment)+2) + for _, item := range environment { + key, _, _ := strings.Cut(item, "=") + if blocked[key] || strings.HasPrefix(key, "GIT_CONFIG_KEY_") || strings.HasPrefix(key, "GIT_CONFIG_VALUE_") { + continue + } + result = append(result, item) + } + return append(result, "GIT_CONFIG_NOSYSTEM=1", "GIT_CONFIG_GLOBAL="+os.DevNull) +} + +func mustPreview(t *testing.T, repo gitx.Repo) Plan { + t.Helper() + plan, err := previewForTest(context.Background(), repo, PreviewOptions{}) + if err != nil { + t.Fatal(err) + } + return plan +} + +func testTreeDigest(t *testing.T, commonDir string) string { + t.Helper() + manifest, err := manifestTree(commonDir, ".") + if err != nil { + t.Fatal(err) + } + return manifest.Digest +} + +func assertDigest(t *testing.T, path, want string) { + t.Helper() + body, err := os.ReadFile(path) + if err != nil { + t.Fatal(err) + } + if got := digest(body); got != want { + t.Fatalf("digest %s = %s, want %s", path, got, want) + } +} + +func findCopy(t *testing.T, copies []CopyRecord, suffix string) CopyRecord { + t.Helper() + for _, copy := range copies { + if strings.HasSuffix(copy.Destination, suffix) { + return copy + } + } + t.Fatalf("copy ending in %s not found", suffix) + return CopyRecord{} +} + +func infoMode(info os.FileInfo) os.FileMode { + if info == nil { + return 0 + } + return info.Mode().Perm() +} + +func importAction(records []ImportRecord, id string) string { + for _, record := range records { + if record.ID == id { + return record.Action + } + } + return "" +} + +func expectedRefSHA(plan Plan, ref string) string { + for _, expected := range plan.ExpectedRefs { + if expected.Ref == ref { + return expected.SHA + } + } + return "" +} + +func expireLegacyLease(t *testing.T, repo gitx.Repo, id string) { + t.Helper() + path := filepath.Join(repo.CommonDir, "ndev-wip", "v1", "leases", id+".json") + var lease legacyLease + if _, err := readJSONFile(path, &lease); err != nil { + t.Fatal(err) + } + lease.ExpiresAt = timePointer(time.Date(2025, 1, 1, 0, 0, 0, 0, time.UTC)) + writeTestJSON(t, path, lease, 0o600) +} + +func hasConflict(plan Plan, code string) bool { + for _, conflict := range plan.Conflicts { + if conflict.Code == code { + return true + } + } + return false +} + +func hasDisposition(plan Plan, code string) bool { + for _, disposition := range plan.Dispositions { + if disposition.Code == code { + return true + } + } + return false +} + +func timePointer(value time.Time) *time.Time { return &value } diff --git a/internal/coordmigration/mode_default.go b/internal/coordmigration/mode_default.go new file mode 100644 index 0000000..ef49ace --- /dev/null +++ b/internal/coordmigration/mode_default.go @@ -0,0 +1,17 @@ +//go:build !windows + +package coordmigration + +import "os" + +func canonicalMode(mode os.FileMode) os.FileMode { return mode.Perm() } + +func confinedLinkSourceMode(mode os.FileMode) os.FileMode { return mode } + +func finalizeConfinedLink(_ *os.Root, _ string, _ os.FileMode) error { return nil } + +func repairExactMode(_ string, _, _ os.FileMode) (bool, error) { return false, nil } + +func repairConfinedMode(_ *os.Root, _ string, _, _ os.FileMode) (bool, error) { + return false, nil +} diff --git a/internal/coordmigration/mode_windows.go b/internal/coordmigration/mode_windows.go new file mode 100644 index 0000000..90b4126 --- /dev/null +++ b/internal/coordmigration/mode_windows.go @@ -0,0 +1,47 @@ +//go:build windows + +package coordmigration + +import "os" + +func canonicalMode(mode os.FileMode) os.FileMode { + if mode.IsDir() { + // Chmod does not change Windows directory permissions. Canonical + // manifests therefore record the private writable directory policy and + // bind archive immutability through read-only files plus exact digests. + return 0o700 + } + if mode.Perm()&0o200 != 0 { + return 0o600 + } + return 0o400 +} + +// Windows maps a mode without 0200 to the read-only file attribute. Wine and +// some Windows filesystems reject hard-link creation when that attribute is +// already set. Publish the complete file while writable, remove the temporary +// name, and then apply the reviewed final mode before the caller can authorize +// the path in the migration journal. +func confinedLinkSourceMode(mode os.FileMode) os.FileMode { return mode | 0o200 } + +func finalizeConfinedLink(root *os.Root, name string, mode os.FileMode) error { + return root.Chmod(name, mode) +} + +func repairExactMode(path string, actual, want os.FileMode) (bool, error) { + if !windowsReadOnlyFinalizeWindow(actual, want) { + return false, nil + } + return true, os.Chmod(path, want) +} + +func repairConfinedMode(root *os.Root, name string, actual, want os.FileMode) (bool, error) { + if !windowsReadOnlyFinalizeWindow(actual, want) { + return false, nil + } + return true, root.Chmod(name, want) +} + +func windowsReadOnlyFinalizeWindow(actual, want os.FileMode) bool { + return actual.Perm()&0o200 != 0 && want.Perm()&0o200 == 0 +} diff --git a/internal/coordmigration/model.go b/internal/coordmigration/model.go new file mode 100644 index 0000000..f7c31d2 --- /dev/null +++ b/internal/coordmigration/model.go @@ -0,0 +1,302 @@ +// Package coordmigration migrates the retired NDev WIP store into the +// standalone coordination domain. It never grants landing authority to the +// standalone command. +package coordmigration + +import ( + "crypto/sha256" + "encoding/hex" + "encoding/json" + "fmt" + "regexp" + "strings" + "time" + + "github.com/nstranquist/wip-commit/internal/contract" +) + +const ( + PlanSchemaVersion = "wip.coordination-migration-plan/1.2.0" + StatusSchemaVersion = "wip.coordination-migration-status/1.1.0" + JournalSchemaVersion = "wip.coordination-migration-journal/1.1.0" + RollbackSchemaVersion = "wip.coordination-migration-rollback/1.0.0" + ReceiptSchemaVersion = "wip.coordination-migration-receipt/1.0.0" + SealSchemaVersion = "wip.legacy-ndev-wip-seal/1.0.0" + DomainID = "github.com/nstranquist/wip-commit" + maxManifestEntries = 20_000 + maxManifestBytes = 128 << 20 + maxRecordBytes = 1 << 20 + // MaxPlanBytes is the one bound used by preview, persisted-plan reload, and + // both command adapters. Keeping one public bound prevents a plan that can be + // produced but cannot later be reviewed, applied, resumed, or inspected. + MaxPlanBytes = 16 << 20 +) + +var digestPattern = regexp.MustCompile(`^sha256:[0-9a-f]{64}$`) + +var ( + migrationIDPattern = regexp.MustCompile(`^migration-[0-9a-f]{24}$`) + revisionPattern = regexp.MustCompile(`^[0-9a-f]{40}([0-9a-f]{24})?$`) + semverPattern = regexp.MustCompile(`^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?(\+[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?$`) +) + +const migrationProducerProduct = "github.com/nstranquist/wip-commit" + +// ProducerIdentity binds a reviewed plan to the exact standalone executable, +// source revision, command protocol, and embedded portable instruction bundle +// that produced it. Apply and resume must present the same identity. +type ProducerIdentity struct { + CommandProtocol string `json:"command_protocol"` + Product string `json:"product"` + Version string `json:"version"` + SourceRevision string `json:"source_revision"` + SourceState string `json:"source_state"` + ReleaseTagged bool `json:"release_tagged"` + ReleaseTag string `json:"release_tag,omitempty"` + PortableBundleSHA256 string `json:"portable_bundle_sha256"` + ExecutableSHA256 string `json:"executable_sha256"` +} + +func (producer ProducerIdentity) Validate() error { + if producer.CommandProtocol != contract.Protocol { + return fmt.Errorf("producer command protocol %q is not %q", producer.CommandProtocol, contract.Protocol) + } + if producer.Product != migrationProducerProduct { + return fmt.Errorf("producer product %q is not %q", producer.Product, migrationProducerProduct) + } + if !semverPattern.MatchString(producer.Version) { + return fmt.Errorf("producer version %q is not SemVer", producer.Version) + } + if !revisionPattern.MatchString(producer.SourceRevision) { + return fmt.Errorf("producer source revision is not an exact Git object id") + } + if producer.SourceState != "clean" && producer.SourceState != "modified" { + return fmt.Errorf("producer source state %q is not clean or modified", producer.SourceState) + } + if producer.ReleaseTagged { + if producer.SourceState != "clean" || producer.ReleaseTag != "v"+producer.Version { + return fmt.Errorf("tagged producer must be clean and use the exact version tag") + } + } else if producer.ReleaseTag != "" { + return fmt.Errorf("untagged producer cannot name a release tag") + } + if !digestPattern.MatchString(producer.PortableBundleSHA256) { + return fmt.Errorf("producer portable bundle digest is invalid") + } + if !digestPattern.MatchString(producer.ExecutableSHA256) { + return fmt.Errorf("producer executable digest is invalid") + } + return nil +} + +type ManifestEntry struct { + Path string `json:"path"` + Type string `json:"type"` + Mode string `json:"mode"` + Size int64 `json:"size,omitempty"` + SHA256 string `json:"sha256,omitempty"` +} + +type TreeManifest struct { + LogicalRoot string `json:"logical_root"` + Exists bool `json:"exists"` + Entries []ManifestEntry `json:"entries"` + Digest string `json:"digest"` +} + +// CanonicalManifest binds the two writable canonical data roots. Migration +// metadata and the sealed source archive are intentionally outside this +// digest, so the value is stable from record publication through completion. +type CanonicalManifest struct { + Capture TreeManifest `json:"capture"` + Review TreeManifest `json:"review"` + Digest string `json:"digest"` +} + +type ImportRecord struct { + Kind string `json:"kind"` + ID string `json:"id"` + Source string `json:"source"` + Destination string `json:"destination"` + Action string `json:"action"` + SourceSHA256 string `json:"source_sha256"` + DestinationSHA256 string `json:"destination_sha256,omitempty"` + Size int64 `json:"size"` + Ref string `json:"ref,omitempty"` + CurrentSHA string `json:"current_sha,omitempty"` +} + +type CopyRecord struct { + Kind string `json:"kind"` + Source string `json:"source"` + Destination string `json:"destination"` + Action string `json:"action"` + SourceSHA256 string `json:"source_sha256"` + DestinationSHA256 string `json:"destination_sha256,omitempty"` + Size int64 `json:"size"` + Mode string `json:"mode"` +} + +type RefExpectation struct { + Ref string `json:"ref"` + SHA string `json:"sha"` +} + +type RecordDisposition struct { + Kind string `json:"kind"` + ID string `json:"id"` + Source string `json:"source"` + Action string `json:"action"` + Code string `json:"code"` + Message string `json:"message"` +} + +type Conflict struct { + Code string `json:"code"` + Kind string `json:"kind"` + ID string `json:"id,omitempty"` + Source string `json:"source,omitempty"` + Destination string `json:"destination,omitempty"` + Message string `json:"message"` +} + +type Plan struct { + SchemaVersion string `json:"schema_version"` + MigrationID string `json:"migration_id"` + RepositoryCommonDir string `json:"repository_common_dir"` + State string `json:"state"` + Producer ProducerIdentity `json:"producer"` + SourceLegacy TreeManifest `json:"source_legacy"` + ExpectedCanonical TreeManifest `json:"expected_canonical"` + ExpectedCanonicalData CanonicalManifest `json:"expected_canonical_data"` + PlannedCanonicalData CanonicalManifest `json:"planned_canonical_data"` + ReconciliationHistory TreeManifest `json:"reconciliation_history"` + LaneImports []ImportRecord `json:"lane_imports"` + LeaseImports []ImportRecord `json:"lease_imports"` + ReviewCopies []CopyRecord `json:"review_copies"` + ReconciliationCopies []CopyRecord `json:"reconciliation_copies"` + Dispositions []RecordDisposition `json:"dispositions"` + ExpectedRefs []RefExpectation `json:"expected_refs"` + Conflicts []Conflict `json:"conflicts"` + PlanDigest string `json:"plan_digest"` +} + +type Journal struct { + SchemaVersion string `json:"schema_version"` + MigrationID string `json:"migration_id"` + PlanDigest string `json:"plan_digest"` + ExpectedCanonicalDigest string `json:"expected_canonical_digest"` + PlannedCanonicalDigest string `json:"planned_canonical_digest"` + PublishedPaths []string `json:"published_paths"` + Phase string `json:"phase"` + UpdatedAt time.Time `json:"updated_at"` + LastError string `json:"last_error,omitempty"` +} + +type WriterFence struct { + SchemaVersion string `json:"schema_version"` + MigrationID string `json:"migration_id"` + PlanDigest string `json:"plan_digest"` + CreatedAt time.Time `json:"created_at"` +} + +type RollbackMarker struct { + SchemaVersion string `json:"schema_version"` + MigrationID string `json:"migration_id"` + PlanDigest string `json:"plan_digest"` + State string `json:"state"` + Reason string `json:"reason"` + UpdatedAt time.Time `json:"updated_at"` +} + +type Seal struct { + SchemaVersion string `json:"schema_version"` + MigrationID string `json:"migration_id"` + PlanDigest string `json:"plan_digest"` + SourceManifest string `json:"source_manifest_digest"` + ArchiveManifest string `json:"archive_manifest_digest"` + ArchiveRelativeDir string `json:"archive_relative_dir"` + SealedAt time.Time `json:"sealed_at"` +} + +type Receipt struct { + SchemaVersion string `json:"schema_version"` + MigrationID string `json:"migration_id"` + PlanDigest string `json:"plan_digest"` + SourceManifest string `json:"source_manifest_digest"` + CanonicalManifest string `json:"canonical_manifest_digest"` + ArchiveManifest string `json:"archive_manifest_digest,omitempty"` + ReconciliationHistory string `json:"reconciliation_history_digest"` + CompletedAt time.Time `json:"completed_at"` + ReceiptDigest string `json:"receipt_digest"` +} + +type Status struct { + SchemaVersion string `json:"schema_version"` + State string `json:"state"` + MigrationID string `json:"migration_id,omitempty"` + PlanDigest string `json:"plan_digest,omitempty"` + Phase string `json:"phase,omitempty"` + LegacyExists bool `json:"legacy_exists"` + Canonical bool `json:"canonical_domain"` + Review bool `json:"review_store"` + Archive bool `json:"sealed_archive"` + CurrentCanonicalManifestDigest string `json:"current_canonical_manifest_digest,omitempty"` + CanonicalAdvanced bool `json:"canonical_advanced"` + Rollback *RollbackMarker `json:"rollback,omitempty"` + Receipt *Receipt `json:"receipt,omitempty"` +} + +type Result struct { + SchemaVersion string `json:"schema_version"` + Mode string `json:"mode"` + Applied bool `json:"applied"` + Resumed bool `json:"resumed"` + RolledBack bool `json:"rolled_back"` + Plan Plan `json:"plan"` + Status Status `json:"status"` + Receipt *Receipt `json:"receipt,omitempty"` +} + +func (plan Plan) ValidateDigest(expected string) error { + if err := plan.Producer.Validate(); err != nil { + return fmt.Errorf("plan producer identity is invalid: %w", err) + } + if !migrationIDPattern.MatchString(plan.MigrationID) { + return fmt.Errorf("plan migration identity is invalid") + } + wantedMigrationID := migrationID(plan.SourceLegacy.Digest, plan.ExpectedCanonical.Digest, plan.ReconciliationHistory.Digest) + if plan.MigrationID != wantedMigrationID { + return fmt.Errorf("plan migration identity does not match its bound manifests") + } + if !digestPattern.MatchString(expected) || plan.PlanDigest != expected { + return fmt.Errorf("plan digest does not match the exact reviewed digest") + } + actual, err := planDigest(plan) + if err != nil { + return err + } + if actual != expected { + return fmt.Errorf("plan content digest is %s, expected %s", actual, expected) + } + return nil +} + +func planDigest(plan Plan) (string, error) { + plan.PlanDigest = "" + body, err := json.Marshal(plan) + if err != nil { + return "", err + } + return digest(body), nil +} + +func digest(body []byte) string { + sum := sha256.Sum256(body) + return "sha256:" + hex.EncodeToString(sum[:]) +} + +func migrationID(source, canonical, reconciliation string) string { + sum := sha256.Sum256([]byte(strings.Join([]string{source, canonical, reconciliation}, "\x00"))) + return "migration-" + hex.EncodeToString(sum[:12]) +} diff --git a/internal/coordmigration/preview.go b/internal/coordmigration/preview.go new file mode 100644 index 0000000..feefd2d --- /dev/null +++ b/internal/coordmigration/preview.go @@ -0,0 +1,736 @@ +package coordmigration + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "io" + "os" + "path/filepath" + "sort" + "strings" + "time" + + "github.com/nstranquist/wip-commit/internal/fail" + "github.com/nstranquist/wip-commit/internal/gitx" + "github.com/nstranquist/wip-commit/internal/safeio" + capturestore "github.com/nstranquist/wip-commit/internal/store" +) + +type PreviewOptions struct { + AfterFirstSnapshot func() error + Now func() time.Time + Producer ProducerIdentity +} + +type legacyLane = capturestore.Lane +type legacyLease = capturestore.Lease + +func Preview(ctx context.Context, repo gitx.Repo, options PreviewOptions) (Plan, error) { + if err := options.Producer.Validate(); err != nil { + return Plan{}, fail.Wrap("MIGRATION_PRODUCER_INVALID", err) + } + firstSource, err := manifestTree(repo.CommonDir, "ndev-wip") + if err != nil { + return Plan{}, fail.Wrap("MIGRATION_SOURCE_UNSAFE", err) + } + firstCanonical, err := manifestTree(repo.CommonDir, "wip") + if err != nil { + return Plan{}, fail.Wrap("MIGRATION_DESTINATION_UNSAFE", err) + } + firstReconciliation, err := manifestTree(repo.CommonDir, filepath.Join("ndev-commit-lane", "reconcile")) + if err != nil { + return Plan{}, fail.Wrap("MIGRATION_SOURCE_UNSAFE", err) + } + firstCanonicalData, err := manifestCanonicalData(repo.CommonDir) + if err != nil { + return Plan{}, fail.Wrap("MIGRATION_DESTINATION_UNSAFE", err) + } + if options.AfterFirstSnapshot != nil { + if err := options.AfterFirstSnapshot(); err != nil { + return Plan{}, err + } + } + secondSource, err := manifestTree(repo.CommonDir, "ndev-wip") + if err != nil { + return Plan{}, fail.Wrap("MIGRATION_SOURCE_UNSAFE", err) + } + secondCanonical, err := manifestTree(repo.CommonDir, "wip") + if err != nil { + return Plan{}, fail.Wrap("MIGRATION_DESTINATION_UNSAFE", err) + } + secondReconciliation, err := manifestTree(repo.CommonDir, filepath.Join("ndev-commit-lane", "reconcile")) + if err != nil { + return Plan{}, fail.Wrap("MIGRATION_SOURCE_UNSAFE", err) + } + secondCanonicalData, err := manifestCanonicalData(repo.CommonDir) + if err != nil { + return Plan{}, fail.Wrap("MIGRATION_DESTINATION_UNSAFE", err) + } + if firstSource.Digest != secondSource.Digest || firstCanonical.Digest != secondCanonical.Digest || firstReconciliation.Digest != secondReconciliation.Digest || firstCanonicalData.Digest != secondCanonicalData.Digest { + return Plan{}, fail.New("MIGRATION_SOURCE_MOVED", "coordination state changed during the read-only preview; stop writers and retry") + } + + plan := Plan{ + SchemaVersion: PlanSchemaVersion, + MigrationID: migrationID(firstSource.Digest, firstCanonical.Digest, firstReconciliation.Digest), + RepositoryCommonDir: repo.CommonDir, + State: "ready", + Producer: options.Producer, + SourceLegacy: firstSource, + ExpectedCanonical: firstCanonical, + ExpectedCanonicalData: firstCanonicalData, + ReconciliationHistory: firstReconciliation, + LaneImports: []ImportRecord{}, + LeaseImports: []ImportRecord{}, + ReviewCopies: []CopyRecord{}, + ReconciliationCopies: []CopyRecord{}, + Dispositions: []RecordDisposition{}, + ExpectedRefs: []RefExpectation{}, + Conflicts: []Conflict{}, + } + now := time.Now().UTC() + if options.Now != nil { + now = options.Now().UTC() + } + portableLanes := map[string]legacyLane{} + portableLeases := map[string]legacyLease{} + if firstCanonical.Exists { + if _, err := exactCanonicalDomain(repo.CommonDir); err != nil { + return Plan{}, err + } + portableLanes, portableLeases, err = loadPortableRecords(repo, firstCanonical, now) + if err != nil { + return Plan{}, fail.Wrap("MIGRATION_DESTINATION_INVALID", err) + } + } + if firstSource.Exists { + if err := validateLegacyLayout(firstSource); err != nil { + return Plan{}, fail.Wrap("MIGRATION_SOURCE_INVALID", err) + } + if err := planLegacyRecords(ctx, repo, &plan, now, portableLanes, portableLeases); err != nil { + return Plan{}, err + } + if err := planReviewCopies(repo, &plan); err != nil { + return Plan{}, err + } + } + if err := planReconciliationCopies(repo, &plan); err != nil { + return Plan{}, err + } + if len(plan.Conflicts) > 0 { + plan.State = "blocked" + } + plan.PlannedCanonicalData, err = planCanonicalData(firstCanonicalData, plan) + if err != nil { + return Plan{}, fail.Wrap("MIGRATION_PLAN_FAILED", err) + } + sort.Slice(plan.LaneImports, func(i, j int) bool { return plan.LaneImports[i].ID < plan.LaneImports[j].ID }) + sort.Slice(plan.LeaseImports, func(i, j int) bool { return plan.LeaseImports[i].ID < plan.LeaseImports[j].ID }) + sort.Slice(plan.ReviewCopies, func(i, j int) bool { return plan.ReviewCopies[i].Destination < plan.ReviewCopies[j].Destination }) + sort.Slice(plan.ReconciliationCopies, func(i, j int) bool { + return plan.ReconciliationCopies[i].Destination < plan.ReconciliationCopies[j].Destination + }) + sort.Slice(plan.Dispositions, func(i, j int) bool { + return dispositionLess(plan.Dispositions[i], plan.Dispositions[j]) + }) + sort.Slice(plan.ExpectedRefs, func(i, j int) bool { return plan.ExpectedRefs[i].Ref < plan.ExpectedRefs[j].Ref }) + sort.Slice(plan.Conflicts, func(i, j int) bool { + return conflictLess(plan.Conflicts[i], plan.Conflicts[j]) + }) + plan.PlanDigest, err = planDigest(plan) + if err != nil { + return Plan{}, fail.Wrap("MIGRATION_PLAN_FAILED", err) + } + encoded, err := normalizedJSON(plan) + if err != nil { + return Plan{}, fail.Wrap("MIGRATION_PLAN_FAILED", err) + } + if len(encoded) > MaxPlanBytes { + return Plan{}, fail.Errorf("MIGRATION_PLAN_TOO_LARGE", "migration plan is %d bytes; maximum is %d", len(encoded), MaxPlanBytes) + } + return plan, nil +} + +func dispositionLess(left, right RecordDisposition) bool { + if left.Kind != right.Kind { + return left.Kind < right.Kind + } + if left.ID != right.ID { + return left.ID < right.ID + } + if left.Source != right.Source { + return left.Source < right.Source + } + if left.Action != right.Action { + return left.Action < right.Action + } + if left.Code != right.Code { + return left.Code < right.Code + } + return left.Message < right.Message +} + +func conflictLess(left, right Conflict) bool { + if left.Code != right.Code { + return left.Code < right.Code + } + if left.Kind != right.Kind { + return left.Kind < right.Kind + } + if left.ID != right.ID { + return left.ID < right.ID + } + if left.Source != right.Source { + return left.Source < right.Source + } + if left.Destination != right.Destination { + return left.Destination < right.Destination + } + return left.Message < right.Message +} + +func validateLegacyLayout(manifest TreeManifest) error { + required := map[string]string{ + ".": "directory", + "v1": "directory", + "v1/lanes": "directory", + "v1/leases": "directory", + } + emptyV2Scaffold := map[string]string{ + "v2": "directory", + "v2/lanes": "directory", + "v2/leases": "directory", + "v2/receipts": "directory", + } + seen := map[string]string{} + for _, entry := range manifest.Entries { + seen[entry.Path] = entry.Type + if entry.Path != "." && !strings.HasPrefix(entry.Path, "v1/") && entry.Path != "v1" { + expectedType, allowed := emptyV2Scaffold[entry.Path] + if !allowed { + return fmt.Errorf("legacy root contains unsupported top-level entry %s", entry.Path) + } + if entry.Type != expectedType { + return fmt.Errorf("legacy v2 scaffold entry %s has type %s, want %s", entry.Path, entry.Type, expectedType) + } + } + if strings.HasPrefix(entry.Path, "v1/lanes/") { + if entry.Type != "file" || filepath.ToSlash(filepath.Dir(entry.Path)) != "v1/lanes" || !strings.HasSuffix(entry.Path, ".json") { + return fmt.Errorf("legacy lane entry is not a direct JSON record: %s", entry.Path) + } + } + if strings.HasPrefix(entry.Path, "v1/leases/") { + if entry.Type != "file" || filepath.ToSlash(filepath.Dir(entry.Path)) != "v1/leases" || !strings.HasSuffix(entry.Path, ".json") { + return fmt.Errorf("legacy lease entry is not a direct JSON record: %s", entry.Path) + } + } + } + for path, kind := range required { + if seen[path] != kind { + return fmt.Errorf("legacy store is missing %s %s", kind, path) + } + } + if _, hasV2 := seen["v2"]; hasV2 { + for path, kind := range emptyV2Scaffold { + if seen[path] != kind { + return fmt.Errorf("legacy v2 scaffold is missing %s %s", kind, path) + } + } + } + return nil +} + +type laneCandidate struct { + path, fileID, action, code, message string + lane legacyLane + normalized []byte + expectedRefSHA string +} + +type leaseCandidate struct { + path, fileID, action, code, message string + lease legacyLease + normalized []byte +} + +func planLegacyRecords(ctx context.Context, repo gitx.Repo, plan *Plan, now time.Time, portableLanes map[string]legacyLane, portableLeases map[string]legacyLease) error { + lanes := map[string]*laneCandidate{} + leases := map[string]*leaseCandidate{} + for _, entry := range plan.SourceLegacy.Entries { + if entry.Type != "file" { + continue + } + switch { + case filepath.ToSlash(filepath.Dir(entry.Path)) == "v1/lanes" && strings.HasSuffix(entry.Path, ".json"): + var lane legacyLane + if _, err := readJSONFile(filepath.Join(repo.CommonDir, "ndev-wip", filepath.FromSlash(entry.Path)), &lane); err != nil { + return fail.Wrap("MIGRATION_SOURCE_INVALID", err) + } + normalized, err := normalizedJSON(lane) + if err != nil { + return err + } + fileID := strings.TrimSuffix(filepath.Base(entry.Path), ".json") + candidate := &laneCandidate{path: entry.Path, fileID: fileID, lane: lane, normalized: normalized, action: "import"} + if readerErr := capturestore.ValidateImportedLane(repo, lane); readerErr != nil || lane.ID != fileID { + candidate.code, candidate.message = "DESTINATION_READER_REJECTED", readerError(readerErr, "lane file identity differs from its record") + candidate.action = terminalLaneAction(lane.State) + } + if _, exists := lanes[fileID]; exists { + return fail.Errorf("MIGRATION_SOURCE_INVALID", "duplicate legacy lane basename %q", fileID) + } + lanes[fileID] = candidate + case filepath.ToSlash(filepath.Dir(entry.Path)) == "v1/leases" && strings.HasSuffix(entry.Path, ".json"): + var lease legacyLease + if _, err := readJSONFile(filepath.Join(repo.CommonDir, "ndev-wip", filepath.FromSlash(entry.Path)), &lease); err != nil { + return fail.Wrap("MIGRATION_SOURCE_INVALID", err) + } + normalized, err := normalizedJSON(lease) + if err != nil { + return err + } + fileID := strings.TrimSuffix(filepath.Base(entry.Path), ".json") + candidate := &leaseCandidate{path: entry.Path, fileID: fileID, lease: lease, normalized: normalized, action: "import"} + if readerErr := capturestore.ValidateImportedLease(repo, lease); readerErr != nil || lease.ID != fileID { + candidate.code, candidate.message = "DESTINATION_READER_REJECTED", readerError(readerErr, "lease file identity differs from its record") + candidate.action = terminalLeaseAction(lease.State) + } + if _, exists := leases[fileID]; exists { + return fail.Errorf("MIGRATION_SOURCE_INVALID", "duplicate legacy lease basename %q", fileID) + } + leases[fileID] = candidate + } + } + + // A lane record is not destination-readable in practice when its durable + // cursor cannot be resolved. Classify this before relationship closure so a + // terminal or stale lane that becomes archive-only also removes its + // dependent leases from the canonical import set. + for _, lane := range lanes { + if lane.action != "import" { + continue + } + actual, err := repo.Text(ctx, nil, "rev-parse", "--verify", lane.lane.Ref+"^{commit}") + if err == nil { + lane.expectedRefSHA = actual + } + stale := staleActiveLane(lane, leases, now) + if err == nil && actual == lane.lane.CurrentSHA { + if stale { + archiveStaleActiveLane(lane, leases, false) + } + continue + } + lane.code, lane.message = "REF_MISMATCH", "lane ref is absent or differs from its stored cursor" + if isTerminalLane(lane.lane.State) { + lane.action = "archive-only" + lane.code, lane.message = "HISTORICAL_REF_MISSING", "terminal lane ref is absent or differs from its stored cursor" + } else if err == nil && stale && refDescendsFrom(ctx, repo, lane.lane.CurrentSHA, actual) { + archiveStaleActiveLane(lane, leases, true) + } else { + lane.action = "conflict" + } + } + + // Excluding one terminal record can make its terminal counterpart invalid. + // Reach a fixed point before any destination path is planned. + for changed := true; changed; { + changed = false + for _, lease := range leases { + if lease.action != "import" { + continue + } + lane := lanes[lease.lease.LaneID] + owner, ownerFound := portableLanes[lease.lease.LaneID] + if lane != nil && lane.action == "import" { + owner, ownerFound = lane.lane, true + } + invalid := !ownerFound || owner.Agent != lease.lease.Agent || owner.Session != lease.lease.Session || !containsString(owner.LeaseIDs, lease.lease.ID) || isTerminalLane(owner.State) && lease.lease.State == "active" + if !invalid { + continue + } + if lease.lease.State == "released" { + lease.action, lease.code, lease.message, changed = "archive-only", "INCOMPATIBLE_HISTORICAL_RELATION", "terminal lease cannot form a valid destination lane relationship", true + } else { + lease.action, lease.code, lease.message = "conflict", "ACTIVE_LEASE_RELATION_INVALID", "active lease does not have an importable owning lane with an exact reverse reference" + } + } + for _, lane := range lanes { + if lane.action != "import" { + continue + } + for _, leaseID := range lane.lane.LeaseIDs { + lease := leases[leaseID] + owned, ownedFound := portableLeases[leaseID] + if lease != nil && lease.action == "import" { + owned, ownedFound = lease.lease, true + } + valid := ownedFound && owned.LaneID == lane.lane.ID && owned.Agent == lane.lane.Agent && owned.Session == lane.lane.Session + if valid && !invalidLaneLeaseState(lane.lane.State, owned.State) { + continue + } + if isTerminalLane(lane.lane.State) { + lane.action, lane.code, lane.message, changed = "archive-only", "INCOMPATIBLE_HISTORICAL_RELATION", "terminal lane references a lease that cannot be imported", true + } else { + lane.action, lane.code, lane.message = "conflict", "ACTIVE_LANE_LEASE_INVALID", "active lane references a lease that cannot be imported" + } + break + } + } + } + + for _, lane := range lanes { + source := filepath.ToSlash(filepath.Join("ndev-wip", lane.path)) + operation := ImportRecord{Kind: "lane", ID: lane.fileID, Source: source, Action: lane.action, SourceSHA256: digest(lane.normalized), Size: int64(len(lane.normalized)), Ref: lane.lane.Ref, CurrentSHA: lane.lane.CurrentSHA} + if lane.action == "import" { + operation.Destination = filepath.ToSlash(filepath.Join("wip", "v1", "lanes", lane.fileID+".json")) + compared, conflict, err := compareRecord(repo.CommonDir, "lane", lane.fileID, lane.path, operation.Destination, operation.SourceSHA256) + if err != nil { + return fail.Wrap("MIGRATION_DESTINATION_UNSAFE", err) + } + compared.Ref, compared.CurrentSHA = lane.lane.Ref, lane.lane.CurrentSHA + compared.Size = int64(len(lane.normalized)) + operation = compared + if conflict != nil { + plan.Conflicts = append(plan.Conflicts, *conflict) + } + } + if lane.expectedRefSHA != "" && operation.Action != "conflict" { + plan.ExpectedRefs = append(plan.ExpectedRefs, RefExpectation{Ref: lane.lane.Ref, SHA: lane.expectedRefSHA}) + } + plan.LaneImports = append(plan.LaneImports, operation) + appendDisposition(plan, "lane", lane.fileID, source, operation.Action, lane.code, lane.message) + if operation.Action == "conflict" && lane.code != "" { + plan.Conflicts = append(plan.Conflicts, Conflict{Code: lane.code, Kind: "lane", ID: lane.fileID, Source: source, Message: lane.message}) + } + } + for _, lease := range leases { + source := filepath.ToSlash(filepath.Join("ndev-wip", lease.path)) + operation := ImportRecord{Kind: "lease", ID: lease.fileID, Source: source, Action: lease.action, SourceSHA256: digest(lease.normalized), Size: int64(len(lease.normalized))} + if lease.action == "import" { + operation.Destination = filepath.ToSlash(filepath.Join("wip", "v1", "leases", lease.fileID+".json")) + compared, conflict, err := compareRecord(repo.CommonDir, "lease", lease.fileID, lease.path, operation.Destination, operation.SourceSHA256) + if err != nil { + return fail.Wrap("MIGRATION_DESTINATION_UNSAFE", err) + } + operation = compared + operation.Size = int64(len(lease.normalized)) + if conflict != nil { + plan.Conflicts = append(plan.Conflicts, *conflict) + } + if lease.lease.State == "active" && lease.lease.ExpiresAt != nil && !now.Before(*lease.lease.ExpiresAt) { + lease.code, lease.message = "EXPIRED_ACTIVE_LEASE", "valid expired lease remains stored but does not grant an active path claim" + } + } + plan.LeaseImports = append(plan.LeaseImports, operation) + appendDisposition(plan, "lease", lease.fileID, source, operation.Action, lease.code, lease.message) + if operation.Action == "conflict" && lease.code != "" { + plan.Conflicts = append(plan.Conflicts, Conflict{Code: lease.code, Kind: "lease", ID: lease.fileID, Source: source, Message: lease.message}) + } + } + if err := validatePlannedDestination(plan, lanes, leases, portableLanes, portableLeases, now); err != nil { + return err + } + return nil +} + +func staleActiveLane(lane *laneCandidate, leases map[string]*leaseCandidate, now time.Time) bool { + if lane.lane.State != "active" { + return false + } + for _, leaseID := range lane.lane.LeaseIDs { + lease := leases[leaseID] + if lease == nil || lease.action != "import" || lease.lease.LaneID != lane.lane.ID || lease.lease.Agent != lane.lane.Agent || lease.lease.Session != lane.lane.Session || lease.lease.State != "active" || lease.lease.ExpiresAt == nil || now.Before(*lease.lease.ExpiresAt) { + return false + } + } + return true +} + +func archiveStaleActiveLane(lane *laneCandidate, leases map[string]*leaseCandidate, refAdvanced bool) { + lane.action = "archive-only" + lane.code = "STALE_ACTIVE_LANE" + lane.message = "active lane has no unexpired path lease; archive its coordination records and preserve its exact ref" + if refAdvanced { + lane.code = "STALE_ACTIVE_REF_ADVANCED" + lane.message = "active lane has no unexpired path lease and its ref advanced from the stored cursor; archive its coordination records and preserve the exact advanced ref" + } + for _, leaseID := range lane.lane.LeaseIDs { + lease := leases[leaseID] + lease.action = "archive-only" + lease.code = lane.code + lease.message = "expired active lease belongs to a stale lane whose coordination records are archive-only" + } +} + +func refDescendsFrom(ctx context.Context, repo gitx.Repo, ancestor, descendant string) bool { + exit, err := repo.Exit(ctx, nil, "merge-base", "--is-ancestor", ancestor, descendant) + return err == nil && exit == 0 +} + +func invalidLaneLeaseState(laneState, leaseState string) bool { + return (laneState == "active" || laneState == "creating") && leaseState == "released" || isTerminalLane(laneState) && leaseState == "active" +} + +// validatePlannedDestination applies the relationship and active-scope checks +// to the exact merged record set that a ready plan would publish. This guards +// cross-store ID references that are individually reader-valid but invalid +// together. +func validatePlannedDestination(plan *Plan, candidates map[string]*laneCandidate, leaseCandidates map[string]*leaseCandidate, portableLanes map[string]legacyLane, portableLeases map[string]legacyLease, now time.Time) error { + if len(plan.Conflicts) != 0 { + return nil + } + lanes := make(map[string]legacyLane, len(portableLanes)+len(candidates)) + leases := make(map[string]legacyLease, len(portableLeases)+len(leaseCandidates)) + for id, lane := range portableLanes { + lanes[id] = lane + } + for id, lease := range portableLeases { + leases[id] = lease + } + for _, record := range plan.LaneImports { + if record.Action == "import" { + lanes[record.ID] = candidates[record.ID].lane + } + } + for _, record := range plan.LeaseImports { + if record.Action == "import" { + leases[record.ID] = leaseCandidates[record.ID].lease + } + } + for id, lease := range leases { + lane, ok := lanes[lease.LaneID] + if !ok || lane.Agent != lease.Agent || lane.Session != lease.Session || !containsString(lane.LeaseIDs, id) || invalidLaneLeaseState(lane.State, lease.State) { + plan.Conflicts = append(plan.Conflicts, Conflict{Code: "DESTINATION_RELATION_INVALID", Kind: "lease", ID: id, Message: "planned canonical lease does not have an exact valid lane relationship"}) + } + } + for id, lane := range lanes { + for _, leaseID := range lane.LeaseIDs { + lease, ok := leases[leaseID] + if !ok || lease.LaneID != id || lease.Agent != lane.Agent || lease.Session != lane.Session || invalidLaneLeaseState(lane.State, lease.State) { + plan.Conflicts = append(plan.Conflicts, Conflict{Code: "DESTINATION_RELATION_INVALID", Kind: "lane", ID: id, Message: "planned canonical lane references a missing, cross-lane, or state-incompatible lease"}) + break + } + } + } + mergedLeases := make([]capturestore.Lease, 0, len(leases)) + for _, lease := range leases { + mergedLeases = append(mergedLeases, lease) + } + if conflict := capturestore.FindActiveLeaseConflict(mergedLeases, now); conflict != nil { + plan.Conflicts = append(plan.Conflicts, Conflict{Code: "PATH_LEASE_CONFLICT", Kind: "lease", ID: conflict.RightLease, Message: fmt.Sprintf("planned active path %q in lane %s overlaps path %q in lane %s", conflict.RightPath, conflict.RightLane, conflict.LeftPath, conflict.LeftLane)}) + } + return nil +} + +func terminalLaneAction(state string) string { + if isTerminalLane(state) { + return "archive-only" + } + return "conflict" +} + +func terminalLeaseAction(state string) string { + if state == "released" { + return "archive-only" + } + return "conflict" +} + +func isTerminalLane(state string) bool { return state == "released" || state == "aborted" } + +func readerError(err error, fallback string) string { + if err != nil { + return err.Error() + } + return fallback +} + +func containsString(values []string, wanted string) bool { + for _, value := range values { + if value == wanted { + return true + } + } + return false +} + +func appendDisposition(plan *Plan, kind, id, source, action, code, message string) { + if code == "" { + return + } + plan.Dispositions = append(plan.Dispositions, RecordDisposition{Kind: kind, ID: id, Source: source, Action: action, Code: code, Message: message}) +} + +func loadPortableRecords(repo gitx.Repo, manifest TreeManifest, now time.Time) (map[string]legacyLane, map[string]legacyLease, error) { + lanes := map[string]legacyLane{} + leases := map[string]legacyLease{} + for _, entry := range manifest.Entries { + if entry.Type != "file" { + continue + } + switch { + case strings.HasPrefix(entry.Path, "v1/lanes/"): + if filepath.ToSlash(filepath.Dir(entry.Path)) != "v1/lanes" || !strings.HasSuffix(entry.Path, ".json") { + return nil, nil, fmt.Errorf("portable lane entry is not a direct JSON record: %s", entry.Path) + } + var lane legacyLane + if _, err := readJSONFile(filepath.Join(repo.CommonDir, "wip", filepath.FromSlash(entry.Path)), &lane); err != nil { + return nil, nil, err + } + fileID := strings.TrimSuffix(filepath.Base(entry.Path), ".json") + if lane.ID != fileID { + return nil, nil, fmt.Errorf("portable lane file identity differs from its record: %s", entry.Path) + } + if err := capturestore.ValidateImportedLane(repo, lane); err != nil { + return nil, nil, err + } + lanes[lane.ID] = lane + case strings.HasPrefix(entry.Path, "v1/leases/"): + if filepath.ToSlash(filepath.Dir(entry.Path)) != "v1/leases" || !strings.HasSuffix(entry.Path, ".json") { + return nil, nil, fmt.Errorf("portable lease entry is not a direct JSON record: %s", entry.Path) + } + var lease legacyLease + if _, err := readJSONFile(filepath.Join(repo.CommonDir, "wip", filepath.FromSlash(entry.Path)), &lease); err != nil { + return nil, nil, err + } + fileID := strings.TrimSuffix(filepath.Base(entry.Path), ".json") + if lease.ID != fileID { + return nil, nil, fmt.Errorf("portable lease file identity differs from its record: %s", entry.Path) + } + if err := capturestore.ValidateImportedLease(repo, lease); err != nil { + return nil, nil, err + } + leases[lease.ID] = lease + } + } + for id, lease := range leases { + lane, ok := lanes[lease.LaneID] + if !ok || lane.Agent != lease.Agent || lane.Session != lease.Session || !containsString(lane.LeaseIDs, id) || invalidLaneLeaseState(lane.State, lease.State) { + return nil, nil, fmt.Errorf("portable lease %s has an invalid lane relationship", id) + } + } + for id, lane := range lanes { + for _, leaseID := range lane.LeaseIDs { + if _, ok := leases[leaseID]; !ok { + return nil, nil, fmt.Errorf("portable lane %s references missing lease %s", id, leaseID) + } + } + } + allLeases := make([]capturestore.Lease, 0, len(leases)) + for _, lease := range leases { + allLeases = append(allLeases, lease) + } + if conflict := capturestore.FindActiveLeaseConflict(allLeases, now); conflict != nil { + return nil, nil, fmt.Errorf("portable active leases %s and %s overlap", conflict.LeftLease, conflict.RightLease) + } + return lanes, leases, nil +} + +func compareRecord(commonDir, kind, id, source, destination, sourceDigest string) (ImportRecord, *Conflict, error) { + operation := ImportRecord{Kind: kind, ID: id, Source: filepath.ToSlash(filepath.Join("ndev-wip", source)), Destination: destination, Action: "import", SourceSHA256: sourceDigest} + path := filepath.Join(commonDir, filepath.FromSlash(destination)) + body, err := safeio.ReadRegular(path, maxRecordBytes) + if errors.Is(err, os.ErrNotExist) { + return operation, nil, nil + } + if err != nil { + return operation, nil, err + } + operation.DestinationSHA256 = digest(body) + if operation.DestinationSHA256 == sourceDigest { + operation.Action = "match" + return operation, nil, nil + } + operation.Action = "conflict" + conflict := &Conflict{Code: "SHADOW_MISMATCH", Kind: kind, ID: id, Source: operation.Source, Destination: destination, Message: "the same record ID has different normalized bytes in the legacy and portable stores"} + return operation, conflict, nil +} + +func planReviewCopies(repo gitx.Repo, plan *Plan) error { + for _, entry := range plan.SourceLegacy.Entries { + if entry.Type != "file" || !isReviewFile(entry.Path) { + continue + } + suffix := strings.TrimPrefix(entry.Path, "v1/") + destination := filepath.ToSlash(filepath.Join("wip", "review", "v1", filepath.FromSlash(suffix))) + operation, conflict, err := compareCopy(repo.CommonDir, "legacy-review", filepath.ToSlash(filepath.Join("ndev-wip", entry.Path)), destination, entry) + if err != nil { + return fail.Wrap("MIGRATION_DESTINATION_UNSAFE", err) + } + plan.ReviewCopies = append(plan.ReviewCopies, operation) + if conflict != nil { + plan.Conflicts = append(plan.Conflicts, *conflict) + } + } + return nil +} + +func planReconciliationCopies(repo gitx.Repo, plan *Plan) error { + for _, entry := range plan.ReconciliationHistory.Entries { + if entry.Type != "file" { + continue + } + source := filepath.ToSlash(filepath.Join("ndev-commit-lane", "reconcile", filepath.FromSlash(entry.Path))) + destination := filepath.ToSlash(filepath.Join("wip", "review", "v1", "reconciliation", filepath.FromSlash(entry.Path))) + operation, conflict, err := compareCopy(repo.CommonDir, "reconciliation", source, destination, entry) + if err != nil { + return fail.Wrap("MIGRATION_DESTINATION_UNSAFE", err) + } + plan.ReconciliationCopies = append(plan.ReconciliationCopies, operation) + if conflict != nil { + plan.Conflicts = append(plan.Conflicts, *conflict) + } + } + return nil +} + +func compareCopy(commonDir, kind, source, destination string, entry ManifestEntry) (CopyRecord, *Conflict, error) { + operation := CopyRecord{Kind: kind, Source: source, Destination: destination, Action: "copy", SourceSHA256: entry.SHA256, Size: entry.Size, Mode: entry.Mode} + path := filepath.Join(commonDir, filepath.FromSlash(destination)) + body, err := safeio.ReadRegular(path, maxManifestBytes) + if errors.Is(err, os.ErrNotExist) { + return operation, nil, nil + } + if err != nil { + return operation, nil, err + } + operation.DestinationSHA256 = digest(body) + info, err := os.Lstat(path) + if err != nil { + return operation, nil, err + } + if operation.DestinationSHA256 == operation.SourceSHA256 && modeString(info.Mode().Perm()) == operation.Mode { + operation.Action = "match" + return operation, nil, nil + } + operation.Action = "conflict" + conflict := &Conflict{Code: "SHADOW_MISMATCH", Kind: kind, Source: source, Destination: destination, Message: "review history destination differs from the legacy source"} + return operation, conflict, nil +} + +func isReviewFile(path string) bool { + return path == "v1/queue.json" || strings.HasPrefix(path, "v1/landing-intents/") || strings.HasPrefix(path, "v1/archive/") +} + +func DecodePlan(body []byte) (Plan, error) { + if len(body) > MaxPlanBytes { + return Plan{}, fmt.Errorf("plan exceeds %d bytes", MaxPlanBytes) + } + var plan Plan + decoder := json.NewDecoder(strings.NewReader(string(body))) + decoder.DisallowUnknownFields() + if err := decoder.Decode(&plan); err != nil { + return Plan{}, err + } + var trailing any + if err := decoder.Decode(&trailing); !errors.Is(err, io.EOF) { + if err == nil { + return Plan{}, errors.New("plan contains multiple JSON values") + } + return Plan{}, err + } + return plan, nil +} diff --git a/internal/coordmigration/status.go b/internal/coordmigration/status.go new file mode 100644 index 0000000..41af602 --- /dev/null +++ b/internal/coordmigration/status.go @@ -0,0 +1,230 @@ +package coordmigration + +import ( + "bytes" + "errors" + "fmt" + "os" + "path/filepath" + + "github.com/nstranquist/wip-commit/internal/contract" + "github.com/nstranquist/wip-commit/internal/fail" + "github.com/nstranquist/wip-commit/internal/gitx" + "github.com/nstranquist/wip-commit/internal/safeio" +) + +// InspectStatus reads migration and store state without creating a directory, +// lock, marker, or receipt. +func InspectStatus(repo gitx.Repo, migrationID string) (Status, error) { + if migrationID != "" && !migrationIDPattern.MatchString(migrationID) { + return Status{}, fail.New("MIGRATION_STATUS_INVALID", "migration identity is invalid") + } + status := Status{SchemaVersion: StatusSchemaVersion, State: "not-started", MigrationID: migrationID} + legacy, err := regularDirectoryState(filepath.Join(repo.CommonDir, "ndev-wip")) + if err != nil { + return Status{}, fail.Wrap("MIGRATION_SOURCE_UNSAFE", err) + } + status.LegacyExists = legacy + canonical, err := exactCanonicalDomain(repo.CommonDir) + if err != nil { + return Status{}, err + } + status.Canonical = canonical + review, err := regularDirectoryState(filepath.Join(repo.CommonDir, "wip", "review", "v1")) + if err != nil { + return Status{}, fail.Wrap("MIGRATION_DESTINATION_UNSAFE", err) + } + status.Review = review + + journal, journalExists, err := readJournal(migrationJournalPath(repo.CommonDir)) + if err != nil { + return Status{}, err + } + if migrationID == "" && journalExists { + migrationID = journal.MigrationID + status.MigrationID = migrationID + } + if journalExists && journal.MigrationID == migrationID { + status.PlanDigest = journal.PlanDigest + status.Phase = journal.Phase + status.State = "in-progress" + } + if migrationID == "" { + if legacy { + status.State = "preview-required" + } else if canonical { + status.State = "canonical" + } + return status, nil + } + + var plan Plan + planExists := false + if loaded, loadErr := loadPersistedPlan(repo.CommonDir, migrationID); loadErr == nil { + plan = loaded + planExists = true + if plan.MigrationID != migrationID { + return Status{}, fail.New("MIGRATION_PLAN_INVALID", "persisted migration plan has a different migration identity") + } + if err := plan.ValidateDigest(plan.PlanDigest); err != nil { + return Status{}, fail.Wrap("MIGRATION_PLAN_INVALID", err) + } + } else if !errors.Is(loadErr, os.ErrNotExist) { + return Status{}, fail.Wrap("MIGRATION_PLAN_INVALID", loadErr) + } else if journalExists && journal.MigrationID == migrationID { + return Status{}, fail.New("MIGRATION_PLAN_INVALID", "migration journal exists without its immutable reviewed plan") + } + if planExists && journalExists && journal.MigrationID == migrationID { + if err := verifyJournalPlanBinding(repo, plan, journal); err != nil { + return Status{}, err + } + } + + rollbackPath := filepath.Join(repo.CommonDir, "wip", "migration", "v1", migrationID, "rollback.json") + var rollback RollbackMarker + if _, err := readJSONFile(rollbackPath, &rollback); err == nil { + if rollback.SchemaVersion != RollbackSchemaVersion || rollback.MigrationID != migrationID || rollback.State != "rolled-back" || !digestPattern.MatchString(rollback.PlanDigest) || !planExists || rollback.PlanDigest != plan.PlanDigest { + return Status{}, fail.New("MIGRATION_ROLLBACK_INVALID", "rollback marker is invalid") + } + status.Rollback = &rollback + status.State = "rolled-back" + } else if !errors.Is(err, os.ErrNotExist) { + return Status{}, fail.Wrap("MIGRATION_ROLLBACK_INVALID", err) + } + + receiptPath := migrationReceiptPath(repo.CommonDir, migrationID) + var receipt Receipt + if _, err := readJSONFile(receiptPath, &receipt); err == nil { + if err := validateReceipt(receipt, migrationID); err != nil { + return Status{}, fail.Wrap("MIGRATION_RECEIPT_INVALID", err) + } + status.Receipt = &receipt + status.PlanDigest = receipt.PlanDigest + if !journalExists || journal.MigrationID != migrationID || journal.Phase == phaseComplete { + status.State = "complete" + } + if !planExists { + return Status{}, fail.New("MIGRATION_PLAN_INVALID", "completion receipt exists without its immutable migration plan") + } + if !journalExists || journal.MigrationID != migrationID { + return Status{}, fail.New("MIGRATION_RECEIPT_INVALID", "completion receipt exists without its exact migration journal") + } + if receipt.PlanDigest != plan.PlanDigest || receipt.SourceManifest != plan.SourceLegacy.Digest || receipt.ReconciliationHistory != plan.ReconciliationHistory.Digest || receipt.CanonicalManifest != plan.PlannedCanonicalData.Digest { + return Status{}, fail.New("MIGRATION_RECEIPT_INVALID", "completion receipt does not bind the persisted plan and planned canonical manifest") + } + } else if !errors.Is(err, os.ErrNotExist) { + return Status{}, fail.Wrap("MIGRATION_RECEIPT_INVALID", err) + } + + archiveRoot := archiveMigrationRoot(repo.CommonDir, migrationID) + archiveExists, err := regularDirectoryState(filepath.Join(archiveRoot, "source")) + if err != nil { + return Status{}, fail.Wrap("MIGRATION_ARCHIVE_INVALID", err) + } + if archiveExists { + var seal Seal + if _, err := readJSONFile(filepath.Join(archiveRoot, "seal.json"), &seal); err != nil { + return Status{}, fail.Wrap("MIGRATION_ARCHIVE_INVALID", err) + } + manifest, err := manifestTree(repo.CommonDir, filepath.ToSlash(filepath.Join("wip", "archive", "legacy-ndev-wip", migrationID, "source"))) + expectedRelative := filepath.ToSlash(filepath.Join("wip", "archive", "legacy-ndev-wip", migrationID, "source")) + if err != nil || seal.SchemaVersion != SealSchemaVersion || seal.MigrationID != migrationID || !digestPattern.MatchString(seal.PlanDigest) || !digestPattern.MatchString(seal.SourceManifest) || seal.ArchiveManifest != manifest.Digest || seal.ArchiveRelativeDir != expectedRelative { + if err != nil { + return Status{}, fail.Wrap("MIGRATION_ARCHIVE_INVALID", err) + } + return Status{}, fail.New("MIGRATION_ARCHIVE_INVALID", "archive seal does not match the archived source") + } + status.Archive = true + if journalExists && journal.MigrationID == migrationID && seal.PlanDigest != journal.PlanDigest { + return Status{}, fail.New("MIGRATION_ARCHIVE_INVALID", "archive seal and migration journal do not bind the same plan") + } + if status.Receipt != nil && (seal.PlanDigest != status.Receipt.PlanDigest || seal.SourceManifest != status.Receipt.SourceManifest || seal.ArchiveManifest != status.Receipt.ArchiveManifest) { + return Status{}, fail.New("MIGRATION_ARCHIVE_INVALID", "archive seal and completion receipt do not bind the same source and plan") + } + } + if status.Receipt != nil && status.Receipt.ArchiveManifest != "" && !status.Archive { + return Status{}, fail.New("MIGRATION_ARCHIVE_INVALID", "completion receipt names an archive that is not sealed") + } + if status.Receipt != nil && status.LegacyExists { + return Status{}, fail.New("MIGRATION_SOURCE_NOT_REMOVED", "completion receipt exists while the legacy source remains present") + } + if journalExists && journal.MigrationID == migrationID && journal.Phase == phaseComplete && status.Receipt == nil { + return Status{}, fail.New("MIGRATION_RECEIPT_INVALID", "complete migration journal has no exact receipt") + } + if status.Rollback != nil && status.Receipt != nil { + return Status{}, fail.New("MIGRATION_STATUS_INVALID", "rollback marker and completion receipt cannot coexist") + } + if planExists && journalExists && journal.MigrationID == migrationID { + if status.Receipt != nil && journal.Phase == phaseComplete { + current, err := manifestCanonicalData(repo.CommonDir) + if err != nil { + return Status{}, fail.Wrap("MIGRATION_CANONICAL_MOVED", err) + } + // A completion receipt is historical cutover proof. Current writers + // can change the two live data roots after the writer fence is gone. + // Keep the static migration envelope exact, and report live-store + // movement instead of treating it as an interrupted migration. + if err := verifyCompletedCanonicalEnvelope(repo.CommonDir, plan, journal); err != nil { + return Status{}, fail.Wrap("MIGRATION_CANONICAL_MOVED", err) + } + status.CurrentCanonicalManifestDigest = current.Digest + status.CanonicalAdvanced = current.Digest != status.Receipt.CanonicalManifest + } else if err := verifyCanonicalTransition(repo.CommonDir, plan, journal, phaseRequiresCanonicalPost(journal.Phase)); err != nil { + return Status{}, fail.Wrap("MIGRATION_CANONICAL_MOVED", err) + } + } + return status, nil +} + +func exactCanonicalDomain(commonDir string) (bool, error) { + rootExists, err := regularDirectoryState(filepath.Join(commonDir, "wip")) + if err != nil || !rootExists { + return false, err + } + marker := domainRecord{SchemaVersion: 2, Domain: DomainID, StateVersion: 1, MinimumReaderProtocol: contract.Protocol, RequiredCapabilities: contract.StateReaderCapabilities()} + want, err := normalizedJSON(marker) + if err != nil { + return false, err + } + got, err := safeio.ReadRegular(filepath.Join(commonDir, "wip", "domain.json"), maxRecordBytes) + if errors.Is(err, os.ErrNotExist) { + return false, fail.New("MIGRATION_DESTINATION_INVALID", "wip root exists without its canonical domain marker") + } + if err != nil { + return false, fail.Wrap("MIGRATION_DESTINATION_INVALID", err) + } + if !bytes.Equal(got, want) { + return false, fail.New("COORDINATION_DOMAIN_CONFLICT", "wip root has a foreign or unsupported domain marker") + } + return true, nil +} + +func regularDirectoryState(path string) (bool, error) { + info, err := os.Lstat(path) + if errors.Is(err, os.ErrNotExist) { + return false, nil + } + if err != nil { + return false, err + } + if !info.IsDir() || info.Mode()&os.ModeSymlink != 0 { + return false, fmt.Errorf("%s is not a regular directory", path) + } + return true, nil +} + +func validateReceipt(receipt Receipt, migrationID string) error { + if receipt.SchemaVersion != ReceiptSchemaVersion || receipt.MigrationID != migrationID || !digestPattern.MatchString(receipt.PlanDigest) || !digestPattern.MatchString(receipt.SourceManifest) || !digestPattern.MatchString(receipt.CanonicalManifest) || !digestPattern.MatchString(receipt.ReconciliationHistory) || receipt.ArchiveManifest != "" && !digestPattern.MatchString(receipt.ArchiveManifest) || !digestPattern.MatchString(receipt.ReceiptDigest) { + return errors.New("receipt schema, identity, or digest is invalid") + } + want := receipt.ReceiptDigest + receipt.ReceiptDigest = "" + body, err := normalizedJSON(receipt) + if err != nil { + return err + } + if digest(body) != want { + return errors.New("receipt digest does not match its content") + } + return nil +} diff --git a/internal/coordmigration/sync_unix.go b/internal/coordmigration/sync_unix.go new file mode 100644 index 0000000..cec2ee9 --- /dev/null +++ b/internal/coordmigration/sync_unix.go @@ -0,0 +1,17 @@ +//go:build aix || darwin || dragonfly || freebsd || linux || netbsd || openbsd || solaris + +package coordmigration + +import "os" + +func syncDirectory(path string) error { + directory, err := os.Open(path) + if err != nil { + return err + } + if err := directory.Sync(); err != nil { + _ = directory.Close() + return err + } + return directory.Close() +} diff --git a/internal/coordmigration/sync_unsupported.go b/internal/coordmigration/sync_unsupported.go new file mode 100644 index 0000000..4202322 --- /dev/null +++ b/internal/coordmigration/sync_unsupported.go @@ -0,0 +1,9 @@ +//go:build !aix && !darwin && !dragonfly && !freebsd && !linux && !netbsd && !openbsd && !solaris && !windows + +package coordmigration + +import "errors" + +func syncDirectory(string) error { + return errors.New("durable directory sync is unsupported on this platform") +} diff --git a/internal/coordmigration/sync_windows.go b/internal/coordmigration/sync_windows.go new file mode 100644 index 0000000..27f1f51 --- /dev/null +++ b/internal/coordmigration/sync_windows.go @@ -0,0 +1,5 @@ +//go:build windows + +package coordmigration + +func syncDirectory(string) error { return nil } diff --git a/internal/engine/chain.go b/internal/engine/chain.go new file mode 100644 index 0000000..6b3a213 --- /dev/null +++ b/internal/engine/chain.go @@ -0,0 +1,95 @@ +package engine + +import ( + "context" + "errors" + "os" + "path/filepath" + "strings" + + "github.com/nstranquist/wip-commit/internal/fail" + "github.com/nstranquist/wip-commit/internal/gitx" +) + +// CompleteIntentChain returns the unique, validated sequence of completed +// capture intents from baseCommit through tipCommit. It fails on a gap, +// ambiguity, foreign branch, moved ref, invalid record, or invalid Git object. +func CompleteIntentChain(ctx context.Context, repo gitx.Repo, targetRef, baseCommit, tipCommit string) ([]Intent, error) { + if !validIntentTargetRef(targetRef) || !intentObjectPattern.MatchString(baseCommit) || !intentObjectPattern.MatchString(tipCommit) { + return nil, fail.New("INVALID_HANDOFF_CHAIN", "handoff chain identity is invalid") + } + actual, err := repo.Text(ctx, nil, "rev-parse", "--verify", targetRef+"^{commit}") + if err != nil { + return nil, fail.Wrap("REF_NOT_FOUND", err) + } + if actual != tipCommit { + return nil, fail.New("REF_MOVED", "lane ref changed before cumulative handoff validation") + } + if baseCommit == tipCommit { + return []Intent{}, nil + } + + directory := filepath.Join(repo.CommonDir, "wip", "v1", "intents") + entries, err := os.ReadDir(directory) + if errors.Is(err, os.ErrNotExist) { + return nil, fail.New("HANDOFF_CHAIN_INCOMPLETE", "capture intent directory does not exist") + } + if err != nil { + return nil, fail.Wrap("INTENT_READ_FAILED", err) + } + if len(entries) > 10_000 { + return nil, fail.New("INTENT_READ_FAILED", "intent directory exceeds 10000 entries") + } + byParent := make(map[string][]Intent) + for _, entry := range entries { + if entry.IsDir() || !strings.HasSuffix(entry.Name(), ".json") { + continue + } + id := strings.TrimSuffix(entry.Name(), ".json") + if !planIDPattern.MatchString(id) { + return nil, fail.New("INTENT_READ_FAILED", "intent directory contains an invalid record name") + } + intent, _, err := LoadIntent(repo, id, "") + if err != nil { + return nil, err + } + if intent.TargetRef != targetRef || intent.State != "complete" { + continue + } + if err := ValidateIntentObjects(ctx, repo, intent); err != nil { + return nil, err + } + byParent[intent.ExpectedOld] = append(byParent[intent.ExpectedOld], intent) + } + + chain := make([]Intent, 0) + cursor := baseCommit + seen := map[string]bool{} + for cursor != tipCommit { + if seen[cursor] || len(chain) >= 10_000 { + return nil, fail.New("HANDOFF_CHAIN_AMBIGUOUS", "capture intent chain contains a cycle or exceeds its bound") + } + seen[cursor] = true + var candidates []Intent + for _, intent := range byParent[cursor] { + code, err := repo.Exit(ctx, nil, "merge-base", "--is-ancestor", intent.ExpectedNew, tipCommit) + if err != nil { + return nil, fail.Wrap("GIT_FAILED", err) + } + if code == 0 { + candidates = append(candidates, intent) + } else if code != 1 { + return nil, fail.New("GIT_FAILED", "Git could not validate a capture segment against the lane tip") + } + } + if len(candidates) == 0 { + return nil, fail.Errorf("HANDOFF_CHAIN_INCOMPLETE", "no completed capture intent continues lane commit %s", cursor) + } + if len(candidates) != 1 { + return nil, fail.Errorf("HANDOFF_CHAIN_AMBIGUOUS", "%d completed capture intents continue lane commit %s", len(candidates), cursor) + } + chain = append(chain, candidates[0]) + cursor = candidates[0].ExpectedNew + } + return chain, nil +} diff --git a/internal/engine/chain_test.go b/internal/engine/chain_test.go new file mode 100644 index 0000000..611d753 --- /dev/null +++ b/internal/engine/chain_test.go @@ -0,0 +1,84 @@ +package engine + +import ( + "context" + "os" + "testing" + + "github.com/nstranquist/wip-commit/internal/fail" + "github.com/nstranquist/wip-commit/internal/gitx" +) + +func TestCompleteIntentChainBindsEveryCaptureFromLaneBaseToTip(t *testing.T) { + repo := engineTestRepo(t) + base := engineGit(t, repo.Root, "rev-parse", "HEAD") + target := "refs/heads/wip/agent/cumulative" + engineGit(t, repo.Root, "update-ref", target, base, "") + + first := completeTestCapture(t, repo, target, base, "core.txt", "first core\n", "fix(core): capture first segment") + second := completeTestCapture(t, repo, target, first.FinalCommit, "docs.txt", "second docs\n", "docs(guide): capture second segment") + + chain, err := CompleteIntentChain(context.Background(), repo, target, base, second.FinalCommit) + if err != nil { + t.Fatal(err) + } + if len(chain) != 2 || chain[0].PlanID != first.PlanID || chain[1].PlanID != second.PlanID || chain[0].ExpectedOld != base || chain[0].ExpectedNew != chain[1].ExpectedOld || chain[1].ExpectedNew != second.FinalCommit { + t.Fatalf("chain = %#v", chain) + } + for _, intent := range chain { + if intent.SchemaVersion != intentSchemaVersion || intent.SourceMode != SourceStagedIndex || intent.UntrackedPolicy != UntrackedNotApplicable || len(intent.SourcePaths) != 1 { + t.Fatalf("source-bound intent = %#v", intent) + } + } +} + +func TestCompleteIntentChainTreatsUnmovedLaneAsEmpty(t *testing.T) { + repo := engineTestRepo(t) + base := engineGit(t, repo.Root, "rev-parse", "HEAD") + target := "refs/heads/wip/agent/empty" + engineGit(t, repo.Root, "update-ref", target, base, "") + + chain, err := CompleteIntentChain(context.Background(), repo, target, base, base) + if err != nil { + t.Fatal(err) + } + if len(chain) != 0 { + t.Fatalf("chain = %#v, want empty", chain) + } +} + +func TestCompleteIntentChainFailsOnMissingSegment(t *testing.T) { + repo := engineTestRepo(t) + base := engineGit(t, repo.Root, "rev-parse", "HEAD") + target := "refs/heads/wip/agent/cumulative-gap" + engineGit(t, repo.Root, "update-ref", target, base, "") + first := completeTestCapture(t, repo, target, base, "core.txt", "first core\n", "fix(core): capture first segment") + second := completeTestCapture(t, repo, target, first.FinalCommit, "docs.txt", "second docs\n", "docs(guide): capture second segment") + _, firstPath, err := LoadIntent(repo, first.PlanID, first.PlanDigest) + if err != nil { + t.Fatal(err) + } + if err := os.Remove(firstPath); err != nil { + t.Fatal(err) + } + if _, err := CompleteIntentChain(context.Background(), repo, target, base, second.FinalCommit); fail.Code(err) != "HANDOFF_CHAIN_INCOMPLETE" { + t.Fatalf("error = %v, want HANDOFF_CHAIN_INCOMPLETE", err) + } +} + +func completeTestCapture(t *testing.T, repo gitx.Repo, target, expected, path, contents, message string) Result { + t.Helper() + write(t, repo.Root, path, contents) + engineGit(t, repo.Root, "add", "--", path) + result, err := Run(context.Background(), Options{ + Repo: repo, TargetRef: target, ExpectedRef: expected, ExpectedSourceHead: engineGit(t, repo.Root, "rev-parse", "HEAD"), + AllowedPaths: []string{path}, Groups: []Group{{Message: message, Files: []string{path}}}, + }) + if err != nil { + t.Fatal(err) + } + if _, err := MarkIntent(repo, result.PlanID, result.PlanDigest, "complete"); err != nil { + t.Fatal(err) + } + return result +} diff --git a/internal/engine/hook.go b/internal/engine/hook.go index 54c6561..ad6cb5e 100644 --- a/internal/engine/hook.go +++ b/internal/engine/hook.go @@ -19,9 +19,12 @@ import ( ) const ( - DefaultHookTimeout = 2 * time.Minute - MaxHookTimeout = 24 * time.Hour - maxHookBytes = 4 << 20 + DefaultHookTimeout = 2 * time.Minute + MaxHookTimeout = 24 * time.Hour + maxHookBytes = 4 << 20 + preflightReadOnly = "NICOS_PREFLIGHT_READ_ONLY" + hookPhasePreCommit = "pre-commit" + hookPhasePostCommit = "post-commit" ) type hookSnapshot struct { @@ -159,10 +162,31 @@ func hooksDigest(hooks ...boundHook) string { return "sha256:" + hex.EncodeToString(hash.Sum(nil)) } -func hookEnvironment(index, target, object string) []string { - environment := gitx.Environment([]string{"GIT_INDEX_FILE=" + index, "WIP_TARGET_REF=" + target}) +func hookEnvironment(privateEnvironment []string, phase, target, object string) []string { + blocked := map[string]bool{ + preflightReadOnly: true, + "WIP_CAPTURE": true, + "WIP_COMMIT_OBJECT": true, + "WIP_HOOK_PHASE": true, + "WIP_SOURCE_READ_ONLY": true, + "WIP_TARGET_REF": true, + } + environment := make([]string, 0, len(privateEnvironment)+6) + for _, entry := range privateEnvironment { + name, _, _ := strings.Cut(entry, "=") + if !blocked[strings.ToUpper(name)] { + environment = append(environment, entry) + } + } + environment = append(environment, + preflightReadOnly+"=1", + "WIP_CAPTURE=1", + "WIP_HOOK_PHASE="+phase, + "WIP_SOURCE_READ_ONLY=1", + "WIP_TARGET_REF="+target, + ) if strings.TrimSpace(object) != "" { environment = append(environment, "WIP_COMMIT_OBJECT="+object) } - return environment + return gitx.Environment(environment) } diff --git a/internal/engine/intent.go b/internal/engine/intent.go index b00219d..2b39ad7 100644 --- a/internal/engine/intent.go +++ b/internal/engine/intent.go @@ -18,14 +18,17 @@ import ( "github.com/nstranquist/wip-commit/internal/fail" "github.com/nstranquist/wip-commit/internal/gitx" "github.com/nstranquist/wip-commit/internal/pathid" + "github.com/nstranquist/wip-commit/internal/policy" "github.com/nstranquist/wip-commit/internal/recordjson" "github.com/nstranquist/wip-commit/internal/safeio" "github.com/nstranquist/wip-commit/internal/strictjson" ) const ( - intentSchemaVersion = 1 - maxIntentBytes = 1 << 20 + intentSchemaVersion = 3 + reviewIntentSchemaVersion = 2 + legacyIntentSchemaVersion = 1 + maxIntentBytes = 1 << 20 ) var planIDPattern = regexp.MustCompile(`^plan-[0-9a-f]{24}$`) @@ -37,22 +40,30 @@ var ( ) type Intent struct { - SchemaVersion int `json:"schema_version"` - PlanID string `json:"plan_id"` - PlanDigest string `json:"plan_digest"` - State string `json:"state"` - TargetRef string `json:"target_ref"` - ExpectedOld string `json:"expected_old"` - ExpectedNew string `json:"expected_new"` - SourceHead string `json:"source_head"` - SourceIndexDigest string `json:"source_index_digest"` - FinalTree string `json:"final_tree"` - HookDigest string `json:"hook_digest"` - RequestedPaths []string `json:"requested_paths"` - AllowedPaths []string `json:"allowed_paths"` - Commits []PlannedCommit `json:"commits"` - CreatedAt time.Time `json:"created_at"` - UpdatedAt time.Time `json:"updated_at"` + SchemaVersion int `json:"schema_version"` + PlanID string `json:"plan_id"` + PlanDigest string `json:"plan_digest"` + ReviewPlanDigest string `json:"review_plan_digest,omitempty"` + MessagePolicy *policy.Receipt `json:"message_policy,omitempty"` + State string `json:"state"` + TargetRef string `json:"target_ref"` + ExpectedOld string `json:"expected_old"` + ExpectedNew string `json:"expected_new"` + SourceHead string `json:"source_head"` + SourceMode SourceMode `json:"source_mode,omitempty"` + UntrackedPolicy UntrackedPolicy `json:"untracked_policy,omitempty"` + // LegacySourceIndexDigest preserves the byte representation and digest of + // schema v1 and v2 records. Schema v3 writes SourceDigest instead. + LegacySourceIndexDigest string `json:"source_index_digest,omitempty"` + SourceDigest string `json:"source_digest,omitempty"` + SourcePaths []string `json:"source_paths,omitempty"` + FinalTree string `json:"final_tree"` + HookDigest string `json:"hook_digest"` + RequestedPaths []string `json:"requested_paths"` + AllowedPaths []string `json:"allowed_paths"` + Commits []PlannedCommit `json:"commits"` + CreatedAt time.Time `json:"created_at"` + UpdatedAt time.Time `json:"updated_at"` } type ReconcileResult struct { @@ -63,26 +74,87 @@ type ReconcileResult struct { AlreadyClean bool `json:"already_clean"` } +type IntentSummary struct { + PlanID string `json:"plan_id"` + PlanDigest string `json:"plan_digest"` + ReviewPlanDigest string `json:"review_plan_digest,omitempty"` + State string `json:"state"` + ExpectedNew string `json:"expected_new"` + MessagePolicy *policy.Receipt `json:"message_policy,omitempty"` + CreatedAt time.Time `json:"created_at"` + UpdatedAt time.Time `json:"updated_at"` +} + +// LatestIntent returns the newest validated capture intent for targetRef. +func LatestIntent(repo gitx.Repo, targetRef string) (*IntentSummary, error) { + directory := filepath.Join(repo.CommonDir, "wip", "v1", "intents") + entries, err := os.ReadDir(directory) + if errors.Is(err, os.ErrNotExist) { + return nil, nil + } + if err != nil { + return nil, fail.Wrap("INTENT_READ_FAILED", err) + } + if len(entries) > 10_000 { + return nil, fail.New("INTENT_READ_FAILED", "intent directory exceeds 10000 entries") + } + var latest *IntentSummary + for _, entry := range entries { + if entry.IsDir() || !strings.HasSuffix(entry.Name(), ".json") { + continue + } + id := strings.TrimSuffix(entry.Name(), ".json") + if !planIDPattern.MatchString(id) { + return nil, fail.New("INTENT_READ_FAILED", "intent directory contains an invalid record name") + } + intent, _, loadErr := LoadIntent(repo, id, "") + if loadErr != nil { + return nil, loadErr + } + if intent.TargetRef != targetRef { + continue + } + candidate := &IntentSummary{PlanID: intent.PlanID, PlanDigest: intent.PlanDigest, ReviewPlanDigest: intent.ReviewPlanDigest, State: intent.State, ExpectedNew: intent.ExpectedNew, MessagePolicy: intent.MessagePolicy, CreatedAt: intent.CreatedAt, UpdatedAt: intent.UpdatedAt} + if latest == nil || candidate.CreatedAt.After(latest.CreatedAt) || candidate.CreatedAt.Equal(latest.CreatedAt) && candidate.PlanID > latest.PlanID { + latest = candidate + } + } + return latest, nil +} + func newIntent(result Result, allowed []string) (Intent, error) { now := time.Now().UTC() + var messagePolicy *policy.Receipt + if result.ReviewPlanDigest != "" { + if result.MessagePolicy != nil { + receipt := *result.MessagePolicy + messagePolicy = &receipt + } + } intent := Intent{ - SchemaVersion: intentSchemaVersion, - State: "prepared", - TargetRef: result.TargetRef, - ExpectedOld: result.ExpectedRef, - ExpectedNew: result.FinalCommit, - SourceHead: result.SourceHead, - SourceIndexDigest: result.SourceIndexDigest, - FinalTree: result.FinalTree, - HookDigest: result.HookDigest, - RequestedPaths: append([]string(nil), result.RequestedPaths...), - AllowedPaths: append([]string(nil), allowed...), - Commits: append([]PlannedCommit(nil), result.Commits...), - CreatedAt: now, - UpdatedAt: now, - } - intent.PlanID = canonicalIntentID(intent.TargetRef, intent.ExpectedOld, intent.ExpectedNew, intent.SourceIndexDigest) + SchemaVersion: intentSchemaVersion, + State: "prepared", + TargetRef: result.TargetRef, + ExpectedOld: result.ExpectedRef, + ExpectedNew: result.FinalCommit, + SourceHead: result.SourceHead, + SourceMode: result.SourceMode, + UntrackedPolicy: result.UntrackedPolicy, + SourceDigest: result.SourceDigest, + SourcePaths: append([]string(nil), result.SourcePaths...), + FinalTree: result.FinalTree, + HookDigest: result.HookDigest, + ReviewPlanDigest: result.ReviewPlanDigest, + MessagePolicy: messagePolicy, + RequestedPaths: append([]string(nil), result.RequestedPaths...), + AllowedPaths: append([]string(nil), allowed...), + Commits: append([]PlannedCommit(nil), result.Commits...), + CreatedAt: now, + UpdatedAt: now, + } + intent.PlanID = canonicalIntentIDV3(intent.TargetRef, intent.ExpectedOld, intent.ExpectedNew, intent.SourceDigest, intent.SourceMode, intent.UntrackedPolicy) sort.Strings(intent.AllowedPaths) + sort.Strings(intent.SourcePaths) digest, err := digestIntent(intent) if err != nil { return Intent{}, err @@ -148,8 +220,8 @@ func LoadIntent(repo gitx.Repo, planID, expectedDigest string) (Intent, string, if err := strictjson.Decode(body, &intent); err != nil { return intent, path, fail.Wrap("INTENT_READ_FAILED", err) } - if intent.SchemaVersion != intentSchemaVersion { - return intent, path, fail.Errorf("MIGRATION_REQUIRED", "intent schema version %d is unsupported; this wip release supports version %d", intent.SchemaVersion, intentSchemaVersion) + if intent.SchemaVersion != legacyIntentSchemaVersion && intent.SchemaVersion != reviewIntentSchemaVersion && intent.SchemaVersion != intentSchemaVersion { + return intent, path, fail.Errorf("MIGRATION_REQUIRED", "intent schema version %d is unsupported; this wip release supports versions %d, %d, and %d", intent.SchemaVersion, legacyIntentSchemaVersion, reviewIntentSchemaVersion, intentSchemaVersion) } if intent.PlanID != planID || !planIDPattern.MatchString(intent.PlanID) { return intent, path, fail.New("INVALID_INTENT", "plan intent identity is invalid") @@ -171,9 +243,57 @@ func LoadIntent(repo gitx.Repo, planID, expectedDigest string) (Intent, string, } func validateIntentRecord(repo gitx.Repo, intent Intent) error { - if !intentDigestPattern.MatchString(intent.PlanDigest) || !intentDigestPattern.MatchString(intent.SourceIndexDigest) || !intentDigestPattern.MatchString(intent.HookDigest) { + sourceDigest := intentSourceDigest(intent) + if !intentDigestPattern.MatchString(intent.PlanDigest) || !intentDigestPattern.MatchString(sourceDigest) || !intentDigestPattern.MatchString(intent.HookDigest) { return fail.New("INVALID_INTENT", "plan intent digest fields are invalid") } + if intent.SchemaVersion == legacyIntentSchemaVersion { + if intent.ReviewPlanDigest != "" || intent.MessagePolicy != nil { + return fail.New("INVALID_INTENT", "legacy plan intent contains unsupported review binding") + } + } else if intent.SchemaVersion == reviewIntentSchemaVersion { + if !intentDigestPattern.MatchString(intent.ReviewPlanDigest) { + return fail.New("INVALID_INTENT", "plan intent reviewed-plan digest is invalid") + } + if intent.MessagePolicy == nil { + return fail.New("INVALID_INTENT", "plan intent message policy is missing") + } + if err := policy.ValidateReceipt(*intent.MessagePolicy); err != nil { + return fail.Wrap("INVALID_INTENT", err) + } + } else if intent.ReviewPlanDigest == "" || intent.MessagePolicy == nil { + if intent.ReviewPlanDigest != "" || intent.MessagePolicy != nil { + return fail.New("INVALID_INTENT", "plan intent review binding is incomplete") + } + } else { + if !intentDigestPattern.MatchString(intent.ReviewPlanDigest) { + return fail.New("INVALID_INTENT", "plan intent reviewed-plan digest is invalid") + } + if err := policy.ValidateReceipt(*intent.MessagePolicy); err != nil { + return fail.Wrap("INVALID_INTENT", err) + } + } + if intent.SchemaVersion < intentSchemaVersion { + if intent.SourceMode != "" || intent.UntrackedPolicy != "" || len(intent.SourcePaths) != 0 || intent.SourceDigest != "" || intent.LegacySourceIndexDigest == "" { + return fail.New("INVALID_INTENT", "legacy plan intent contains unsupported source binding") + } + } else { + if intent.SourceDigest == "" || intent.LegacySourceIndexDigest != "" { + return fail.New("INVALID_INTENT", "plan intent source digest field is invalid for schema v3") + } + mode, untracked, err := NormalizeSource(intent.SourceMode, intent.UntrackedPolicy) + if err != nil || mode != intent.SourceMode || untracked != intent.UntrackedPolicy { + return fail.New("INVALID_INTENT", "plan intent source binding is invalid") + } + if err := validateIntentPaths(repo, intent.SourcePaths, "source"); err != nil { + return err + } + for _, sourcePath := range intent.SourcePaths { + if !pathid.Covered(sourcePath, intent.RequestedPaths) { + return fail.New("INVALID_INTENT", "plan intent source paths exceed its requested paths") + } + } + } if !intentObjectPattern.MatchString(intent.ExpectedOld) || !intentObjectPattern.MatchString(intent.ExpectedNew) || !intentObjectPattern.MatchString(intent.SourceHead) || !intentObjectPattern.MatchString(intent.FinalTree) || intent.ExpectedOld == intent.ExpectedNew { return fail.New("INVALID_INTENT", "plan intent object identities are invalid") } @@ -183,7 +303,10 @@ func validateIntentRecord(repo gitx.Repo, intent Intent) error { if intent.CreatedAt.IsZero() || intent.UpdatedAt.IsZero() || intent.UpdatedAt.Before(intent.CreatedAt) { return fail.New("INVALID_INTENT", "plan intent timestamps are invalid") } - wantedID := canonicalIntentID(intent.TargetRef, intent.ExpectedOld, intent.ExpectedNew, intent.SourceIndexDigest) + wantedID := canonicalIntentID(intent.TargetRef, intent.ExpectedOld, intent.ExpectedNew, sourceDigest) + if intent.SchemaVersion == intentSchemaVersion { + wantedID = canonicalIntentIDV3(intent.TargetRef, intent.ExpectedOld, intent.ExpectedNew, sourceDigest, intent.SourceMode, intent.UntrackedPolicy) + } if intent.PlanID != wantedID { return fail.New("INVALID_INTENT", "plan intent id does not match its immutable publication identity") } @@ -207,7 +330,7 @@ func validateIntentRecord(repo gitx.Repo, intent Intent) error { if planned.Index != index+1 || planned.Parent != cursor || !intentObjectPattern.MatchString(planned.Parent) || !intentObjectPattern.MatchString(planned.Commit) || !intentObjectPattern.MatchString(planned.Tree) { return fail.Errorf("INVALID_INTENT", "plan intent commit %d identity or parent chain is invalid", index+1) } - if err := ValidateMessage(planned.Message, true); err != nil { + if err := ValidateMessageSafety(planned.Message); err != nil { return fail.Wrap("INVALID_INTENT", fmt.Errorf("commit %d message: %w", index+1, err)) } if planned.VerifyCount < 0 || planned.VerifyCount > maxVerifyCommands || planned.Repairs < 0 { @@ -232,6 +355,13 @@ func validateIntentRecord(repo gitx.Repo, intent Intent) error { return nil } +func intentSourceDigest(intent Intent) string { + if intent.SchemaVersion < intentSchemaVersion { + return intent.LegacySourceIndexDigest + } + return intent.SourceDigest +} + func validateIntentPaths(repo gitx.Repo, paths []string, label string) error { if len(paths) == 0 || len(paths) > maxPlannedPaths { return fail.New("INVALID_INTENT", "plan intent "+label+" path count is outside the safety bounds") @@ -266,6 +396,12 @@ func canonicalIntentID(targetRef, expectedOld, expectedNew, sourceIndexDigest st return "plan-" + hex.EncodeToString(sum[:12]) } +func canonicalIntentIDV3(targetRef, expectedOld, expectedNew, sourceIndexDigest string, mode SourceMode, untracked UntrackedPolicy) string { + entropy := strings.Join([]string{targetRef, expectedOld, expectedNew, sourceIndexDigest, string(mode), string(untracked)}, "\x00") + sum := sha256.Sum256([]byte(entropy)) + return "plan-" + hex.EncodeToString(sum[:12]) +} + func sameOrderedStrings(left, right []string) bool { if len(left) != len(right) { return false @@ -344,48 +480,56 @@ func ValidateApplied(ctx context.Context, repo gitx.Repo, planID, planDigest, ta if actual != intent.ExpectedNew { return Intent{}, false, fail.Errorf("REF_MOVED", "lane ref is %s, not plan result %s", actual, intent.ExpectedNew) } - if laneCursor == intent.ExpectedNew && intent.State == "complete" { - return intent, true, nil + alreadyComplete := laneCursor == intent.ExpectedNew && intent.State == "complete" + if err := ValidateIntentObjects(ctx, repo, intent); err != nil { + return Intent{}, false, err } + return intent, alreadyComplete, nil +} + +// ValidateIntentObjects verifies the immutable commit chain without requiring +// the lane ref to still point at this intent's final commit. Cumulative handoff +// validation uses it for earlier segments of an active lane. +func ValidateIntentObjects(ctx context.Context, repo gitx.Repo, intent Intent) error { cursor := intent.ExpectedOld for index, planned := range intent.Commits { if planned.Commit == "" || planned.Parent != cursor { - return Intent{}, false, receiptMismatch(index, "has an invalid parent chain") + return receiptMismatch(index, "has an invalid parent chain") } parent, parentErr := repo.Text(ctx, nil, "rev-parse", "--verify", planned.Commit+"^1") if parentErr != nil || parent != cursor { - return Intent{}, false, receiptMismatch(index, "does not continue its receipt parent") + return receiptMismatch(index, "does not continue its receipt parent") } tree, treeErr := repo.Text(ctx, nil, "show", "-s", "--format=%T", planned.Commit) if treeErr != nil || tree != planned.Tree { - return Intent{}, false, receiptMismatch(index, "tree does not match its receipt") + return receiptMismatch(index, "tree does not match its receipt") } message, messageErr := repo.Text(ctx, nil, "show", "-s", "--format=%B", planned.Commit) if messageErr != nil || strings.TrimSpace(message) != strings.TrimSpace(planned.Message) { - return Intent{}, false, receiptMismatch(index, "message does not match its receipt") + return receiptMismatch(index, "message does not match its receipt") } changed, changedErr := repo.NULPaths(ctx, nil, "diff", "--no-renames", "--name-only", "-z", cursor, planned.Commit) if changedErr != nil || !samePathSet(changed, planned.ChangedPaths) { - return Intent{}, false, receiptMismatch(index, "path set does not match its receipt") + return receiptMismatch(index, "path set does not match its receipt") } for _, path := range changed { if !pathid.Covered(path, intent.RequestedPaths) || !pathid.Covered(path, intent.AllowedPaths) { - return Intent{}, false, receiptMismatch(index, fmt.Sprintf("contains out-of-scope path %q", path)) + return receiptMismatch(index, fmt.Sprintf("contains out-of-scope path %q", path)) } } cursor = planned.Commit } if cursor != intent.ExpectedNew { - return Intent{}, false, fail.New("CAPTURE_RECEIPT_MISMATCH", "plan receipt does not end at the applied ref") + return fail.New("CAPTURE_RECEIPT_MISMATCH", "plan receipt does not end at the applied ref") } if intent.FinalTree == "" || intent.FinalTree != intent.Commits[len(intent.Commits)-1].Tree { - return Intent{}, false, fail.New("CAPTURE_RECEIPT_MISMATCH", "plan final tree does not match its last commit") + return fail.New("CAPTURE_RECEIPT_MISMATCH", "plan final tree does not match its last commit") } finalTree, err := repo.Text(ctx, nil, "show", "-s", "--format=%T", intent.ExpectedNew) if err != nil || finalTree != intent.FinalTree { - return Intent{}, false, fail.New("CAPTURE_RECEIPT_MISMATCH", "applied commit does not contain the receipt final tree") + return fail.New("CAPTURE_RECEIPT_MISMATCH", "applied commit does not contain the receipt final tree") } - return intent, false, nil + return nil } func intentPath(repo gitx.Repo, planID string) (string, error) { diff --git a/internal/engine/message.go b/internal/engine/message.go index 2002f6a..ce062b8 100644 --- a/internal/engine/message.go +++ b/internal/engine/message.go @@ -1,67 +1,14 @@ package engine import ( - "regexp" - "strings" - "unicode" - "unicode/utf8" - - "github.com/nstranquist/wip-commit/internal/fail" + "github.com/nstranquist/wip-commit/internal/message" + "github.com/nstranquist/wip-commit/internal/policy" ) -const subjectLimit = 72 - -var ( - conventional = regexp.MustCompile(`^([a-z][a-z0-9-]*)(?:\(([a-z0-9][a-z0-9._/-]*)\))?(!)?: (.+)$`) - types = map[string]bool{"build": true, "chore": true, "ci": true, "docs": true, "feat": true, "fix": true, "perf": true, "refactor": true, "revert": true, "style": true, "test": true} - vague = map[string]bool{"change": true, "changes": true, "fix": true, "misc": true, "stuff": true, "update": true, "updates": true, "work": true} -) - -func ValidateMessage(message string, allowWIP bool) error { - if !utf8.ValidString(message) { - return fail.New("INVALID_COMMIT_MESSAGE", "commit message must be valid UTF-8") - } - for _, character := range message { - if character == '\r' || character == '\x00' || (unicode.IsControl(character) && character != '\n' && character != '\t') { - return fail.New("INVALID_COMMIT_MESSAGE", "commit message contains an unsupported control character") - } - } - trimmed := strings.TrimSpace(message) - if message != trimmed { - return fail.New("INVALID_COMMIT_MESSAGE", "commit message cannot start or end with whitespace") - } - message = trimmed - if message == "" { - return fail.New("INVALID_COMMIT_MESSAGE", "commit message cannot be empty") - } - lines := strings.Split(message, "\n") - subject := strings.TrimSpace(lines[0]) - if utf8.RuneCountInString(subject) > subjectLimit { - return fail.New("INVALID_COMMIT_MESSAGE", "commit subject exceeds 72 characters") - } - if len(lines) > 1 && strings.TrimSpace(lines[1]) != "" { - return fail.New("INVALID_COMMIT_MESSAGE", "separate the subject and body with a blank line") - } - match := conventional.FindStringSubmatch(subject) - if match == nil { - return fail.New("INVALID_COMMIT_MESSAGE", "use (): ") - } - if match[1] == "wip" { - if !allowWIP { - return fail.New("WIP_PREFIX_NOT_AUTHORIZED", "wip: requires explicit authorization") - } - } else if !types[match[1]] { - return fail.Errorf("INVALID_COMMIT_MESSAGE", "unsupported Conventional Commit type %q", match[1]) - } - description := strings.TrimSpace(match[4]) - if description != match[4] { - return fail.New("INVALID_COMMIT_MESSAGE", "use one space after the subject colon") - } - if utf8.RuneCountInString(description) < 4 || vague[strings.ToLower(strings.TrimSuffix(description, "."))] { - return fail.New("INVALID_COMMIT_MESSAGE", "name the concrete outcome") - } - if strings.HasSuffix(description, ".") { - return fail.New("INVALID_COMMIT_MESSAGE", "commit subject must not end with a period") - } - return nil +// ValidateMessage remains for callers of the pre-v2 internal API. New capture +// paths validate named policy before entering the engine. +func ValidateMessage(value string, allowWIP bool) error { + return policy.Validate(policy.Default(), value, allowWIP) } + +func ValidateMessageSafety(value string) error { return message.ValidateSafety(value) } diff --git a/internal/engine/plan.go b/internal/engine/plan.go index 842d4d8..d2664b4 100644 --- a/internal/engine/plan.go +++ b/internal/engine/plan.go @@ -11,6 +11,7 @@ import ( "os" "path/filepath" "sort" + "strconv" "strings" "sync" "time" @@ -18,11 +19,12 @@ import ( "github.com/nstranquist/wip-commit/internal/fail" "github.com/nstranquist/wip-commit/internal/gitx" "github.com/nstranquist/wip-commit/internal/pathid" + "github.com/nstranquist/wip-commit/internal/policy" "github.com/nstranquist/wip-commit/internal/process" ) const ( - ResultSchemaVersion = "1.0.0" + ResultSchemaVersion = "3.0.0" DefaultVerifyTimeout = 2 * time.Minute MaxVerifyTimeout = 24 * time.Hour maxVerifyOutput = 64 * 1024 @@ -30,12 +32,17 @@ const ( maxPlannedPaths = 10_000 maxVerifyCommands = 64 maxVerifyArguments = 256 + maxVerifyScopes = 256 + maxVerifyTreeEntries = 16_384 + maxVerifyTreeBytes = 512 << 20 + maxVerifyListing = 64 << 20 ) type VerifyCommand struct { - Argv []string `json:"argv"` - Directory string `json:"directory,omitempty"` - TimeoutMS int64 `json:"timeout_ms,omitempty"` + Argv []string `json:"argv"` + Directory string `json:"directory,omitempty"` + Materialize []string `json:"materialize,omitempty"` + TimeoutMS int64 `json:"timeout_ms,omitempty"` } type Group struct { @@ -55,11 +62,29 @@ type PlannedCommit struct { Repairs int `json:"repairs_applied"` } +type ExecutionCount struct { + Planned int `json:"planned"` + Executed int `json:"executed"` + Skipped int `json:"skipped"` +} + +type ExecutionReport struct { + Policy string `json:"policy"` + PreCommitHooks ExecutionCount `json:"pre_commit_hooks"` + PostCommitHooks ExecutionCount `json:"post_commit_hooks"` + VerifyCommands ExecutionCount `json:"verify_commands"` +} + type Options struct { Repo gitx.Repo TargetRef string ExpectedRef string ExpectedSourceHead string + ExpectedSourceDigest string + SourceMode SourceMode + UntrackedPolicy UntrackedPolicy + ReviewPlanDigest string + MessagePolicy policy.Receipt AllowedPaths []string Groups []Group AllowWIP bool @@ -72,29 +97,58 @@ type Options struct { } type Result struct { - SchemaVersion string `json:"schema_version"` - TargetRef string `json:"target_ref"` - ExpectedRef string `json:"expected_ref"` - FinalCommit string `json:"final_commit,omitempty"` - FinalTree string `json:"final_tree"` - SourceHead string `json:"source_head"` - SourceWorktree string `json:"source_worktree"` - SourceIndexDigest string `json:"source_index_digest"` - HookDigest string `json:"hook_digest"` - RequestedPaths []string `json:"requested_paths"` - Commits []PlannedCommit `json:"commits"` - GateOutcome string `json:"gate_outcome"` - DryRun bool `json:"dry_run"` - RefUpdated bool `json:"ref_updated"` - PublicationScope string `json:"publication_scope,omitempty"` - PlanID string `json:"plan_id,omitempty"` - PlanDigest string `json:"plan_digest,omitempty"` - IntentPath string `json:"intent_path,omitempty"` - IntentState string `json:"intent_state,omitempty"` + SchemaVersion string `json:"schema_version"` + TargetRef string `json:"target_ref"` + ExpectedRef string `json:"expected_ref"` + FinalCommit string `json:"final_commit,omitempty"` + FinalTree string `json:"final_tree"` + SourceHead string `json:"source_head"` + SourceWorktree string `json:"source_worktree"` + SourceMode SourceMode `json:"source_mode"` + UntrackedPolicy UntrackedPolicy `json:"untracked_policy"` + SourceDigest string `json:"source_digest"` + SourcePaths []string `json:"source_paths"` + HookDigest string `json:"hook_digest"` + RequestedPaths []string `json:"requested_paths"` + Commits []PlannedCommit `json:"commits"` + GateOutcome string `json:"gate_outcome"` + Execution *ExecutionReport `json:"execution,omitempty"` + DryRun bool `json:"dry_run"` + RefUpdated bool `json:"ref_updated"` + PublicationScope string `json:"publication_scope,omitempty"` + PlanID string `json:"plan_id,omitempty"` + PlanDigest string `json:"plan_digest,omitempty"` + ReviewPlanDigest string `json:"review_plan_digest,omitempty"` + MessagePolicy *policy.Receipt `json:"message_policy,omitempty"` + IntentPath string `json:"intent_path,omitempty"` + IntentState string `json:"intent_state,omitempty"` } func Run(ctx context.Context, options Options) (result Result, err error) { result.SchemaVersion, result.DryRun, result.GateOutcome = ResultSchemaVersion, options.DryRun, "failed" + result.ReviewPlanDigest = options.ReviewPlanDigest + options.SourceMode, options.UntrackedPolicy, err = NormalizeSource(options.SourceMode, options.UntrackedPolicy) + if err != nil { + return result, err + } + result.SourceMode, result.UntrackedPolicy = options.SourceMode, options.UntrackedPolicy + boundPlan := strings.TrimSpace(options.ReviewPlanDigest) != "" || options.MessagePolicy != (policy.Receipt{}) || strings.TrimSpace(options.ExpectedSourceDigest) != "" + if boundPlan && (strings.TrimSpace(options.ReviewPlanDigest) == "" || options.MessagePolicy == (policy.Receipt{}) || strings.TrimSpace(options.ExpectedSourceDigest) == "") { + return result, fail.New("INVALID_PLAN_BINDING", "reviewed plan digest, message policy, and expected source digest must be supplied together") + } + if boundPlan { + receipt := options.MessagePolicy + result.MessagePolicy = &receipt + if !intentDigestPattern.MatchString(options.ReviewPlanDigest) { + return result, fail.New("INVALID_PLAN_BINDING", "reviewed plan digest must be a sha256 receipt") + } + if !intentDigestPattern.MatchString(options.ExpectedSourceDigest) { + return result, fail.New("INVALID_PLAN_BINDING", "expected source digest must be a sha256 receipt") + } + if err := policy.ValidateReceipt(options.MessagePolicy); err != nil { + return result, err + } + } if len(options.Groups) == 0 { return result, fail.New("INVALID_PLAN", "commit plan must contain at least one group") } @@ -161,9 +215,23 @@ func Run(ctx context.Context, options Options) (result Result, err error) { } result.SourceHead, result.SourceWorktree = head, options.Repo.Root - indexRoot, err := preparePrivateIndexRoot(options.Repo.GitDir) - if err != nil { - return result, err + indexRoot := "" + var objectEnvironment []string + if options.DryRun { + indexRoot, err = os.MkdirTemp("", "wip-dry-run-*") + if err != nil { + return result, fail.Wrap("TEMP_INDEX_FAILED", err) + } + defer func() { _ = os.RemoveAll(indexRoot) }() + objectEnvironment, err = isolatedObjectEnvironment(options.Repo, indexRoot) + if err != nil { + return result, err + } + } else { + indexRoot, err = preparePrivateIndexRoot(options.Repo.GitDir) + if err != nil { + return result, err + } } preHook, err := prepareHook(ctx, options.Repo, indexRoot, "pre-commit") if err != nil { @@ -176,13 +244,37 @@ func Run(ctx context.Context, options Options) (result Result, err error) { } defer postHook.cleanup() result.HookDigest = hooksDigest(preHook, postHook) + if options.DryRun { + preCommitHooks, postCommitHooks, verifyCommands := 0, 0, 0 + if preHook.Private != "" { + preCommitHooks = len(groups) + } + if postHook.Private != "" { + postCommitHooks = len(groups) + } + for _, group := range groups { + verifyCommands += len(group.Verify) + } + result.Execution = &ExecutionReport{ + Policy: "no-exec", + PreCommitHooks: skippedExecutionCount(preCommitHooks), + PostCommitHooks: skippedExecutionCount(postCommitHooks), + VerifyCommands: skippedExecutionCount(verifyCommands), + } + } - source, err := options.Repo.IndexEntries(ctx, nil) + sourceSnapshot, cleanupSource, err := captureSource(ctx, options.Repo, expected, allPaths, options.SourceMode, options.UntrackedPolicy, indexRoot, options.DryRun) if err != nil { - return result, fail.Wrap("GIT_FAILED", err) + return result, err + } + defer cleanupSource() + source := sourceSnapshot.Entries + result.SourcePaths = append([]string(nil), sourceSnapshot.Paths...) + result.SourceDigest = sourceSnapshot.Digest + if boundPlan && result.SourceDigest != options.ExpectedSourceDigest { + return result, fail.New("SOURCE_MOVED", "the selected source no longer matches the reviewed plan") } - result.SourceIndexDigest = selectedDigest(source, allPaths) - index, environment, cleanup, err := privateIndex(ctx, options.Repo, indexRoot, expected) + _, environment, cleanup, err := privateIndex(ctx, options.Repo, indexRoot, expected, objectEnvironment) if err != nil { return result, err } @@ -207,14 +299,17 @@ func Run(ctx context.Context, options Options) (result Result, err error) { if preHookTree == parentTree { return result, fail.Errorf("EMPTY_COMMIT_GROUP", "group %d has no captured staged change", groupIndex+1) } - if err := preHook.run(ctx, options.Repo, hookEnvironment(index, target, ""), options.HookTimeout, options.Output, options.ErrorOutput); err != nil { - return result, err - } - tree, treeErr := options.Repo.Text(ctx, environment, "write-tree") - if treeErr != nil { - return result, fail.Wrap("PRIVATE_INDEX_FAILED", treeErr) + tree := preHookTree + if !options.DryRun { + if err := preHook.run(ctx, options.Repo, hookEnvironment(environment, hookPhasePreCommit, target, ""), options.HookTimeout, options.Output, options.ErrorOutput); err != nil { + return result, err + } + tree, treeErr = options.Repo.Text(ctx, environment, "write-tree") + if treeErr != nil { + return result, fail.Wrap("PRIVATE_INDEX_FAILED", treeErr) + } } - changed, changedErr := options.Repo.NULPaths(ctx, nil, "diff", "--no-renames", "--name-only", "-z", parentTree, tree) + changed, changedErr := options.Repo.NULPaths(ctx, environment, "diff", "--no-renames", "--name-only", "-z", parentTree, tree) if changedErr != nil { return result, fail.Wrap("PRIVATE_INDEX_FAILED", changedErr) } @@ -229,13 +324,13 @@ func Run(ctx context.Context, options Options) (result Result, err error) { return result, fail.Errorf("LEASE_REQUIRED", "group %d changed unleased path %q", groupIndex+1, path) } } - if _, err := options.Repo.Text(ctx, nil, "diff", "--check", parentTree, tree); err != nil { + if _, err := options.Repo.Text(ctx, environment, "diff", "--check", parentTree, tree); err != nil { return result, fail.Wrap("DIFF_CHECK_FAILED", err) } - if err := verifyTree(ctx, options.Repo, environment, tree, group.Verify, options.DefaultVerifyTimeout); err != nil { + if err := verifyTree(ctx, options.Repo, environment, tree, group.Verify, options.DefaultVerifyTimeout, !options.DryRun); err != nil { return result, err } - repairs, repairsErr := options.Repo.NULPaths(ctx, nil, "diff", "--no-renames", "--name-only", "-z", preHookTree, tree) + repairs, repairsErr := options.Repo.NULPaths(ctx, environment, "diff", "--no-renames", "--name-only", "-z", preHookTree, tree) if repairsErr != nil { return result, fail.Wrap("PRIVATE_INDEX_FAILED", repairsErr) } @@ -255,7 +350,7 @@ func Run(ctx context.Context, options Options) (result Result, err error) { result.Commits = append(result.Commits, planned) } result.FinalTree = parentTree - if options.BeforePublish != nil { + if !options.DryRun && options.BeforePublish != nil { if err := options.BeforePublish(); err != nil { return result, err } @@ -264,12 +359,13 @@ func Run(ctx context.Context, options Options) (result Result, err error) { if err != nil || currentHead != head { return result, fail.New("SOURCE_HEAD_MOVED", "source HEAD changed while capture was prepared") } - currentIndex, err := options.Repo.IndexEntries(ctx, nil) + currentSource, cleanupCurrentSource, err := captureSource(ctx, options.Repo, expected, allPaths, options.SourceMode, options.UntrackedPolicy, indexRoot, options.DryRun) if err != nil { - return result, fail.Wrap("GIT_FAILED", err) + return result, err } - if selectedDigest(currentIndex, allPaths) != result.SourceIndexDigest { - return result, fail.New("SOURCE_INDEX_MOVED", "selected staged entries changed while capture was prepared") + defer cleanupCurrentSource() + if currentSource.Digest != result.SourceDigest || !sameSourcePaths(currentSource.Paths, result.SourcePaths) { + return result, fail.New("SOURCE_MOVED", "the selected source changed while capture was prepared") } if err := preHook.validate(); err != nil { return result, err @@ -278,7 +374,7 @@ func Run(ctx context.Context, options Options) (result Result, err error) { return result, err } if options.DryRun { - result.GateOutcome = "passed" + result.GateOutcome = "skipped" return result, nil } result.FinalCommit = parentCommit @@ -305,7 +401,7 @@ func Run(ctx context.Context, options Options) (result Result, err error) { _, _ = fmt.Fprintf(options.ErrorOutput, "wip: prepare post-commit index for %s: %v\n", commit.Commit, err) continue } - if err := postHook.run(ctx, options.Repo, hookEnvironment(index, target, commit.Commit), options.HookTimeout, options.Output, options.ErrorOutput); err != nil { + if err := postHook.run(ctx, options.Repo, hookEnvironment(environment, hookPhasePostCommit, target, commit.Commit), options.HookTimeout, options.Output, options.ErrorOutput); err != nil { _, _ = fmt.Fprintf(options.ErrorOutput, "wip: post-commit hook failed for %s: %v\n", commit.Commit, err) } } @@ -339,22 +435,23 @@ func preparePrivateIndexRoot(gitDir string) (string, error) { return filepath.Join(gitDir, "wip", "indexes"), nil } -func normalizeGroups(repo gitx.Repo, input []Group, allowWIP bool) ([]Group, []string, error) { +func normalizeGroups(repo gitx.Repo, input []Group, _ bool) ([]Group, []string, error) { groups := make([]Group, 0, len(input)) - seenMessages := map[string]bool{} var all []string for index, group := range input { if len(group.Verify) > maxVerifyCommands { return nil, nil, fail.Errorf("INVALID_PLAN", "group %d exceeds %d verify commands", index+1, maxVerifyCommands) } - if err := ValidateMessage(group.Message, allowWIP); err != nil { + if err := ValidateMessageSafety(group.Message); err != nil { return nil, nil, fail.Wrap("INVALID_COMMIT_MESSAGE", fmt.Errorf("group %d: %w", index+1, err)) } - key := strings.ToLower(strings.TrimSpace(group.Message)) - if seenMessages[key] { - return nil, nil, fail.Errorf("DUPLICATE_COMMIT_MESSAGE", "group %d repeats a prior message", index+1) + for commandIndex := range group.Verify { + normalized, verifyErr := normalizeVerifyCommand(repo, group.Verify[commandIndex], commandIndex) + if verifyErr != nil { + return nil, nil, fail.Wrap("INVALID_VERIFY_COMMAND", fmt.Errorf("group %d: %w", index+1, verifyErr)) + } + group.Verify[commandIndex] = normalized } - seenMessages[key] = true paths, err := repo.NormalizePaths(group.Files) if err != nil { return nil, nil, err @@ -379,7 +476,68 @@ func normalizeGroups(repo gitx.Repo, input []Group, allowWIP bool) ([]Group, []s return groups, all, nil } -func privateIndex(ctx context.Context, repo gitx.Repo, root, base string) (string, []string, func(), error) { +func normalizeVerifyCommand(repo gitx.Repo, command VerifyCommand, index int) (VerifyCommand, error) { + if len(command.Argv) == 0 || strings.TrimSpace(command.Argv[0]) == "" { + return VerifyCommand{}, fmt.Errorf("verify command %d has no executable", index+1) + } + if len(command.Argv) > maxVerifyArguments { + return VerifyCommand{}, fmt.Errorf("verify command %d exceeds %d arguments", index+1, maxVerifyArguments) + } + for _, argument := range command.Argv { + if strings.ContainsRune(argument, '\x00') { + return VerifyCommand{}, fmt.Errorf("verify command %d contains a NUL argument", index+1) + } + } + if command.TimeoutMS < 0 || command.TimeoutMS > MaxVerifyTimeout.Milliseconds() { + return VerifyCommand{}, fmt.Errorf("verify command %d timeout is outside the safety range", index+1) + } + if command.Directory != "" && command.Directory != "." { + directory, err := normalizeVerifyScope(repo, command.Directory) + if err != nil { + return VerifyCommand{}, fmt.Errorf("verify command %d directory: %w", index+1, err) + } + command.Directory = directory + } + if len(command.Materialize) > maxVerifyScopes { + return VerifyCommand{}, fmt.Errorf("verify command %d exceeds %d materialization scopes", index+1, maxVerifyScopes) + } + materialize := make([]string, 0, len(command.Materialize)) + seen := map[string]bool{} + for _, raw := range command.Materialize { + scope, err := normalizeVerifyScope(repo, raw) + if err != nil { + return VerifyCommand{}, fmt.Errorf("verify command %d materialization scope: %w", index+1, err) + } + if seen[scope] { + return VerifyCommand{}, fmt.Errorf("verify command %d has duplicate materialization scope %q", index+1, scope) + } + seen[scope] = true + materialize = append(materialize, scope) + } + sort.Strings(materialize) + command.Materialize = materialize + return command, nil +} + +func normalizeVerifyScope(repo gitx.Repo, raw string) (string, error) { + if strings.TrimSpace(raw) == "" || strings.ContainsRune(raw, '\x00') || strings.ContainsRune(raw, '\\') || filepath.IsAbs(raw) { + return "", fmt.Errorf("scope must be a non-empty portable repository-relative path") + } + clean := filepath.ToSlash(filepath.Clean(filepath.FromSlash(raw))) + if clean != raw || clean == "." || clean == ".." || strings.HasPrefix(clean, "../") { + return "", fmt.Errorf("scope %q is not canonical", raw) + } + normalized, err := repo.NormalizePaths([]string{raw}) + if err != nil || len(normalized) != 1 || normalized[0] != raw { + if err != nil { + return "", err + } + return "", fmt.Errorf("scope %q is not canonical", raw) + } + return raw, nil +} + +func privateIndex(ctx context.Context, repo gitx.Repo, root, base string, baseEnvironment []string) (string, []string, func(), error) { file, err := os.CreateTemp(root, "*.index") if err != nil { return "", nil, func() {}, fail.Wrap("TEMP_INDEX_FAILED", err) @@ -392,13 +550,26 @@ func privateIndex(ctx context.Context, repo gitx.Repo, root, base string) (strin if err := os.Remove(path); err != nil { return "", nil, func() {}, fail.Wrap("TEMP_INDEX_FAILED", err) } - environment := []string{"GIT_INDEX_FILE=" + path} + environment := append([]string(nil), baseEnvironment...) + environment = append(environment, "GIT_INDEX_FILE="+path) if _, err := repo.Text(ctx, environment, "read-tree", base); err != nil { return "", nil, func() {}, fail.Wrap("PRIVATE_INDEX_FAILED", err) } return path, environment, func() { _ = os.Remove(path) }, nil } +func sameSourcePaths(left, right []string) bool { + if len(left) != len(right) { + return false + } + for index := range left { + if left[index] != right[index] { + return false + } + } + return true +} + func stageEntries(ctx context.Context, repo gitx.Repo, environment []string, paths []string, staged, base map[string]string) error { candidates := map[string]bool{} for path := range staged { @@ -453,51 +624,62 @@ func selectedDigest(entries map[string]string, paths []string) string { return "sha256:" + hex.EncodeToString(hash.Sum(nil)) } -func verifyTree(ctx context.Context, repo gitx.Repo, environment []string, tree string, commands []VerifyCommand, defaultTimeout time.Duration) error { +// SelectedIndexDigest returns a stable digest for entries covered by paths. +// Callers use it to bind a reviewed plan to the exact staged index content. +func SelectedIndexDigest(entries map[string]string, paths []string) string { + return selectedDigest(entries, paths) +} + +func skippedExecutionCount(planned int) ExecutionCount { + return ExecutionCount{Planned: planned, Executed: 0, Skipped: planned} +} + +func verifyTree(ctx context.Context, repo gitx.Repo, environment []string, tree string, commands []VerifyCommand, defaultTimeout time.Duration, execute bool) error { if len(commands) == 0 { return nil } - scratch, err := os.MkdirTemp("", "wip-verify-*") + paths, err := verifyMaterializationPaths(ctx, repo, environment, tree, commands, maxVerifyTreeEntries, maxVerifyTreeBytes) if err != nil { - return fail.Wrap("VERIFY_FAILED", err) - } - defer func() { _ = os.RemoveAll(scratch) }() - if _, err := repo.Text(ctx, environment, "checkout-index", "--all", "--force", "--prefix="+scratch+string(filepath.Separator)); err != nil { - return fail.Wrap("VERIFY_FAILED", err) + return err } - for index, command := range commands { - if len(command.Argv) == 0 || strings.TrimSpace(command.Argv[0]) == "" { - return fail.Errorf("INVALID_VERIFY_COMMAND", "verify command %d has no executable", index+1) - } - if len(command.Argv) > maxVerifyArguments { - return fail.Errorf("INVALID_VERIFY_COMMAND", "verify command %d exceeds %d arguments", index+1, maxVerifyArguments) - } - for _, argument := range command.Argv { - if strings.ContainsRune(argument, '\x00') { - return fail.Errorf("INVALID_VERIFY_COMMAND", "verify command %d contains a NUL argument", index+1) - } + scratch := "" + if execute { + createdScratch, err := os.MkdirTemp("", "wip-verify-*") + if err != nil { + return fail.Wrap("VERIFY_FAILED", err) + } + defer func() { _ = os.RemoveAll(createdScratch) }() + // macOS exposes /var as a symlink to /private/var. Resolve the scratch + // root once before comparing a resolved verification subdirectory to it. + // Otherwise an in-tree directory appears to escape whenever TMPDIR uses + // the /var spelling. The candidate directory is still resolved for every + // command, so a symlink inside the candidate cannot cross this root. + scratch, err = filepath.EvalSymlinks(createdScratch) + if err != nil { + return fail.Wrap("VERIFY_FAILED", err) } - if strings.ContainsRune(command.Directory, '\x00') { - return fail.Errorf("INVALID_VERIFY_COMMAND", "verify command %d directory contains NUL", index+1) + if err := checkoutVerifyPaths(ctx, repo, environment, scratch+string(filepath.Separator), paths); err != nil { + return err } + } + for index, command := range commands { directory := scratch if command.Directory != "" { - candidate := filepath.Clean(command.Directory) - if filepath.IsAbs(candidate) || candidate == ".." || strings.HasPrefix(candidate, ".."+string(filepath.Separator)) { - return fail.Errorf("INVALID_VERIFY_COMMAND", "verify command %d directory escapes the candidate tree", index+1) - } - resolved, resolveErr := filepath.EvalSymlinks(filepath.Join(scratch, candidate)) - if resolveErr != nil { - return fail.Errorf("INVALID_VERIFY_COMMAND", "verify command %d directory is unavailable", index+1) - } - relative, relativeErr := filepath.Rel(scratch, resolved) - if relativeErr != nil || relative == ".." || strings.HasPrefix(relative, ".."+string(filepath.Separator)) { - return fail.Errorf("INVALID_VERIFY_COMMAND", "verify command %d directory follows a symlink outside the candidate tree", index+1) + candidate := filepath.FromSlash(command.Directory) + if execute { + resolved, resolveErr := filepath.EvalSymlinks(filepath.Join(scratch, candidate)) + if resolveErr != nil { + return fail.Errorf("INVALID_VERIFY_COMMAND", "verify command %d directory is unavailable", index+1) + } + relative, relativeErr := filepath.Rel(scratch, resolved) + if relativeErr != nil || relative == ".." || strings.HasPrefix(relative, ".."+string(filepath.Separator)) { + return fail.Errorf("INVALID_VERIFY_COMMAND", "verify command %d directory follows a symlink outside the candidate tree", index+1) + } + directory = resolved } - directory = resolved } - if command.TimeoutMS < 0 || command.TimeoutMS > MaxVerifyTimeout.Milliseconds() { - return fail.Errorf("INVALID_VERIFY_COMMAND", "verify command %d timeout is outside the safety range", index+1) + if !execute { + continue } timeout := defaultTimeout if command.TimeoutMS > 0 { @@ -526,15 +708,143 @@ func verifyTree(ctx context.Context, repo gitx.Repo, environment []string, tree return nil } +func verifyMaterializationPaths(ctx context.Context, repo gitx.Repo, environment []string, tree string, commands []VerifyCommand, maxEntries int, maxBytes int64) ([]string, error) { + fullTree := false + scopeSet := map[string]bool{} + for index, command := range commands { + if command.Directory == "." { + fullTree = true + } else if command.Directory != "" { + kind, kindErr := repo.Text(ctx, environment, "cat-file", "-t", tree+":"+command.Directory) + if kindErr != nil || kind != "tree" { + return nil, fail.Errorf("INVALID_VERIFY_COMMAND", "verify command %d directory is unavailable in the candidate tree", index+1) + } + scopeSet[command.Directory] = true + } else if len(command.Materialize) == 0 { + fullTree = true + } + for _, scope := range command.Materialize { + scopeSet[scope] = true + } + } + scopes := make([]string, 0, len(scopeSet)) + for scope := range scopeSet { + scopes = append(scopes, scope) + } + sort.Strings(scopes) + + arguments := []string{"ls-tree", "-r", "-l", "-z", "--full-tree", tree} + if !fullTree { + arguments = append(arguments, "--") + for _, scope := range scopes { + arguments = append(arguments, ":(top,literal)"+scope) + } + } + listing := &boundedBuffer{limit: maxVerifyListing} + errorsOutput := &boundedBuffer{limit: maxVerifyOutput} + command := process.CommandContext(ctx, "git", append([]string{"-C", repo.Root}, arguments...)...) + command.Env = gitx.Environment(environment) + command.Stdout, command.Stderr = listing, errorsOutput + if runErr := command.Run(); runErr != nil { + return nil, fail.Errorf("VERIFY_FAILED", "list candidate tree: %s", strings.TrimSpace(errorsOutput.String())) + } + if listing.Truncated() { + return nil, fail.Errorf("VERIFY_MATERIALIZATION_LIMIT", "candidate tree listing exceeds %d bytes", maxVerifyListing) + } + paths, _, parseErr := parseVerifyTreeListing(listing.String(), maxEntries, maxBytes) + if parseErr != nil { + return nil, parseErr + } + if !fullTree { + for _, scope := range scopes { + matched := false + for _, path := range paths { + if path == scope || strings.HasPrefix(path, scope+"/") { + matched = true + break + } + } + if !matched { + return nil, fail.Errorf("INVALID_VERIFY_COMMAND", "materialization scope %q is unavailable in the candidate tree", scope) + } + } + } + return paths, nil +} + +func parseVerifyTreeListing(listing string, maxEntries int, maxBytes int64) ([]string, int64, error) { + paths := make([]string, 0) + seen := map[string]bool{} + var totalBytes int64 + for _, row := range strings.Split(listing, "\x00") { + if row == "" { + continue + } + metadata, path, found := strings.Cut(row, "\t") + fields := strings.Fields(metadata) + if !found || len(fields) != 4 || path == "" { + return nil, 0, fail.New("VERIFY_FAILED", "candidate tree listing is malformed") + } + if seen[path] { + continue + } + size := int64(0) + if fields[3] != "-" { + parsed, err := strconv.ParseInt(fields[3], 10, 64) + if err != nil || parsed < 0 { + return nil, 0, fail.New("VERIFY_FAILED", "candidate tree listing has an invalid object size") + } + size = parsed + } + if len(paths) >= maxEntries { + return nil, 0, fail.Errorf("VERIFY_MATERIALIZATION_LIMIT", "candidate tree exceeds %d materialized entries", maxEntries) + } + if size > maxBytes-totalBytes { + return nil, 0, fail.Errorf("VERIFY_MATERIALIZATION_LIMIT", "candidate tree exceeds %d materialized bytes", maxBytes) + } + seen[path] = true + paths = append(paths, path) + totalBytes += size + } + sort.Strings(paths) + return paths, totalBytes, nil +} + +func checkoutVerifyPaths(ctx context.Context, repo gitx.Repo, environment []string, prefix string, paths []string) error { + var input bytes.Buffer + for _, path := range paths { + _, _ = input.WriteString(path) + _ = input.WriteByte(0) + } + errorsOutput := &boundedBuffer{limit: maxVerifyOutput} + // Verification must see the candidate's committed bytes. A host-level + // core.autocrlf (the Windows default) would otherwise rewrite line endings. + command := process.CommandContext(ctx, "git", "-C", repo.Root, "-c", "core.autocrlf=false", "-c", "core.eol=lf", "checkout-index", "--force", "--stdin", "-z", "--prefix="+prefix) + command.Env = gitx.Environment(environment) + command.Stdin = &input + command.Stderr = errorsOutput + if err := command.Run(); err != nil { + detail := strings.TrimSpace(errorsOutput.String()) + if detail == "" { + detail = err.Error() + } + return fail.Errorf("VERIFY_FAILED", "materialize candidate tree: %s", detail) + } + return nil +} + func verificationEnvironment(tree string) []string { blocked := map[string]bool{ - "GIT_INDEX_FILE": true, - "WIP_AGENT": true, - "WIP_CANDIDATE_TREE": true, - "WIP_COMMIT_OBJECT": true, - "WIP_LANE": true, - "WIP_SESSION": true, - "WIP_TARGET_REF": true, + "GIT_INDEX_FILE": true, + "WIP_AGENT": true, + "WIP_CAPTURE": true, + "WIP_CANDIDATE_TREE": true, + "WIP_COMMIT_OBJECT": true, + "WIP_HOOK_PHASE": true, + "WIP_LANE": true, + "WIP_SESSION": true, + "WIP_SOURCE_READ_ONLY": true, + "WIP_TARGET_REF": true, } inherited := gitx.Environment(nil) environment := make([]string, 0, len(inherited)+1) @@ -548,9 +858,10 @@ func verificationEnvironment(tree string) []string { } type boundedBuffer struct { - mu sync.Mutex - buffer bytes.Buffer - limit int + mu sync.Mutex + buffer bytes.Buffer + limit int + truncated bool } func (buffer *boundedBuffer) Write(value []byte) (int, error) { @@ -560,13 +871,22 @@ func (buffer *boundedBuffer) Write(value []byte) (int, error) { remaining := buffer.limit - buffer.buffer.Len() if remaining > 0 { if len(value) > remaining { + buffer.truncated = true value = value[:remaining] } _, _ = buffer.buffer.Write(value) + } else if len(value) > 0 { + buffer.truncated = true } return original, nil } +func (buffer *boundedBuffer) Truncated() bool { + buffer.mu.Lock() + defer buffer.mu.Unlock() + return buffer.truncated +} + func (buffer *boundedBuffer) String() string { buffer.mu.Lock() defer buffer.mu.Unlock() diff --git a/internal/engine/plan_test.go b/internal/engine/plan_test.go index f0405b0..b9f0a19 100644 --- a/internal/engine/plan_test.go +++ b/internal/engine/plan_test.go @@ -17,6 +17,7 @@ import ( "github.com/nstranquist/wip-commit/internal/fail" "github.com/nstranquist/wip-commit/internal/gitx" + "github.com/nstranquist/wip-commit/internal/policy" ) func TestRunSplitPlanPreservesHeadAndFullIndex(t *testing.T) { @@ -67,6 +68,68 @@ func TestRunSplitPlanPreservesHeadAndFullIndex(t *testing.T) { } } +func TestRunEnforcesSafetyButDoesNotOwnRepositoryNamingPolicy(t *testing.T) { + repo := engineTestRepo(t) + write(t, repo.Root, "core.txt", "new core\n") + engineGit(t, repo.Root, "add", "core.txt") + head := engineGit(t, repo.Root, "rev-parse", "HEAD") + target := "refs/heads/wip/agent/policy-boundary" + engineGit(t, repo.Root, "update-ref", target, head, "") + receipt := policy.Default() + entries, err := repo.IndexEntries(context.Background(), nil) + if err != nil { + t.Fatal(err) + } + result, err := Run(context.Background(), Options{ + Repo: repo, TargetRef: target, ExpectedRef: head, ExpectedSourceHead: head, + AllowedPaths: []string{"core.txt"}, + Groups: []Group{{Message: "plain repository checkpoint", Files: []string{"core.txt"}}}, + ReviewPlanDigest: "sha256:" + strings.Repeat("a", 64), + ExpectedSourceDigest: SelectedIndexDigest(entries, []string{"core.txt"}), + MessagePolicy: receipt, + }) + if err != nil { + t.Fatalf("capture kernel applied repository naming policy: %v", err) + } + if result.MessagePolicy == nil || *result.MessagePolicy != receipt || result.ReviewPlanDigest == "" { + t.Fatalf("policy binding evidence = %#v", result) + } +} + +func TestRunRejectsReviewedIndexMismatchBeforeHooks(t *testing.T) { + if runtime.GOOS == "windows" { + t.Skip("fixture uses a POSIX hook") + } + repo := engineTestRepo(t) + write(t, repo.Root, "core.txt", "new core\n") + engineGit(t, repo.Root, "add", "core.txt") + head := engineGit(t, repo.Root, "rev-parse", "HEAD") + target := "refs/heads/wip/agent/reviewed-index" + engineGit(t, repo.Root, "update-ref", target, head, "") + marker := filepath.Join(repo.Root, "hook-ran") + hook := filepath.Join(repo.GitDir, "hooks", "pre-commit") + if err := os.WriteFile(hook, []byte("#!/bin/sh\n: > hook-ran\n"), 0o700); err != nil { + t.Fatal(err) + } + result, err := Run(context.Background(), Options{ + Repo: repo, TargetRef: target, ExpectedRef: head, ExpectedSourceHead: head, + AllowedPaths: []string{"core.txt"}, + Groups: []Group{{Message: "plain repository checkpoint", Files: []string{"core.txt"}}}, + ReviewPlanDigest: "sha256:" + strings.Repeat("a", 64), + ExpectedSourceDigest: "sha256:" + strings.Repeat("b", 64), + MessagePolicy: policy.Default(), + }) + if fail.Code(err) != "SOURCE_MOVED" { + t.Fatalf("index mismatch error = %v (%s)", err, fail.Code(err)) + } + if result.RefUpdated { + t.Fatalf("index mismatch published a ref: %#v", result) + } + if _, statErr := os.Stat(marker); !errors.Is(statErr, os.ErrNotExist) { + t.Fatalf("pre-commit hook ran before the reviewed index check: %v", statErr) + } +} + func TestDryRunDoesNotInventSplitParentCommits(t *testing.T) { repo := engineTestRepo(t) write(t, repo.Root, "core.txt", "new core\n") @@ -95,6 +158,9 @@ func TestDryRunDoesNotInventSplitParentCommits(t *testing.T) { if result.Commits[0].Commit != "" || result.Commits[1].Commit != "" || result.RefUpdated { t.Fatalf("dry-run published commit evidence: %#v", result) } + if result.SchemaVersion != ResultSchemaVersion || result.GateOutcome != "skipped" || result.Execution == nil || result.Execution.Policy != "no-exec" { + t.Fatalf("dry-run contract = %#v", result) + } if got := engineGit(t, repo.Root, "rev-parse", target); got != head { t.Fatalf("dry-run moved ref: %s -> %s", head, got) } @@ -103,15 +169,134 @@ func TestDryRunDoesNotInventSplitParentCommits(t *testing.T) { } } +func TestDryRunSkipsVerifyCommandsAndBeforePublish(t *testing.T) { + repo := engineTestRepo(t) + write(t, repo.Root, "core.txt", "new core\n") + engineGit(t, repo.Root, "add", "core.txt") + head := engineGit(t, repo.Root, "rev-parse", "HEAD") + target := "refs/heads/wip/agent/dry-run-no-exec" + engineGit(t, repo.Root, "update-ref", target, head, "") + verifyMarker := filepath.Join(t.TempDir(), "verify-ran") + publishMarker := filepath.Join(t.TempDir(), "before-publish-ran") + t.Setenv("WIP_DRY_RUN_VERIFY_MARKER", verifyMarker) + + result, err := Run(context.Background(), Options{ + Repo: repo, TargetRef: target, ExpectedRef: head, ExpectedSourceHead: head, + AllowedPaths: []string{"core.txt"}, + Groups: []Group{{ + Message: "fix(core): prove no-exec preview", Files: []string{"core.txt"}, + Verify: []VerifyCommand{{Argv: []string{os.Args[0], "-test.run=^TestEngineDryRunVerifyMarkerHelper$", "-test.count=1"}}}, + }}, + DryRun: true, + BeforePublish: func() error { + return os.WriteFile(publishMarker, []byte("callback ran\n"), 0o600) + }, + }) + if err != nil { + t.Fatal(err) + } + if result.GateOutcome != "skipped" || result.Execution == nil || result.Execution.Policy != "no-exec" { + t.Fatalf("dry-run result = %#v", result) + } + wantVerify := ExecutionCount{Planned: 1, Executed: 0, Skipped: 1} + if result.Execution.VerifyCommands != wantVerify { + t.Fatalf("verify execution report = %#v, want %#v", result.Execution.VerifyCommands, wantVerify) + } + for _, marker := range []string{verifyMarker, publishMarker} { + if _, statErr := os.Lstat(marker); !errors.Is(statErr, os.ErrNotExist) { + t.Fatalf("dry-run executed marker %s: %v", marker, statErr) + } + } +} + +func TestEngineDryRunVerifyMarkerHelper(t *testing.T) { + marker := os.Getenv("WIP_DRY_RUN_VERIFY_MARKER") + if marker == "" { + return + } + if err := os.WriteFile(marker, []byte("verify ran\n"), 0o600); err != nil { + t.Fatal(err) + } +} + +func TestDryRunSkipsExecutableRepositoryHooks(t *testing.T) { + if runtime.GOOS == "windows" { + t.Skip("fixture uses POSIX hooks; hosted Windows tests cover the no-exec verify path") + } + repo := engineTestRepo(t) + preMarker := filepath.Join(t.TempDir(), "pre-commit-ran") + postMarker := filepath.Join(t.TempDir(), "post-commit-ran") + t.Setenv("WIP_DRY_RUN_PRE_HOOK_MARKER", preMarker) + t.Setenv("WIP_DRY_RUN_POST_HOOK_MARKER", postMarker) + for name, body := range map[string]string{ + "pre-commit": "#!/bin/sh\n: > \"$WIP_DRY_RUN_PRE_HOOK_MARKER\"\n", + "post-commit": "#!/bin/sh\n: > \"$WIP_DRY_RUN_POST_HOOK_MARKER\"\n", + } { + hook := engineGit(t, repo.Root, "rev-parse", "--git-path", "hooks/"+name) + if !filepath.IsAbs(hook) { + hook = filepath.Join(repo.Root, hook) + } + if err := os.WriteFile(hook, []byte(body), 0o700); err != nil { + t.Fatal(err) + } + } + write(t, repo.Root, "core.txt", "new core\n") + engineGit(t, repo.Root, "add", "core.txt") + head := engineGit(t, repo.Root, "rev-parse", "HEAD") + target := "refs/heads/wip/agent/dry-run-hooks" + engineGit(t, repo.Root, "update-ref", target, head, "") + + result, err := Run(context.Background(), Options{ + Repo: repo, TargetRef: target, ExpectedRef: head, ExpectedSourceHead: head, + AllowedPaths: []string{"core.txt"}, Groups: []Group{{Message: "fix(hooks): prove no-exec preview", Files: []string{"core.txt"}}}, DryRun: true, + }) + if err != nil { + t.Fatal(err) + } + wantHook := ExecutionCount{Planned: 1, Executed: 0, Skipped: 1} + if result.Execution == nil || result.Execution.PreCommitHooks != wantHook || result.Execution.PostCommitHooks != wantHook { + t.Fatalf("hook execution report = %#v", result.Execution) + } + for _, marker := range []string{preMarker, postMarker} { + if _, statErr := os.Lstat(marker); !errors.Is(statErr, os.ErrNotExist) { + t.Fatalf("dry-run executed hook marker %s: %v", marker, statErr) + } + } +} + +func TestHookEnvironmentForcesReadOnlyPreflightMarker(t *testing.T) { + t.Setenv(preflightReadOnly, "inherited-unsafe-value") + environment := hookEnvironment([]string{ + "GIT_INDEX_FILE=/private/index", + preflightReadOnly + "=private-unsafe-value", + }, hookPhasePreCommit, "refs/heads/wip/agent/read-only-hook", "commit-object") + + markerCount := 0 + markerValue := "" + for _, entry := range environment { + name, value, _ := strings.Cut(entry, "=") + if strings.EqualFold(name, preflightReadOnly) { + markerCount++ + markerValue = value + } + } + if markerCount != 1 || markerValue != "1" { + t.Fatalf("%s entries = %d, value = %q", preflightReadOnly, markerCount, markerValue) + } +} + func TestVerificationEnvironmentDoesNotInheritCaptureIdentity(t *testing.T) { for name, value := range map[string]string{ - "GIT_INDEX_FILE": "/foreign/index", - "WIP_AGENT": "foreign-agent", - "WIP_CANDIDATE_TREE": "foreign-tree", - "WIP_COMMIT_OBJECT": "foreign-commit", - "WIP_LANE": "foreign-lane", - "WIP_SESSION": "foreign-session", - "WIP_TARGET_REF": "refs/heads/wip/foreign/lane", + "GIT_INDEX_FILE": "/foreign/index", + "WIP_AGENT": "foreign-agent", + "WIP_CAPTURE": "1", + "WIP_CANDIDATE_TREE": "foreign-tree", + "WIP_COMMIT_OBJECT": "foreign-commit", + "WIP_HOOK_PHASE": "pre-commit", + "WIP_LANE": "foreign-lane", + "WIP_SESSION": "foreign-session", + "WIP_SOURCE_READ_ONLY": "1", + "WIP_TARGET_REF": "refs/heads/wip/foreign/lane", } { t.Setenv(name, value) } @@ -121,7 +306,7 @@ func TestVerificationEnvironmentDoesNotInheritCaptureIdentity(t *testing.T) { name, value, _ := strings.Cut(entry, "=") values[strings.ToUpper(name)] = value } - for _, name := range []string{"GIT_INDEX_FILE", "WIP_AGENT", "WIP_COMMIT_OBJECT", "WIP_LANE", "WIP_SESSION", "WIP_TARGET_REF"} { + for _, name := range []string{"GIT_INDEX_FILE", "WIP_AGENT", "WIP_CAPTURE", "WIP_COMMIT_OBJECT", "WIP_HOOK_PHASE", "WIP_LANE", "WIP_SESSION", "WIP_SOURCE_READ_ONLY", "WIP_TARGET_REF"} { if _, exists := values[name]; exists { t.Fatalf("verification inherited %s", name) } @@ -131,6 +316,55 @@ func TestVerificationEnvironmentDoesNotInheritCaptureIdentity(t *testing.T) { } } +func TestHookEnvironmentOverridesSpoofedCaptureContract(t *testing.T) { + private := []string{ + "GIT_INDEX_FILE=/private/index", + "WIP_CAPTURE=0", + "wip_hook_phase=foreign", + "WIP_SOURCE_READ_ONLY=0", + "WIP_TARGET_REF=refs/heads/wip/foreign/lane", + "WIP_COMMIT_OBJECT=foreign", + } + pre := hookEnvironment(private, hookPhasePreCommit, "refs/heads/wip/agent/lane", "") + assertExactEnvironmentValue(t, pre, "WIP_CAPTURE", "1") + assertExactEnvironmentValue(t, pre, "WIP_HOOK_PHASE", hookPhasePreCommit) + assertExactEnvironmentValue(t, pre, "WIP_SOURCE_READ_ONLY", "1") + assertExactEnvironmentValue(t, pre, "WIP_TARGET_REF", "refs/heads/wip/agent/lane") + assertEnvironmentAbsent(t, pre, "WIP_COMMIT_OBJECT") + assertExactEnvironmentValue(t, pre, "GIT_INDEX_FILE", "/private/index") + + post := hookEnvironment(private, hookPhasePostCommit, "refs/heads/wip/agent/lane", "abc123") + assertExactEnvironmentValue(t, post, "WIP_HOOK_PHASE", hookPhasePostCommit) + assertExactEnvironmentValue(t, post, "WIP_COMMIT_OBJECT", "abc123") +} + +func assertExactEnvironmentValue(t *testing.T, environment []string, name, want string) { + t.Helper() + count := 0 + for _, entry := range environment { + key, value, _ := strings.Cut(entry, "=") + if strings.EqualFold(key, name) { + count++ + if value != want { + t.Fatalf("%s = %q, want %q in %q", name, value, want, environment) + } + } + } + if count != 1 { + t.Fatalf("%s occurs %d times, want exactly once in %q", name, count, environment) + } +} + +func assertEnvironmentAbsent(t *testing.T, environment []string, name string) { + t.Helper() + for _, entry := range environment { + key, _, _ := strings.Cut(entry, "=") + if strings.EqualFold(key, name) { + t.Fatalf("%s survived in %q", name, environment) + } + } +} + func TestOversizedIntentFailsBeforeRefPublication(t *testing.T) { repo := engineTestRepo(t) head := engineGit(t, repo.Root, "rev-parse", "HEAD") @@ -141,14 +375,14 @@ func TestOversizedIntentFailsBeforeRefPublication(t *testing.T) { paths[index] = fmt.Sprintf("generated/%04d/%080d.txt", index, index) } result := Result{ - TargetRef: target, - ExpectedRef: head, - FinalCommit: strings.Repeat("b", len(head)), - SourceHead: head, - SourceIndexDigest: "sha256:" + strings.Repeat("c", 64), - FinalTree: strings.Repeat("d", len(head)), - HookDigest: "sha256:" + strings.Repeat("e", 64), - RequestedPaths: paths, + TargetRef: target, + ExpectedRef: head, + FinalCommit: strings.Repeat("b", len(head)), + SourceHead: head, + SourceDigest: "sha256:" + strings.Repeat("c", 64), + FinalTree: strings.Repeat("d", len(head)), + HookDigest: "sha256:" + strings.Repeat("e", 64), + RequestedPaths: paths, Commits: []PlannedCommit{{ Index: 1, Message: "feat(records): exercise bounded intent", Parent: head, Commit: strings.Repeat("b", len(head)), Tree: strings.Repeat("d", len(head)), ChangedPaths: paths, @@ -223,6 +457,87 @@ func TestRunIsAtomicWhenLateVerifyFails(t *testing.T) { } } +func TestVerifyMaterializesOnlyDeclaredCandidateScopes(t *testing.T) { + repo := engineTestRepo(t) + write(t, repo.Root, "component/core.txt", "base component\n") + write(t, repo.Root, "shared/dependency.txt", "declared dependency\n") + write(t, repo.Root, "unrelated.txt", "must stay unavailable\n") + engineGit(t, repo.Root, "add", "component/core.txt", "shared/dependency.txt", "unrelated.txt") + engineGit(t, repo.Root, "commit", "-m", "test: add scoped verification fixture") + head := engineGit(t, repo.Root, "rev-parse", "HEAD") + write(t, repo.Root, "component/core.txt", "candidate component\n") + engineGit(t, repo.Root, "add", "component/core.txt") + target := "refs/heads/wip/agent/scoped-verify" + engineGit(t, repo.Root, "update-ref", target, head, "") + t.Setenv("WIP_TEST_SCOPED_VERIFY", "1") + + result, err := Run(context.Background(), Options{ + Repo: repo, TargetRef: target, ExpectedRef: head, ExpectedSourceHead: head, + AllowedPaths: []string{"component/core.txt"}, + Groups: []Group{{ + Message: "test(verify): materialize reviewed scopes", + Files: []string{"component/core.txt"}, + Verify: []VerifyCommand{{ + Argv: []string{os.Args[0], "-test.run=^TestScopedVerifyMaterializationHelper$", "-test.count=1"}, + Directory: "component", + Materialize: []string{"shared/dependency.txt"}, + }}, + }}, + }) + if err != nil { + t.Fatal(err) + } + if !result.RefUpdated { + t.Fatalf("scoped verification did not publish: %#v", result) + } +} + +func TestScopedVerifyMaterializationHelper(t *testing.T) { + if os.Getenv("WIP_TEST_SCOPED_VERIFY") != "1" { + return + } + for path, want := range map[string]string{ + "core.txt": "candidate component\n", + "../shared/dependency.txt": "declared dependency\n", + } { + body, err := os.ReadFile(path) + if err != nil || string(body) != want { + t.Fatalf("materialized %s = %q, %v; want %q", path, body, err, want) + } + } + if _, err := os.Lstat("../unrelated.txt"); !errors.Is(err, os.ErrNotExist) { + t.Fatalf("unrelated candidate path became visible: %v", err) + } +} + +func TestVerifyMaterializationLimitsFailClosed(t *testing.T) { + listing := "100644 blob aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa 4\tone.txt\x00" + + "100644 blob bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb 5\ttwo.txt\x00" + if _, _, err := parseVerifyTreeListing(listing, 1, 100); fail.Code(err) != "VERIFY_MATERIALIZATION_LIMIT" { + t.Fatalf("entry limit error = %v (%s)", err, fail.Code(err)) + } + if _, _, err := parseVerifyTreeListing(listing, 10, 3); fail.Code(err) != "VERIFY_MATERIALIZATION_LIMIT" { + t.Fatalf("byte limit error = %v (%s)", err, fail.Code(err)) + } + if _, _, err := parseVerifyTreeListing("malformed\x00", 10, 100); fail.Code(err) != "VERIFY_FAILED" { + t.Fatalf("malformed listing error = %v (%s)", err, fail.Code(err)) + } +} + +func TestVerifyMaterializationScopesMustBeCanonical(t *testing.T) { + repo := engineTestRepo(t) + for _, scope := range []string{"../outside", "component/../core.txt", "component\\core.txt", ".git/config", "."} { + _, err := normalizeVerifyCommand(repo, VerifyCommand{Argv: []string{"git", "--version"}, Materialize: []string{scope}}, 0) + if err == nil { + t.Errorf("invalid materialization scope %q passed", scope) + } + } + _, err := normalizeVerifyCommand(repo, VerifyCommand{Argv: []string{"git", "--version"}, Materialize: []string{"core.txt", "core.txt"}}, 0) + if err == nil { + t.Fatal("duplicate materialization scope passed") + } +} + func TestRunDetectsSelectedIndexMovementAfterFinalGate(t *testing.T) { repo := engineTestRepo(t) write(t, repo.Root, "core.txt", "first staged value\n") @@ -239,7 +554,7 @@ func TestRunDetectsSelectedIndexMovementAfterFinalGate(t *testing.T) { return nil }, }) - if fail.Code(err) != "SOURCE_INDEX_MOVED" { + if fail.Code(err) != "SOURCE_MOVED" { t.Fatalf("error = %v (%s)", err, fail.Code(err)) } if got := engineGit(t, repo.Root, "rev-parse", target); got != head { @@ -291,6 +606,44 @@ func TestRunHandlesNewlineFilename(t *testing.T) { } } +func TestVerifyDirectoryAllowsSymlinkedScratchParent(t *testing.T) { + if runtime.GOOS == "windows" { + t.Skip("symlink creation requires platform-specific privileges") + } + repo := engineTestRepo(t) + write(t, repo.Root, "component/core.txt", "new core\n") + engineGit(t, repo.Root, "add", "component/core.txt") + head := engineGit(t, repo.Root, "rev-parse", "HEAD") + target := "refs/heads/wip/agent/symlinked-temp-root" + engineGit(t, repo.Root, "update-ref", target, head, "") + + realTempRoot, err := filepath.EvalSymlinks(t.TempDir()) + if err != nil { + t.Fatal(err) + } + tempLink := filepath.Join(t.TempDir(), "tmp-link") + if err := os.Symlink(realTempRoot, tempLink); err != nil { + t.Fatal(err) + } + t.Setenv("TMPDIR", tempLink) + + result, err := Run(context.Background(), Options{ + Repo: repo, TargetRef: target, ExpectedRef: head, ExpectedSourceHead: head, + AllowedPaths: []string{"component/core.txt"}, + Groups: []Group{{ + Message: "test(verify): allow physical candidate directory", + Files: []string{"component/core.txt"}, + Verify: []VerifyCommand{{Argv: []string{"git", "--version"}, Directory: "component"}}, + }}, + }) + if err != nil { + t.Fatal(err) + } + if !result.RefUpdated || engineGit(t, repo.Root, "rev-parse", target) != result.FinalCommit { + t.Fatalf("verification did not publish the candidate: %#v", result) + } +} + func TestVerifyDirectoryCannotFollowSymlinkOutsideCandidate(t *testing.T) { if runtime.GOOS == "windows" { t.Skip("symlink creation requires platform-specific privileges") @@ -476,6 +829,12 @@ func TestValidateAppliedChecksGitObjectsAgainstReceipt(t *testing.T) { if _, clean, err := ValidateApplied(context.Background(), repo, result.PlanID, result.PlanDigest, target, head); err != nil || clean { t.Fatalf("valid applied receipt clean=%v err=%v", clean, err) } + if _, err := MarkIntent(repo, result.PlanID, result.PlanDigest, "complete"); err != nil { + t.Fatal(err) + } + if _, clean, err := ValidateApplied(context.Background(), repo, result.PlanID, result.PlanDigest, target, result.FinalCommit); err != nil || !clean { + t.Fatalf("valid complete receipt clean=%v err=%v", clean, err) + } intent, path, err := LoadIntent(repo, result.PlanID, result.PlanDigest) if err != nil { @@ -493,7 +852,7 @@ func TestValidateAppliedChecksGitObjectsAgainstReceipt(t *testing.T) { if err := os.WriteFile(path, append(body, '\n'), 0o600); err != nil { t.Fatal(err) } - if _, _, err := ValidateApplied(context.Background(), repo, result.PlanID, intent.PlanDigest, target, head); fail.Code(err) != "CAPTURE_RECEIPT_MISMATCH" { + if _, _, err := ValidateApplied(context.Background(), repo, result.PlanID, intent.PlanDigest, target, result.FinalCommit); fail.Code(err) != "CAPTURE_RECEIPT_MISMATCH" { t.Fatalf("mismatched %s receipt error = %v (%s)", test.name, err, fail.Code(err)) } }) @@ -600,6 +959,50 @@ func TestHookSnapshotMovementFailsBeforeRefUpdate(t *testing.T) { } } +func TestCopiedHooksReceiveReadOnlyPreflightMarker(t *testing.T) { + if runtime.GOOS == "windows" { + t.Skip("fixture uses POSIX hooks") + } + t.Setenv(preflightReadOnly, "0") + repo := engineTestRepo(t) + for name, body := range map[string]string{ + "pre-commit": "#!/bin/sh\ntest \"$NICOS_PREFLIGHT_READ_ONLY\" = 1\n", + "post-commit": "#!/bin/sh\nprintf '%s\\n' \"$NICOS_PREFLIGHT_READ_ONLY\" > hook-read-only-marker\n", + } { + hook := engineGit(t, repo.Root, "rev-parse", "--git-path", "hooks/"+name) + if !filepath.IsAbs(hook) { + hook = filepath.Join(repo.Root, hook) + } + if err := os.WriteFile(hook, []byte(body), 0o700); err != nil { + t.Fatal(err) + } + } + write(t, repo.Root, "core.txt", "new core\n") + engineGit(t, repo.Root, "add", "core.txt") + head := engineGit(t, repo.Root, "rev-parse", "HEAD") + target := "refs/heads/wip/agent/read-only-hook" + engineGit(t, repo.Root, "update-ref", target, head, "") + + result, err := Run(context.Background(), Options{ + Repo: repo, TargetRef: target, ExpectedRef: head, ExpectedSourceHead: head, + AllowedPaths: []string{"core.txt"}, + Groups: []Group{{Message: "fix(hooks): force read-only preflight mode", Files: []string{"core.txt"}}}, + }) + if err != nil { + t.Fatal(err) + } + if !result.RefUpdated { + t.Fatalf("capture did not publish its lane ref: %#v", result) + } + marker, err := os.ReadFile(filepath.Join(repo.Root, "hook-read-only-marker")) + if err != nil { + t.Fatal(err) + } + if string(marker) != "1\n" { + t.Fatalf("post-commit %s = %q", preflightReadOnly, marker) + } +} + func TestPostHookSeesEachCommitPrivateTree(t *testing.T) { if runtime.GOOS == "windows" { t.Skip("fixture uses a POSIX hook") diff --git a/internal/engine/source.go b/internal/engine/source.go new file mode 100644 index 0000000..b5abafc --- /dev/null +++ b/internal/engine/source.go @@ -0,0 +1,258 @@ +package engine + +import ( + "context" + "errors" + "os" + "path/filepath" + "sort" + "strings" + + "github.com/nstranquist/wip-commit/internal/fail" + "github.com/nstranquist/wip-commit/internal/gitx" + "github.com/nstranquist/wip-commit/internal/pathid" +) + +type SourceMode string + +const ( + SourceStagedIndex SourceMode = "staged_index" + SourceWorktree SourceMode = "worktree_snapshot" +) + +type UntrackedPolicy string + +const ( + UntrackedNotApplicable UntrackedPolicy = "not_applicable" + UntrackedForbid UntrackedPolicy = "forbid" + UntrackedInclude UntrackedPolicy = "include" +) + +type SourceSnapshot struct { + Mode SourceMode + UntrackedPolicy UntrackedPolicy + BaseCommit string + Paths []string + Entries map[string]string + Digest string +} + +func NormalizeSource(mode SourceMode, untracked UntrackedPolicy) (SourceMode, UntrackedPolicy, error) { + if mode == "" { + mode = SourceStagedIndex + } + switch mode { + case SourceStagedIndex: + if untracked == "" { + untracked = UntrackedNotApplicable + } + if untracked != UntrackedNotApplicable { + return "", "", fail.New("INVALID_SOURCE_POLICY", "staged-index capture requires untracked policy not_applicable") + } + case SourceWorktree: + if untracked == "" { + untracked = UntrackedForbid + } + if untracked != UntrackedForbid && untracked != UntrackedInclude { + return "", "", fail.New("INVALID_SOURCE_POLICY", "worktree snapshot requires untracked policy forbid or include") + } + default: + return "", "", fail.Errorf("INVALID_SOURCE_POLICY", "unsupported source mode %q", mode) + } + return mode, untracked, nil +} + +// InspectSource returns an exact source projection without changing the caller +// index or the repository object database. Worktree blobs and trees are held +// in a temporary object directory that is removed before this function +// returns. +func InspectSource(ctx context.Context, repo gitx.Repo, baseCommit string, scopes []string, mode SourceMode, untracked UntrackedPolicy) (SourceSnapshot, error) { + mode, untracked, err := NormalizeSource(mode, untracked) + if err != nil { + return SourceSnapshot{}, err + } + scopes, err = repo.NormalizePaths(scopes) + if err != nil { + return SourceSnapshot{}, err + } + if len(scopes) == 0 { + return SourceSnapshot{}, fail.New("EMPTY_SELECTION", "source inspection requires at least one explicit path scope") + } + if mode == SourceStagedIndex { + paths, err := changedPaths(ctx, repo, nil, baseCommit, scopes, true) + if err != nil { + return SourceSnapshot{}, err + } + entries, err := repo.IndexEntries(ctx, nil) + if err != nil { + return SourceSnapshot{}, fail.Wrap("GIT_FAILED", err) + } + return newSourceSnapshot(mode, untracked, baseCommit, paths, entries), nil + } + + root, err := os.MkdirTemp("", "wip-source-inspect-*") + if err != nil { + return SourceSnapshot{}, fail.Wrap("SOURCE_SNAPSHOT_FAILED", err) + } + defer func() { _ = os.RemoveAll(root) }() + return snapshotWorktree(ctx, repo, baseCommit, scopes, untracked, root, true) +} + +func captureSource(ctx context.Context, repo gitx.Repo, baseCommit string, scopes []string, mode SourceMode, untracked UntrackedPolicy, privateRoot string, isolateObjects bool) (SourceSnapshot, func(), error) { + mode, untracked, err := NormalizeSource(mode, untracked) + if err != nil { + return SourceSnapshot{}, func() {}, err + } + if mode == SourceStagedIndex { + entries, err := repo.IndexEntries(ctx, nil) + if err != nil { + return SourceSnapshot{}, func() {}, fail.Wrap("GIT_FAILED", err) + } + return newSourceSnapshot(mode, untracked, baseCommit, scopes, entries), func() {}, nil + } + snapshot, indexPath, err := snapshotWorktreeAt(ctx, repo, baseCommit, scopes, untracked, privateRoot, isolateObjects) + if err != nil { + return SourceSnapshot{}, func() {}, err + } + return snapshot, func() { _ = os.Remove(indexPath) }, nil +} + +func snapshotWorktree(ctx context.Context, repo gitx.Repo, baseCommit string, scopes []string, untracked UntrackedPolicy, root string, isolateObjects bool) (SourceSnapshot, error) { + snapshot, indexPath, err := snapshotWorktreeAt(ctx, repo, baseCommit, scopes, untracked, root, isolateObjects) + if indexPath != "" { + _ = os.Remove(indexPath) + } + return snapshot, err +} + +func snapshotWorktreeAt(ctx context.Context, repo gitx.Repo, baseCommit string, scopes []string, untracked UntrackedPolicy, root string, isolateObjects bool) (SourceSnapshot, string, error) { + if _, err := repo.Text(ctx, nil, "rev-parse", "--verify", baseCommit+"^{commit}"); err != nil { + return SourceSnapshot{}, "", fail.Wrap("SOURCE_BASE_INVALID", err) + } + file, err := os.CreateTemp(root, "source-*.index") + if err != nil { + return SourceSnapshot{}, "", fail.Wrap("SOURCE_SNAPSHOT_FAILED", err) + } + indexPath := file.Name() + if err := file.Close(); err != nil { + _ = os.Remove(indexPath) + return SourceSnapshot{}, "", fail.Wrap("SOURCE_SNAPSHOT_FAILED", err) + } + if err := os.Remove(indexPath); err != nil { + return SourceSnapshot{}, "", fail.Wrap("SOURCE_SNAPSHOT_FAILED", err) + } + environment := []string{"GIT_INDEX_FILE=" + indexPath} + if isolateObjects { + objectEnvironment, err := isolatedObjectEnvironment(repo, root) + if err != nil { + return SourceSnapshot{}, indexPath, err + } + environment = append(environment, objectEnvironment...) + } + if _, err := repo.Text(ctx, environment, "read-tree", baseCommit); err != nil { + return SourceSnapshot{}, indexPath, fail.Wrap("SOURCE_SNAPSHOT_FAILED", err) + } + tracked, err := changedPaths(ctx, repo, environment, baseCommit, scopes, false) + if err != nil { + return SourceSnapshot{}, indexPath, err + } + untrackedPaths, err := repo.NULPaths(ctx, environment, "ls-files", "--others", "--exclude-standard", "-z", "--") + if err != nil { + return SourceSnapshot{}, indexPath, fail.Wrap("SOURCE_SNAPSHOT_FAILED", err) + } + untrackedPaths = coveredPaths(untrackedPaths, scopes) + if len(untrackedPaths) > 0 && untracked == UntrackedForbid { + return SourceSnapshot{}, indexPath, fail.Errorf("UNTRACKED_PATH_FORBIDDEN", "worktree source contains %d untracked path(s) in the selected scope; review and use untracked policy include to capture them", len(untrackedPaths)) + } + paths := canonicalSourcePaths(tracked, untrackedPaths) + if len(paths) == 0 { + return newSourceSnapshot(SourceWorktree, untracked, baseCommit, nil, map[string]string{}), indexPath, nil + } + // Git can reject an exact tracked file when one of its parent directories + // is ignored. Update base-tracked entries separately so ignore rules cannot + // hide them. Add only the already-enumerated untracked files with --force; + // this never expands an ignored directory or weakens the explicit include + // policy. + if len(tracked) > 0 { + args := append([]string{"add", "--update", "--"}, tracked...) + if _, err := repo.Text(ctx, environment, args...); err != nil { + return SourceSnapshot{}, indexPath, fail.Wrap("SOURCE_SNAPSHOT_FAILED", err) + } + } + if len(untrackedPaths) > 0 { + args := append([]string{"add", "--force", "--"}, untrackedPaths...) + if _, err := repo.Text(ctx, environment, args...); err != nil { + return SourceSnapshot{}, indexPath, fail.Wrap("SOURCE_SNAPSHOT_FAILED", err) + } + } + entries, err := repo.IndexEntries(ctx, environment) + if err != nil { + return SourceSnapshot{}, indexPath, fail.Wrap("SOURCE_SNAPSHOT_FAILED", err) + } + return newSourceSnapshot(SourceWorktree, untracked, baseCommit, paths, entries), indexPath, nil +} + +func isolatedObjectEnvironment(repo gitx.Repo, root string) ([]string, error) { + objectRoot := filepath.Join(root, "objects") + if err := os.Mkdir(objectRoot, 0o700); err != nil && !errors.Is(err, os.ErrExist) { + return nil, fail.Wrap("SOURCE_SNAPSHOT_FAILED", err) + } + return []string{ + "GIT_OBJECT_DIRECTORY=" + objectRoot, + "GIT_ALTERNATE_OBJECT_DIRECTORIES=" + filepath.Join(repo.CommonDir, "objects"), + }, nil +} + +func changedPaths(ctx context.Context, repo gitx.Repo, environment []string, baseCommit string, scopes []string, cached bool) ([]string, error) { + args := []string{"diff"} + if cached { + args = append(args, "--cached") + } + args = append(args, "--no-renames", "--name-only", "-z", baseCommit, "--") + paths, err := repo.NULPaths(ctx, environment, args...) + if err != nil { + return nil, fail.Wrap("SOURCE_SNAPSHOT_FAILED", err) + } + return coveredPaths(paths, scopes), nil +} + +func coveredPaths(paths, scopes []string) []string { + selected := make([]string, 0, len(paths)) + for _, path := range paths { + if pathid.Covered(path, scopes) { + selected = append(selected, path) + } + } + sort.Strings(selected) + return selected +} + +func canonicalSourcePaths(groups ...[]string) []string { + seen := map[string]bool{} + var paths []string + for _, group := range groups { + for _, path := range group { + if !seen[path] { + seen[path] = true + paths = append(paths, path) + } + } + } + sort.Strings(paths) + return paths +} + +func newSourceSnapshot(mode SourceMode, untracked UntrackedPolicy, baseCommit string, paths []string, entries map[string]string) SourceSnapshot { + paths = append([]string(nil), paths...) + sort.Strings(paths) + selected := make(map[string]string) + for path, entry := range entries { + if pathid.Covered(path, paths) { + selected[path] = entry + } + } + return SourceSnapshot{ + Mode: mode, UntrackedPolicy: untracked, BaseCommit: strings.TrimSpace(baseCommit), + Paths: paths, Entries: selected, Digest: selectedDigest(selected, paths), + } +} diff --git a/internal/engine/source_test.go b/internal/engine/source_test.go new file mode 100644 index 0000000..ca86a94 --- /dev/null +++ b/internal/engine/source_test.go @@ -0,0 +1,244 @@ +package engine + +import ( + "context" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/nstranquist/wip-commit/internal/fail" + "github.com/nstranquist/wip-commit/internal/policy" +) + +func TestInspectWorktreeSourceIsExactAndDoesNotChangeCallerIndex(t *testing.T) { + repo := engineTestRepo(t) + write(t, repo.Root, "core.txt", "worktree core\n") + write(t, repo.Root, "docs.txt", "staged docs\n") + write(t, repo.Root, "new.txt", "untracked\n") + engineGit(t, repo.Root, "add", "docs.txt") + indexBefore := engineGitRaw(t, repo.Root, "ls-files", "-s", "-z") + objectsBefore := objectNames(t, filepath.Join(repo.CommonDir, "objects")) + head := engineGit(t, repo.Root, "rev-parse", "HEAD") + + snapshot, err := InspectSource(context.Background(), repo, head, []string{"core.txt", "new.txt"}, SourceWorktree, UntrackedInclude) + if err != nil { + t.Fatal(err) + } + if snapshot.Mode != SourceWorktree || snapshot.UntrackedPolicy != UntrackedInclude || len(snapshot.Paths) != 2 || snapshot.Paths[0] != "core.txt" || snapshot.Paths[1] != "new.txt" { + t.Fatalf("snapshot = %#v", snapshot) + } + if snapshot.Entries["core.txt"] == "" || snapshot.Entries["new.txt"] == "" || snapshot.Digest == "" { + t.Fatalf("snapshot entries = %#v", snapshot) + } + if got := engineGitRaw(t, repo.Root, "ls-files", "-s", "-z"); got != indexBefore { + t.Fatalf("caller index changed:\nwant %q\n got %q", indexBefore, got) + } + if got := objectNames(t, filepath.Join(repo.CommonDir, "objects")); !samePlanStringsForTest(got, objectsBefore) { + t.Fatalf("inspection changed common object database:\nwant %q\n got %q", objectsBefore, got) + } +} + +func TestInspectWorktreeSourceRejectsUntrackedUnlessIncluded(t *testing.T) { + repo := engineTestRepo(t) + write(t, repo.Root, "new.txt", "untracked\n") + head := engineGit(t, repo.Root, "rev-parse", "HEAD") + if _, err := InspectSource(context.Background(), repo, head, []string{"new.txt"}, SourceWorktree, UntrackedForbid); failCode(err) != "UNTRACKED_PATH_FORBIDDEN" { + t.Fatalf("error = %v, want UNTRACKED_PATH_FORBIDDEN", err) + } + if _, err := InspectSource(context.Background(), repo, head, []string{"new.txt"}, SourceStagedIndex, UntrackedInclude); failCode(err) != "INVALID_SOURCE_POLICY" { + t.Fatalf("error = %v, want INVALID_SOURCE_POLICY", err) + } +} + +func TestInspectWorktreeSourceCapturesTrackedFileBelowIgnoredDirectory(t *testing.T) { + repo := engineTestRepo(t) + write(t, repo.Root, ".gitignore", ".cache/\n") + write(t, repo.Root, ".cache/catalog/truth.json", "base truth\n") + engineGit(t, repo.Root, "add", ".gitignore") + engineGit(t, repo.Root, "add", "--force", ".cache/catalog/truth.json") + engineGit(t, repo.Root, "commit", "-m", "track ignored truth") + write(t, repo.Root, ".cache/catalog/truth.json", "current truth\n") + indexBefore := engineGitRaw(t, repo.Root, "ls-files", "-s", "-z") + objectsBefore := objectNames(t, filepath.Join(repo.CommonDir, "objects")) + head := engineGit(t, repo.Root, "rev-parse", "HEAD") + + snapshot, err := InspectSource(context.Background(), repo, head, []string{".cache/catalog/truth.json"}, SourceWorktree, UntrackedInclude) + if err != nil { + t.Fatal(err) + } + if len(snapshot.Paths) != 1 || snapshot.Paths[0] != ".cache/catalog/truth.json" || snapshot.Entries[".cache/catalog/truth.json"] == "" { + t.Fatalf("snapshot = %#v", snapshot) + } + if got := engineGitRaw(t, repo.Root, "ls-files", "-s", "-z"); got != indexBefore { + t.Fatalf("caller index changed:\nwant %q\n got %q", indexBefore, got) + } + if got := objectNames(t, filepath.Join(repo.CommonDir, "objects")); !samePlanStringsForTest(got, objectsBefore) { + t.Fatalf("inspection changed common object database:\nwant %q\n got %q", objectsBefore, got) + } +} + +func TestInspectStagedSourceIgnoresUnstagedBytes(t *testing.T) { + repo := engineTestRepo(t) + write(t, repo.Root, "core.txt", "staged core\n") + engineGit(t, repo.Root, "add", "core.txt") + write(t, repo.Root, "core.txt", "unstaged core\n") + head := engineGit(t, repo.Root, "rev-parse", "HEAD") + snapshot, err := InspectSource(context.Background(), repo, head, []string{"core.txt"}, SourceStagedIndex, UntrackedNotApplicable) + if err != nil { + t.Fatal(err) + } + if len(snapshot.Paths) != 1 || snapshot.Paths[0] != "core.txt" { + t.Fatalf("paths = %q", snapshot.Paths) + } + staged, err := repo.IndexEntries(context.Background(), nil) + if err != nil { + t.Fatal(err) + } + if snapshot.Entries["core.txt"] != staged["core.txt"] { + t.Fatalf("snapshot entry = %q, staged entry = %q", snapshot.Entries["core.txt"], staged["core.txt"]) + } +} + +func TestRunCapturesWorktreeSnapshotWithoutUsingCallerIndex(t *testing.T) { + repo := engineTestRepo(t) + write(t, repo.Root, "core.txt", "worktree core\n") + write(t, repo.Root, "new.txt", "worktree new\n") + write(t, repo.Root, "foreign.txt", "foreign staged\n") + engineGit(t, repo.Root, "add", "foreign.txt") + indexBefore := engineGitRaw(t, repo.Root, "ls-files", "-s", "-z") + head := engineGit(t, repo.Root, "rev-parse", "HEAD") + target := "refs/heads/wip/agent/worktree-source" + engineGit(t, repo.Root, "update-ref", target, head, "") + inspection, err := InspectSource(context.Background(), repo, head, []string{"core.txt", "new.txt"}, SourceWorktree, UntrackedInclude) + if err != nil { + t.Fatal(err) + } + result, err := Run(context.Background(), Options{ + Repo: repo, TargetRef: target, ExpectedRef: head, ExpectedSourceHead: head, + SourceMode: SourceWorktree, UntrackedPolicy: UntrackedInclude, + ExpectedSourceDigest: inspection.Digest, ReviewPlanDigest: "sha256:" + strings.Repeat("a", 64), MessagePolicy: policy.Default(), + AllowedPaths: []string{"core.txt", "new.txt"}, + Groups: []Group{ + {Message: "fix(core): capture worktree source", Files: []string{"core.txt"}}, + {Message: "feat(core): add exact untracked source", Files: []string{"new.txt"}}, + }, + }) + if err != nil { + t.Fatal(err) + } + if !result.RefUpdated || result.SourceMode != SourceWorktree || result.UntrackedPolicy != UntrackedInclude || result.SourceDigest != inspection.Digest { + t.Fatalf("result = %#v", result) + } + if got := engineGitRaw(t, repo.Root, "ls-files", "-s", "-z"); got != indexBefore { + t.Fatalf("caller index changed:\nwant %q\n got %q", indexBefore, got) + } + if got := engineGit(t, repo.Root, "show", result.FinalCommit+":core.txt"); got != "worktree core" { + t.Fatalf("captured core = %q", got) + } + if got := engineGit(t, repo.Root, "show", result.FinalCommit+":new.txt"); got != "worktree new" { + t.Fatalf("captured new = %q", got) + } + if got := engineGit(t, repo.Root, "show", result.FinalCommit+":foreign.txt"); got != "base foreign" { + t.Fatalf("foreign caller-index content leaked = %q", got) + } +} + +func TestRunRejectsWorktreeSourceMovementBeforeRefCAS(t *testing.T) { + repo := engineTestRepo(t) + write(t, repo.Root, "core.txt", "first worktree value\n") + head := engineGit(t, repo.Root, "rev-parse", "HEAD") + target := "refs/heads/wip/agent/worktree-moved" + engineGit(t, repo.Root, "update-ref", target, head, "") + inspection, err := InspectSource(context.Background(), repo, head, []string{"core.txt"}, SourceWorktree, UntrackedForbid) + if err != nil { + t.Fatal(err) + } + result, err := Run(context.Background(), Options{ + Repo: repo, TargetRef: target, ExpectedRef: head, ExpectedSourceHead: head, + SourceMode: SourceWorktree, UntrackedPolicy: UntrackedForbid, + ExpectedSourceDigest: inspection.Digest, ReviewPlanDigest: "sha256:" + strings.Repeat("b", 64), MessagePolicy: policy.Default(), + AllowedPaths: []string{"core.txt"}, Groups: []Group{{Message: "fix(core): reject moved source", Files: []string{"core.txt"}}}, + BeforePublish: func() error { + write(t, repo.Root, "core.txt", "second worktree value\n") + return nil + }, + }) + if fail.Code(err) != "SOURCE_MOVED" || result.RefUpdated { + t.Fatalf("result = %#v, error = %v", result, err) + } + if got := engineGit(t, repo.Root, "rev-parse", target); got != head { + t.Fatalf("target moved to %s, want %s", got, head) + } +} + +func TestDryRunKeepsGeneratedGitObjectsOutsideRepository(t *testing.T) { + repo := engineTestRepo(t) + write(t, repo.Root, "core.txt", "dry-run core\n") + engineGit(t, repo.Root, "add", "core.txt") + objectsBefore := objectNames(t, filepath.Join(repo.CommonDir, "objects")) + head := engineGit(t, repo.Root, "rev-parse", "HEAD") + target := "refs/heads/wip/agent/dry-object-store" + engineGit(t, repo.Root, "update-ref", target, head, "") + result, err := Run(context.Background(), Options{ + Repo: repo, TargetRef: target, ExpectedRef: head, ExpectedSourceHead: head, + AllowedPaths: []string{"core.txt"}, Groups: []Group{{Message: "fix(core): prove pure dry run", Files: []string{"core.txt"}}}, DryRun: true, + }) + if err != nil { + t.Fatal(err) + } + if result.SchemaVersion != ResultSchemaVersion || result.RefUpdated || result.FinalCommit != "" || result.GateOutcome != "skipped" { + t.Fatalf("result = %#v", result) + } + if result.Execution == nil || result.Execution.Policy != "no-exec" || result.Execution.PreCommitHooks != (ExecutionCount{}) || result.Execution.PostCommitHooks != (ExecutionCount{}) || result.Execution.VerifyCommands != (ExecutionCount{}) { + t.Fatalf("dry-run execution report = %#v", result.Execution) + } + if got := objectNames(t, filepath.Join(repo.CommonDir, "objects")); !samePlanStringsForTest(got, objectsBefore) { + t.Fatalf("dry-run changed common object database:\nwant %q\n got %q", objectsBefore, got) + } + if _, err := os.Lstat(filepath.Join(repo.GitDir, "wip")); !os.IsNotExist(err) { + t.Fatalf("dry-run created repository-private state: %v", err) + } +} + +func objectNames(t *testing.T, root string) []string { + t.Helper() + var names []string + err := filepath.WalkDir(root, func(path string, entry os.DirEntry, err error) error { + if err != nil { + return err + } + if path == root || entry.IsDir() { + return nil + } + relative, err := filepath.Rel(root, path) + if err != nil { + return err + } + names = append(names, filepath.ToSlash(relative)) + return nil + }) + if err != nil { + t.Fatal(err) + } + return names +} + +func samePlanStringsForTest(left, right []string) bool { + if len(left) != len(right) { + return false + } + for index := range left { + if left[index] != right[index] { + return false + } + } + return true +} + +func failCode(err error) string { + if err == nil { + return "" + } + return fail.Code(err) +} diff --git a/internal/filelock/filelock.go b/internal/filelock/filelock.go index d2020ab..75f2557 100644 --- a/internal/filelock/filelock.go +++ b/internal/filelock/filelock.go @@ -10,22 +10,42 @@ import ( type Lock struct{ file *os.File } -const MaxWait = 24 * time.Hour +const ( + // DefaultWait is an explicit bound for internal serialization. Callers that + // expose a wait option must pass the user's value so zero remains fail-fast. + DefaultWait = 2 * time.Minute + MaxWait = 24 * time.Hour +) func Acquire(path string, wait time.Duration) (*Lock, error) { + return acquire(path, wait, true) +} + +// AcquireExisting locks an existing regular lock file without changing its +// bytes or creating a parent directory. +func AcquireExisting(path string, wait time.Duration) (*Lock, error) { + return acquire(path, wait, false) +} + +func acquire(path string, wait time.Duration, writeOwner bool) (*Lock, error) { if wait < 0 { return nil, errors.New("lock wait cannot be negative") } if wait > MaxWait { return nil, fmt.Errorf("lock wait exceeds %s", MaxWait) } - if wait == 0 { - wait = 2 * time.Minute + if writeOwner { + if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil { + return nil, err + } } - if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil { - return nil, err + var file *os.File + var err error + if writeOwner { + file, err = openOrCreate(path) + } else { + file, err = openExisting(path) } - file, err := os.OpenFile(path, os.O_RDWR|os.O_CREATE, 0o600) if err != nil { return nil, err } @@ -37,14 +57,18 @@ func Acquire(path string, wait time.Duration) (*Lock, error) { return nil, lockErr } if owned { - if err = file.Truncate(0); err == nil { - _, err = file.Seek(0, 0) - } - if err == nil { - _, err = fmt.Fprintf(file, "pid=%d\nstarted_at=%s\n", os.Getpid(), time.Now().UTC().Format(time.RFC3339Nano)) - } - if err == nil { - err = file.Sync() + if writeOwner { + if err = file.Truncate(0); err == nil { + _, err = file.Seek(0, 0) + } + if err == nil { + _, err = fmt.Fprintf(file, "pid=%d\nstarted_at=%s\n", os.Getpid(), time.Now().UTC().Format(time.RFC3339Nano)) + } + if err == nil { + err = file.Sync() + } + } else { + err = validateExistingPath(path, file) } if err != nil { _ = unlock(file) @@ -53,12 +77,74 @@ func Acquire(path string, wait time.Duration) (*Lock, error) { } return &Lock{file: file}, nil } - if time.Now().After(deadline) { + if wait == 0 || !time.Now().Before(deadline) { _ = file.Close() return nil, fmt.Errorf("lock remained held after %s: %s", wait, path) } - time.Sleep(50 * time.Millisecond) + pause := min(50*time.Millisecond, time.Until(deadline)) + if pause > 0 { + time.Sleep(pause) + } + } +} + +func openOrCreate(path string) (*os.File, error) { + file, err := os.OpenFile(path, os.O_RDWR|os.O_CREATE|os.O_EXCL, 0o600) + if err == nil { + return file, nil + } + if !errors.Is(err, os.ErrExist) { + return nil, err + } + // The exclusive create prevents following an existing symlink. Opening an + // existing lock then verifies both its type and path identity. + return openExisting(path) +} + +func openExisting(path string) (*os.File, error) { + expected, err := regularPathInfo(path) + if err != nil { + return nil, err + } + file, err := os.OpenFile(path, os.O_RDWR, 0o600) + if err != nil { + return nil, err + } + opened, err := file.Stat() + if err != nil || !os.SameFile(expected, opened) { + _ = file.Close() + if err != nil { + return nil, err + } + return nil, fmt.Errorf("lock path changed while opening: %s", path) + } + return file, nil +} + +func validateExistingPath(path string, file *os.File) error { + current, err := regularPathInfo(path) + if err != nil { + return err + } + opened, err := file.Stat() + if err != nil { + return err + } + if !os.SameFile(opened, current) { + return fmt.Errorf("lock path changed while acquiring: %s", path) + } + return nil +} + +func regularPathInfo(path string) (os.FileInfo, error) { + info, err := os.Lstat(path) + if err != nil { + return nil, err + } + if !info.Mode().IsRegular() || info.Mode()&os.ModeSymlink != 0 { + return nil, fmt.Errorf("lock path is not a regular file: %s", path) } + return info, nil } func (lock *Lock) Release() error { diff --git a/internal/filelock/filelock_test.go b/internal/filelock/filelock_test.go index 9291283..13149d9 100644 --- a/internal/filelock/filelock_test.go +++ b/internal/filelock/filelock_test.go @@ -1,7 +1,10 @@ package filelock import ( + "os" "path/filepath" + "runtime" + "strings" "testing" "time" ) @@ -34,6 +37,164 @@ func TestExclusiveLockWaitAndRelease(t *testing.T) { } } +func TestZeroWaitIsFailFast(t *testing.T) { + path := filepath.Join(t.TempDir(), "locks", "lane.lock") + first, err := Acquire(path, time.Second) + if err != nil { + t.Fatal(err) + } + defer func() { _ = first.Release() }() + + started := time.Now() + if _, err := Acquire(path, 0); err == nil { + t.Fatal("zero-wait acquisition bypassed the current owner") + } + if elapsed := time.Since(started); elapsed > 500*time.Millisecond { + t.Fatalf("zero-wait acquisition blocked for %s", elapsed) + } + + started = time.Now() + if _, err := AcquireExisting(path, 0); err == nil { + t.Fatal("zero-wait existing acquisition bypassed the current owner") + } + if elapsed := time.Since(started); elapsed > 500*time.Millisecond { + t.Fatalf("zero-wait existing acquisition blocked for %s", elapsed) + } +} + +func TestAcquireExistingPreservesLockFile(t *testing.T) { + path := filepath.Join(t.TempDir(), "locks", "lane.lock") + created, err := Acquire(path, time.Second) + if err != nil { + t.Fatal(err) + } + if err := created.Release(); err != nil { + t.Fatal(err) + } + before, err := os.ReadFile(path) + if err != nil { + t.Fatal(err) + } + observed, err := AcquireExisting(path, time.Second) + if err != nil { + t.Fatal(err) + } + if err := observed.Release(); err != nil { + t.Fatal(err) + } + after, err := os.ReadFile(path) + if err != nil { + t.Fatal(err) + } + if string(after) != string(before) { + t.Fatalf("existing lock changed bytes: before=%q after=%q", before, after) + } + + missingRoot := t.TempDir() + missingParent := filepath.Join(missingRoot, "missing") + missing := filepath.Join(missingParent, "lane.lock") + if _, err := AcquireExisting(missing, time.Second); err == nil { + t.Fatal("existing lock acquisition created a missing lock") + } + if _, err := os.Lstat(missing); !os.IsNotExist(err) { + t.Fatalf("missing lock path changed: %v", err) + } + if _, err := os.Lstat(missingParent); !os.IsNotExist(err) { + t.Fatalf("missing lock parent changed: %v", err) + } + + if _, err := AcquireExisting(t.TempDir(), time.Second); err == nil { + t.Fatal("existing lock acquisition accepted a directory") + } + if runtime.GOOS != "windows" { + target := filepath.Join(t.TempDir(), "target.lock") + if err := os.WriteFile(target, []byte("target\n"), 0o600); err != nil { + t.Fatal(err) + } + link := filepath.Join(t.TempDir(), "link.lock") + if err := os.Symlink(target, link); err != nil { + t.Fatal(err) + } + if _, err := AcquireExisting(link, time.Second); err == nil { + t.Fatal("existing lock acquisition followed a symlink") + } + } +} + +func TestAcquireDoesNotFollowExistingSymlink(t *testing.T) { + if runtime.GOOS == "windows" { + t.Skip("symlink creation needs optional Windows privileges") + } + directory := t.TempDir() + target := filepath.Join(directory, "target") + if err := os.WriteFile(target, []byte("preserve\n"), 0o600); err != nil { + t.Fatal(err) + } + link := filepath.Join(directory, "lock") + if err := os.Symlink(target, link); err != nil { + t.Fatal(err) + } + if _, err := Acquire(link, 0); err == nil { + t.Fatal("Acquire followed an existing lock symlink") + } + body, err := os.ReadFile(target) + if err != nil || string(body) != "preserve\n" { + t.Fatalf("lock symlink target changed: %q err=%v", body, err) + } +} + +func TestValidateExistingPathRejectsReplacement(t *testing.T) { + directory := t.TempDir() + path := filepath.Join(directory, "lane.lock") + if err := os.WriteFile(path, []byte("original\n"), 0o600); err != nil { + t.Fatal(err) + } + opened, err := openExisting(path) + if err != nil { + t.Fatal(err) + } + defer func() { _ = opened.Close() }() + oldPath := filepath.Join(directory, "old.lock") + if err := os.Rename(path, oldPath); err != nil { + if runtime.GOOS != "windows" { + t.Fatal(err) + } + // Windows denies replacement while the lock handle is open. That is a + // stronger kernel guarantee than the identity check exercised below on + // systems that allow renaming an open file. Prove that the failed rename + // preserved the original path, bytes, and identity. + if err := validateExistingPath(path, opened); err != nil { + t.Fatalf("failed rename changed the open lock identity: %v", err) + } + body, readErr := os.ReadFile(path) + if readErr != nil || string(body) != "original\n" { + t.Fatalf("failed rename changed the open lock: %q err=%v", body, readErr) + } + if _, statErr := os.Lstat(oldPath); !os.IsNotExist(statErr) { + t.Fatalf("failed rename published the old path: %v", statErr) + } + return + } + if err := os.WriteFile(path, []byte("replacement\n"), 0o600); err != nil { + t.Fatal(err) + } + if err := validateExistingPath(path, opened); err == nil || !strings.Contains(err.Error(), "changed while acquiring") { + t.Fatalf("replacement validation error = %v", err) + } +} + +func TestAcquireExistingWaitsForOwner(t *testing.T) { + path := filepath.Join(t.TempDir(), "lane.lock") + first, err := Acquire(path, time.Second) + if err != nil { + t.Fatal(err) + } + defer func() { _ = first.Release() }() + if _, err := AcquireExisting(path, 100*time.Millisecond); err == nil { + t.Fatal("existing lock acquisition bypassed the current owner") + } +} + func TestLockWaitBounds(t *testing.T) { path := filepath.Join(t.TempDir(), "lane.lock") if _, err := Acquire(path, -time.Second); err == nil { diff --git a/internal/gitx/gitx.go b/internal/gitx/gitx.go index 0c4b9fe..817d658 100644 --- a/internal/gitx/gitx.go +++ b/internal/gitx/gitx.go @@ -31,8 +31,12 @@ var isolatedRepositoryEnvironment = map[string]bool{ "GIT_CONFIG_PARAMETERS": true, "GIT_DIR": true, "GIT_GRAFT_FILE": true, + "GIT_GLOB_PATHSPECS": true, + "GIT_ICASE_PATHSPECS": true, "GIT_IMPLICIT_WORK_TREE": true, + "GIT_LITERAL_PATHSPECS": true, "GIT_NAMESPACE": true, + "GIT_NOGLOB_PATHSPECS": true, "GIT_NO_REPLACE_OBJECTS": true, "GIT_OBJECT_DIRECTORY": true, "GIT_PREFIX": true, @@ -42,6 +46,16 @@ var isolatedRepositoryEnvironment = map[string]bool{ "GIT_WORK_TREE": true, } +// trustedRepositoryOverrides are the repository-local selectors that the +// capture kernel may supply itself after inherited selectors have been +// removed. Keep this list narrow. In particular, callers cannot replace the +// repository selected by Repo.Root, GitDir, or CommonDir. +var trustedRepositoryOverrides = map[string]bool{ + "GIT_ALTERNATE_OBJECT_DIRECTORIES": true, + "GIT_INDEX_FILE": true, + "GIT_OBJECT_DIRECTORY": true, +} + func Discover(ctx context.Context, directory string) (Repo, error) { if directory == "" { var err error @@ -192,6 +206,28 @@ func (repo Repo) IndexEntries(ctx context.Context, env []string) (map[string]str return entries, nil } +// TreeEntries returns index-shaped entries for a committed tree. The values use +// the same " 0" representation as IndexEntries. +func (repo Repo) TreeEntries(ctx context.Context, treeish string) (map[string]string, error) { + output, err := repo.Raw(ctx, nil, "ls-tree", "-r", "-z", "--full-tree", treeish) + if err != nil { + return nil, err + } + entries := map[string]string{} + for _, row := range strings.Split(output, "\x00") { + if row == "" { + continue + } + parts := strings.SplitN(row, "\t", 2) + fields := strings.Fields(parts[0]) + if len(parts) != 2 || len(fields) != 3 { + return nil, fmt.Errorf("malformed git ls-tree row") + } + entries[parts[1]] = fields[0] + " " + fields[2] + " 0" + } + return entries, nil +} + func (repo Repo) NormalizePaths(input []string) ([]string, error) { seen := map[string]string{} out := make([]string, 0, len(input)) @@ -250,13 +286,19 @@ func commandRaw(ctx context.Context, dir string, env []string, args ...string) ( func mergedEnvironment(extra []string) []string { environment := make([]string, 0, len(os.Environ())+len(extra)) + extraNames := make(map[string]bool, len(extra)) + for _, entry := range extra { + extraNames[environmentName(entry)] = true + } for _, entry := range os.Environ() { - if !isolatesRepositoryEnvironment(environmentName(entry)) { + name := environmentName(entry) + if !isolatesRepositoryEnvironment(name) && !extraNames[name] { environment = append(environment, entry) } } for _, entry := range extra { - if !isolatesRepositoryEnvironment(environmentName(entry)) { + name := environmentName(entry) + if !isolatesRepositoryEnvironment(name) || trustedRepositoryOverrides[name] { environment = append(environment, entry) } } diff --git a/internal/gitx/gitx_test.go b/internal/gitx/gitx_test.go index 03fcc91..dbc512a 100644 --- a/internal/gitx/gitx_test.go +++ b/internal/gitx/gitx_test.go @@ -90,6 +90,10 @@ func TestDiscoverIgnoresInheritedRepositoryRoutingEnvironment(t *testing.T) { t.Setenv("GIT_COMMON_DIR", second.CommonDir) t.Setenv("GIT_OBJECT_DIRECTORY", filepath.Join(second.CommonDir, "objects")) t.Setenv("GIT_NAMESPACE", "foreign") + t.Setenv("GIT_GLOB_PATHSPECS", "1") + t.Setenv("GIT_ICASE_PATHSPECS", "1") + t.Setenv("GIT_LITERAL_PATHSPECS", "1") + t.Setenv("GIT_NOGLOB_PATHSPECS", "1") t.Setenv("GIT_CONFIG_COUNT", "1") t.Setenv("GIT_CONFIG_KEY_0", "core.worktree") t.Setenv("GIT_CONFIG_VALUE_0", second.Root) @@ -112,6 +116,64 @@ func TestDiscoverIgnoresInheritedRepositoryRoutingEnvironment(t *testing.T) { } } +func TestRepoCommandsUseTrustedPrivateIndexWithoutChangingCallerIndex(t *testing.T) { + repo, _ := initializedRepo(t) + ctx := context.Background() + callerBefore, err := repo.Raw(ctx, nil, "ls-files", "-s", "-z") + if err != nil { + t.Fatal(err) + } + privateIndex := filepath.Join(t.TempDir(), "capture.index") + environment := []string{ + "GIT_INDEX_FILE=" + privateIndex, + "GIT_DIR=/tmp/forbidden.git", + "WIP_TARGET_REF=refs/heads/wip/test/private-index", + } + if _, err := repo.Text(ctx, environment, "read-tree", "HEAD"); err != nil { + t.Fatal(err) + } + if _, err := repo.Text(ctx, environment, "update-index", "--force-remove", "--", "tracked.txt"); err != nil { + t.Fatal(err) + } + if _, err := os.Stat(privateIndex); err != nil { + t.Fatalf("trusted private index was not created: %v", err) + } + callerAfter, err := repo.Raw(ctx, nil, "ls-files", "-s", "-z") + if err != nil { + t.Fatal(err) + } + if callerAfter != callerBefore { + t.Fatalf("caller index changed through private-index operation:\nwant %q\n got %q", callerBefore, callerAfter) + } + privateEntries, err := repo.Raw(ctx, []string{"GIT_INDEX_FILE=" + privateIndex}, "ls-files", "-s", "-z") + if err != nil { + t.Fatal(err) + } + if strings.Contains(privateEntries, "tracked.txt") { + t.Fatalf("private index update did not take effect: %q", privateEntries) + } + commandEnvironment := mergedEnvironment(environment) + for _, entry := range commandEnvironment { + name := environmentName(entry) + if name == "GIT_DIR" { + t.Fatalf("untrusted repository override survived: %q", entry) + } + } + if !containsEnvironment(commandEnvironment, "GIT_INDEX_FILE", privateIndex) || !containsEnvironment(commandEnvironment, "WIP_TARGET_REF", "refs/heads/wip/test/private-index") { + t.Fatalf("trusted command environment was not preserved: %q", commandEnvironment) + } +} + +func containsEnvironment(environment []string, name, value string) bool { + wanted := name + "=" + value + for _, entry := range environment { + if entry == wanted { + return true + } + } + return false +} + func TestCommandOutputHelpersPreserveExactGitResults(t *testing.T) { repo, _ := initializedRepo(t) ctx := context.Background() @@ -170,6 +232,27 @@ func TestCommandOutputHelpersPreserveExactGitResults(t *testing.T) { } } +func TestTreeEntriesMatchACleanIndex(t *testing.T) { + repo, _ := initializedRepo(t) + ctx := context.Background() + index, err := repo.IndexEntries(ctx, nil) + if err != nil { + t.Fatal(err) + } + tree, err := repo.TreeEntries(ctx, "HEAD") + if err != nil { + t.Fatal(err) + } + if len(tree) != len(index) { + t.Fatalf("TreeEntries(HEAD) has %d entries, want %d: %#v", len(tree), len(index), tree) + } + for path, want := range index { + if got := tree[path]; got != want { + t.Errorf("TreeEntries(HEAD)[%q] = %q, want %q", path, got, want) + } + } +} + func initializedRepo(t *testing.T) (Repo, string) { t.Helper() directory := t.TempDir() diff --git a/internal/message/message.go b/internal/message/message.go new file mode 100644 index 0000000..29ffee5 --- /dev/null +++ b/internal/message/message.go @@ -0,0 +1,35 @@ +package message + +import ( + "strings" + "unicode" + "unicode/utf8" + + "github.com/nstranquist/wip-commit/internal/fail" +) + +const MaxBytes = 64 << 10 + +// ValidateSafety enforces only the invariants needed to store and reproduce a +// Git commit message safely. Repository naming conventions belong to policy. +func ValidateSafety(value string) error { + if len(value) > MaxBytes { + return fail.Errorf("INVALID_COMMIT_MESSAGE", "commit message exceeds %d bytes", MaxBytes) + } + if !utf8.ValidString(value) { + return fail.New("INVALID_COMMIT_MESSAGE", "commit message must be valid UTF-8") + } + for _, character := range value { + if character == '\r' || character == '\x00' || (unicode.IsControl(character) && character != '\n' && character != '\t') { + return fail.New("INVALID_COMMIT_MESSAGE", "commit message contains an unsupported control character") + } + } + trimmed := strings.TrimSpace(value) + if value != trimmed { + return fail.New("INVALID_COMMIT_MESSAGE", "commit message cannot start or end with whitespace") + } + if trimmed == "" || strings.TrimSpace(strings.SplitN(trimmed, "\n", 2)[0]) == "" { + return fail.New("INVALID_COMMIT_MESSAGE", "commit message subject cannot be empty") + } + return nil +} diff --git a/internal/message/message_test.go b/internal/message/message_test.go new file mode 100644 index 0000000..1f8ee88 --- /dev/null +++ b/internal/message/message_test.go @@ -0,0 +1,21 @@ +package message + +import ( + "strings" + "testing" + + "github.com/nstranquist/wip-commit/internal/fail" +) + +func TestValidateSafety(t *testing.T) { + for _, valid := range []string{"plain subject", "subject\n\nbody", "fix(core): conventional remains valid"} { + if err := ValidateSafety(valid); err != nil { + t.Fatalf("ValidateSafety(%q) = %v", valid, err) + } + } + for _, invalid := range []string{"", " subject", "subject\n", "subject\x00body", strings.Repeat("x", MaxBytes+1)} { + if err := ValidateSafety(invalid); fail.Code(err) != "INVALID_COMMIT_MESSAGE" { + t.Errorf("ValidateSafety(%q) = %v (%s)", invalid, err, fail.Code(err)) + } + } +} diff --git a/internal/policy/message.go b/internal/policy/message.go new file mode 100644 index 0000000..275903d --- /dev/null +++ b/internal/policy/message.go @@ -0,0 +1,154 @@ +package policy + +import ( + "crypto/sha256" + "encoding/hex" + "errors" + "os" + "path/filepath" + "regexp" + "strings" + "unicode/utf8" + + "github.com/nstranquist/wip-commit/internal/fail" + "github.com/nstranquist/wip-commit/internal/message" + "github.com/nstranquist/wip-commit/internal/safeio" + "github.com/nstranquist/wip-commit/internal/strictjson" +) + +const ( + ConfigName = ".wip-commit.json" + ConfigSchemaVersion = "1.0.0" + ConventionalV1 = "conventional-v1" + SafetyOnlyV1 = "safety-only-v1" + maxConfigBytes = 64 << 10 + subjectLimit = 72 +) + +var ( + conventional = regexp.MustCompile(`^([a-z][a-z0-9-]*)(?:\(([a-z0-9][a-z0-9._/-]*)\))?(!)?: (.+)$`) + types = map[string]bool{"build": true, "chore": true, "ci": true, "docs": true, "feat": true, "fix": true, "perf": true, "refactor": true, "revert": true, "style": true, "test": true} + vague = map[string]bool{"change": true, "changes": true, "fix": true, "misc": true, "stuff": true, "update": true, "updates": true, "work": true} +) + +type Receipt struct { + ID string `json:"id"` + Version string `json:"version"` + Digest string `json:"digest"` +} + +type config struct { + SchemaVersion string `json:"schema_version"` + MessagePolicy string `json:"message_policy"` +} + +func Default() Receipt { return mustResolve(ConventionalV1) } + +func Resolve(name string) (Receipt, error) { + name = strings.TrimSpace(name) + if name == "" { + name = ConventionalV1 + } + if name != ConventionalV1 && name != SafetyOnlyV1 { + return Receipt{}, fail.Errorf("INVALID_MESSAGE_POLICY", "unsupported message policy %q", name) + } + sum := sha256.Sum256([]byte(name + "\x00" + ConfigSchemaVersion)) + return Receipt{ID: name, Version: ConfigSchemaVersion, Digest: "sha256:" + hex.EncodeToString(sum[:])}, nil +} + +func mustResolve(name string) Receipt { + receipt, err := Resolve(name) + if err != nil { + panic(err) + } + return receipt +} + +func Load(repoRoot, override string) (Receipt, error) { + if strings.TrimSpace(override) != "" { + return Resolve(override) + } + body, err := safeio.ReadRegular(filepath.Join(repoRoot, ConfigName), maxConfigBytes) + if errors.Is(err, os.ErrNotExist) { + return Default(), nil + } + if err != nil { + return Receipt{}, fail.Wrap("MESSAGE_POLICY_READ_FAILED", err) + } + var value config + if err := strictjson.Decode(body, &value); err != nil { + return Receipt{}, fail.Wrap("MESSAGE_POLICY_READ_FAILED", err) + } + if value.SchemaVersion != ConfigSchemaVersion { + return Receipt{}, fail.Errorf("MIGRATION_REQUIRED", "message policy schema %q is unsupported; this wip release supports %s", value.SchemaVersion, ConfigSchemaVersion) + } + return Resolve(value.MessagePolicy) +} + +func ValidateReceipt(receipt Receipt) error { + wanted, err := Resolve(receipt.ID) + if err != nil { + return err + } + if receipt != wanted { + return fail.New("INVALID_MESSAGE_POLICY", "message policy receipt does not match its named policy") + } + return nil +} + +func Validate(receipt Receipt, value string, allowWIP bool) error { + if err := ValidateReceipt(receipt); err != nil { + return err + } + if err := message.ValidateSafety(value); err != nil { + return err + } + if receipt.ID == SafetyOnlyV1 { + return nil + } + lines := strings.Split(value, "\n") + subject := strings.TrimSpace(lines[0]) + if utf8.RuneCountInString(subject) > subjectLimit { + return fail.New("MESSAGE_POLICY_REJECTED", "commit subject exceeds 72 characters under conventional-v1") + } + if len(lines) > 1 && strings.TrimSpace(lines[1]) != "" { + return fail.New("MESSAGE_POLICY_REJECTED", "separate the subject and body with a blank line under conventional-v1") + } + match := conventional.FindStringSubmatch(subject) + if match == nil { + return fail.New("MESSAGE_POLICY_REJECTED", "use (): under conventional-v1") + } + if match[1] == "wip" { + if !allowWIP { + return fail.New("WIP_PREFIX_NOT_AUTHORIZED", "wip: requires explicit authorization") + } + } else if !types[match[1]] { + return fail.Errorf("MESSAGE_POLICY_REJECTED", "unsupported Conventional Commit type %q", match[1]) + } + description := strings.TrimSpace(match[4]) + if description != match[4] { + return fail.New("MESSAGE_POLICY_REJECTED", "use one space after the subject colon") + } + if utf8.RuneCountInString(description) < 4 || vague[strings.ToLower(strings.TrimSuffix(description, "."))] { + return fail.New("MESSAGE_POLICY_REJECTED", "name the concrete outcome") + } + if strings.HasSuffix(description, ".") { + return fail.New("MESSAGE_POLICY_REJECTED", "commit subject must not end with a period") + } + return nil +} + +func ValidateMessages(receipt Receipt, values []string, allowWIP bool) error { + seen := map[string]bool{} + for _, value := range values { + if err := Validate(receipt, value, allowWIP); err != nil { + return err + } + key := strings.ToLower(strings.TrimSpace(value)) + if seen[key] { + return fail.New("MESSAGE_POLICY_REJECTED", "commit groups need distinct messages under "+receipt.ID) + } + seen[key] = true + } + return nil +} diff --git a/internal/policy/message_test.go b/internal/policy/message_test.go new file mode 100644 index 0000000..c1b1061 --- /dev/null +++ b/internal/policy/message_test.go @@ -0,0 +1,47 @@ +package policy + +import ( + "os" + "path/filepath" + "testing" + + "github.com/nstranquist/wip-commit/internal/fail" +) + +func TestNamedMessagePolicies(t *testing.T) { + conventional := Default() + if err := Validate(conventional, "fix(core): preserve exact capture", false); err != nil { + t.Fatal(err) + } + if err := Validate(conventional, "plain local checkpoint", false); fail.Code(err) != "MESSAGE_POLICY_REJECTED" { + t.Fatalf("conventional rejection = %v (%s)", err, fail.Code(err)) + } + safety, err := Resolve(SafetyOnlyV1) + if err != nil { + t.Fatal(err) + } + if err := Validate(safety, "plain local checkpoint", false); err != nil { + t.Fatal(err) + } +} + +func TestLoadMessagePolicyIsStrictAndDefaults(t *testing.T) { + directory := t.TempDir() + if got, err := Load(directory, ""); err != nil || got != Default() { + t.Fatalf("default = %#v, %v", got, err) + } + path := filepath.Join(directory, ConfigName) + if err := os.WriteFile(path, []byte(`{"schema_version":"1.0.0","message_policy":"safety-only-v1"}`), 0o600); err != nil { + t.Fatal(err) + } + got, err := Load(directory, "") + if err != nil || got.ID != SafetyOnlyV1 { + t.Fatalf("configured = %#v, %v", got, err) + } + if err := os.WriteFile(path, []byte(`{"schema_version":"1.0.0","message_policy":"safety-only-v1","unknown":true}`), 0o600); err != nil { + t.Fatal(err) + } + if _, err := Load(directory, ""); fail.Code(err) != "MESSAGE_POLICY_READ_FAILED" { + t.Fatalf("strict error = %v (%s)", err, fail.Code(err)) + } +} diff --git a/internal/store/archive.go b/internal/store/archive.go index 3ff7d4e..f69f98f 100644 --- a/internal/store/archive.go +++ b/internal/store/archive.go @@ -51,6 +51,11 @@ func (store Store) ArchiveCandidates(before time.Time) ([]ArchiveCandidate, erro if before.IsZero() { return nil, fail.New("INVALID_ARGS", "archive cutoff cannot be zero") } + registry, err := store.existingRegistryLock(filelock.DefaultWait) + if err != nil { + return nil, err + } + defer func() { _ = registry.Release() }() entries, err := readRecordEntries(filepath.Join(store.Root, "lanes")) if err != nil { return nil, err @@ -61,7 +66,7 @@ func (store Store) ArchiveCandidates(before time.Time) ([]ArchiveCandidate, erro return nil, fail.New("ARCHIVE_REFUSED", "lane record directory contains an unexpected entry: "+entry.Name()) } id := strings.TrimSuffix(entry.Name(), ".json") - candidate, eligible, err := store.archiveCandidate(id, before) + candidate, eligible, err := store.archiveCandidateLocked(id, before) if err != nil { return nil, err } @@ -77,8 +82,8 @@ func (store Store) ArchiveCandidates(before time.Time) ([]ArchiveCandidate, erro return candidates, nil } -func (store Store) archiveCandidate(id string, before time.Time) (ArchiveCandidate, bool, error) { - lane, err := store.Load(id) +func (store Store) archiveCandidateLocked(id string, before time.Time) (ArchiveCandidate, bool, error) { + lane, err := store.loadLane(id) if err != nil { return ArchiveCandidate{}, false, err } @@ -104,10 +109,13 @@ func (store Store) archiveCandidate(id string, before time.Time) (ArchiveCandida // records are compared again while every selected lane and the lease registry // are locked. func (store Store) Archive(ctx context.Context, before time.Time, expected []ArchiveCandidate) (ArchiveReceipt, error) { + if !store.WriterFenced() { + return withWriterFence(store, func(fenced Store) (ArchiveReceipt, error) { return fenced.Archive(ctx, before, expected) }) + } if err := validateArchiveCandidates(expected, before); err != nil { return ArchiveReceipt{}, err } - archiveLock, err := filelock.Acquire(filepath.Join(store.Root, "locks", "archive.lock"), 0) + archiveLock, err := filelock.Acquire(filepath.Join(store.Root, "locks", "archive.lock"), filelock.DefaultWait) if err != nil { return ArchiveReceipt{}, fail.Wrap("LOCK_TIMEOUT", err) } @@ -117,10 +125,13 @@ func (store Store) Archive(ctx context.Context, before time.Time, expected []Arc // ResumeArchive continues only the immutable prepared receipt named by id. func (store Store) ResumeArchive(ctx context.Context, id string) (ArchiveReceipt, error) { + if !store.WriterFenced() { + return withWriterFence(store, func(fenced Store) (ArchiveReceipt, error) { return fenced.ResumeArchive(ctx, id) }) + } if err := validateID(id, "archive"); err != nil { return ArchiveReceipt{}, err } - archiveLock, err := filelock.Acquire(filepath.Join(store.Root, "locks", "archive.lock"), 0) + archiveLock, err := filelock.Acquire(filepath.Join(store.Root, "locks", "archive.lock"), filelock.DefaultWait) if err != nil { return ArchiveReceipt{}, fail.Wrap("LOCK_TIMEOUT", err) } @@ -147,7 +158,7 @@ func (store Store) ResumeArchive(ctx context.Context, id string) (ArchiveReceipt func (store Store) archiveLocked(ctx context.Context, receipt ArchiveReceipt, resume bool) (ArchiveReceipt, error) { locks := make([]*filelock.Lock, 0, len(receipt.Candidates)) for _, candidate := range receipt.Candidates { - lock, err := store.LaneLock(candidate.LaneID, 0) + lock, err := store.LaneLock(candidate.LaneID, filelock.DefaultWait) if err != nil { for index := len(locks) - 1; index >= 0; index-- { _ = locks[index].Release() @@ -161,7 +172,7 @@ func (store Store) archiveLocked(ctx context.Context, receipt ArchiveReceipt, re _ = locks[index].Release() } }() - registry, err := store.registryLock(0) + registry, err := store.registryLock(filelock.DefaultWait) if err != nil { return ArchiveReceipt{}, err } @@ -169,7 +180,7 @@ func (store Store) archiveLocked(ctx context.Context, receipt ArchiveReceipt, re if !resume { // Rebuild only the exact reviewed records under every relevant lock. for _, candidate := range receipt.Candidates { - fresh, eligible, err := store.archiveCandidate(candidate.LaneID, receipt.Before) + fresh, eligible, err := store.archiveCandidateLocked(candidate.LaneID, receipt.Before) if err != nil { return ArchiveReceipt{}, err } @@ -236,10 +247,13 @@ func sameArchiveCandidate(left, right ArchiveCandidate) bool { } func (store Store) RestoreArchive(ctx context.Context, id string) (ArchiveReceipt, error) { + if !store.WriterFenced() { + return withWriterFence(store, func(fenced Store) (ArchiveReceipt, error) { return fenced.RestoreArchive(ctx, id) }) + } if err := validateID(id, "archive"); err != nil { return ArchiveReceipt{}, err } - archiveLock, err := filelock.Acquire(filepath.Join(store.Root, "locks", "archive.lock"), 0) + archiveLock, err := filelock.Acquire(filepath.Join(store.Root, "locks", "archive.lock"), filelock.DefaultWait) if err != nil { return ArchiveReceipt{}, fail.Wrap("LOCK_TIMEOUT", err) } @@ -259,7 +273,7 @@ func (store Store) RestoreArchive(ctx context.Context, id string) (ArchiveReceip } locks := make([]*filelock.Lock, 0, len(receipt.Candidates)) for _, candidate := range receipt.Candidates { - lock, err := store.LaneLock(candidate.LaneID, 0) + lock, err := store.LaneLock(candidate.LaneID, filelock.DefaultWait) if err != nil { for index := len(locks) - 1; index >= 0; index-- { _ = locks[index].Release() @@ -273,7 +287,7 @@ func (store Store) RestoreArchive(ctx context.Context, id string) (ArchiveReceip _ = locks[index].Release() } }() - registry, err := store.registryLock(0) + registry, err := store.registryLock(filelock.DefaultWait) if err != nil { return ArchiveReceipt{}, err } @@ -528,6 +542,13 @@ func (store Store) ValidateArchiveFiles(receipt ArchiveReceipt) error { if err := validateArchiveBatchContents(root, receipt); err != nil { return err } + historicalSources := map[string]string{} + if receipt.State == "restored" { + historicalSources, err = store.restoredArchiveSources(root, receipt) + if err != nil { + return err + } + } candidates := make(map[string]ArchiveCandidate, len(receipt.Candidates)) laneRecords := map[string]bool{} leaseCounts := map[string]int{} @@ -544,15 +565,28 @@ func (store Store) ValidateArchiveFiles(receipt ArchiveReceipt) error { if err != nil { return err } - if live == stored { - return fail.New("ARCHIVE_FAILED", "archive receipt file exists on both sides or neither side: "+relative) - } - if receipt.State == "complete" && !stored || receipt.State == "restored" && !live { - return fail.New("ARCHIVE_FAILED", "archive receipt file is on the wrong side for state "+receipt.State+": "+relative) - } source := relative - if stored { - source = archived + if receipt.State == "restored" { + historical, rearchived := historicalSources[relative] + if stored { + return fail.New("ARCHIVE_FAILED", "archive receipt file is on the wrong side for state restored: "+relative) + } + if live == rearchived { + return fail.New("ARCHIVE_FAILED", "restored archive receipt file exists live and in a successor archive, or in neither location: "+relative) + } + if rearchived { + source = historical + } + } else { + if live == stored { + return fail.New("ARCHIVE_FAILED", "archive receipt file exists on both sides or neither side: "+relative) + } + if receipt.State == "complete" && !stored { + return fail.New("ARCHIVE_FAILED", "archive receipt file is on the wrong side for state "+receipt.State+": "+relative) + } + if stored { + source = archived + } } parts := strings.Split(relative, "/") id := strings.TrimSuffix(parts[1], ".json") @@ -607,6 +641,63 @@ func (store Store) ValidateArchiveFiles(receipt ArchiveReceipt) error { return nil } +// restoredArchiveSources resolves records that a later validated receipt has +// archived again. Restored receipts remain durable history, so a missing live +// record is valid only when exactly one newer non-restored receipt owns it. +func (store Store) restoredArchiveSources(root *os.Root, receipt ArchiveReceipt) (map[string]string, error) { + targets := make(map[string]bool, len(receipt.Files)) + for _, relative := range receipt.Files { + targets[relative] = true + } + sources := make(map[string]string, len(receipt.Files)) + entries, err := rootDirectoryEntries(root, "archive", maxRecordEntries) + if err != nil { + return nil, err + } + for _, entry := range entries { + if !entry.IsDir() || entry.Type()&os.ModeSymlink != 0 { + return nil, fail.New("ARCHIVE_FAILED", "archive batch is not a regular directory: "+entry.Name()) + } + if entry.Name() == receipt.ID { + continue + } + other, err := loadArchiveReceipt(store.Root, entry.Name()) + if err != nil { + return nil, err + } + if other.State == "restored" || !other.CreatedAt.After(receipt.UpdatedAt) { + continue + } + intersecting := make([]string, 0) + for _, relative := range other.Files { + if targets[relative] { + intersecting = append(intersecting, relative) + } + } + if len(intersecting) == 0 { + continue + } + if err := store.ValidateArchiveFiles(other); err != nil { + return nil, err + } + for _, relative := range intersecting { + archived := filepath.ToSlash(filepath.Join("archive", other.ID, filepath.FromSlash(relative))) + stored, err := archiveRegularExists(root, archived) + if err != nil { + return nil, err + } + if !stored { + continue + } + if _, duplicate := sources[relative]; duplicate { + return nil, fail.New("ARCHIVE_FAILED", "restored archive receipt file has multiple successor owners: "+relative) + } + sources[relative] = archived + } + } + return sources, nil +} + func validateArchiveBatchContents(root *os.Root, receipt ArchiveReceipt) error { batch := filepath.ToSlash(filepath.Join("archive", receipt.ID)) entries, err := rootDirectoryEntries(root, batch, 4) diff --git a/internal/store/domain_upgrade.go b/internal/store/domain_upgrade.go new file mode 100644 index 0000000..0002352 --- /dev/null +++ b/internal/store/domain_upgrade.go @@ -0,0 +1,114 @@ +package store + +import ( + "crypto/sha256" + "encoding/hex" + "encoding/json" + "errors" + "os" + "path/filepath" + + "github.com/nstranquist/wip-commit/internal/atomicfile" + "github.com/nstranquist/wip-commit/internal/fail" + "github.com/nstranquist/wip-commit/internal/filelock" + "github.com/nstranquist/wip-commit/internal/gitx" + "github.com/nstranquist/wip-commit/internal/safeio" +) + +type DomainUpgradePlan struct { + Path string + CurrentSHA256 string + DesiredSHA256 string + CurrentSchema int + DesiredSchema int + AlreadyCurrent bool + UpgradeRequired bool +} + +// InspectDomainUpgrade creates a byte-bound domain-marker plan without writes. +func InspectDomainUpgrade(repo gitx.Repo) (DomainUpgradePlan, error) { + laneStore, initialized, err := Inspect(repo) + if err != nil { + return DomainUpgradePlan{}, err + } + if !initialized || !laneStore.Domain.MarkerExists { + return DomainUpgradePlan{}, fail.New("STATE_NOT_INITIALIZED", "coordination state has no domain marker; run wip init instead") + } + return inspectDomainUpgrade(repo, laneStore.Domain) +} + +// ApplyDomainUpgrade replaces only the exact marker reviewed by the caller. +// The coordination lock serializes marker creation and other domain upgrades. +func ApplyDomainUpgrade(repo gitx.Repo, expectedCurrentSHA256 string) (DomainUpgradePlan, error) { + lock, err := filelock.Acquire(filepath.Join(repo.CommonDir, "wip-coordination.lock"), filelock.DefaultWait) + if err != nil { + return DomainUpgradePlan{}, fail.Wrap("LOCK_TIMEOUT", err) + } + defer func() { _ = lock.Release() }() + laneStore, initialized, err := Inspect(repo) + if err != nil { + return DomainUpgradePlan{}, err + } + if !initialized || !laneStore.Domain.MarkerExists { + return DomainUpgradePlan{}, fail.New("STATE_NOT_INITIALIZED", "coordination state has no domain marker; run wip init instead") + } + plan, err := inspectDomainUpgrade(repo, laneStore.Domain) + if err != nil { + return DomainUpgradePlan{}, err + } + if expectedCurrentSHA256 == "" || plan.CurrentSHA256 != expectedCurrentSHA256 { + return DomainUpgradePlan{}, fail.New("UPGRADE_PLAN_MOVED", "domain marker changed after preview; review a new upgrade plan") + } + if plan.AlreadyCurrent { + return plan, nil + } + body, err := currentDomainBody() + if err != nil { + return DomainUpgradePlan{}, err + } + if err := atomicfile.Write(plan.Path, body, 0o600); err != nil { + return DomainUpgradePlan{}, fail.Wrap("UPGRADE_FAILED", err) + } + verified, err := inspectDomainUpgrade(repo, domainMetadata(currentDomainRecord(), true)) + if err != nil { + return DomainUpgradePlan{}, err + } + if verified.CurrentSHA256 != plan.DesiredSHA256 || !verified.AlreadyCurrent { + return DomainUpgradePlan{}, fail.New("UPGRADE_FAILED", "domain marker verification failed after atomic replacement") + } + return verified, nil +} + +func inspectDomainUpgrade(repo gitx.Repo, metadata DomainMetadata) (DomainUpgradePlan, error) { + path := filepath.Join(repo.CommonDir, "wip", "domain.json") + current, err := safeio.ReadRegular(path, 64<<10) + if errors.Is(err, os.ErrNotExist) { + return DomainUpgradePlan{}, fail.New("STATE_NOT_INITIALIZED", "coordination state has no domain marker; run wip init instead") + } + if err != nil { + return DomainUpgradePlan{}, fail.Wrap("STORE_FAILED", err) + } + desired, err := currentDomainBody() + if err != nil { + return DomainUpgradePlan{}, err + } + currentDigest, desiredDigest := digestBytes(current), digestBytes(desired) + return DomainUpgradePlan{ + Path: path, CurrentSHA256: currentDigest, DesiredSHA256: desiredDigest, + CurrentSchema: metadata.SchemaVersion, DesiredSchema: domainSchemaVersion, + AlreadyCurrent: currentDigest == desiredDigest, UpgradeRequired: metadata.UpgradeRequired, + }, nil +} + +func currentDomainBody() ([]byte, error) { + body, err := json.MarshalIndent(currentDomainRecord(), "", " ") + if err != nil { + return nil, fail.Wrap("UPGRADE_FAILED", err) + } + return append(body, '\n'), nil +} + +func digestBytes(body []byte) string { + digest := sha256.Sum256(body) + return "sha256:" + hex.EncodeToString(digest[:]) +} diff --git a/internal/store/domain_upgrade_test.go b/internal/store/domain_upgrade_test.go new file mode 100644 index 0000000..ffacc28 --- /dev/null +++ b/internal/store/domain_upgrade_test.go @@ -0,0 +1,50 @@ +package store + +import ( + "encoding/json" + "os" + "path/filepath" + "testing" + + "github.com/nstranquist/wip-commit/internal/fail" +) + +func TestDomainUpgradeIsExactAndIdempotent(t *testing.T) { + repo := testRepo(t) + if _, err := Open(repo); err != nil { + t.Fatal(err) + } + marker := filepath.Join(repo.CommonDir, "wip", "domain.json") + legacy, err := json.MarshalIndent(domainRecord{SchemaVersion: legacyDomainSchemaVersion, Domain: domainID, StateVersion: SchemaVersion}, "", " ") + if err != nil { + t.Fatal(err) + } + if err := os.WriteFile(marker, append(legacy, '\n'), 0o600); err != nil { + t.Fatal(err) + } + plan, err := InspectDomainUpgrade(repo) + if err != nil || !plan.UpgradeRequired || plan.AlreadyCurrent || plan.CurrentSHA256 == plan.DesiredSHA256 { + t.Fatalf("legacy plan = %#v err=%v", plan, err) + } + if _, err := ApplyDomainUpgrade(repo, "sha256:"+string(make([]byte, 64))); fail.Code(err) != "UPGRADE_PLAN_MOVED" { + t.Fatalf("moved plan error = %v (%s)", err, fail.Code(err)) + } + applied, err := ApplyDomainUpgrade(repo, plan.CurrentSHA256) + if err != nil || !applied.AlreadyCurrent || applied.CurrentSHA256 != plan.DesiredSHA256 { + t.Fatalf("applied plan = %#v err=%v", applied, err) + } + opened, err := Open(repo) + if err != nil || opened.Domain.UpgradeRequired || opened.Domain.SchemaVersion != domainSchemaVersion { + t.Fatalf("upgraded store = %#v err=%v", opened.Domain, err) + } + if replay, err := ApplyDomainUpgrade(repo, plan.DesiredSHA256); err != nil || !replay.AlreadyCurrent { + t.Fatalf("idempotent apply = %#v err=%v", replay, err) + } +} + +func TestDomainUpgradeRequiresExistingMarker(t *testing.T) { + repo := testRepo(t) + if _, err := InspectDomainUpgrade(repo); fail.Code(err) != "STATE_NOT_INITIALIZED" { + t.Fatalf("missing marker error = %v (%s)", err, fail.Code(err)) + } +} diff --git a/internal/store/store.go b/internal/store/store.go index ccbf52d..58bf9a7 100644 --- a/internal/store/store.go +++ b/internal/store/store.go @@ -10,12 +10,14 @@ import ( "os" "path/filepath" "regexp" + "slices" "sort" "strconv" "strings" "time" "github.com/nstranquist/wip-commit/internal/atomicfile" + "github.com/nstranquist/wip-commit/internal/contract" "github.com/nstranquist/wip-commit/internal/fail" "github.com/nstranquist/wip-commit/internal/filelock" "github.com/nstranquist/wip-commit/internal/gitx" @@ -26,13 +28,14 @@ import ( ) const ( - SchemaVersion = 1 - DefaultLeaseTTL = 15 * time.Minute - maxRecordBytes = 1 << 20 - maxStateEntries = 32 - maxRecordEntries = 10_000 - domainSchemaVersion = 1 - domainID = "github.com/nstranquist/wip-commit" + SchemaVersion = 1 + DefaultLeaseTTL = 15 * time.Minute + maxRecordBytes = 1 << 20 + maxStateEntries = 32 + maxRecordEntries = 10_000 + legacyDomainSchemaVersion = 1 + domainSchemaVersion = 2 + domainID = "github.com/nstranquist/wip-commit" ) var ( @@ -98,46 +101,70 @@ type CreateOptions struct { } type Store struct { - Repo gitx.Repo - Root string - LeaseTTL time.Duration + Repo gitx.Repo + Root string + LeaseTTL time.Duration + Domain DomainMetadata + writerFence *WriterFence +} + +type DomainMetadata struct { + SchemaVersion int + Domain string + StateVersion int + MinimumReaderProtocol string + RequiredCapabilities []string + MarkerExists bool + UpgradeRequired bool } func Open(repo gitx.Repo) (Store, error) { - coordinationLock, err := filelock.Acquire(filepath.Join(repo.CommonDir, "wip-coordination.lock"), 0) + coordinationLock, err := AcquireWriterFence(repo, filelock.DefaultWait) if err != nil { - return Store{}, fail.Wrap("LOCK_TIMEOUT", err) + return Store{}, err } defer func() { _ = coordinationLock.Release() }() - root, err := prepareStateRoot(repo, true) + return openWithWriterFence(repo, nil) +} + +// OpenWithWriterFence prepares the store under a command-scoped writer token. +// The caller must retain and release the token only after the full command has +// completed all mutation and post-write verification. +func OpenWithWriterFence(repo gitx.Repo, fence *WriterFence) (Store, error) { + if !fence.validFor(repo) { + return Store{}, fail.New("WRITER_FENCE_REQUIRED", "store mutation requires the exact repository writer fence") + } + if err := refuseActiveMigrationFence(repo.CommonDir); err != nil { + return Store{}, err + } + return openWithWriterFence(repo, fence) +} + +func openWithWriterFence(repo gitx.Repo, fence *WriterFence) (Store, error) { + root, domain, _, err := prepareStateRoot(repo, true) if err != nil { return Store{}, err } - return Store{Repo: repo, Root: root, LeaseTTL: DefaultLeaseTTL}, nil + return Store{Repo: repo, Root: root, LeaseTTL: DefaultLeaseTTL, Domain: domain, writerFence: fence}, nil } // Check validates the coordination domain and existing state without creating // files or directories. It is suitable for init preflight and dry-run. func Check(repo gitx.Repo) error { - _, err := prepareStateRoot(repo, false) + _, _, _, err := prepareStateRoot(repo, false) return err } // Inspect opens existing state read-only. It never creates a marker, state // directory, lock, lane, or lease. func Inspect(repo gitx.Repo) (Store, bool, error) { - if err := Check(repo); err != nil { + root, domain, markerExists, err := prepareStateRoot(repo, false) + if err != nil { return Store{}, false, err } - root := filepath.Join(repo.CommonDir, "wip", fmt.Sprintf("v%d", SchemaVersion)) info, err := os.Lstat(root) if errors.Is(err, os.ErrNotExist) { - if _, markerErr := os.Lstat(filepath.Join(repo.CommonDir, "wip", "domain.json")); errors.Is(markerErr, os.ErrNotExist) { - return Store{Repo: repo, Root: root, LeaseTTL: DefaultLeaseTTL}, false, nil - } else if markerErr != nil { - return Store{}, false, fail.Wrap("STORE_FAILED", markerErr) - } - return Store{Repo: repo, Root: root, LeaseTTL: DefaultLeaseTTL}, true, nil + return Store{Repo: repo, Root: root, LeaseTTL: DefaultLeaseTTL, Domain: domain}, markerExists, nil } if err != nil { return Store{}, false, fail.Wrap("STORE_FAILED", err) @@ -145,82 +172,127 @@ func Inspect(repo gitx.Repo) (Store, bool, error) { if !info.IsDir() || info.Mode()&os.ModeSymlink != 0 { return Store{}, false, fail.New("STORE_FAILED", "wip state version root is not a regular directory") } - return Store{Repo: repo, Root: root, LeaseTTL: DefaultLeaseTTL}, true, nil + return Store{Repo: repo, Root: root, LeaseTTL: DefaultLeaseTTL, Domain: domain}, true, nil } type domainRecord struct { - SchemaVersion int `json:"schema_version"` - Domain string `json:"domain"` - StateVersion int `json:"state_version"` + SchemaVersion int `json:"schema_version"` + Domain string `json:"domain"` + StateVersion int `json:"state_version"` + MinimumReaderProtocol string `json:"minimum_reader_protocol,omitempty"` + RequiredCapabilities []string `json:"required_capabilities,omitempty"` +} + +func currentDomainRecord() domainRecord { + return domainRecord{ + SchemaVersion: domainSchemaVersion, + Domain: domainID, + StateVersion: SchemaVersion, + MinimumReaderProtocol: contract.Protocol, + RequiredCapabilities: contract.StateReaderCapabilities(), + } +} + +func domainMetadata(marker domainRecord, exists bool) DomainMetadata { + return DomainMetadata{ + SchemaVersion: marker.SchemaVersion, + Domain: marker.Domain, + StateVersion: marker.StateVersion, + MinimumReaderProtocol: marker.MinimumReaderProtocol, + RequiredCapabilities: slices.Clone(marker.RequiredCapabilities), + MarkerExists: exists, + UpgradeRequired: exists && marker.SchemaVersion == legacyDomainSchemaVersion, + } } -func prepareStateRoot(repo gitx.Repo, create bool) (string, error) { +func prepareStateRoot(repo gitx.Repo, create bool) (string, DomainMetadata, bool, error) { common, err := os.OpenRoot(repo.CommonDir) if err != nil { - return "", fail.Wrap("STORE_FAILED", err) + return "", DomainMetadata{}, false, fail.Wrap("STORE_FAILED", err) } defer func() { _ = common.Close() }() if _, err := common.Lstat("ndev-wip"); err == nil { - return "", fail.New("COORDINATION_DOMAIN_CONFLICT", "legacy ndev-wip state exists; stop all lane processes and migrate or archive that domain before using standalone wip") + return "", DomainMetadata{}, false, fail.New("COORDINATION_DOMAIN_CONFLICT", "legacy ndev-wip state exists; stop all lane processes and migrate or archive that domain before using standalone wip") } else if !errors.Is(err, os.ErrNotExist) { - return "", fail.Wrap("STORE_FAILED", err) + return "", DomainMetadata{}, false, fail.Wrap("STORE_FAILED", err) } stateExists, err := ensureDirectory(common, "wip", create) if err != nil { - return "", err + return "", DomainMetadata{}, false, err } stateRoot := filepath.Join(repo.CommonDir, "wip") root := filepath.Join(stateRoot, fmt.Sprintf("v%d", SchemaVersion)) if !stateExists { - return root, nil + return root, domainMetadata(currentDomainRecord(), false), false, nil } if err := validateStateDirectories(common, "wip"); err != nil { - return "", err + return "", DomainMetadata{}, false, err } versionPath := fmt.Sprintf("wip/v%d", SchemaVersion) versionExists, err := ensureDirectory(common, versionPath, false) if err != nil { - return "", err + return "", DomainMetadata{}, false, err } if versionExists { if err := validateVersionLayout(common, versionPath); err != nil { - return "", err + return "", DomainMetadata{}, false, err } } markerPath := filepath.Join(stateRoot, "domain.json") markerBody, markerErr := safeio.ReadRegular(markerPath, 64<<10) + markerExists := markerErr == nil if errors.Is(markerErr, os.ErrNotExist) { if !create { - return root, nil + return root, domainMetadata(currentDomainRecord(), false), false, nil } - marker := domainRecord{SchemaVersion: domainSchemaVersion, Domain: domainID, StateVersion: SchemaVersion} + marker := currentDomainRecord() body, marshalErr := json.MarshalIndent(marker, "", " ") if marshalErr != nil { - return "", fail.Wrap("STORE_FAILED", marshalErr) + return "", DomainMetadata{}, false, fail.Wrap("STORE_FAILED", marshalErr) } if createErr := atomicfile.Create(markerPath, append(body, '\n'), 0o600); createErr != nil && !errors.Is(createErr, atomicfile.ErrExists) { - return "", fail.Wrap("STORE_FAILED", createErr) + return "", DomainMetadata{}, false, fail.Wrap("STORE_FAILED", createErr) } markerBody, markerErr = safeio.ReadRegular(markerPath, 64<<10) + markerExists = markerErr == nil } if markerErr != nil { - return "", fail.Wrap("STORE_FAILED", markerErr) + return "", DomainMetadata{}, false, fail.Wrap("STORE_FAILED", markerErr) + } + var header struct { + SchemaVersion int `json:"schema_version"` + } + if err := json.Unmarshal(markerBody, &header); err != nil { + return "", DomainMetadata{}, false, fail.Wrap("STORE_FAILED", err) + } + if header.SchemaVersion != legacyDomainSchemaVersion && header.SchemaVersion != domainSchemaVersion { + return "", DomainMetadata{}, false, fail.Errorf("MIGRATION_REQUIRED", "domain marker schema version %d is unsupported; this wip release supports versions %d and %d", header.SchemaVersion, legacyDomainSchemaVersion, domainSchemaVersion) } var marker domainRecord if err := strictjson.Decode(markerBody, &marker); err != nil { - return "", fail.Wrap("STORE_FAILED", err) + return "", DomainMetadata{}, false, fail.Wrap("STORE_FAILED", err) } if marker.Domain != domainID { - return "", fail.New("COORDINATION_DOMAIN_CONFLICT", "wip state is owned by an unsupported coordination domain") - } - if marker.SchemaVersion != domainSchemaVersion { - return "", fail.Errorf("MIGRATION_REQUIRED", "domain marker schema version %d is unsupported; this wip release supports version %d", marker.SchemaVersion, domainSchemaVersion) + return "", DomainMetadata{}, false, fail.New("COORDINATION_DOMAIN_CONFLICT", "wip state is owned by an unsupported coordination domain") } if marker.StateVersion != SchemaVersion { - return "", fail.Errorf("MIGRATION_REQUIRED", "state domain owns v%d; this wip release supports v%d", marker.StateVersion, SchemaVersion) + return "", DomainMetadata{}, false, fail.Errorf("MIGRATION_REQUIRED", "state domain owns v%d; this wip release supports v%d", marker.StateVersion, SchemaVersion) + } + if marker.SchemaVersion == domainSchemaVersion { + if marker.MinimumReaderProtocol == "" || len(marker.RequiredCapabilities) == 0 || !slices.IsSorted(marker.RequiredCapabilities) || len(marker.RequiredCapabilities) != len(slices.Compact(slices.Clone(marker.RequiredCapabilities))) { + return "", DomainMetadata{}, false, fail.New("STORE_FAILED", "domain reader-floor contract is empty, unsorted, or duplicated") + } + if err := contract.MeetsProtocolFloor(contract.Protocol, marker.MinimumReaderProtocol); err != nil { + return "", DomainMetadata{}, false, fail.Wrap("MIGRATION_REQUIRED", err) + } + if err := contract.Supports(marker.RequiredCapabilities); err != nil { + return "", DomainMetadata{}, false, fail.Wrap("MIGRATION_REQUIRED", err) + } + } else if create { + return "", DomainMetadata{}, false, fail.New("MIGRATION_REQUIRED", "legacy coordination marker is read-only; review and apply wip upgrade --state before mutation") } if !create { - return root, nil + return root, domainMetadata(marker, markerExists), markerExists, nil } paths := []string{fmt.Sprintf("wip/v%d", SchemaVersion)} for _, directory := range []string{"lanes", "leases", "locks", "intents", "profiles", "init-intents", "archive"} { @@ -228,10 +300,10 @@ func prepareStateRoot(repo gitx.Repo, create bool) (string, error) { } for _, path := range paths { if _, err := ensureDirectory(common, path, true); err != nil { - return "", err + return "", DomainMetadata{}, false, err } } - return root, nil + return root, domainMetadata(marker, markerExists), markerExists, nil } func ensureDirectory(root *os.Root, path string, create bool) (bool, error) { @@ -331,6 +403,22 @@ func (store Store) LaneLock(id string, wait time.Duration) (*filelock.Lock, erro return lock, nil } +// ExistingLaneLock acquires an existing lane lock without changing its file. +// Lane creation always publishes this lock before the lane becomes active. +func (store Store) ExistingLaneLock(id string, wait time.Duration) (*filelock.Lock, error) { + if err := validateID(id, "lane"); err != nil { + return nil, err + } + lock, err := filelock.AcquireExisting(filepath.Join(store.Root, "locks", "lane-"+id+".lock"), wait) + if err != nil { + return nil, fail.Wrap("LOCK_TIMEOUT", err) + } + return lock, nil +} + +// The registry fence serializes operational lane and lease records. Windows +// can reject an open while another process atomically replaces a record. A +// caller that also needs a lane lock must acquire the lane lock first. func (store Store) registryLock(wait time.Duration) (*filelock.Lock, error) { lock, err := filelock.Acquire(filepath.Join(store.Root, "locks", "leases.lock"), wait) if err != nil { @@ -339,7 +427,22 @@ func (store Store) registryLock(wait time.Duration) (*filelock.Lock, error) { return lock, nil } +// existingRegistryLock serializes a read without creating the lock or +// rewriting its owner record. Lane creation publishes leases.lock before an +// active lane becomes visible. A missing or replaced lock therefore means the +// state is incomplete and the reader must fail closed. +func (store Store) existingRegistryLock(wait time.Duration) (*filelock.Lock, error) { + lock, err := filelock.AcquireExisting(filepath.Join(store.Root, "locks", "leases.lock"), wait) + if err != nil { + return nil, fail.Wrap("LOCK_TIMEOUT", err) + } + return lock, nil +} + func (store Store) Create(ctx context.Context, options CreateOptions) (Lane, error) { + if !store.WriterFenced() { + return withWriterFence(store, func(fenced Store) (Lane, error) { return fenced.Create(ctx, options) }) + } for label, value := range map[string]string{"lane": options.ID, "agent": options.Agent, "session": options.Session} { if err := validateID(value, label); err != nil { return Lane{}, err @@ -377,12 +480,12 @@ func (store Store) Create(ctx context.Context, options CreateOptions) (Lane, err if _, err := store.Repo.Text(ctx, nil, "check-ref-format", ref); err != nil { return Lane{}, fail.Wrap("INVALID_REF", err) } - lock, err := store.LaneLock(options.ID, 0) + lock, err := store.LaneLock(options.ID, filelock.DefaultWait) if err != nil { return Lane{}, err } defer func() { _ = lock.Release() }() - registry, registryErr := store.registryLock(0) + registry, registryErr := store.registryLock(filelock.DefaultWait) if registryErr != nil { return Lane{}, registryErr } @@ -394,7 +497,7 @@ func (store Store) Create(ctx context.Context, options CreateOptions) (Lane, err } candidate := Lane{SchemaVersion: SchemaVersion, ID: options.ID, Agent: options.Agent, Session: options.Session, Mode: options.Mode, Ref: ref, BaseRef: options.BaseRef, BaseSHA: base, CurrentSHA: base, Worktree: worktree, State: "creating"} if _, statErr := os.Stat(store.lanePath(options.ID)); statErr == nil { - existing, loadErr := store.Load(options.ID) + existing, loadErr := store.loadLane(options.ID) if loadErr != nil { return Lane{}, loadErr } @@ -433,18 +536,21 @@ func (store Store) finishCreate(ctx context.Context, lane Lane) (Lane, error) { } func (store Store) Claim(id, agent, session string, paths []string) (Lease, error) { + if !store.WriterFenced() { + return withWriterFence(store, func(fenced Store) (Lease, error) { return fenced.Claim(id, agent, session, paths) }) + } if err := validateID(agent, "agent"); err != nil { return Lease{}, err } if err := validateID(session, "session"); err != nil { return Lease{}, err } - lock, err := store.LaneLock(id, 0) + lock, err := store.LaneLock(id, filelock.DefaultWait) if err != nil { return Lease{}, err } defer func() { _ = lock.Release() }() - lane, err := store.Load(id) + lane, err := store.loadLane(id) if err != nil { return Lease{}, err } @@ -458,7 +564,7 @@ func (store Store) Claim(id, agent, session string, paths []string) (Lease, erro if len(normalized) == 0 { return Lease{}, fail.New("INVALID_ARGS", "at least one path is required") } - registry, err := store.registryLock(0) + registry, err := store.registryLock(filelock.DefaultWait) if err != nil { return Lease{}, err } @@ -533,19 +639,48 @@ func (store Store) Claim(id, agent, session string, paths []string) (Lease, erro } func (store Store) Renew(id, agent, session string) ([]Lease, error) { - lock, err := store.LaneLock(id, 0) + if !store.WriterFenced() { + return withWriterFence(store, func(fenced Store) ([]Lease, error) { return fenced.Renew(id, agent, session) }) + } + lock, err := store.LaneLock(id, filelock.DefaultWait) if err != nil { return nil, err } defer func() { _ = lock.Release() }() - lane, err := store.Load(id) + lane, err := store.loadLane(id) if err != nil { return nil, err } if err := ownedActive(lane, agent, session); err != nil { return nil, err } - registry, err := store.registryLock(0) + return store.renewLocked(lane) +} + +// RenewWithLockHeld extends every active lease for expected. The caller must +// hold expected's lane lock for the complete call. +func (store Store) RenewWithLockHeld(expected Lane) ([]Lease, error) { + if err := store.requireWriterFence(); err != nil { + return nil, err + } + lane, err := store.Load(expected.ID) + if err != nil { + return nil, err + } + if !sameLaneSnapshot(lane, expected) { + return nil, fail.New("LANE_MOVED", "lane changed before its leases could be renewed") + } + if err := ownedActive(lane, expected.Agent, expected.Session); err != nil { + return nil, err + } + if lane.Worktree != store.Repo.Root { + return nil, fail.New("WORKTREE_MISMATCH", "lane is bound to a different checkout") + } + return store.renewLocked(lane) +} + +func (store Store) renewLocked(lane Lane) ([]Lease, error) { + registry, err := store.registryLock(filelock.DefaultWait) if err != nil { return nil, err } @@ -563,7 +698,7 @@ func (store Store) Renew(id, agent, session string) ([]Lease, error) { } var renewed []Lease for _, lease := range leases { - if lease.LaneID != id || !activeLease(lease, now) { + if lease.LaneID != lane.ID || !activeLease(lease, now) { continue } expires := now.Add(store.leaseTTL()) @@ -580,6 +715,15 @@ func (store Store) Renew(id, agent, session string) ([]Lease, error) { } func (store Store) Current(agent, session, id string) (Status, error) { + registry, err := store.existingRegistryLock(filelock.DefaultWait) + if err != nil { + return Status{}, err + } + defer func() { _ = registry.Release() }() + return store.currentLocked(agent, session, id) +} + +func (store Store) currentLocked(agent, session, id string) (Status, error) { entries, err := readRecordEntries(filepath.Join(store.Root, "lanes")) if err != nil { return Status{}, fail.Wrap("STORE_FAILED", err) @@ -590,7 +734,7 @@ func (store Store) Current(agent, session, id string) (Status, error) { if entryErr != nil { return Status{}, entryErr } - lane, loadErr := store.Load(fileID) + lane, loadErr := store.loadLane(fileID) if loadErr != nil { return Status{}, loadErr } @@ -613,11 +757,20 @@ func (store Store) Current(agent, session, id string) (Status, error) { sort.Strings(ids) return Status{}, fail.New("LANE_AMBIGUOUS", "multiple lanes match; select one: "+strings.Join(ids, ", ")) } - return store.Status(matches[0].ID) + return store.statusLocked(matches[0].ID) } func (store Store) Status(id string) (Status, error) { - lane, err := store.Load(id) + registry, err := store.existingRegistryLock(filelock.DefaultWait) + if err != nil { + return Status{}, err + } + defer func() { _ = registry.Release() }() + return store.statusLocked(id) +} + +func (store Store) statusLocked(id string) (Status, error) { + lane, err := store.loadLane(id) if err != nil { return Status{}, err } @@ -626,6 +779,27 @@ func (store Store) Status(id string) (Status, error) { } func (store Store) Load(id string) (Lane, error) { + if err := validateID(id, "lane"); err != nil { + return Lane{}, err + } + // A new store has no registry lock until its first lane transaction. Return + // the stable absence result without creating that lock. If the lane record + // exists, the published registry lock is mandatory and the read fails + // closed when it is missing. + if _, err := os.Lstat(store.lanePath(id)); errors.Is(err, os.ErrNotExist) { + return Lane{}, fail.New("LANE_NOT_FOUND", "lane not found: "+id) + } else if err != nil { + return Lane{}, fail.Wrap("STORE_FAILED", err) + } + registry, err := store.existingRegistryLock(filelock.DefaultWait) + if err != nil { + return Lane{}, err + } + defer func() { _ = registry.Release() }() + return store.loadLane(id) +} + +func (store Store) loadLane(id string) (Lane, error) { if err := validateID(id, "lane"); err != nil { return Lane{}, err } @@ -647,6 +821,15 @@ func (store Store) Load(id string) (Lane, error) { } func (store Store) LoadLease(id string) (Lease, error) { + registry, err := store.existingRegistryLock(filelock.DefaultWait) + if err != nil { + return Lease{}, err + } + defer func() { _ = registry.Release() }() + return store.loadLease(id) +} + +func (store Store) loadLease(id string) (Lease, error) { if err := validateID(id, "lease"); err != nil { return Lease{}, err } @@ -668,6 +851,15 @@ func (store Store) LoadLease(id string) (Lease, error) { } func (store Store) ActivePaths(id string) ([]string, error) { + registry, err := store.existingRegistryLock(filelock.DefaultWait) + if err != nil { + return nil, err + } + defer func() { _ = registry.Release() }() + return store.activePathsLocked(id) +} + +func (store Store) activePathsLocked(id string) ([]string, error) { leases, err := store.leases(id, true) if err != nil { return nil, err @@ -681,12 +873,12 @@ func (store Store) ActivePaths(id string) ([]string, error) { } func (store Store) ValidateCapture(ctx context.Context, expected Lane, expectedPaths []string) error { - registry, err := store.registryLock(0) + registry, err := store.existingRegistryLock(filelock.DefaultWait) if err != nil { return err } defer func() { _ = registry.Release() }() - current, err := store.Load(expected.ID) + current, err := store.loadLane(expected.ID) if err != nil { return err } @@ -717,12 +909,18 @@ func (store Store) ValidateCapture(ctx context.Context, expected Lane, expectedP // active lease while the caller holds the lane lock. The registry lock prevents // another lane from claiming an expired path between validation and renewal. func (store Store) RefreshCaptureLease(ctx context.Context, expected Lane, expectedPaths []string) error { - registry, err := store.registryLock(0) + if !store.WriterFenced() { + _, err := withWriterFence(store, func(fenced Store) (struct{}, error) { + return struct{}{}, fenced.RefreshCaptureLease(ctx, expected, expectedPaths) + }) + return err + } + registry, err := store.registryLock(filelock.DefaultWait) if err != nil { return err } defer func() { _ = registry.Release() }() - current, err := store.Load(expected.ID) + current, err := store.loadLane(expected.ID) if err != nil { return err } @@ -940,7 +1138,18 @@ func (store Store) validateCaptureIdentity(ctx context.Context, current, expecte } func (store Store) RecordCommit(ctx context.Context, id, commit string) error { - lane, err := store.Load(id) + if !store.WriterFenced() { + _, err := withWriterFence(store, func(fenced Store) (struct{}, error) { + return struct{}{}, fenced.RecordCommit(ctx, id, commit) + }) + return err + } + registry, err := store.registryLock(filelock.DefaultWait) + if err != nil { + return err + } + defer func() { _ = registry.Release() }() + lane, err := store.loadLane(id) if err != nil { return err } @@ -970,16 +1179,17 @@ func (store Store) RecordCommit(ctx context.Context, id, commit string) error { } func (store Store) Release(id, agent, session string, abort bool) error { - lock, err := store.LaneLock(id, 0) - if err != nil { + if !store.WriterFenced() { + _, err := withWriterFence(store, func(fenced Store) (struct{}, error) { + return struct{}{}, fenced.Release(id, agent, session, abort) + }) return err } - defer func() { _ = lock.Release() }() - registry, err := store.registryLock(0) + lock, err := store.LaneLock(id, filelock.DefaultWait) if err != nil { return err } - defer func() { _ = registry.Release() }() + defer func() { _ = lock.Release() }() lane, err := store.Load(id) if err != nil { return err @@ -987,6 +1197,34 @@ func (store Store) Release(id, agent, session string, abort bool) error { if lane.Agent != agent || lane.Session != session { return fail.New("IDENTITY_MISMATCH", "lane belongs to another agent or session") } + return store.releaseLocked(lane, abort) +} + +// ReleaseWithLockHeld releases expected and its leases. The caller must hold +// expected's lane lock for the complete call. +func (store Store) ReleaseWithLockHeld(expected Lane, abort bool) error { + if err := store.requireWriterFence(); err != nil { + return err + } + lane, err := store.Load(expected.ID) + if err != nil { + return err + } + if !sameLaneSnapshot(lane, expected) { + return fail.New("LANE_MOVED", "lane changed before it could be released") + } + if lane.Worktree != store.Repo.Root { + return fail.New("WORKTREE_MISMATCH", "lane is bound to a different checkout") + } + return store.releaseLocked(lane, abort) +} + +func (store Store) releaseLocked(lane Lane, abort bool) error { + registry, err := store.registryLock(filelock.DefaultWait) + if err != nil { + return err + } + defer func() { _ = registry.Release() }() now := time.Now().UTC() leases, err := store.leases("", false) if err != nil { @@ -996,7 +1234,7 @@ func (store Store) Release(id, agent, session string, abort bool) error { return err } for _, lease := range leases { - if lease.LaneID != id || lease.State != "active" { + if lease.LaneID != lane.ID || lease.State != "active" { continue } lease.State, lease.UpdatedAt, lease.ReleasedAt = "released", now, &now @@ -1012,6 +1250,24 @@ func (store Store) Release(id, agent, session string, abort bool) error { return store.writeLane(lane) } +func sameLaneSnapshot(left, right Lane) bool { + return left.SchemaVersion == right.SchemaVersion && + left.ID == right.ID && + left.Agent == right.Agent && + left.Session == right.Session && + left.Mode == right.Mode && + left.Ref == right.Ref && + left.BaseRef == right.BaseRef && + left.BaseSHA == right.BaseSHA && + left.CurrentSHA == right.CurrentSHA && + left.Worktree == right.Worktree && + sameStrings(left.LeaseIDs, right.LeaseIDs) && + left.State == right.State && + left.CreatedAt.Equal(right.CreatedAt) && + left.UpdatedAt.Equal(right.UpdatedAt) && + left.LastCommit == right.LastCommit +} + func validateReleaseLeaseLinks(lane Lane, leases []Lease) error { owned := map[string]Lease{} for _, lease := range leases { @@ -1041,7 +1297,7 @@ func (store Store) worktreeConflict(id, worktree string, mode Mode) (string, err if entryErr != nil { return "", entryErr } - lane, loadErr := store.Load(fileID) + lane, loadErr := store.loadLane(fileID) if loadErr != nil { return "", loadErr } @@ -1064,7 +1320,7 @@ func (store Store) leases(laneID string, activeOnly bool) ([]Lease, error) { if entryErr != nil { return nil, entryErr } - lease, loadErr := store.LoadLease(fileID) + lease, loadErr := store.loadLease(fileID) if loadErr != nil { return nil, loadErr } @@ -1197,6 +1453,13 @@ func (store Store) validateLane(lane Lane, id string) error { return nil } +// ValidateImportedLane applies the exact durable-reader contract without +// creating state. Coordination migration uses it before it publishes a legacy +// record into the canonical store. +func ValidateImportedLane(repo gitx.Repo, lane Lane) error { + return (Store{Repo: repo}).validateLane(lane, lane.ID) +} + func (store Store) validateLease(lease Lease, id string) error { if lease.SchemaVersion != SchemaVersion { return fail.Errorf("MIGRATION_REQUIRED", "lease schema version %d is unsupported; this wip release supports version %d", lease.SchemaVersion, SchemaVersion) @@ -1219,6 +1482,12 @@ func (store Store) validateLease(lease Lease, id string) error { return nil } +// ValidateImportedLease applies the exact durable-reader contract without +// creating state. It does not renew or otherwise rewrite the lease. +func ValidateImportedLease(repo gitx.Repo, lease Lease) error { + return (Store{Repo: repo}).validateLease(lease, lease.ID) +} + func objectID(value string) bool { if len(value) != 40 && len(value) != 64 { return false diff --git a/internal/store/store_test.go b/internal/store/store_test.go index fe706e6..729060f 100644 --- a/internal/store/store_test.go +++ b/internal/store/store_test.go @@ -9,12 +9,14 @@ import ( "os/exec" "path/filepath" "runtime" + "sort" "strings" "sync" "testing" "time" "github.com/nstranquist/wip-commit/internal/atomicfile" + "github.com/nstranquist/wip-commit/internal/contract" "github.com/nstranquist/wip-commit/internal/fail" "github.com/nstranquist/wip-commit/internal/filelock" "github.com/nstranquist/wip-commit/internal/gitx" @@ -59,6 +61,123 @@ func TestConcurrentSharedClaimsAreExclusive(t *testing.T) { } } +func TestOperationalRecordsUseTheRegistryFence(t *testing.T) { + repo := testRepo(t) + laneStore, err := Open(repo) + if err != nil { + t.Fatal(err) + } + lane, err := laneStore.Create(context.Background(), CreateOptions{ID: "registry-reads", Agent: "agent", Session: "session", Mode: ModeShared}) + if err != nil { + t.Fatal(err) + } + lease, err := laneStore.Claim(lane.ID, lane.Agent, lane.Session, []string{"base.txt"}) + if err != nil { + t.Fatal(err) + } + reads := []struct { + name string + run func() error + }{ + {name: "load lane", run: func() error { _, err := laneStore.Load(lane.ID); return err }}, + {name: "load lease", run: func() error { _, err := laneStore.LoadLease(lease.ID); return err }}, + {name: "current", run: func() error { _, err := laneStore.Current(lane.Agent, lane.Session, lane.ID); return err }}, + {name: "status", run: func() error { _, err := laneStore.Status(lane.ID); return err }}, + {name: "active paths", run: func() error { _, err := laneStore.ActivePaths(lane.ID); return err }}, + {name: "archive candidates", run: func() error { _, err := laneStore.ArchiveCandidates(time.Now().UTC().Add(time.Hour)); return err }}, + } + for _, read := range reads { + t.Run(read.name, func(t *testing.T) { + assertWaitsForRegistry(t, laneStore, read.run) + }) + } + tree := git(t, repo.Root, "rev-parse", lane.CurrentSHA+"^{tree}") + commit := git(t, repo.Root, "commit-tree", tree, "-p", lane.CurrentSHA, "-m", "test: advance lane") + git(t, repo.Root, "update-ref", lane.Ref, commit, lane.CurrentSHA) + assertWaitsForRegistry(t, laneStore, func() error { + return laneStore.RecordCommit(context.Background(), lane.ID, commit) + }) +} + +func TestOperationalReadsPreserveRegistryLockBytes(t *testing.T) { + repo := testRepo(t) + laneStore, err := Open(repo) + if err != nil { + t.Fatal(err) + } + lane, err := laneStore.Create(context.Background(), CreateOptions{ID: "registry-read-only", Agent: "agent", Session: "session", Mode: ModeShared}) + if err != nil { + t.Fatal(err) + } + lease, err := laneStore.Claim(lane.ID, lane.Agent, lane.Session, []string{"base.txt"}) + if err != nil { + t.Fatal(err) + } + lockPath := filepath.Join(laneStore.Root, "locks", "leases.lock") + reads := []struct { + name string + run func() error + }{ + {name: "load lane", run: func() error { _, err := laneStore.Load(lane.ID); return err }}, + {name: "load lease", run: func() error { _, err := laneStore.LoadLease(lease.ID); return err }}, + {name: "current", run: func() error { _, err := laneStore.Current(lane.Agent, lane.Session, lane.ID); return err }}, + {name: "status", run: func() error { _, err := laneStore.Status(lane.ID); return err }}, + {name: "active paths", run: func() error { _, err := laneStore.ActivePaths(lane.ID); return err }}, + {name: "validate capture", run: func() error { return laneStore.ValidateCapture(context.Background(), lane, []string{"base.txt"}) }}, + {name: "archive candidates", run: func() error { _, err := laneStore.ArchiveCandidates(time.Now().UTC().Add(time.Hour)); return err }}, + } + for _, read := range reads { + t.Run(read.name, func(t *testing.T) { + before, err := os.ReadFile(lockPath) + if err != nil { + t.Fatal(err) + } + if err := read.run(); err != nil { + t.Fatal(err) + } + after, err := os.ReadFile(lockPath) + if err != nil { + t.Fatal(err) + } + if string(after) != string(before) { + t.Fatalf("read changed registry lock bytes: before=%q after=%q", before, after) + } + }) + } +} + +func assertWaitsForRegistry(t *testing.T, laneStore Store, run func() error) { + t.Helper() + lock, err := laneStore.registryLock(time.Second) + if err != nil { + t.Fatal(err) + } + started := make(chan struct{}) + done := make(chan error, 1) + go func() { + close(started) + done <- run() + }() + <-started + select { + case err := <-done: + _ = lock.Release() + t.Fatalf("operation passed the registry fence: %v", err) + case <-time.After(75 * time.Millisecond): + } + if err := lock.Release(); err != nil { + t.Fatal(err) + } + select { + case err := <-done: + if err != nil { + t.Fatal(err) + } + case <-time.After(5 * time.Second): + t.Fatal("operation did not continue after the registry fence opened") + } +} + func TestClaimIsIdempotentAndExpiredLeaseCannotRenew(t *testing.T) { repo := testRepo(t) laneStore, _ := Open(repo) @@ -483,7 +602,7 @@ func TestInspectReportsMarkerOnlyDomainWithoutCreatingState(t *testing.T) { if err := os.Mkdir(stateRoot, 0o700); err != nil { t.Fatal(err) } - body, err := json.Marshal(domainRecord{SchemaVersion: domainSchemaVersion, Domain: domainID, StateVersion: SchemaVersion}) + body, err := json.Marshal(currentDomainRecord()) if err != nil { t.Fatal(err) } @@ -638,9 +757,60 @@ func TestCoordinationDomainMarkerAndForeignDomainFailClosed(t *testing.T) { if err != nil { t.Fatal(err) } - if !strings.Contains(string(body), domainID) || laneStore.Root != filepath.Join(repo.CommonDir, "wip", "v1") { + if !strings.Contains(string(body), domainID) || !strings.Contains(string(body), `"minimum_reader_protocol": "`+contract.Protocol+`"`) || laneStore.Root != filepath.Join(repo.CommonDir, "wip", "v1") { t.Fatalf("domain marker/root mismatch: %s root=%s", body, laneStore.Root) } + if laneStore.Domain.SchemaVersion != domainSchemaVersion || laneStore.Domain.UpgradeRequired { + t.Fatalf("domain metadata = %#v", laneStore.Domain) + } + }) + + t.Run("legacy marker is read-only", func(t *testing.T) { + repo := testRepo(t) + if _, err := Open(repo); err != nil { + t.Fatal(err) + } + marker := filepath.Join(repo.CommonDir, "wip", "domain.json") + legacy, err := json.MarshalIndent(domainRecord{SchemaVersion: legacyDomainSchemaVersion, Domain: domainID, StateVersion: SchemaVersion}, "", " ") + if err != nil { + t.Fatal(err) + } + legacy = append(legacy, '\n') + if err := os.WriteFile(marker, legacy, 0o600); err != nil { + t.Fatal(err) + } + inspected, initialized, err := Inspect(repo) + if err != nil || !initialized || !inspected.Domain.UpgradeRequired || inspected.Domain.SchemaVersion != legacyDomainSchemaVersion { + t.Fatalf("legacy inspection = %#v initialized=%v err=%v", inspected.Domain, initialized, err) + } + if _, err := Open(repo); fail.Code(err) != "MIGRATION_REQUIRED" { + t.Fatalf("legacy mutation error = %v (%s)", err, fail.Code(err)) + } + body, err := os.ReadFile(marker) + if err != nil || string(body) != string(legacy) { + t.Fatalf("legacy marker changed after refused mutation: %q err=%v", body, err) + } + }) + + t.Run("unsupported reader capability fails closed", func(t *testing.T) { + repo := testRepo(t) + if _, err := Open(repo); err != nil { + t.Fatal(err) + } + marker := filepath.Join(repo.CommonDir, "wip", "domain.json") + current := currentDomainRecord() + current.RequiredCapabilities = append(current.RequiredCapabilities, "state.future.v1") + sort.Strings(current.RequiredCapabilities) + body, err := json.Marshal(current) + if err != nil { + t.Fatal(err) + } + if err := os.WriteFile(marker, body, 0o600); err != nil { + t.Fatal(err) + } + if _, _, err := Inspect(repo); fail.Code(err) != "MIGRATION_REQUIRED" { + t.Fatalf("unsupported capability error = %v (%s)", err, fail.Code(err)) + } }) t.Run("foreign", func(t *testing.T) { @@ -685,7 +855,7 @@ func TestCoordinationDomainMarkerAndForeignDomainFailClosed(t *testing.T) { if err != nil { t.Fatal(err) } - body = []byte(strings.Replace(string(body), `"schema_version": 1`, `"schema_version": 2`, 1)) + body = []byte(strings.Replace(string(body), `"schema_version": 2`, `"schema_version": 3`, 1)) if err := os.WriteFile(marker, body, 0o600); err != nil { t.Fatal(err) } @@ -712,7 +882,7 @@ func TestCoordinationLockPreventsDualDomainCreationRace(t *testing.T) { }() go func() { <-start - lock, err := filelock.Acquire(filepath.Join(repo.CommonDir, "wip-coordination.lock"), 0) + lock, err := filelock.Acquire(filepath.Join(repo.CommonDir, "wip-coordination.lock"), filelock.DefaultWait) if err != nil { results <- "legacy-error:" + err.Error() return @@ -904,6 +1074,50 @@ func TestArchiveIsRecoverableAndResumesPartialMoves(t *testing.T) { if err != nil || again.State != "restored" { t.Fatalf("idempotent restore = %#v err=%v", again, err) } + + secondCutoff := cutoff.Add(time.Second) + secondCandidates, err := laneStore.ArchiveCandidates(secondCutoff) + if err != nil || len(secondCandidates) != 1 { + t.Fatalf("rearchive candidates = %#v err=%v", secondCandidates, err) + } + rearchived, err := laneStore.Archive(context.Background(), secondCutoff, secondCandidates) + if err != nil || rearchived.State != "complete" || rearchived.ID == receipt.ID { + t.Fatalf("rearchive receipt = %#v err=%v; first=%s", rearchived, err, receipt.ID) + } + if err := laneStore.ValidateArchiveFiles(restored); err != nil { + t.Fatalf("restored receipt did not follow rearchived records: %v", err) + } + if err := laneStore.ValidateArchiveFiles(rearchived); err != nil { + t.Fatalf("rearchived receipt placement: %v", err) + } + if _, err := laneStore.Load(lane.ID); fail.Code(err) != "LANE_NOT_FOUND" { + t.Fatalf("rearchive left live lane: %v (%s)", err, fail.Code(err)) + } + + heldRecord := filepath.Join(laneStore.Root, "locks", "held-rearchived-record") + archivedRecord := filepath.Join(laneStore.Root, "archive", rearchived.ID, filepath.FromSlash(rearchived.Files[0])) + if err := os.Rename(archivedRecord, heldRecord); err != nil { + t.Fatal(err) + } + if err := laneStore.ValidateArchiveFiles(restored); fail.Code(err) != "ARCHIVE_FAILED" { + t.Fatalf("missing successor record error = %v (%s)", err, fail.Code(err)) + } + if err := os.Rename(heldRecord, archivedRecord); err != nil { + t.Fatal(err) + } + + secondRestore, err := laneStore.RestoreArchive(context.Background(), rearchived.ID) + if err != nil || secondRestore.State != "restored" { + t.Fatalf("rearchive restore = %#v err=%v", secondRestore, err) + } + for _, historical := range []ArchiveReceipt{restored, secondRestore} { + if err := laneStore.ValidateArchiveFiles(historical); err != nil { + t.Fatalf("restored archive history %s: %v", historical.ID, err) + } + } + if got := git(t, repo.Root, "rev-parse", lane.Ref); got != lane.CurrentSHA { + t.Fatalf("rearchive lifecycle moved lane ref: %s", got) + } } func TestArchiveRejectsCandidateMovementAfterPreview(t *testing.T) { @@ -983,9 +1197,19 @@ func TestArchiveReceiptRejectsCrossLaneAndExtraRecords(t *testing.T) { leases = append(leases, lease) } cutoff := time.Now().UTC().Add(-24 * time.Hour) - candidate, eligible, err := laneStore.archiveCandidate(lanes[0].ID, cutoff) - if err != nil || !eligible { - t.Fatalf("candidate = %#v eligible=%v err=%v", candidate, eligible, err) + candidates, err := laneStore.ArchiveCandidates(cutoff) + if err != nil { + t.Fatal(err) + } + var candidate ArchiveCandidate + for _, item := range candidates { + if item.LaneID == lanes[0].ID { + candidate = item + break + } + } + if candidate.LaneID == "" { + t.Fatalf("candidate for %s not found in %#v", lanes[0].ID, candidates) } receipt, err := laneStore.prepareArchiveReceipt(cutoff, []ArchiveCandidate{candidate}) if err != nil { diff --git a/internal/store/writer_fence.go b/internal/store/writer_fence.go new file mode 100644 index 0000000..b263102 --- /dev/null +++ b/internal/store/writer_fence.go @@ -0,0 +1,89 @@ +package store + +import ( + "errors" + "os" + "path/filepath" + "time" + + "github.com/nstranquist/wip-commit/internal/fail" + "github.com/nstranquist/wip-commit/internal/filelock" + "github.com/nstranquist/wip-commit/internal/gitx" +) + +const migrationWriterFenceName = "wip-coordination-migration-v1.fence.json" + +const DefaultWriterFenceWait = filelock.DefaultWait + +// WriterFence is the exclusive repository-wide coordination writer token. +// Command dispatch keeps it until every mutation and verification has returned. +type WriterFence struct { + commonDir string + lock *filelock.Lock +} + +func AcquireWriterFence(repo gitx.Repo, wait time.Duration) (*WriterFence, error) { + lock, err := filelock.Acquire(filepath.Join(repo.CommonDir, "wip-coordination.lock"), wait) + if err != nil { + return nil, fail.Wrap("LOCK_TIMEOUT", err) + } + fence := &WriterFence{commonDir: filepath.Clean(repo.CommonDir), lock: lock} + if err := refuseActiveMigrationFence(repo.CommonDir); err != nil { + _ = fence.Release() + return nil, err + } + return fence, nil +} + +func (fence *WriterFence) Release() error { + if fence == nil || fence.lock == nil { + return nil + } + err := fence.lock.Release() + fence.lock = nil + return err +} + +func (fence *WriterFence) validFor(repo gitx.Repo) bool { + return fence != nil && fence.lock != nil && fence.commonDir == filepath.Clean(repo.CommonDir) +} + +// WriterFenced reports whether command dispatch retained a live exact token. +func (store Store) WriterFenced() bool { + return store.writerFence != nil && store.writerFence.validFor(store.Repo) +} + +func withWriterFence[T any](store Store, operation func(Store) (T, error)) (T, error) { + var zero T + if store.WriterFenced() { + return operation(store) + } + fence, err := AcquireWriterFence(store.Repo, DefaultWriterFenceWait) + if err != nil { + return zero, err + } + defer func() { _ = fence.Release() }() + store.writerFence = fence + return operation(store) +} + +func (store Store) requireWriterFence() error { + if !store.WriterFenced() { + return fail.New("WRITER_FENCE_REQUIRED", "store mutation requires the exact repository writer fence") + } + return nil +} + +func refuseActiveMigrationFence(commonDir string) error { + info, err := os.Lstat(filepath.Join(commonDir, migrationWriterFenceName)) + if errors.Is(err, os.ErrNotExist) { + return nil + } + if err != nil { + return fail.Wrap("MIGRATION_IN_PROGRESS", err) + } + if !info.Mode().IsRegular() || info.Mode()&os.ModeSymlink != 0 { + return fail.New("MIGRATION_IN_PROGRESS", "coordination migration writer fence is unsafe; refuse all writes") + } + return fail.New("MIGRATION_IN_PROGRESS", "coordination migration holds the repository writer fence") +} diff --git a/oss_capture_schema_test.go b/oss_capture_schema_test.go new file mode 100644 index 0000000..e8c646b --- /dev/null +++ b/oss_capture_schema_test.go @@ -0,0 +1,73 @@ +package wipcommit + +import ( + "encoding/json" + "os" + "testing" +) + +func TestCaptureSchemasAreStrictJSONContracts(t *testing.T) { + tests := []struct { + path string + typeName string + required []string + }{ + { + path: "docs/PLAN.schema.json", + typeName: "object", + required: []string{"schema_version", "state", "lane", "target_ref", "lane_tip", "source_head", "source_mode", "untracked_policy", "source_digest", "source_scopes", "lease_digest", "message_policy", "source_paths", "groups"}, + }, + { + path: "docs/PLAN.legacy-v1.schema.json", + typeName: "array", + }, + { + path: "docs/STATUS.schema.json", + typeName: "object", + required: []string{"schema_version", "lane", "leases", "message_policy", "active_paths", "leased_but_not_staged", "empty_lease_scopes", "capture_candidates", "captured_but_still_staged", "staged_leased", "foreign_staged", "expired_lease_ids", "lease_remaining_ms", "renewal", "ref_health"}, + }, + { + path: "docs/HANDOFF.schema.json", + typeName: "object", + required: []string{"schema_version", "handoff_digest", "capture_only", "landing_authorized", "review_eligible", "lane_ref", "lane_tip", "lane_base_commit", "final_tree", "tip_plan_id", "tip_capture_intent_digest", "segments"}, + }, + } + for _, test := range tests { + t.Run(test.path, func(t *testing.T) { + body, err := os.ReadFile(test.path) + if err != nil { + t.Fatal(err) + } + var schema map[string]any + if err := json.Unmarshal(body, &schema); err != nil { + t.Fatalf("schema is not JSON: %v", err) + } + if schema["$schema"] != "https://json-schema.org/draft/2020-12/schema" { + t.Errorf("unexpected JSON Schema dialect: %v", schema["$schema"]) + } + if schema["type"] != test.typeName { + t.Errorf("type = %v, want %s", schema["type"], test.typeName) + } + if strict, ok := schema["additionalProperties"]; test.typeName == "object" && (!ok || strict != false) { + t.Errorf("top-level object must reject additional properties") + } + required := stringSet(schema["required"]) + for _, field := range test.required { + if !required[field] { + t.Errorf("required field %q is missing", field) + } + } + }) + } +} + +func stringSet(value any) map[string]bool { + result := map[string]bool{} + values, _ := value.([]any) + for _, value := range values { + if text, ok := value.(string); ok { + result[text] = true + } + } + return result +} diff --git a/oss_plan_test.go b/oss_plan_test.go index 8f38922..897467e 100644 --- a/oss_plan_test.go +++ b/oss_plan_test.go @@ -142,8 +142,12 @@ func assertOSSVersionReferences(t *testing.T, target string) { if len(match) != 2 { t.Fatal("cmd/wip/main.go has no static version") } - if wanted := "v" + string(match[1]); target != wanted { - t.Fatalf("plan target %q does not match command version %q", target, wanted) + targetMatch := regexp.MustCompile(`^v((?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*))(?:-|$)`).FindStringSubmatch(target) + if len(targetMatch) != 2 { + t.Fatalf("plan target %q is not a SemVer release line", target) + } + if wanted := targetMatch[1] + "-dev"; string(match[1]) != wanted { + t.Fatalf("plan target %q requires command development version %q, found %q", target, wanted, match[1]) } for _, check := range []struct { path string diff --git a/oss_protocol_docs_test.go b/oss_protocol_docs_test.go new file mode 100644 index 0000000..9c1c266 --- /dev/null +++ b/oss_protocol_docs_test.go @@ -0,0 +1,122 @@ +package wipcommit + +import ( + "os" + "strings" + "testing" + + "github.com/nstranquist/wip-commit/internal/contract" +) + +func TestCurrentProtocolDocsMatchPrivateSourceContracts(t *testing.T) { + required := map[string][]string{ + "README.md": { + contract.Protocol, + `"schema_version": "3.0.0"`, + `"agent": "codex"`, + `"session": "parser-errors-review"`, + `"source_mode": "worktree_snapshot"`, + `"source_digest": "sha256:"`, + "version 2 cumulative handoff", + "`landing_authorized` to `false`", + "`wip plan --observe`", + }, + "CHANGELOG.md": { + contract.Protocol, + "version 3 draft/reviewed plan schema", + "version 2 cumulative capture-only handoff", + }, + "docs/ARCHITECTURE.md": { + "`worktree_snapshot`", + "`source_digest`", + "version 3 object", + "version 2 output", + "handoffs/.json", + "plans/.json", + "`wip/v1/locks/leases.lock` artifact", + }, + "docs/STATE-COMPATIBILITY.md": { + contract.Protocol, + "capture-intent schema version 3", + "`handoffs` and `plans` review directories", + "`wip/v1/locks/leases.lock` artifact before imported", + }, + "docs/OSS-PUBLIC-BETA.requirements.yaml": { + "one version 3 plan", + "cumulative version 2 handoff", + "manifest-bound registry lock", + }, + "cmd/wip/app.go": { + "selected leased source paths", + "reviewed v3 plan", + "cumulative capture-only handoff", + "digest-bound coordination migration", + }, + "skills/wip-commit/SKILL.md": { + "--source worktree_snapshot", + "--source staged_index", + "cumulative base-to-tip capture", + }, + "skills/wip-commit/references/automation.md": { + "--source worktree_snapshot", + "continuous parent chain", + "handoff_digest", + }, + } + for path, fragments := range required { + body, err := os.ReadFile(path) + if err != nil { + t.Fatal(err) + } + text := string(body) + for _, fragment := range fragments { + if !strings.Contains(text, fragment) { + t.Errorf("%s does not contain current contract text %q", path, fragment) + } + } + } + + currentDocs := []string{ + "README.md", + "CHANGELOG.md", + "THREAT-MODEL.md", + "cmd/wip/app.go", + "docs/ARCHITECTURE.md", + "docs/BETA-EXERCISE.md", + "docs/ERRORS.md", + "docs/KEP-0001-capture-to-landing-boundary.md", + "docs/KEP-0003-agent-facing-capture-workflow.md", + "docs/OSS-PRACTICE-GUIDE.md", + "docs/OSS-PUBLIC-BETA.md", + "docs/OSS-PUBLIC-BETA.requirements.yaml", + "docs/OSS-READINESS.md", + "docs/STATE-COMPATIBILITY.md", + "examples/README.md", + "SECURITY.md", + "skills/wip-commit/SKILL.md", + "skills/wip-commit/benchmark/README.md", + "skills/wip-commit/references/automation.md", + } + forbidden := []string{ + "wip.command/2.0.0", + "source_index_digest", + `"staged_paths"`, + "SOURCE_INDEX_MOVED", + "staged leased paths", + "complete source-index", + "one version 2 plan", + "Capture one reviewed v2 plan", + "latest complete capture receipt", + } + for _, path := range currentDocs { + body, err := os.ReadFile(path) + if err != nil { + t.Fatal(err) + } + for _, fragment := range forbidden { + if strings.Contains(string(body), fragment) { + t.Errorf("%s contains stale contract text %q", path, fragment) + } + } + } +} diff --git a/oss_release_test.go b/oss_release_test.go index a7f147b..5ac7cce 100644 --- a/oss_release_test.go +++ b/oss_release_test.go @@ -45,7 +45,7 @@ func TestBetaReleaseWorkflowContract(t *testing.T) { "id-token: write", "go test -race -count=3 ./...", "go run ./scripts/release", - "actions/attest@508db95dd578ae2727ebd6217d5ba78e4fbda05d", + "actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6", "dist/checksums.txt", "dist/release-receipt.json", "--prerelease", diff --git a/oss_skill_test.go b/oss_skill_test.go index c3e57db..47709cf 100644 --- a/oss_skill_test.go +++ b/oss_skill_test.go @@ -29,11 +29,15 @@ func TestPortableSkillContract(t *testing.T) { for _, required := range []string{ "name: wip-commit", "wip init", - "wip --json commit --plan", + "wip --json plan --out", + "wip --json capture --plan", + "wip --json handoff", "git add -- ", - "ref_updated", - "gate_outcome", - "intent_state", + "data.capture.ref_updated", + "data.capture.gate_outcome", + "data.capture.intent_state", + "data.handoff.capture_only", + "data.handoff.landing_authorized", "wip reconcile", "wip release", "references/automation.md", diff --git a/oss_version_corpus_test.go b/oss_version_corpus_test.go new file mode 100644 index 0000000..698a258 --- /dev/null +++ b/oss_version_corpus_test.go @@ -0,0 +1,79 @@ +package wipcommit + +import ( + "os" + "strings" + "testing" +) + +func TestReleaseCorpusUsesCurrentLineWithoutRewritingHistoricalEvidence(t *testing.T) { + const ( + currentSource = "0.2.0-dev" + currentTag = "v0.2.0-beta.1" + oldLine = "0.1.0" + ) + + prospective := map[string][]string{ + "README.md": {currentSource, currentTag}, + "CHANGELOG.md": {currentSource, currentTag}, + "SECURITY.md": {currentTag}, + "docs/KEP-0002-hosted-candidate-correction.md": {currentTag}, + "docs/OSS-PUBLIC-BETA.md": {currentTag}, + "docs/OSS-READINESS.md": {currentTag}, + "docs/RELEASE.md": {currentTag}, + "scripts/release/main.go": {currentTag}, + } + for path, required := range prospective { + body := readVersionCorpusFile(t, path) + if strings.Contains(body, oldLine) { + t.Errorf("%s contains superseded prospective release line %q", path, oldLine) + } + for _, fragment := range required { + if !strings.Contains(body, fragment) { + t.Errorf("%s does not contain current release identity %q", path, fragment) + } + } + } + + mixedEvidence := map[string][]string{ + "docs/OSS-PUBLIC-BETA.requirements.yaml": { + `"target_version": "v0.2.0-beta.1"`, + "returned wip 0.1.0-beta.1", + }, + "docs/PUBLICATION-CORRECTION.md": { + "target is `v0.2.0-beta.1`", + "candidate/v0.1.0-beta.1:31996054315", + }, + "docs/PUBLICATION-EVIDENCE.md": { + "Current release target: `v0.2.0-beta.1`", + "`wip 0.1.0-beta.1`", + }, + "docs/PUBLICATION-HANDOFF.md": { + "Current release target: `v0.2.0-beta.1`", + "refs/heads/candidate/v0.1.0-beta.1", + }, + "docs/DOGFOOD.md": { + "installed binary reported `0.1.0-beta.1`", + }, + "docs/BETA-EXERCISE.maintainer-2026-08-16.json": { + `"wip_version": "0.1.0-beta.1"`, + }, + } + for path, required := range mixedEvidence { + body := readVersionCorpusFile(t, path) + for _, fragment := range required { + if !strings.Contains(body, fragment) { + t.Errorf("%s does not preserve release evidence %q", path, fragment) + } + } + } +} + +func readVersionCorpusFile(t *testing.T, path string) string { + t.Helper() + body, err := os.ReadFile(path) + if err != nil { + t.Fatal(err) + } + return string(body) +} diff --git a/portfolio/manifest.yaml b/portfolio/manifest.yaml index c1458b7..de221d4 100644 --- a/portfolio/manifest.yaml +++ b/portfolio/manifest.yaml @@ -1,8 +1,46 @@ -schema_version: 1 +schema_version: 2 product_id: product.wip-commit -visibility: internal -reviewed: false -assets: [] +visibility: public +reviewed: true +presentation: + summary: Guarded split-commit capture for parallel agents in shared Git checkouts. + detail: Discover path ownership, isolate an exact staged delta, run policy gates, create a recoverable commit, and keep unrelated or concurrently staged work outside the commit. + language: Go + lane: Git safety and agent ergonomics +access: + profile: go-cli + primary_action: + kind: source + label: Build wip-commit + url: https://github.com/nstranquist/wip-commit#build-locally + repository_url: https://github.com/nstranquist/wip-commit + documentation_url: https://github.com/nstranquist/wip-commit#start-with-wip-init + feedback_url: https://github.com/nstranquist/wip-commit/issues/new + module: github.com/nstranquist/wip-commit + binary: wip + smoke_argv: [go, run, ./cmd/wip, --help] +proof: + claims: + - id: exact-path-capture + statement: The workflow captures an explicit path set instead of committing the entire shared index. + evidence_kind: documentation + evidence_url: https://github.com/nstranquist/wip-commit#capture-work + - id: safety-boundary + statement: The repository documents index ownership, recovery, and unsupported destructive operations. + evidence_kind: documentation + evidence_url: https://github.com/nstranquist/wip-commit#safety-scope + boundaries: + - The public repository currently has no SemVer tag or formal GitHub Release. + - Guarded commits reduce shared-checkout risk but cannot infer human ownership intent. +assets: + - path: assets/brand/wip-commit.svg + kind: logo + alt: wip-commit application icon + provenance: authored-svg + copyright_owner: Nico Stranquist + generator: catalog-brand-svg/v2 + concept: git-shield + score: 100 case_study: enabled: false evidence: [] diff --git a/scripts/publication-correction/main.go b/scripts/publication-correction/main.go new file mode 100644 index 0000000..38f5ff9 --- /dev/null +++ b/scripts/publication-correction/main.go @@ -0,0 +1,1513 @@ +// Command publication-correction creates a fail-closed receipt for a hosted +// candidate correction. It reads local and GitHub evidence. It does not change +// a repository, pull request, workflow run, tag, or Git ref. +package main + +import ( + "bytes" + "context" + "crypto/sha256" + "encoding/hex" + "encoding/json" + "errors" + "flag" + "fmt" + "io" + "os" + "os/exec" + "path/filepath" + "regexp" + "runtime" + "sort" + "strconv" + "strings" + "time" + + "github.com/nstranquist/wip-commit/internal/gitx" + "github.com/nstranquist/wip-commit/internal/safeio" +) + +const ( + receiptSchemaVersion = "1.0.0" + verifierCommandPath = "scripts/publication-correction/main.go" + verifierSchemaPath = "docs/PUBLICATION-CORRECTION.schema.json" + maximumManifestBytes = 64 << 10 + maximumFirstReceiptBytes = 2 << 20 + maximumVerifierFileBytes = 2 << 20 + maximumCommandOutputBytes = 2 << 20 + gitCommandTimeout = 2 * time.Minute + githubCommandTimeout = 30 * time.Second + secretScanTimeout = 5 * time.Minute +) + +var ( + objectPattern = regexp.MustCompile(`^(?:[0-9a-f]{40}|[0-9a-f]{64})$`) + targetPattern = regexp.MustCompile(`^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$`) + runLabelPattern = regexp.MustCompile(`^[a-z][a-z0-9-]{0,62}$`) + runEventPattern = regexp.MustCompile(`^[a-z][a-z0-9_]{0,62}$`) + sha256Pattern = regexp.MustCompile(`^sha256:[0-9a-f]{64}$`) + allowedPhaseNames = map[string]bool{"pre-main": true, "finalized": true} +) + +type typedError struct { + Code string + Err error +} + +func (err *typedError) Error() string { return err.Err.Error() } +func (err *typedError) Unwrap() error { return err.Err } + +func problem(code, format string, arguments ...any) error { + return &typedError{Code: code, Err: fmt.Errorf(format, arguments...)} +} + +func wrapProblem(code string, err error, format string, arguments ...any) error { + if err == nil { + return nil + } + prefix := fmt.Sprintf(format, arguments...) + if prefix == "" { + return &typedError{Code: code, Err: err} + } + return &typedError{Code: code, Err: fmt.Errorf("%s: %w", prefix, err)} +} + +func errorCode(err error) string { + var typed *typedError + if errors.As(err, &typed) && typed.Code != "" { + return typed.Code + } + return "INTERNAL_ERROR" +} + +type objectEvidence struct { + Commit string `json:"commit"` + Tree string `json:"tree"` +} + +type firstReceiptEvidence struct { + SchemaVersion string `json:"schema_version"` + Digest string `json:"digest"` + Bootstrap string `json:"bootstrap_commit"` + BootstrapTree string `json:"bootstrap_tree"` + Candidate string `json:"candidate_commit"` + CandidateTree string `json:"candidate_tree"` +} + +type verifierEvidence struct { + Commit string `json:"commit"` + Tree string `json:"tree"` + CommandPath string `json:"command_path"` + CommandDigest string `json:"command_digest"` + SchemaPath string `json:"schema_path"` + SchemaDigest string `json:"schema_digest"` + Clean bool `json:"clean"` + CompleteHistory bool `json:"complete_history"` + ReplacementRefCount int `json:"replacement_ref_count"` + ObjectIntegrityCheck string `json:"object_integrity_check"` +} + +type correctionCommit struct { + Commit string `json:"commit"` + Tree string `json:"tree"` + Parent string `json:"parent"` +} + +type correctionEvidence struct { + OldCandidate objectEvidence `json:"old_candidate"` + NewCandidate objectEvidence `json:"new_candidate"` + Commits []correctionCommit `json:"commits"` + BootstrapDelta []string `json:"bootstrap_delta_paths"` + CorrectionDelta []string `json:"correction_delta_paths"` + MergeFree bool `json:"merge_free"` + OldIsAncestor bool `json:"old_is_ancestor"` + BootstrapIsAncestor bool `json:"bootstrap_is_ancestor"` +} + +type localEvidence struct { + Clean bool `json:"clean"` + CompleteHistory bool `json:"complete_history"` + ReplacementRefCount int `json:"replacement_ref_count"` + ObjectIntegrityCheck string `json:"object_integrity_check"` + HistorySecretScan string `json:"history_secret_scan"` + WorktreeSecretScan string `json:"worktree_secret_scan"` + PathManifestMatched bool `json:"path_manifest_matched"` + CheckedOutCandidate bool `json:"checked_out_candidate"` +} + +type identityEvidence struct { + HistoryCommitCount int `json:"history_commit_count"` + UniqueAuthorNames int `json:"unique_author_names"` + UniqueAuthorEmails int `json:"unique_author_emails"` + UniqueCommitterNames int `json:"unique_committer_names"` + UniqueCommitterEmails int `json:"unique_committer_emails"` + IdentitySetDigest string `json:"identity_set_digest"` + PublicEmailMatch bool `json:"public_email_match"` + PublicNameMatch bool `json:"public_name_match"` +} + +type repositoryEvidence struct { + FullName string `json:"full_name"` + Visibility string `json:"visibility"` + DefaultBranch string `json:"default_branch"` + AuthenticatedOwner bool `json:"authenticated_owner"` +} + +type remoteEvidence struct { + CandidateRef string `json:"candidate_ref"` + CandidateCommit string `json:"candidate_commit"` + MainRef string `json:"main_ref"` + MainCommit string `json:"main_commit"` +} + +type pullRequestEvidence struct { + Number int `json:"number"` + State string `json:"state"` + HeadRef string `json:"head_ref"` + HeadCommit string `json:"head_commit"` + BaseRef string `json:"base_ref"` + BaseCommit string `json:"base_commit"` + Merged bool `json:"merged"` + MergeCommit string `json:"merge_commit,omitempty"` +} + +type runEvidence struct { + Label string `json:"label"` + ID int64 `json:"id"` + Event string `json:"event"` + HeadBranch string `json:"head_branch"` + HeadCommit string `json:"head_commit"` + Status string `json:"status"` + Conclusion string `json:"conclusion"` + Attempt int `json:"attempt"` + Workflow string `json:"workflow"` +} + +type requiredCheckEvidence struct { + Context string `json:"context"` + IntegrationID int64 `json:"integration_id"` + CheckRunID int64 `json:"check_run_id"` + Status string `json:"status"` + Conclusion string `json:"conclusion"` +} + +type rulesetEvidence struct { + ID int64 `json:"id"` + Name string `json:"name"` + Enforcement string `json:"enforcement"` + NoBypassActors bool `json:"no_bypass_actors"` + DeletionBlocked bool `json:"deletion_blocked"` + NonFastForwardBlocked bool `json:"non_fast_forward_blocked"` + LinearHistoryRequired bool `json:"linear_history_required"` + PullRequestRequired bool `json:"pull_request_required"` + RequiredApprovingReviewCount int `json:"required_approving_review_count"` + DismissStaleReviews bool `json:"dismiss_stale_reviews"` + LastPushApprovalRequired bool `json:"last_push_approval_required"` + ReviewThreadsResolved bool `json:"review_threads_resolved"` + AllowedMergeMethods []string `json:"allowed_merge_methods"` + StrictRequiredChecks bool `json:"strict_required_checks"` + RequiredChecksOnCreate bool `json:"required_checks_on_create"` +} + +type receipt struct { + SchemaVersion string `json:"schema_version"` + GeneratedAt time.Time `json:"generated_at"` + Target string `json:"target_repository"` + Phase string `json:"phase"` + Verifier verifierEvidence `json:"verifier"` + Bootstrap objectEvidence `json:"bootstrap"` + FirstReceipt firstReceiptEvidence `json:"first_receipt"` + Correction correctionEvidence `json:"correction"` + Local localEvidence `json:"local"` + Identity identityEvidence `json:"identity"` + Repository repositoryEvidence `json:"repository"` + Remote remoteEvidence `json:"remote"` + PullRequest pullRequestEvidence `json:"pull_request"` + HostedRuns []runEvidence `json:"hosted_runs"` + Ruleset rulesetEvidence `json:"ruleset"` + RequiredChecks []requiredCheckEvidence `json:"required_checks"` +} + +type identitySet struct { + HistoryCommitCount int + AuthorNames []string + AuthorEmails []string + CommitterNames []string + CommitterEmails []string + Digest string +} + +type gitEvidence struct { + Bootstrap objectEvidence + Correction correctionEvidence + Identity identitySet +} + +type firstReceiptDocument struct { + SchemaVersion string `json:"schema_version"` + TargetRepository string `json:"target_repository"` + TargetVisibility string `json:"target_visibility"` + DefaultBranch string `json:"default_branch"` + Bootstrap objectEvidence `json:"bootstrap"` + Candidate struct { + Commit string `json:"commit"` + Tree string `json:"tree"` + } `json:"candidate"` + HistoryCommitCount int `json:"history_commit_count"` + DeltaPaths []string `json:"delta_paths"` + Local struct { + Clean bool `json:"clean"` + HistorySecretScan string `json:"history_secret_scan"` + WorktreeSecretScan string `json:"worktree_secret_scan"` + ObjectIntegrityCheck string `json:"object_integrity_check"` + ExpectedDeltaMatched bool `json:"expected_delta_matched"` + BootstrapIsAncestor bool `json:"bootstrap_is_ancestor"` + LinearCandidateRange bool `json:"linear_candidate_range"` + } `json:"local"` + GitHub struct { + AuthenticatedOwner bool `json:"authenticated_owner"` + TargetRepositoryExists bool `json:"target_repository_exists"` + PublicAuthorIdentityMatch bool `json:"public_author_identity_match"` + } `json:"github"` +} + +type runSpec struct { + Label, Event, Branch string + ID int64 +} + +type stringList []string + +func (values *stringList) String() string { return strings.Join(*values, ",") } +func (values *stringList) Set(value string) error { + *values = append(*values, value) + return nil +} + +type externalRunner func(context.Context, time.Duration, string, string, ...string) (string, string, int, error) + +type dependencies struct { + external externalRunner + now func() time.Time +} + +type options struct { + RepoDir, VerifierDir, Target, Phase, Bootstrap, OldCandidate, Candidate, CandidateRef string + FirstReceipt, PathsFile, Out string + PullRequest int + Ruleset int64 + Runs []runSpec +} + +func main() { + if err := run(context.Background(), os.Args[1:], os.Stdout); err != nil { + fmt.Fprintf(os.Stderr, "publication-correction: %s: %s\n", errorCode(err), err) + os.Exit(2) + } +} + +func run(ctx context.Context, args []string, stdout io.Writer) error { + return runWithDependencies(ctx, args, stdout, dependencies{external: externalCommandWithTimeout, now: time.Now}) +} + +func runWithDependencies(ctx context.Context, args []string, stdout io.Writer, deps dependencies) error { + if deps.external == nil || deps.now == nil { + return problem("DEPENDENCIES_INCOMPLETE", "publication-correction dependencies are incomplete") + } + configuration, err := parseOptions(args) + if err != nil { + return err + } + repo, err := gitx.Discover(ctx, configuration.RepoDir) + if err != nil { + return wrapProblem("NOT_A_REPOSITORY", err, "discover candidate checkout") + } + if err := verifyModuleTarget(repo.Root, configuration.Target); err != nil { + return err + } + verifierRepo, err := gitx.Discover(ctx, configuration.VerifierDir) + if err != nil { + return wrapProblem("VERIFIER_INVALID", err, "discover verifier checkout") + } + if err := verifyModuleTarget(verifierRepo.Root, configuration.Target); err != nil { + return problem("VERIFIER_INVALID", "verifier go.mod does not match github.com/%s", configuration.Target) + } + verifier, err := collectVerifierEvidence(ctx, verifierRepo) + if err != nil { + return err + } + if err := validateBranchName(ctx, repo, configuration.CandidateRef); err != nil { + return err + } + roots := []string{repo.Root, verifierRepo.Root} + outputPath, err := validatedReceiptOutput(roots, configuration.Out) + if err != nil { + return err + } + manifest, err := loadExpectedPaths(repo, configuration.PathsFile) + if err != nil { + return err + } + firstReceipt, err := loadFirstReceipt(roots, configuration.FirstReceipt, configuration.Target, configuration.Bootstrap, configuration.OldCandidate) + if err != nil { + return err + } + gitState, err := collectGitEvidence(ctx, repo, configuration.Bootstrap, configuration.OldCandidate, configuration.Candidate, manifest) + if err != nil { + return err + } + if firstReceipt.BootstrapTree != gitState.Bootstrap.Tree || firstReceipt.CandidateTree != gitState.Correction.OldCandidate.Tree { + return problem("FIRST_RECEIPT_MISMATCH", "first receipt trees do not match the local bootstrap and old candidate") + } + if err := runSecretScans(ctx, repo.Root, deps.external); err != nil { + return err + } + hosted, err := collectGitHubEvidence(ctx, repo.Root, configuration, gitState.Identity, deps.external) + if err != nil { + return err + } + + result := receipt{ + SchemaVersion: receiptSchemaVersion, + GeneratedAt: deps.now().UTC(), + Target: configuration.Target, + Phase: configuration.Phase, + Verifier: verifier, + Bootstrap: gitState.Bootstrap, + FirstReceipt: firstReceipt, + Correction: gitState.Correction, + Local: localEvidence{ + Clean: true, + CompleteHistory: true, + ReplacementRefCount: 0, + ObjectIntegrityCheck: "passed", + HistorySecretScan: "passed", + WorktreeSecretScan: "passed", + PathManifestMatched: true, + CheckedOutCandidate: true, + }, + Identity: identityEvidence{ + HistoryCommitCount: gitState.Identity.HistoryCommitCount, + UniqueAuthorNames: len(gitState.Identity.AuthorNames), + UniqueAuthorEmails: len(gitState.Identity.AuthorEmails), + UniqueCommitterNames: len(gitState.Identity.CommitterNames), + UniqueCommitterEmails: len(gitState.Identity.CommitterEmails), + IdentitySetDigest: gitState.Identity.Digest, + PublicEmailMatch: true, + PublicNameMatch: hosted.PublicNameMatch, + }, + Repository: hosted.Repository, + Remote: hosted.Remote, + PullRequest: hosted.PullRequest, + HostedRuns: hosted.Runs, + Ruleset: hosted.Ruleset, + RequiredChecks: hosted.RequiredChecks, + } + body, digest, err := encodeReceipt(result) + if err != nil { + return err + } + if err := writeReceipt(outputPath, body); err != nil { + return err + } + return json.NewEncoder(stdout).Encode(map[string]any{ + "ok": true, + "action": "publication-correction", + "candidate_commit": result.Correction.NewCandidate.Commit, + "candidate_tree": result.Correction.NewCandidate.Tree, + "phase": result.Phase, + "receipt_digest": digest, + }) +} + +func parseOptions(args []string) (options, error) { + var configuration options + var rawRuns stringList + flags := flag.NewFlagSet("publication-correction", flag.ContinueOnError) + flags.SetOutput(io.Discard) + flags.StringVar(&configuration.RepoDir, "repo-dir", ".", "exact candidate checkout") + flags.StringVar(&configuration.VerifierDir, "verifier-dir", ".", "clean checkout that contains this verifier") + flags.StringVar(&configuration.Target, "target", "", "GitHub OWNER/REPO") + flags.StringVar(&configuration.Phase, "phase", "pre-main", "pre-main or finalized") + flags.StringVar(&configuration.Bootstrap, "bootstrap", "", "reviewed bootstrap commit") + flags.StringVar(&configuration.OldCandidate, "old-candidate", "", "candidate bound by the first receipt") + flags.StringVar(&configuration.Candidate, "candidate", "", "corrected candidate commit") + flags.StringVar(&configuration.CandidateRef, "candidate-ref", "", "remote candidate branch without refs/heads/") + flags.StringVar(&configuration.FirstReceipt, "first-receipt", "", "immutable pre-first-push receipt") + flags.StringVar(&configuration.PathsFile, "paths-file", "", "reviewed bootstrap-delta path manifest") + flags.StringVar(&configuration.Out, "out", "", "new private receipt outside the checkout") + flags.IntVar(&configuration.PullRequest, "pull-request", 0, "verification pull request number") + flags.Int64Var(&configuration.Ruleset, "ruleset", 0, "required main-branch ruleset ID") + flags.Var(&rawRuns, "run", "LABEL:EVENT:BRANCH:ID; repeat for each required hosted run") + if err := flags.Parse(args); err != nil { + return configuration, problem("INVALID_ARGS", "%s", err) + } + if flags.NArg() != 0 { + return configuration, problem("INVALID_ARGS", "unexpected positional arguments: %s", strings.Join(flags.Args(), " ")) + } + if !targetPattern.MatchString(configuration.Target) || strings.Contains(configuration.Target, "..") { + return configuration, problem("INVALID_ARGS", "--target must use OWNER/REPO") + } + if !allowedPhaseNames[configuration.Phase] { + return configuration, problem("INVALID_ARGS", "--phase must be pre-main or finalized") + } + for label, value := range map[string]string{ + "--bootstrap": configuration.Bootstrap, + "--old-candidate": configuration.OldCandidate, + "--candidate": configuration.Candidate, + } { + if !objectPattern.MatchString(value) { + return configuration, problem("INVALID_ARGS", "%s must be a complete Git object ID", label) + } + } + if configuration.Bootstrap == configuration.OldCandidate || configuration.OldCandidate == configuration.Candidate { + return configuration, problem("INVALID_ARGS", "bootstrap, old candidate, and candidate must identify distinct commits") + } + if configuration.CandidateRef == "" || strings.HasPrefix(configuration.CandidateRef, "refs/") { + return configuration, problem("INVALID_ARGS", "--candidate-ref must be a branch name without refs/heads/") + } + if configuration.PullRequest <= 0 || configuration.Ruleset <= 0 { + return configuration, problem("INVALID_ARGS", "--pull-request and --ruleset must be positive") + } + for label, value := range map[string]string{ + "--first-receipt": configuration.FirstReceipt, + "--paths-file": configuration.PathsFile, + "--out": configuration.Out, + } { + if strings.TrimSpace(value) == "" { + return configuration, problem("INVALID_ARGS", "%s is required", label) + } + } + runs, err := parseRunSpecs(rawRuns) + if err != nil { + return configuration, err + } + configuration.Runs = runs + return configuration, nil +} + +func parseRunSpecs(values []string) ([]runSpec, error) { + if len(values) == 0 { + return nil, problem("INVALID_ARGS", "at least one --run is required") + } + seenLabels, seenIDs := map[string]bool{}, map[int64]bool{} + runs := make([]runSpec, 0, len(values)) + for _, value := range values { + parts := strings.Split(value, ":") + if len(parts) != 4 || !runLabelPattern.MatchString(parts[0]) || !runEventPattern.MatchString(parts[1]) || strings.TrimSpace(parts[2]) == "" { + return nil, problem("INVALID_ARGS", "--run must use LABEL:EVENT:BRANCH:ID") + } + id, err := strconv.ParseInt(parts[3], 10, 64) + if err != nil || id <= 0 { + return nil, problem("INVALID_ARGS", "--run ID must be a positive integer") + } + if seenLabels[parts[0]] || seenIDs[id] { + return nil, problem("INVALID_ARGS", "--run labels and IDs must be unique") + } + seenLabels[parts[0]], seenIDs[id] = true, true + runs = append(runs, runSpec{Label: parts[0], Event: parts[1], Branch: parts[2], ID: id}) + } + sort.Slice(runs, func(left, right int) bool { return runs[left].Label < runs[right].Label }) + return runs, nil +} + +func verifyModuleTarget(root, target string) error { + body, err := safeio.ReadRegular(filepath.Join(root, "go.mod"), maximumManifestBytes) + if err != nil { + return wrapProblem("TARGET_MISMATCH", err, "read go.mod") + } + wanted, count := "module github.com/"+target, 0 + for _, line := range strings.Split(strings.ReplaceAll(string(body), "\r\n", "\n"), "\n") { + if strings.HasPrefix(strings.TrimSpace(line), "module ") { + count++ + if strings.TrimSpace(line) != wanted { + return problem("TARGET_MISMATCH", "go.mod module must equal github.com/%s", target) + } + } + } + if count != 1 { + return problem("TARGET_MISMATCH", "go.mod must contain exactly one module declaration") + } + return nil +} + +func validateBranchName(parent context.Context, repo gitx.Repo, branch string) error { + ctx, cancel := context.WithTimeout(parent, gitCommandTimeout) + defer cancel() + resolved, err := repo.Text(ctx, nil, "check-ref-format", "--branch", branch) + if err != nil || resolved != branch { + return gitProblem(ctx, "INVALID_ARGS", err, "--candidate-ref is not a valid Git branch") + } + return nil +} + +func loadExpectedPaths(repo gitx.Repo, name string) ([]string, error) { + path := name + if !filepath.IsAbs(path) { + path = filepath.Join(repo.Root, path) + } + inside, err := pathWithinRoot(repo.Root, path) + if err != nil || !inside { + return nil, problem("PATH_MANIFEST_UNSAFE", "--paths-file must resolve inside the candidate checkout") + } + body, err := safeio.ReadRegular(path, maximumManifestBytes) + if err != nil { + return nil, wrapProblem("PATH_MANIFEST_INVALID", err, "read path manifest") + } + var paths []string + for _, line := range strings.Split(strings.ReplaceAll(string(body), "\r\n", "\n"), "\n") { + if line = strings.TrimSpace(line); line != "" { + paths = append(paths, line) + } + } + if len(paths) == 0 { + return nil, problem("PATH_MANIFEST_INVALID", "path manifest is empty") + } + normalized, err := repo.NormalizePaths(paths) + if err != nil || !equalStrings(paths, normalized) { + return nil, problem("PATH_MANIFEST_INVALID", "path manifest must contain unique sorted canonical repository paths") + } + return normalized, nil +} + +func loadFirstReceipt(roots []string, name, target, bootstrap, oldCandidate string) (firstReceiptEvidence, error) { + path, err := filepath.Abs(name) + if err != nil { + return firstReceiptEvidence{}, wrapProblem("FIRST_RECEIPT_INVALID", err, "resolve first receipt") + } + for _, root := range roots { + inside, containmentErr := pathWithinRoot(root, path) + if containmentErr != nil || inside { + return firstReceiptEvidence{}, problem("FIRST_RECEIPT_INVALID", "--first-receipt must resolve outside the candidate and verifier checkouts") + } + } + body, err := safeio.ReadRegular(path, maximumFirstReceiptBytes) + if err != nil { + return firstReceiptEvidence{}, wrapProblem("FIRST_RECEIPT_INVALID", err, "read first receipt") + } + if runtime.GOOS != "windows" { + info, statErr := os.Stat(path) + if statErr != nil || info.Mode().Perm()&0o077 != 0 { + return firstReceiptEvidence{}, problem("FIRST_RECEIPT_INVALID", "first receipt must not grant group or other permissions") + } + } + var document firstReceiptDocument + decoder := json.NewDecoder(bytes.NewReader(body)) + if err := decoder.Decode(&document); err != nil { + return firstReceiptEvidence{}, wrapProblem("FIRST_RECEIPT_INVALID", err, "decode first receipt") + } + if err := requireJSONEOF(decoder); err != nil { + return firstReceiptEvidence{}, wrapProblem("FIRST_RECEIPT_INVALID", err, "decode first receipt") + } + if document.SchemaVersion != "1.0.0" || document.TargetRepository != target || document.TargetVisibility != "public" || document.DefaultBranch != "main" || document.Bootstrap.Commit != bootstrap || document.Candidate.Commit != oldCandidate { + return firstReceiptEvidence{}, problem("FIRST_RECEIPT_MISMATCH", "first receipt does not bind the target, bootstrap, and old candidate") + } + if document.HistoryCommitCount < 2 || len(document.DeltaPaths) == 0 || !document.Local.Clean || document.Local.HistorySecretScan != "passed" || document.Local.WorktreeSecretScan != "passed" || document.Local.ObjectIntegrityCheck != "passed" || !document.Local.ExpectedDeltaMatched || !document.Local.BootstrapIsAncestor || !document.Local.LinearCandidateRange || !document.GitHub.AuthenticatedOwner || document.GitHub.TargetRepositoryExists || !document.GitHub.PublicAuthorIdentityMatch { + return firstReceiptEvidence{}, problem("FIRST_RECEIPT_INVALID", "first receipt does not contain the required successful pre-first-push evidence") + } + if !objectPattern.MatchString(document.Bootstrap.Tree) || !objectPattern.MatchString(document.Candidate.Tree) { + return firstReceiptEvidence{}, problem("FIRST_RECEIPT_INVALID", "first receipt contains an invalid object ID") + } + digest := sha256.Sum256(body) + return firstReceiptEvidence{ + SchemaVersion: document.SchemaVersion, + Digest: "sha256:" + hex.EncodeToString(digest[:]), + Bootstrap: bootstrap, + BootstrapTree: document.Bootstrap.Tree, + Candidate: oldCandidate, + CandidateTree: document.Candidate.Tree, + }, nil +} + +func collectVerifierEvidence(parent context.Context, repo gitx.Repo) (verifierEvidence, error) { + ctx, cancel := context.WithTimeout(parent, gitCommandTimeout) + defer cancel() + var result verifierEvidence + shallow, err := repo.Text(ctx, nil, "rev-parse", "--is-shallow-repository") + if err != nil || shallow != "false" { + return result, verifierProblem(ctx, err, "verifier history must be complete and non-shallow") + } + replacements, err := repo.Lines(ctx, nil, "for-each-ref", "--format=%(refname)", "refs/replace") + if err != nil { + return result, verifierProblem(ctx, err, "inspect verifier replacement refs") + } + if len(replacements) != 0 { + return result, problem("VERIFIER_INVALID", "verifier repository has replacement refs") + } + if _, err := repo.Raw(ctx, nil, "fsck", "--strict", "--no-dangling"); err != nil { + return result, verifierProblem(ctx, err, "verify verifier object integrity") + } + status, err := repo.Raw(ctx, nil, "status", "--porcelain=v1", "-z", "--untracked-files=all") + if err != nil { + return result, verifierProblem(ctx, err, "inspect verifier checkout") + } + if status != "" { + return result, problem("VERIFIER_INVALID", "verifier checkout is not clean") + } + commit, err := repo.Text(ctx, nil, "rev-parse", "--verify", "HEAD^{commit}") + if err != nil || !objectPattern.MatchString(commit) { + return result, verifierProblem(ctx, err, "resolve verifier commit") + } + tree, err := objectTree(ctx, repo, commit) + if err != nil { + return result, problem("VERIFIER_INVALID", "resolve verifier tree: %v", err) + } + commandDigest, err := trackedBlobDigest(ctx, repo, commit, verifierCommandPath) + if err != nil { + return result, err + } + schemaDigest, err := trackedBlobDigest(ctx, repo, commit, verifierSchemaPath) + if err != nil { + return result, err + } + return verifierEvidence{ + Commit: commit, + Tree: tree, + CommandPath: verifierCommandPath, + CommandDigest: commandDigest, + SchemaPath: verifierSchemaPath, + SchemaDigest: schemaDigest, + Clean: true, + CompleteHistory: true, + ReplacementRefCount: 0, + ObjectIntegrityCheck: "passed", + }, nil +} + +func trackedBlobDigest(ctx context.Context, repo gitx.Repo, commit, path string) (string, error) { + object := commit + ":" + path + typeName, err := repo.Text(ctx, nil, "cat-file", "-t", object) + if err != nil || typeName != "blob" { + return "", verifierProblem(ctx, err, "verifier artifact %s is not a tracked file", path) + } + sizeText, err := repo.Text(ctx, nil, "cat-file", "-s", object) + if err != nil { + return "", verifierProblem(ctx, err, "inspect verifier artifact %s", path) + } + size, err := strconv.ParseInt(sizeText, 10, 64) + if err != nil || size < 1 || size > maximumVerifierFileBytes { + return "", problem("VERIFIER_INVALID", "verifier artifact %s has an invalid size", path) + } + body, err := repo.Raw(ctx, nil, "cat-file", "blob", object) + if err != nil || int64(len(body)) != size { + return "", verifierProblem(ctx, err, "read verifier artifact %s", path) + } + digest := sha256.Sum256([]byte(body)) + return "sha256:" + hex.EncodeToString(digest[:]), nil +} + +func verifierProblem(ctx context.Context, err error, format string, arguments ...any) error { + if errors.Is(ctx.Err(), context.DeadlineExceeded) { + return problem("COMMAND_TIMEOUT", "verifier checks exceeded %s", gitCommandTimeout) + } + if err == nil { + return problem("VERIFIER_INVALID", format, arguments...) + } + return wrapProblem("VERIFIER_INVALID", err, format, arguments...) +} + +func collectGitEvidence(parent context.Context, repo gitx.Repo, bootstrap, oldCandidate, candidate string, expectedPaths []string) (gitEvidence, error) { + ctx, cancel := context.WithTimeout(parent, gitCommandTimeout) + defer cancel() + var result gitEvidence + if _, err := repo.Text(ctx, nil, "check-ref-format", "--branch", "main"); err != nil { + return result, gitProblem(ctx, "GIT_CHECK_FAILED", err, "validate Git command execution") + } + shallow, err := repo.Text(ctx, nil, "rev-parse", "--is-shallow-repository") + if err != nil || shallow != "false" { + return result, gitProblem(ctx, "GIT_CHECK_FAILED", err, "candidate history must be complete and non-shallow") + } + replacements, err := repo.Lines(ctx, nil, "for-each-ref", "--format=%(refname)", "refs/replace") + if err != nil { + return result, gitProblem(ctx, "GIT_CHECK_FAILED", err, "inspect replacement refs") + } + if len(replacements) != 0 { + return result, problem("GIT_CHECK_FAILED", "candidate repository has replacement refs") + } + if _, err := repo.Raw(ctx, nil, "fsck", "--strict", "--no-dangling"); err != nil { + return result, gitProblem(ctx, "OBJECT_CHECK_FAILED", err, "candidate object integrity check") + } + status, err := repo.Raw(ctx, nil, "status", "--porcelain=v1", "-z", "--untracked-files=all") + if err != nil { + return result, gitProblem(ctx, "GIT_CHECK_FAILED", err, "inspect candidate checkout") + } + if status != "" { + return result, problem("CHECKOUT_NOT_CLEAN", "candidate checkout is not clean") + } + for label, object := range map[string]string{"bootstrap": bootstrap, "old candidate": oldCandidate, "candidate": candidate} { + resolved, resolveErr := repo.Text(ctx, nil, "rev-parse", "--verify", object+"^{commit}") + if resolveErr != nil || resolved != object { + return result, gitProblem(ctx, "CANDIDATE_MISMATCH", resolveErr, "%s does not resolve exactly", label) + } + } + head, err := repo.Text(ctx, nil, "rev-parse", "HEAD") + if err != nil || head != candidate { + return result, gitProblem(ctx, "CANDIDATE_MISMATCH", err, "checked-out commit does not equal --candidate") + } + ancestorCode, err := repo.Exit(ctx, nil, "merge-base", "--is-ancestor", bootstrap, oldCandidate) + if err != nil || ancestorCode != 0 { + return result, gitProblem(ctx, "CORRECTION_NOT_LINEAR", err, "bootstrap is not an ancestor of the old candidate") + } + commits, err := collectLinearCorrectionRange(ctx, repo, oldCandidate, candidate) + if err != nil { + return result, err + } + bootstrapTree, err := objectTree(ctx, repo, bootstrap) + if err != nil { + return result, err + } + oldTree, err := objectTree(ctx, repo, oldCandidate) + if err != nil { + return result, err + } + candidateTree, err := objectTree(ctx, repo, candidate) + if err != nil { + return result, err + } + bootstrapDelta, err := changedPaths(ctx, repo, bootstrap, candidate) + if err != nil { + return result, err + } + if !equalStrings(bootstrapDelta, expectedPaths) { + return result, problem("PATH_MANIFEST_MISMATCH", "bootstrap delta does not match the reviewed path manifest") + } + correctionDelta, err := changedPaths(ctx, repo, oldCandidate, candidate) + if err != nil { + return result, err + } + if len(correctionDelta) == 0 { + return result, problem("CORRECTION_NOT_LINEAR", "correction range does not change a reviewed path") + } + identities, err := collectIdentities(ctx, repo, candidate) + if err != nil { + return result, err + } + result.Bootstrap = objectEvidence{Commit: bootstrap, Tree: bootstrapTree} + result.Correction = correctionEvidence{ + OldCandidate: objectEvidence{Commit: oldCandidate, Tree: oldTree}, + NewCandidate: objectEvidence{Commit: candidate, Tree: candidateTree}, + Commits: commits, + BootstrapDelta: bootstrapDelta, + CorrectionDelta: correctionDelta, + MergeFree: true, + OldIsAncestor: true, + BootstrapIsAncestor: true, + } + result.Identity = identities + return result, nil +} + +func collectLinearCorrectionRange(ctx context.Context, repo gitx.Repo, oldCandidate, candidate string) ([]correctionCommit, error) { + commits, err := repo.Lines(ctx, nil, "rev-list", "--reverse", "--topo-order", oldCandidate+".."+candidate) + if err != nil { + return nil, gitProblem(ctx, "CORRECTION_NOT_LINEAR", err, "inspect correction range") + } + if len(commits) == 0 || commits[len(commits)-1] != candidate { + return nil, problem("CORRECTION_NOT_LINEAR", "old candidate must be an ancestor of a non-empty correction range") + } + previous := oldCandidate + result := make([]correctionCommit, 0, len(commits)) + for _, commit := range commits { + parents, parentErr := repo.Text(ctx, nil, "rev-list", "--parents", "-n", "1", commit) + if parentErr != nil { + return nil, gitProblem(ctx, "CORRECTION_NOT_LINEAR", parentErr, "inspect correction commit") + } + fields := strings.Fields(parents) + if len(fields) != 2 || fields[0] != commit || fields[1] != previous { + return nil, problem("CORRECTION_NOT_LINEAR", "correction range is not a linear first-parent chain") + } + tree, treeErr := objectTree(ctx, repo, commit) + if treeErr != nil { + return nil, treeErr + } + result = append(result, correctionCommit{Commit: commit, Tree: tree, Parent: previous}) + previous = commit + } + return result, nil +} + +func objectTree(ctx context.Context, repo gitx.Repo, object string) (string, error) { + tree, err := repo.Text(ctx, nil, "show", "-s", "--format=%T", object) + if err != nil || !objectPattern.MatchString(tree) { + return "", gitProblem(ctx, "OBJECT_CHECK_FAILED", err, "resolve commit tree") + } + return tree, nil +} + +func changedPaths(ctx context.Context, repo gitx.Repo, old, current string) ([]string, error) { + paths, err := repo.NULPaths(ctx, nil, "diff", "--no-renames", "--name-only", "-z", old, current) + if err != nil { + return nil, gitProblem(ctx, "GIT_CHECK_FAILED", err, "inspect changed paths") + } + sort.Strings(paths) + return paths, nil +} + +func collectIdentities(ctx context.Context, repo gitx.Repo, candidate string) (identitySet, error) { + countText, err := repo.Text(ctx, nil, "rev-list", "--count", candidate) + if err != nil { + return identitySet{}, gitProblem(ctx, "IDENTITY_MISMATCH", err, "count history identities") + } + count, err := strconv.Atoi(countText) + if err != nil || count < 1 { + return identitySet{}, problem("IDENTITY_MISMATCH", "history commit count is invalid") + } + output, err := repo.Raw(ctx, nil, "log", "-z", "--format=%H%x00%an%x00%ae%x00%cn%x00%ce%x00", candidate) + if err != nil { + return identitySet{}, gitProblem(ctx, "IDENTITY_MISMATCH", err, "read history identities") + } + values := nonemptyNULValues(output) + if len(values) != count*5 { + return identitySet{}, problem("IDENTITY_MISMATCH", "history identity stream is incomplete") + } + authorNames, authorEmails, committerNames, committerEmails := map[string]bool{}, map[string]bool{}, map[string]bool{}, map[string]bool{} + for index := 0; index < len(values); index += 5 { + if !objectPattern.MatchString(values[index]) { + return identitySet{}, problem("IDENTITY_MISMATCH", "history identity stream contains an invalid commit") + } + authorNames[values[index+1]], authorEmails[values[index+2]] = true, true + committerNames[values[index+3]], committerEmails[values[index+4]] = true, true + } + result := identitySet{ + HistoryCommitCount: count, + AuthorNames: sortedKeys(authorNames), + AuthorEmails: sortedKeys(authorEmails), + CommitterNames: sortedKeys(committerNames), + CommitterEmails: sortedKeys(committerEmails), + } + hash := sha256.New() + for _, group := range []struct { + label string + values []string + }{ + {label: "author-email", values: result.AuthorEmails}, + {label: "author-name", values: result.AuthorNames}, + {label: "committer-email", values: result.CommitterEmails}, + {label: "committer-name", values: result.CommitterNames}, + } { + for _, value := range group.values { + _, _ = fmt.Fprintf(hash, "%s\x00%s\x00", group.label, value) + } + } + result.Digest = "sha256:" + hex.EncodeToString(hash.Sum(nil)) + return result, nil +} + +func gitProblem(ctx context.Context, code string, err error, format string, arguments ...any) error { + if errors.Is(ctx.Err(), context.DeadlineExceeded) { + return problem("COMMAND_TIMEOUT", "Git checks exceeded %s", gitCommandTimeout) + } + message := fmt.Sprintf(format, arguments...) + if err == nil { + return problem(code, "%s", message) + } + return wrapProblem(code, err, "%s", message) +} + +type hostedEvidence struct { + Repository repositoryEvidence + Remote remoteEvidence + PullRequest pullRequestEvidence + Runs []runEvidence + Ruleset rulesetEvidence + RequiredChecks []requiredCheckEvidence + PublicNameMatch bool +} + +type githubUser struct { + Login string `json:"login"` + Name string `json:"name"` + Email string `json:"email"` +} + +type githubViewer struct { + Data struct { + Viewer struct { + Login string `json:"login"` + } `json:"viewer"` + } `json:"data"` +} + +type githubRepository struct { + FullName string `json:"full_name"` + Visibility string `json:"visibility"` + Private bool `json:"private"` + DefaultBranch string `json:"default_branch"` + Owner struct { + Login string `json:"login"` + } `json:"owner"` +} + +type githubRef struct { + Ref string `json:"ref"` + Object struct { + SHA string `json:"sha"` + Type string `json:"type"` + } `json:"object"` +} + +type githubPullRequest struct { + Number int `json:"number"` + State string `json:"state"` + Merged bool `json:"merged"` + MergedAt *time.Time `json:"merged_at"` + MergeCommit string `json:"merge_commit_sha"` + Head struct { + Ref string `json:"ref"` + SHA string `json:"sha"` + } `json:"head"` + Base struct { + Ref string `json:"ref"` + SHA string `json:"sha"` + } `json:"base"` +} + +type githubRun struct { + ID int64 `json:"id"` + Event string `json:"event"` + HeadBranch string `json:"head_branch"` + HeadSHA string `json:"head_sha"` + Status string `json:"status"` + Conclusion string `json:"conclusion"` + Attempt int `json:"run_attempt"` + Name string `json:"name"` +} + +type githubRuleset struct { + ID int64 `json:"id"` + Name string `json:"name"` + Target string `json:"target"` + Enforcement string `json:"enforcement"` + BypassActors []map[string]any `json:"bypass_actors"` + Conditions struct { + RefName struct { + Include []string `json:"include"` + Exclude []string `json:"exclude"` + } `json:"ref_name"` + } `json:"conditions"` + Rules []struct { + Type string `json:"type"` + Parameters struct { + RequiredApprovingReviewCount int `json:"required_approving_review_count"` + DismissStaleReviews bool `json:"dismiss_stale_reviews_on_push"` + RequireLastPushApproval bool `json:"require_last_push_approval"` + RequireReviewThreadResolution bool `json:"required_review_thread_resolution"` + AllowedMergeMethods []string `json:"allowed_merge_methods"` + StrictRequiredChecks bool `json:"strict_required_status_checks_policy"` + DoNotEnforceOnCreate bool `json:"do_not_enforce_on_create"` + RequiredChecks []struct { + Context string `json:"context"` + IntegrationID int64 `json:"integration_id"` + } `json:"required_status_checks"` + } `json:"parameters"` + } `json:"rules"` +} + +type githubJobs struct { + Jobs []struct { + ID int64 `json:"id"` + Name string `json:"name"` + Status string `json:"status"` + Conclusion string `json:"conclusion"` + } `json:"jobs"` +} + +type githubCheckRun struct { + ID int64 `json:"id"` + Name string `json:"name"` + Status string `json:"status"` + Conclusion string `json:"conclusion"` + App struct { + ID int64 `json:"id"` + } `json:"app"` +} + +func collectGitHubEvidence(ctx context.Context, directory string, configuration options, identities identitySet, runExternal externalRunner) (hostedEvidence, error) { + var result hostedEvidence + owner := strings.SplitN(configuration.Target, "/", 2)[0] + authenticated, err := githubAuthenticatedLogin(ctx, directory, runExternal) + if err != nil { + return result, err + } + if authenticated != owner { + return result, problem("TARGET_MISMATCH", "authenticated GitHub account does not match the target owner") + } + var publicOwner githubUser + if err := githubAPI(ctx, directory, runExternal, "users/"+owner, &publicOwner); err != nil { + return result, err + } + if publicOwner.Login != owner || strings.TrimSpace(publicOwner.Email) == "" { + return result, problem("IDENTITY_MISMATCH", "target owner public email is unavailable") + } + if !allIdentityValuesMatch(identities.AuthorEmails, publicOwner.Email) || !allIdentityValuesMatch(identities.CommitterEmails, publicOwner.Email) { + return result, problem("IDENTITY_MISMATCH", "history author or committer email does not match the public owner profile") + } + result.PublicNameMatch = allIdentityValuesMatch(identities.AuthorNames, publicOwner.Name) && allIdentityValuesMatch(identities.CommitterNames, publicOwner.Name) + var repository githubRepository + if err := githubAPI(ctx, directory, runExternal, "repos/"+configuration.Target, &repository); err != nil { + return result, err + } + if repository.FullName != configuration.Target || repository.Owner.Login != owner || repository.Private || repository.Visibility != "public" || repository.DefaultBranch != "main" { + return result, problem("TARGET_MISMATCH", "target repository identity, visibility, owner, or default branch differs") + } + var candidateRef githubRef + if err := githubAPI(ctx, directory, runExternal, "repos/"+configuration.Target+"/git/ref/heads/"+configuration.CandidateRef, &candidateRef); err != nil { + return result, err + } + if candidateRef.Ref != "refs/heads/"+configuration.CandidateRef || candidateRef.Object.Type != "commit" || candidateRef.Object.SHA != configuration.Candidate { + return result, problem("REMOTE_REF_MISMATCH", "remote candidate ref does not equal the corrected candidate") + } + var mainRef githubRef + if err := githubAPI(ctx, directory, runExternal, "repos/"+configuration.Target+"/git/ref/heads/main", &mainRef); err != nil { + return result, err + } + expectedMain := configuration.Bootstrap + if configuration.Phase == "finalized" { + expectedMain = configuration.Candidate + } + if mainRef.Ref != "refs/heads/main" || mainRef.Object.Type != "commit" || mainRef.Object.SHA != expectedMain { + return result, problem("REMOTE_REF_MISMATCH", "remote main does not match the required %s phase commit", configuration.Phase) + } + var pull githubPullRequest + if err := githubAPI(ctx, directory, runExternal, fmt.Sprintf("repos/%s/pulls/%d", configuration.Target, configuration.PullRequest), &pull); err != nil { + return result, err + } + expectedPRState := "open" + if configuration.Phase == "finalized" { + expectedPRState = "closed" + } + if pull.Number != configuration.PullRequest || pull.State != expectedPRState || pull.Merged || pull.MergedAt != nil || pull.Head.Ref != configuration.CandidateRef || pull.Head.SHA != configuration.Candidate || pull.Base.Ref != "main" || pull.Base.SHA != configuration.Bootstrap { + return result, problem("PULL_REQUEST_MISMATCH", "verification pull request does not match the candidate, phase, base, or unmerged state") + } + runs, verificationRun, err := collectRuns(ctx, directory, configuration, runExternal) + if err != nil { + return result, err + } + ruleset, requirements, err := collectRuleset(ctx, directory, configuration, runExternal) + if err != nil { + return result, err + } + checks, err := collectRequiredChecks(ctx, directory, configuration.Target, verificationRun, requirements, runExternal) + if err != nil { + return result, err + } + result.Repository = repositoryEvidence{FullName: configuration.Target, Visibility: "public", DefaultBranch: "main", AuthenticatedOwner: true} + result.Remote = remoteEvidence{CandidateRef: configuration.CandidateRef, CandidateCommit: configuration.Candidate, MainRef: "main", MainCommit: expectedMain} + result.PullRequest = pullRequestEvidence{Number: pull.Number, State: pull.State, HeadRef: pull.Head.Ref, HeadCommit: pull.Head.SHA, BaseRef: pull.Base.Ref, BaseCommit: pull.Base.SHA, Merged: false, MergeCommit: pull.MergeCommit} + result.Runs, result.Ruleset, result.RequiredChecks = runs, ruleset, checks + return result, nil +} + +func githubAuthenticatedLogin(ctx context.Context, directory string, runExternal externalRunner) (string, error) { + stdout, stderr, code, err := runExternal(ctx, githubCommandTimeout, directory, "gh", "api", "graphql", "-f", "query=query { viewer { login } }") + if err != nil { + if errors.Is(err, context.DeadlineExceeded) { + return "", problem("COMMAND_TIMEOUT", "GitHub request exceeded %s", githubCommandTimeout) + } + return "", wrapProblem("GITHUB_CHECK_FAILED", err, "query authenticated GitHub viewer") + } + if code != 0 { + return "", problem("GITHUB_CHECK_FAILED", "GitHub viewer request failed: %s", commandFailureOutput("", stderr)) + } + var viewer githubViewer + if err := json.Unmarshal([]byte(stdout), &viewer); err != nil { + return "", wrapProblem("GITHUB_CHECK_FAILED", err, "decode authenticated GitHub viewer") + } + if strings.TrimSpace(viewer.Data.Viewer.Login) == "" { + return "", problem("GITHUB_CHECK_FAILED", "authenticated GitHub viewer has no login") + } + return viewer.Data.Viewer.Login, nil +} + +func collectRuns(ctx context.Context, directory string, configuration options, runExternal externalRunner) ([]runEvidence, int64, error) { + runs := make([]runEvidence, 0, len(configuration.Runs)) + verificationRun, pullRuns, candidatePushes, mainPushes := int64(0), 0, 0, 0 + for _, spec := range configuration.Runs { + var run githubRun + if err := githubAPI(ctx, directory, runExternal, fmt.Sprintf("repos/%s/actions/runs/%d", configuration.Target, spec.ID), &run); err != nil { + return nil, 0, err + } + if run.ID != spec.ID || run.Event != spec.Event || run.HeadBranch != spec.Branch || run.HeadSHA != configuration.Candidate || run.Status != "completed" || run.Conclusion != "success" || run.Attempt < 1 || strings.TrimSpace(run.Name) == "" { + return nil, 0, problem("HOSTED_RUN_FAILED", "hosted run %s does not match its reviewed event, branch, candidate, or successful result", spec.Label) + } + if run.Event == "pull_request" && run.HeadBranch == configuration.CandidateRef { + pullRuns++ + verificationRun = run.ID + } + if run.Event == "push" && run.HeadBranch == configuration.CandidateRef { + candidatePushes++ + } + if run.Event == "push" && run.HeadBranch == "main" { + mainPushes++ + } + runs = append(runs, runEvidence{Label: spec.Label, ID: run.ID, Event: run.Event, HeadBranch: run.HeadBranch, HeadCommit: run.HeadSHA, Status: run.Status, Conclusion: run.Conclusion, Attempt: run.Attempt, Workflow: run.Name}) + } + if pullRuns != 1 || candidatePushes < 1 { + return nil, 0, problem("HOSTED_RUN_INCOMPLETE", "runs must contain one candidate pull-request run and at least one candidate push run") + } + if configuration.Phase == "finalized" && mainPushes < 1 { + return nil, 0, problem("HOSTED_RUN_INCOMPLETE", "finalized runs must contain a successful main push run") + } + return runs, verificationRun, nil +} + +type checkRequirement struct { + Context string + IntegrationID int64 +} + +func collectRuleset(ctx context.Context, directory string, configuration options, runExternal externalRunner) (rulesetEvidence, []checkRequirement, error) { + var ruleset githubRuleset + if err := githubAPI(ctx, directory, runExternal, fmt.Sprintf("repos/%s/rulesets/%d", configuration.Target, configuration.Ruleset), &ruleset); err != nil { + return rulesetEvidence{}, nil, err + } + if ruleset.ID != configuration.Ruleset || strings.TrimSpace(ruleset.Name) == "" || ruleset.Target != "branch" || ruleset.Enforcement != "active" || len(ruleset.BypassActors) != 0 || !equalStrings(ruleset.Conditions.RefName.Include, []string{"~DEFAULT_BRANCH"}) || len(ruleset.Conditions.RefName.Exclude) != 0 { + return rulesetEvidence{}, nil, problem("RULESET_MISMATCH", "ruleset must have a name, no bypass actor, and one active default-branch target") + } + ruleCounts := map[string]int{} + var pullParameters struct { + RequiredApprovingReviewCount int + DismissStaleReviews bool + RequireLastPushApproval bool + RequireReviewThreadResolution bool + AllowedMergeMethods []string + } + strict, requiredChecksOnCreate := false, false + var requirements []checkRequirement + for _, rule := range ruleset.Rules { + ruleCounts[rule.Type]++ + switch rule.Type { + case "pull_request": + pullParameters.RequiredApprovingReviewCount = rule.Parameters.RequiredApprovingReviewCount + pullParameters.DismissStaleReviews = rule.Parameters.DismissStaleReviews + pullParameters.RequireLastPushApproval = rule.Parameters.RequireLastPushApproval + pullParameters.RequireReviewThreadResolution = rule.Parameters.RequireReviewThreadResolution + pullParameters.AllowedMergeMethods = append([]string(nil), rule.Parameters.AllowedMergeMethods...) + case "required_status_checks": + strict = rule.Parameters.StrictRequiredChecks + requiredChecksOnCreate = !rule.Parameters.DoNotEnforceOnCreate + for _, check := range rule.Parameters.RequiredChecks { + requirements = append(requirements, checkRequirement{Context: check.Context, IntegrationID: check.IntegrationID}) + } + } + } + for _, requiredRule := range []string{"deletion", "non_fast_forward", "required_linear_history", "pull_request", "required_status_checks"} { + if ruleCounts[requiredRule] != 1 { + return rulesetEvidence{}, nil, problem("RULESET_MISMATCH", "ruleset must contain exactly one %s rule", requiredRule) + } + } + if pullParameters.RequiredApprovingReviewCount < 1 || !pullParameters.DismissStaleReviews || !pullParameters.RequireLastPushApproval || !pullParameters.RequireReviewThreadResolution || !equalStrings(pullParameters.AllowedMergeMethods, []string{"rebase"}) { + return rulesetEvidence{}, nil, problem("RULESET_MISMATCH", "pull-request rule must require review, stale-review dismissal, last-push approval, resolved threads, and rebase-only merges") + } + if !strict || !requiredChecksOnCreate || len(requirements) == 0 { + return rulesetEvidence{}, nil, problem("RULESET_MISMATCH", "status checks must be strict, required on branch creation, and non-empty") + } + sort.Slice(requirements, func(left, right int) bool { return requirements[left].Context < requirements[right].Context }) + seen := map[string]bool{} + for _, requirement := range requirements { + if strings.TrimSpace(requirement.Context) == "" || requirement.IntegrationID <= 0 || seen[requirement.Context] { + return rulesetEvidence{}, nil, problem("RULESET_MISMATCH", "ruleset contains an invalid or duplicate required check") + } + seen[requirement.Context] = true + } + return rulesetEvidence{ + ID: ruleset.ID, + Name: ruleset.Name, + Enforcement: ruleset.Enforcement, + NoBypassActors: true, + DeletionBlocked: true, + NonFastForwardBlocked: true, + LinearHistoryRequired: true, + PullRequestRequired: true, + RequiredApprovingReviewCount: pullParameters.RequiredApprovingReviewCount, + DismissStaleReviews: true, + LastPushApprovalRequired: true, + ReviewThreadsResolved: true, + AllowedMergeMethods: []string{"rebase"}, + StrictRequiredChecks: true, + RequiredChecksOnCreate: true, + }, requirements, nil +} + +func collectRequiredChecks(ctx context.Context, directory, target string, verificationRun int64, requirements []checkRequirement, runExternal externalRunner) ([]requiredCheckEvidence, error) { + var jobs githubJobs + endpoint := fmt.Sprintf("repos/%s/actions/runs/%d/jobs?filter=latest&per_page=100", target, verificationRun) + if err := githubAPI(ctx, directory, runExternal, endpoint, &jobs); err != nil { + return nil, err + } + result := make([]requiredCheckEvidence, 0, len(requirements)) + for _, requirement := range requirements { + var jobID int64 + for _, job := range jobs.Jobs { + if job.Name == requirement.Context && job.Status == "completed" && job.Conclusion == "success" && job.ID > jobID { + jobID = job.ID + } + } + if jobID == 0 { + return nil, problem("REQUIRED_CHECK_FAILED", "required check %q has no successful job in the verification run", requirement.Context) + } + var check githubCheckRun + if err := githubAPI(ctx, directory, runExternal, fmt.Sprintf("repos/%s/check-runs/%d", target, jobID), &check); err != nil { + return nil, err + } + if check.ID != jobID || check.Name != requirement.Context || check.App.ID != requirement.IntegrationID || check.Status != "completed" || check.Conclusion != "success" { + return nil, problem("REQUIRED_CHECK_FAILED", "required check %q does not match its integration or successful result", requirement.Context) + } + result = append(result, requiredCheckEvidence{Context: check.Name, IntegrationID: check.App.ID, CheckRunID: check.ID, Status: check.Status, Conclusion: check.Conclusion}) + } + return result, nil +} + +func githubAPI(ctx context.Context, directory string, runExternal externalRunner, endpoint string, target any) error { + stdout, stderr, code, err := runExternal(ctx, githubCommandTimeout, directory, "gh", "api", endpoint) + if err != nil { + if errors.Is(err, context.DeadlineExceeded) { + return problem("COMMAND_TIMEOUT", "GitHub request exceeded %s", githubCommandTimeout) + } + return wrapProblem("GITHUB_CHECK_FAILED", err, "query GitHub API") + } + if code != 0 { + return problem("GITHUB_CHECK_FAILED", "GitHub API request failed: %s", commandFailureOutput("", stderr)) + } + if err := json.Unmarshal([]byte(stdout), target); err != nil { + return wrapProblem("GITHUB_CHECK_FAILED", err, "decode GitHub API response") + } + return nil +} + +func allIdentityValuesMatch(values []string, expected string) bool { + if len(values) == 0 || strings.TrimSpace(expected) == "" { + return false + } + for _, value := range values { + if !strings.EqualFold(strings.TrimSpace(value), strings.TrimSpace(expected)) { + return false + } + } + return true +} + +func runSecretScans(ctx context.Context, directory string, runExternal externalRunner) error { + for _, arguments := range [][]string{{"git", "--redact", "--exit-code", "1", "."}, {"dir", "--redact", "--exit-code", "1", "."}} { + stdout, stderr, code, err := runExternal(ctx, secretScanTimeout, directory, "gitleaks", arguments...) + if err != nil { + if errors.Is(err, context.DeadlineExceeded) { + return problem("COMMAND_TIMEOUT", "secret scan exceeded %s", secretScanTimeout) + } + return wrapProblem("SECRET_SCAN_FAILED", err, "run gitleaks %s", arguments[0]) + } + if code != 0 { + return problem("SECRET_SCAN_FAILED", "gitleaks %s failed: %s", arguments[0], commandFailureOutput(stdout, stderr)) + } + } + return nil +} + +func externalCommandWithTimeout(ctx context.Context, timeout time.Duration, directory, name string, arguments ...string) (string, string, int, error) { + commandContext, cancel := context.WithTimeout(ctx, timeout) + defer cancel() + stdout, stderr, code, err := externalCommand(commandContext, directory, name, arguments...) + if commandContext.Err() != nil { + return stdout, stderr, -1, commandContext.Err() + } + return stdout, stderr, code, err +} + +func externalCommand(ctx context.Context, directory, name string, arguments ...string) (string, string, int, error) { + command := exec.CommandContext(ctx, name, arguments...) + command.Dir = directory + command.Env = gitx.Environment(nil) + stdout, stderr := newBoundedOutput(maximumCommandOutputBytes), newBoundedOutput(maximumCommandOutputBytes) + command.Stdout, command.Stderr = &stdout, &stderr + err := command.Run() + if ctx.Err() != nil { + return stdout.String(), stderr.String(), -1, ctx.Err() + } + if err == nil { + return stdout.String(), stderr.String(), 0, nil + } + var exitError *exec.ExitError + if errors.As(err, &exitError) { + return stdout.String(), stderr.String(), exitError.ExitCode(), nil + } + return stdout.String(), stderr.String(), -1, err +} + +type boundedOutput struct { + buffer bytes.Buffer + remaining int + truncated bool +} + +func newBoundedOutput(maximum int) boundedOutput { return boundedOutput{remaining: maximum} } + +func (output *boundedOutput) Write(value []byte) (int, error) { + length, writeLength := len(value), min(output.remaining, len(value)) + if writeLength > 0 { + _, _ = output.buffer.Write(value[:writeLength]) + output.remaining -= writeLength + } + if writeLength < length { + output.truncated = true + } + return length, nil +} + +func (output *boundedOutput) String() string { + if output.truncated { + return output.buffer.String() + "\n[output truncated]" + } + return output.buffer.String() +} + +func commandFailureOutput(stdout, stderr string) string { + var parts []string + if value := strings.TrimSpace(stdout); value != "" { + parts = append(parts, value) + } + if value := strings.TrimSpace(stderr); value != "" { + parts = append(parts, value) + } + if len(parts) == 0 { + return "no diagnostic output" + } + return strings.Join(parts, "\n") +} + +func encodeReceipt(value receipt) ([]byte, string, error) { + body, err := json.MarshalIndent(value, "", " ") + if err != nil { + return nil, "", wrapProblem("RECEIPT_ENCODE_FAILED", err, "encode correction receipt") + } + body = append(body, '\n') + digest := sha256.Sum256(body) + return body, "sha256:" + hex.EncodeToString(digest[:]), nil +} + +func writeReceipt(path string, body []byte) error { + file, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o600) + if errors.Is(err, os.ErrExist) { + return problem("OUTPUT_EXISTS", "receipt output already exists") + } + if err != nil { + return wrapProblem("OUTPUT_WRITE_FAILED", err, "create correction receipt") + } + complete := false + defer func() { + _ = file.Close() + if !complete { + _ = os.Remove(path) + } + }() + if written, writeErr := file.Write(body); writeErr != nil || written != len(body) { + if writeErr == nil { + writeErr = io.ErrShortWrite + } + return wrapProblem("OUTPUT_WRITE_FAILED", writeErr, "write correction receipt") + } + if err := file.Sync(); err != nil { + return wrapProblem("OUTPUT_WRITE_FAILED", err, "sync correction receipt") + } + if err := file.Close(); err != nil { + return wrapProblem("OUTPUT_WRITE_FAILED", err, "close correction receipt") + } + complete = true + return nil +} + +func validatedReceiptOutput(roots []string, name string) (string, error) { + out, err := filepath.Abs(name) + if err != nil { + return "", wrapProblem("OUTPUT_UNSAFE", err, "resolve receipt output") + } + for _, root := range roots { + inside, containmentErr := pathWithinRoot(root, out) + if containmentErr != nil || inside { + return "", problem("OUTPUT_UNSAFE", "--out must resolve outside the candidate and verifier checkouts") + } + } + resolvedParent, err := filepath.EvalSymlinks(filepath.Dir(out)) + if err != nil { + return "", wrapProblem("OUTPUT_UNSAFE", err, "resolve receipt directory") + } + info, err := os.Stat(resolvedParent) + if err != nil || !info.IsDir() { + return "", problem("OUTPUT_UNSAFE", "receipt parent must be an existing directory") + } + if runtime.GOOS != "windows" && info.Mode().Perm()&0o077 != 0 { + return "", problem("OUTPUT_UNSAFE", "receipt directory must not grant group or other permissions") + } + resolvedOut := filepath.Join(resolvedParent, filepath.Base(out)) + if _, err := os.Lstat(resolvedOut); err == nil { + return "", problem("OUTPUT_EXISTS", "receipt output already exists") + } else if !errors.Is(err, os.ErrNotExist) { + return "", wrapProblem("OUTPUT_UNSAFE", err, "inspect receipt output") + } + return resolvedOut, nil +} + +func pathWithinRoot(root, name string) (bool, error) { + resolvedRoot, err := filepath.EvalSymlinks(root) + if err != nil { + return false, err + } + var resolvedName string + if existing, resolveErr := filepath.EvalSymlinks(name); resolveErr == nil { + resolvedName = existing + } else { + parent, parentErr := filepath.EvalSymlinks(filepath.Dir(name)) + if parentErr != nil { + return false, parentErr + } + resolvedName = filepath.Join(parent, filepath.Base(name)) + } + relative, err := filepath.Rel(resolvedRoot, resolvedName) + if err != nil { + return false, err + } + return relative != ".." && !strings.HasPrefix(relative, ".."+string(filepath.Separator)), nil +} + +func requireJSONEOF(decoder *json.Decoder) error { + var extra any + if err := decoder.Decode(&extra); err != io.EOF { + if err == nil { + return errors.New("document contains more than one JSON value") + } + return err + } + return nil +} + +func nonemptyNULValues(output string) []string { + var values []string + for _, value := range strings.Split(output, "\x00") { + if value = strings.TrimSpace(value); value != "" { + values = append(values, value) + } + } + return values +} + +func sortedKeys(values map[string]bool) []string { + keys := make([]string, 0, len(values)) + for value := range values { + if strings.TrimSpace(value) != "" { + keys = append(keys, value) + } + } + sort.Strings(keys) + return keys +} + +func equalStrings(left, right []string) bool { + if len(left) != len(right) { + return false + } + for index := range left { + if left[index] != right[index] { + return false + } + } + return true +} diff --git a/scripts/publication-correction/main_test.go b/scripts/publication-correction/main_test.go new file mode 100644 index 0000000..3aeb096 --- /dev/null +++ b/scripts/publication-correction/main_test.go @@ -0,0 +1,829 @@ +package main + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "io" + "os" + "os/exec" + "path/filepath" + "runtime" + "strconv" + "strings" + "testing" + "time" + + "github.com/nstranquist/wip-commit/internal/gitx" +) + +const ( + testTarget = "owner/project" + testOwner = "owner" + testPublicName = "Public Author" + testPublicEmail = "public@example.invalid" + testCandidateRef = "candidate/beta" + testRulesetID = int64(77) + testIntegration = int64(15368) + testCandidateRun = int64(101) + testPullRun = int64(102) + testMainRun = int64(103) + testCheckRun = int64(201) +) + +type correctionFixture struct { + repo gitx.Repo + verifier gitx.Repo + bootstrap, old string + candidate string + correctionCommits []string + pathsFile string + firstReceipt string + out string + privateDirectory string + hosted *hostedFixture +} + +type hostedRunFixture struct { + ID int64 + Event string + HeadBranch string + HeadSHA string + Status string + Conclusion string + Attempt int + Name string +} + +type hostedFixture struct { + bootstrap, candidate, candidateRef string + mainCommit string + publicName, publicEmail string + repositoryPrivate bool + repositoryVisibility string + remoteCandidate string + pullState string + pullHead string + pullMerged bool + pullMergedAt any + runs map[int64]hostedRunFixture + rulesetEnforcement string + rulesetStrict bool + rulesetBypass bool + rulesetDeletion bool + rulesetNonFastForward bool + rulesetLinearHistory bool + rulesetPullRequest bool + rulesetReviewCount int + rulesetDismissStale bool + rulesetLastPushApproval bool + rulesetReviewThreads bool + rulesetAllowedMergeMethods []string + rulesetDoNotEnforceOnCreate bool + checkIntegration int64 + checkConclusion string + secretFailure bool + timeoutCommand string +} + +func TestRunFinalizedCorrectionSuccess(t *testing.T) { + fixture := newCorrectionFixture(t, 1) + stdout := runFixture(t, fixture, "finalized") + var result map[string]any + if err := json.Unmarshal([]byte(stdout), &result); err != nil { + t.Fatal(err) + } + if result["ok"] != true || result["phase"] != "finalized" || result["candidate_commit"] != fixture.candidate { + t.Fatalf("result = %#v", result) + } + var receiptValue receipt + readJSONFile(t, fixture.out, &receiptValue) + if receiptValue.SchemaVersion != receiptSchemaVersion || receiptValue.Correction.NewCandidate.Commit != fixture.candidate || receiptValue.Correction.NewCandidate.Tree == "" { + t.Fatalf("receipt identity = %#v", receiptValue) + } + if len(receiptValue.Correction.Commits) != 1 || len(receiptValue.RequiredChecks) != 1 || len(receiptValue.HostedRuns) != 3 { + t.Fatalf("receipt evidence counts = correction %d, checks %d, runs %d", len(receiptValue.Correction.Commits), len(receiptValue.RequiredChecks), len(receiptValue.HostedRuns)) + } + if receiptValue.Remote.MainCommit != fixture.candidate || receiptValue.PullRequest.State != "closed" || receiptValue.PullRequest.Merged { + t.Fatalf("finalized evidence = %#v %#v", receiptValue.Remote, receiptValue.PullRequest) + } + if !sha256Pattern.MatchString(receiptValue.FirstReceipt.Digest) || !sha256Pattern.MatchString(receiptValue.Identity.IdentitySetDigest) { + t.Fatalf("receipt digests = %#v %#v", receiptValue.FirstReceipt, receiptValue.Identity) + } + if !sha256Pattern.MatchString(receiptValue.Verifier.CommandDigest) || !sha256Pattern.MatchString(receiptValue.Verifier.SchemaDigest) || !receiptValue.Ruleset.NoBypassActors || !receiptValue.Ruleset.LastPushApprovalRequired { + t.Fatalf("verifier or ruleset evidence = %#v %#v", receiptValue.Verifier, receiptValue.Ruleset) + } + info, err := os.Stat(fixture.out) + if err != nil { + t.Fatal(err) + } + if runtime.GOOS != "windows" && info.Mode().Perm() != 0o600 { + t.Fatalf("receipt mode = %v", info.Mode()) + } + body, err := os.ReadFile(fixture.out) + if err != nil { + t.Fatal(err) + } + for _, forbidden := range []string{fixture.repo.Root, fixture.firstReceipt, testPublicName, testPublicEmail, "token-value", "raw secret finding"} { + if strings.Contains(string(body), forbidden) { + t.Fatalf("receipt contains forbidden private value %q", forbidden) + } + } +} + +func TestRunPreMainCorrectionSuccess(t *testing.T) { + fixture := newCorrectionFixture(t, 1) + fixture.hosted.mainCommit = fixture.bootstrap + fixture.hosted.pullState = "open" + delete(fixture.hosted.runs, testMainRun) + stdout := runFixture(t, fixture, "pre-main") + if !strings.Contains(stdout, `"phase":"pre-main"`) { + t.Fatalf("stdout = %s", stdout) + } + var got receipt + readJSONFile(t, fixture.out, &got) + if got.Remote.MainCommit != fixture.bootstrap || got.PullRequest.State != "open" || len(got.HostedRuns) != 2 { + t.Fatalf("pre-main receipt = %#v", got) + } +} + +func TestRunRecordsDisplayNameDifferenceWithoutWeakeningEmailIdentity(t *testing.T) { + fixture := newCorrectionFixture(t, 1) + fixture.hosted.publicName = "Different Display Name" + runFixture(t, fixture, "finalized") + var got receipt + readJSONFile(t, fixture.out, &got) + if !got.Identity.PublicEmailMatch || got.Identity.PublicNameMatch { + t.Fatalf("identity result = %#v", got.Identity) + } +} + +func TestRunRecordsMultipleLinearCorrectionCommits(t *testing.T) { + fixture := newCorrectionFixture(t, 3) + runFixture(t, fixture, "finalized") + var got receipt + readJSONFile(t, fixture.out, &got) + if len(got.Correction.Commits) != 3 { + t.Fatalf("correction commits = %#v", got.Correction.Commits) + } + previous := fixture.old + for index, commit := range got.Correction.Commits { + if commit.Parent != previous || commit.Commit != fixture.correctionCommits[index] || commit.Tree == "" { + t.Fatalf("commit %d = %#v", index, commit) + } + previous = commit.Commit + } +} + +func TestRunRejectsHostedEvidenceMismatchesWithoutReceipt(t *testing.T) { + tests := []struct { + name string + code string + edit func(*correctionFixture) + }{ + {name: "moved candidate ref", code: "REMOTE_REF_MISMATCH", edit: func(f *correctionFixture) { f.hosted.remoteCandidate = f.old }}, + {name: "failed run", code: "HOSTED_RUN_FAILED", edit: func(f *correctionFixture) { + run := f.hosted.runs[testCandidateRun] + run.Conclusion = "failure" + f.hosted.runs[testCandidateRun] = run + }}, + {name: "pending run", code: "HOSTED_RUN_FAILED", edit: func(f *correctionFixture) { + run := f.hosted.runs[testCandidateRun] + run.Status, run.Conclusion = "in_progress", "" + f.hosted.runs[testCandidateRun] = run + }}, + {name: "run for another head", code: "HOSTED_RUN_FAILED", edit: func(f *correctionFixture) { + run := f.hosted.runs[testPullRun] + run.HeadSHA = f.old + f.hosted.runs[testPullRun] = run + }}, + {name: "pull request head moved", code: "PULL_REQUEST_MISMATCH", edit: func(f *correctionFixture) { f.hosted.pullHead = f.old }}, + {name: "pull request merged", code: "PULL_REQUEST_MISMATCH", edit: func(f *correctionFixture) { + f.hosted.pullMerged = true + f.hosted.pullMergedAt = "2026-08-17T00:00:00Z" + }}, + {name: "private repository", code: "TARGET_MISMATCH", edit: func(f *correctionFixture) { + f.hosted.repositoryPrivate, f.hosted.repositoryVisibility = true, "private" + }}, + {name: "public identity changed", code: "IDENTITY_MISMATCH", edit: func(f *correctionFixture) { f.hosted.publicEmail = "different@example.invalid" }}, + {name: "failed required check", code: "REQUIRED_CHECK_FAILED", edit: func(f *correctionFixture) { f.hosted.checkConclusion = "failure" }}, + {name: "different check integration", code: "REQUIRED_CHECK_FAILED", edit: func(f *correctionFixture) { f.hosted.checkIntegration = 999 }}, + {name: "inactive ruleset", code: "RULESET_MISMATCH", edit: func(f *correctionFixture) { f.hosted.rulesetEnforcement = "disabled" }}, + {name: "non-strict ruleset", code: "RULESET_MISMATCH", edit: func(f *correctionFixture) { f.hosted.rulesetStrict = false }}, + {name: "ruleset bypass", code: "RULESET_MISMATCH", edit: func(f *correctionFixture) { f.hosted.rulesetBypass = true }}, + {name: "deletion allowed", code: "RULESET_MISMATCH", edit: func(f *correctionFixture) { f.hosted.rulesetDeletion = false }}, + {name: "force push allowed", code: "RULESET_MISMATCH", edit: func(f *correctionFixture) { f.hosted.rulesetNonFastForward = false }}, + {name: "nonlinear history", code: "RULESET_MISMATCH", edit: func(f *correctionFixture) { f.hosted.rulesetLinearHistory = false }}, + {name: "pull requests optional", code: "RULESET_MISMATCH", edit: func(f *correctionFixture) { f.hosted.rulesetPullRequest = false }}, + {name: "reviews optional", code: "RULESET_MISMATCH", edit: func(f *correctionFixture) { f.hosted.rulesetReviewCount = 0 }}, + {name: "stale reviews retained", code: "RULESET_MISMATCH", edit: func(f *correctionFixture) { f.hosted.rulesetDismissStale = false }}, + {name: "last push approval optional", code: "RULESET_MISMATCH", edit: func(f *correctionFixture) { f.hosted.rulesetLastPushApproval = false }}, + {name: "review threads unresolved", code: "RULESET_MISMATCH", edit: func(f *correctionFixture) { f.hosted.rulesetReviewThreads = false }}, + {name: "merge commits allowed", code: "RULESET_MISMATCH", edit: func(f *correctionFixture) { f.hosted.rulesetAllowedMergeMethods = []string{"merge", "rebase"} }}, + {name: "checks skipped on create", code: "RULESET_MISMATCH", edit: func(f *correctionFixture) { f.hosted.rulesetDoNotEnforceOnCreate = true }}, + {name: "secret scan failure", code: "SECRET_SCAN_FAILED", edit: func(f *correctionFixture) { f.hosted.secretFailure = true }}, + } + for _, test := range tests { + t.Run(test.name, func(t *testing.T) { + fixture := newCorrectionFixture(t, 1) + test.edit(fixture) + expectFixtureFailure(t, fixture, "finalized", test.code) + }) + } +} + +func TestRunRejectsLocalEvidenceMismatchesWithoutReceipt(t *testing.T) { + t.Run("changed path manifest", func(t *testing.T) { + fixture := newCorrectionFixture(t, 1) + writeCorrectionFile(t, fixture.repo.Root, fixture.pathsFile, "core.txt\ndocs/paths.txt\n") + correctionGit(t, fixture.repo.Root, "add", fixture.pathsFile) + correctionGit(t, fixture.repo.Root, "commit", "-m", "test: change reviewed manifest") + fixture.updateCandidate(correctionGit(t, fixture.repo.Root, "rev-parse", "HEAD")) + expectFixtureFailure(t, fixture, "finalized", "PATH_MANIFEST_MISMATCH") + }) + + t.Run("merge commit", func(t *testing.T) { + fixture := newCorrectionFixture(t, 1) + correctionGit(t, fixture.repo.Root, "branch", "side", fixture.old) + correctionGit(t, fixture.repo.Root, "switch", "side") + writeCorrectionFile(t, fixture.repo.Root, "side.txt", "side\n") + correctionGit(t, fixture.repo.Root, "add", "side.txt") + correctionGit(t, fixture.repo.Root, "commit", "-m", "test: create side") + correctionGit(t, fixture.repo.Root, "switch", "main") + correctionGit(t, fixture.repo.Root, "merge", "--no-ff", "side", "-m", "test: merge side") + fixture.updateCandidate(correctionGit(t, fixture.repo.Root, "rev-parse", "HEAD")) + expectFixtureFailure(t, fixture, "finalized", "CORRECTION_NOT_LINEAR") + }) + + t.Run("checked out commit differs", func(t *testing.T) { + fixture := newCorrectionFixture(t, 2) + arguments := fixture.arguments("finalized") + replaceFlag(arguments, "--candidate", fixture.correctionCommits[0]) + err := runWithDependencies(context.Background(), arguments, io.Discard, fixture.dependencies()) + assertTypedError(t, err, "CANDIDATE_MISMATCH") + assertNoFile(t, fixture.out) + }) + + t.Run("different target repository", func(t *testing.T) { + fixture := newCorrectionFixture(t, 1) + arguments := fixture.arguments("finalized") + replaceFlag(arguments, "--target", "owner/different") + err := runWithDependencies(context.Background(), arguments, io.Discard, fixture.dependencies()) + assertTypedError(t, err, "TARGET_MISMATCH") + assertNoFile(t, fixture.out) + }) + + t.Run("first receipt trees differ", func(t *testing.T) { + fixture := newCorrectionFixture(t, 1) + var first map[string]any + readJSONFile(t, fixture.firstReceipt, &first) + first["candidate"].(map[string]any)["tree"] = fixture.bootstrap + writeJSONFile(t, fixture.firstReceipt, first, 0o600) + expectFixtureFailure(t, fixture, "finalized", "FIRST_RECEIPT_MISMATCH") + }) + + t.Run("corrupt object database", func(t *testing.T) { + fixture := newCorrectionFixture(t, 1) + object := fixture.candidate + path := filepath.Join(fixture.repo.GitDir, "objects", object[:2], object[2:]) + if err := os.Chmod(path, 0o600); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(path, []byte("corrupt"), 0o600); err != nil { + t.Fatal(err) + } + expectFixtureFailure(t, fixture, "finalized", "OBJECT_CHECK_FAILED") + }) +} + +func TestRunRejectsInvalidVerifierWithoutReceipt(t *testing.T) { + t.Run("dirty verifier", func(t *testing.T) { + fixture := newCorrectionFixture(t, 1) + writeCorrectionFile(t, fixture.verifier.Root, "untracked.txt", "dirty\n") + expectFixtureFailure(t, fixture, "finalized", "VERIFIER_INVALID") + }) + + t.Run("wrong verifier module", func(t *testing.T) { + fixture := newCorrectionFixture(t, 1) + writeCorrectionFile(t, fixture.verifier.Root, "go.mod", "module github.com/owner/different\n\ngo 1.25.12\n") + correctionGit(t, fixture.verifier.Root, "add", "go.mod") + correctionGit(t, fixture.verifier.Root, "commit", "-m", "test: change verifier module") + expectFixtureFailure(t, fixture, "finalized", "VERIFIER_INVALID") + }) + + t.Run("missing verifier schema", func(t *testing.T) { + fixture := newCorrectionFixture(t, 1) + correctionGit(t, fixture.verifier.Root, "rm", verifierSchemaPath) + correctionGit(t, fixture.verifier.Root, "commit", "-m", "test: remove verifier schema") + expectFixtureFailure(t, fixture, "finalized", "VERIFIER_INVALID") + }) +} + +func TestRunRejectsUnsafeOrExistingOutput(t *testing.T) { + t.Run("existing output", func(t *testing.T) { + fixture := newCorrectionFixture(t, 1) + if err := os.WriteFile(fixture.out, []byte("keep\n"), 0o600); err != nil { + t.Fatal(err) + } + err := runWithDependencies(context.Background(), fixture.arguments("finalized"), io.Discard, fixture.dependencies()) + assertTypedError(t, err, "OUTPUT_EXISTS") + body, err := os.ReadFile(fixture.out) + if err != nil || string(body) != "keep\n" { + t.Fatalf("existing output changed: %q, %v", body, err) + } + }) + + t.Run("output inside checkout", func(t *testing.T) { + fixture := newCorrectionFixture(t, 1) + fixture.out = filepath.Join(fixture.repo.Root, "receipt.json") + expectFixtureFailure(t, fixture, "finalized", "OUTPUT_UNSAFE") + }) + + t.Run("output inside verifier checkout", func(t *testing.T) { + fixture := newCorrectionFixture(t, 1) + fixture.out = filepath.Join(fixture.verifier.Root, "receipt.json") + expectFixtureFailure(t, fixture, "finalized", "OUTPUT_UNSAFE") + }) + + if runtime.GOOS != "windows" { + t.Run("open receipt directory", func(t *testing.T) { + fixture := newCorrectionFixture(t, 1) + if err := os.Chmod(fixture.privateDirectory, 0o755); err != nil { + t.Fatal(err) + } + expectFixtureFailure(t, fixture, "finalized", "OUTPUT_UNSAFE") + }) + } +} + +func TestRunRejectsTimeoutAndIncompleteDependencies(t *testing.T) { + fixture := newCorrectionFixture(t, 1) + fixture.hosted.timeoutCommand = "gitleaks" + expectFixtureFailure(t, fixture, "finalized", "COMMAND_TIMEOUT") + if err := runWithDependencies(context.Background(), nil, io.Discard, dependencies{}); errorCode(err) != "DEPENDENCIES_INCOMPLETE" { + t.Fatalf("incomplete dependencies error = %v (%s)", err, errorCode(err)) + } +} + +func TestReceiptEncodingIsDeterministicAndRedacted(t *testing.T) { + first := newCorrectionFixture(t, 2) + runFixture(t, first, "finalized") + firstBody, err := os.ReadFile(first.out) + if err != nil { + t.Fatal(err) + } + // Commit object IDs differ across fixture repositories. Compare two encodings + // of the same validated receipt instead of two repository histories. + var value receipt + if err := json.Unmarshal(firstBody, &value); err != nil { + t.Fatal(err) + } + bodyOne, digestOne, err := encodeReceipt(value) + if err != nil { + t.Fatal(err) + } + bodyTwo, digestTwo, err := encodeReceipt(value) + if err != nil { + t.Fatal(err) + } + if string(bodyOne) != string(bodyTwo) || digestOne != digestTwo { + t.Fatal("receipt encoding or digest is not deterministic") + } +} + +func TestReceiptSchemaMatchesGeneratedTopLevelContract(t *testing.T) { + fixture := newCorrectionFixture(t, 1) + runFixture(t, fixture, "finalized") + var document map[string]any + readJSONFile(t, fixture.out, &document) + var schema struct { + Schema string `json:"$schema"` + AdditionalProperties bool `json:"additionalProperties"` + Required []string `json:"required"` + Properties map[string]any `json:"properties"` + } + readJSONFile(t, filepath.Join("..", "..", "docs", "PUBLICATION-CORRECTION.schema.json"), &schema) + if schema.Schema != "https://json-schema.org/draft/2020-12/schema" || schema.AdditionalProperties { + t.Fatalf("schema identity = %#v", schema) + } + required := map[string]bool{} + for _, name := range schema.Required { + if required[name] { + t.Fatalf("duplicate required property %q", name) + } + required[name] = true + } + if len(required) != len(document) || len(schema.Properties) != len(document) { + t.Fatalf("schema keys = required %d, properties %d, receipt %d", len(required), len(schema.Properties), len(document)) + } + for name := range document { + if !required[name] || schema.Properties[name] == nil { + t.Errorf("generated property %q is not required by the schema", name) + } + } +} + +func TestExternalCommandWithTimeout(t *testing.T) { + t.Setenv("GO_WANT_CORRECTION_HELPER", "1") + arguments := func(mode string) []string { + return []string{"-test.run=^TestCorrectionExternalHelperProcess$", "--", mode} + } + stdout, stderr, code, err := externalCommandWithTimeout(context.Background(), 2*time.Second, t.TempDir(), os.Args[0], arguments("success")...) + if err != nil || code != 0 || stdout != "stdout" || stderr != "stderr" { + t.Fatalf("success = stdout %q, stderr %q, code %d, err %v", stdout, stderr, code, err) + } + _, _, code, err = externalCommandWithTimeout(context.Background(), 2*time.Second, t.TempDir(), os.Args[0], arguments("failure")...) + if err != nil || code != 7 { + t.Fatalf("failure = code %d, err %v", code, err) + } + _, _, code, err = externalCommandWithTimeout(context.Background(), 50*time.Millisecond, t.TempDir(), os.Args[0], arguments("timeout")...) + if err == nil || code != -1 || !errors.Is(err, context.DeadlineExceeded) { + t.Fatalf("timeout = code %d, err %v", code, err) + } +} + +func TestCorrectionExternalHelperProcess(t *testing.T) { + if os.Getenv("GO_WANT_CORRECTION_HELPER") != "1" { + return + } + switch os.Args[len(os.Args)-1] { + case "success": + _, _ = fmt.Fprint(os.Stdout, "stdout") + _, _ = fmt.Fprint(os.Stderr, "stderr") + os.Exit(0) + case "failure": + os.Exit(7) + case "timeout": + time.Sleep(10 * time.Second) + os.Exit(0) + default: + os.Exit(8) + } +} + +func newCorrectionFixture(t *testing.T, correctionCount int) *correctionFixture { + t.Helper() + if correctionCount < 1 { + t.Fatal("correctionCount must be positive") + } + directory := t.TempDir() + correctionGit(t, directory, "init", "-b", "main") + correctionGit(t, directory, "config", "user.name", testPublicName) + correctionGit(t, directory, "config", "user.email", testPublicEmail) + writeCorrectionFile(t, directory, "README.md", "base\n") + writeCorrectionFile(t, directory, "go.mod", "module github.com/"+testTarget+"\n\ngo 1.25.12\n") + correctionGit(t, directory, "add", "README.md", "go.mod") + correctionGit(t, directory, "commit", "-m", "test: create bootstrap") + bootstrap := correctionGit(t, directory, "rev-parse", "HEAD") + + paths := []string{"core.txt", "docs/paths.txt"} + for index := 1; index <= correctionCount; index++ { + paths = append(paths, fmt.Sprintf("fix-%d.txt", index)) + } + writeCorrectionFile(t, directory, "core.txt", "old candidate\n") + writeCorrectionFile(t, directory, "docs/paths.txt", strings.Join(paths, "\n")+"\n") + correctionGit(t, directory, "add", "core.txt", "docs/paths.txt") + correctionGit(t, directory, "commit", "-m", "test: create old candidate") + oldCandidate := correctionGit(t, directory, "rev-parse", "HEAD") + + var corrections []string + for index := 1; index <= correctionCount; index++ { + name := fmt.Sprintf("fix-%d.txt", index) + writeCorrectionFile(t, directory, name, fmt.Sprintf("correction %d\n", index)) + correctionGit(t, directory, "add", name) + correctionGit(t, directory, "commit", "-m", fmt.Sprintf("fix: correction %d", index)) + corrections = append(corrections, correctionGit(t, directory, "rev-parse", "HEAD")) + } + candidate := corrections[len(corrections)-1] + repo, err := gitx.Discover(context.Background(), directory) + if err != nil { + t.Fatal(err) + } + verifier := newVerifierFixture(t) + privateDirectory := t.TempDir() + if err := os.Chmod(privateDirectory, 0o700); err != nil { + t.Fatal(err) + } + firstReceipt := filepath.Join(privateDirectory, "first.json") + first := map[string]any{ + "schema_version": "1.0.0", + "target_repository": testTarget, + "target_visibility": "public", + "default_branch": "main", + "bootstrap": map[string]any{ + "commit": bootstrap, + "tree": correctionGit(t, directory, "show", "-s", "--format=%T", bootstrap), + }, + "candidate": map[string]any{ + "commit": oldCandidate, + "tree": correctionGit(t, directory, "show", "-s", "--format=%T", oldCandidate), + }, + "history_commit_count": 2, + "delta_paths": []string{"core.txt", "docs/paths.txt"}, + "local": map[string]any{ + "clean": true, "history_secret_scan": "passed", "worktree_secret_scan": "passed", + "object_integrity_check": "passed", "expected_delta_matched": true, + "bootstrap_is_ancestor": true, "linear_candidate_range": true, + }, + "github": map[string]any{ + "authenticated_owner": true, "target_repository_exists": false, "public_author_identity_match": true, + }, + } + writeJSONFile(t, firstReceipt, first, 0o600) + hosted := newHostedFixture(bootstrap, candidate) + return &correctionFixture{ + repo: repo, + verifier: verifier, + bootstrap: bootstrap, + old: oldCandidate, + candidate: candidate, + correctionCommits: corrections, + pathsFile: "docs/paths.txt", + firstReceipt: firstReceipt, + out: filepath.Join(privateDirectory, "correction.json"), + privateDirectory: privateDirectory, + hosted: hosted, + } +} + +func newVerifierFixture(t *testing.T) gitx.Repo { + t.Helper() + directory := t.TempDir() + correctionGit(t, directory, "init", "-b", "main") + correctionGit(t, directory, "config", "user.name", testPublicName) + correctionGit(t, directory, "config", "user.email", testPublicEmail) + writeCorrectionFile(t, directory, "go.mod", "module github.com/"+testTarget+"\n\ngo 1.25.12\n") + writeCorrectionFile(t, directory, verifierCommandPath, "package main\n") + writeCorrectionFile(t, directory, verifierSchemaPath, "{}\n") + correctionGit(t, directory, "add", "go.mod", verifierCommandPath, verifierSchemaPath) + correctionGit(t, directory, "commit", "-m", "test: create verifier") + repo, err := gitx.Discover(context.Background(), directory) + if err != nil { + t.Fatal(err) + } + return repo +} + +func newHostedFixture(bootstrap, candidate string) *hostedFixture { + return &hostedFixture{ + bootstrap: bootstrap, + candidate: candidate, + candidateRef: testCandidateRef, + mainCommit: candidate, + publicName: testPublicName, + publicEmail: testPublicEmail, + repositoryVisibility: "public", + remoteCandidate: candidate, + pullState: "closed", + pullHead: candidate, + rulesetEnforcement: "active", + rulesetStrict: true, + rulesetDeletion: true, + rulesetNonFastForward: true, + rulesetLinearHistory: true, + rulesetPullRequest: true, + rulesetReviewCount: 1, + rulesetDismissStale: true, + rulesetLastPushApproval: true, + rulesetReviewThreads: true, + rulesetAllowedMergeMethods: []string{"rebase"}, + checkIntegration: testIntegration, + checkConclusion: "success", + runs: map[int64]hostedRunFixture{ + testCandidateRun: {ID: testCandidateRun, Event: "push", HeadBranch: testCandidateRef, HeadSHA: candidate, Status: "completed", Conclusion: "success", Attempt: 1, Name: "ci"}, + testPullRun: {ID: testPullRun, Event: "pull_request", HeadBranch: testCandidateRef, HeadSHA: candidate, Status: "completed", Conclusion: "success", Attempt: 1, Name: "ci"}, + testMainRun: {ID: testMainRun, Event: "push", HeadBranch: "main", HeadSHA: candidate, Status: "completed", Conclusion: "success", Attempt: 1, Name: "ci"}, + }, + } +} + +func (fixture *correctionFixture) updateCandidate(candidate string) { + fixture.candidate = candidate + fixture.hosted.candidate = candidate + fixture.hosted.mainCommit = candidate + fixture.hosted.remoteCandidate = candidate + fixture.hosted.pullHead = candidate + for id, run := range fixture.hosted.runs { + run.HeadSHA = candidate + fixture.hosted.runs[id] = run + } +} + +func (fixture *correctionFixture) arguments(phase string) []string { + arguments := []string{ + "--repo-dir", fixture.repo.Root, + "--verifier-dir", fixture.verifier.Root, + "--target", testTarget, + "--phase", phase, + "--bootstrap", fixture.bootstrap, + "--old-candidate", fixture.old, + "--candidate", fixture.candidate, + "--candidate-ref", testCandidateRef, + "--first-receipt", fixture.firstReceipt, + "--paths-file", fixture.pathsFile, + "--pull-request", "1", + "--ruleset", strconv.FormatInt(testRulesetID, 10), + "--out", fixture.out, + "--run", fmt.Sprintf("candidate-push:push:%s:%d", testCandidateRef, testCandidateRun), + "--run", fmt.Sprintf("verification-pr:pull_request:%s:%d", testCandidateRef, testPullRun), + } + if phase == "finalized" { + arguments = append(arguments, "--run", fmt.Sprintf("main-push:push:main:%d", testMainRun)) + } + return arguments +} + +func (fixture *correctionFixture) dependencies() dependencies { + return dependencies{ + external: fixture.hosted.run, + now: func() time.Time { return time.Date(2026, time.August, 17, 12, 0, 0, 123456789, time.UTC) }, + } +} + +func (fixture *hostedFixture) run(_ context.Context, _ time.Duration, _ string, name string, arguments ...string) (string, string, int, error) { + if fixture.timeoutCommand == name { + return "", "", -1, context.DeadlineExceeded + } + if name == "gitleaks" { + if fixture.secretFailure { + return "raw secret finding", "", 1, nil + } + return "", "", 0, nil + } + if name == "gh" && len(arguments) == 4 && arguments[0] == "api" && arguments[1] == "graphql" && arguments[2] == "-f" { + body, err := json.Marshal(map[string]any{"data": map[string]any{"viewer": map[string]any{"login": testOwner}}}) + if err != nil { + return "", "", -1, err + } + return string(body), "", 0, nil + } + if name != "gh" || len(arguments) != 2 || arguments[0] != "api" { + return "", "", -1, fmt.Errorf("unexpected external command %q %q", name, arguments) + } + endpoint := arguments[1] + var value any + switch endpoint { + case "users/" + testOwner: + value = map[string]any{"login": testOwner, "name": fixture.publicName, "email": fixture.publicEmail} + case "repos/" + testTarget: + value = map[string]any{ + "full_name": testTarget, "visibility": fixture.repositoryVisibility, "private": fixture.repositoryPrivate, + "default_branch": "main", "owner": map[string]any{"login": testOwner}, + } + case "repos/" + testTarget + "/git/ref/heads/" + fixture.candidateRef: + value = map[string]any{"ref": "refs/heads/" + fixture.candidateRef, "object": map[string]any{"sha": fixture.remoteCandidate, "type": "commit"}} + case "repos/" + testTarget + "/git/ref/heads/main": + value = map[string]any{"ref": "refs/heads/main", "object": map[string]any{"sha": fixture.mainCommit, "type": "commit"}} + case "repos/" + testTarget + "/pulls/1": + value = map[string]any{ + "number": 1, "state": fixture.pullState, "merged": fixture.pullMerged, "merged_at": fixture.pullMergedAt, + "merge_commit_sha": fixture.candidate, + "head": map[string]any{"ref": fixture.candidateRef, "sha": fixture.pullHead}, + "base": map[string]any{"ref": "main", "sha": fixture.bootstrap}, + } + case fmt.Sprintf("repos/%s/rulesets/%d", testTarget, testRulesetID): + var bypassActors any + if fixture.rulesetBypass { + bypassActors = []any{map[string]any{"actor_id": 1, "actor_type": "RepositoryRole", "bypass_mode": "always"}} + } + var rules []any + if fixture.rulesetDeletion { + rules = append(rules, map[string]any{"type": "deletion"}) + } + if fixture.rulesetNonFastForward { + rules = append(rules, map[string]any{"type": "non_fast_forward"}) + } + if fixture.rulesetLinearHistory { + rules = append(rules, map[string]any{"type": "required_linear_history"}) + } + if fixture.rulesetPullRequest { + rules = append(rules, map[string]any{"type": "pull_request", "parameters": map[string]any{ + "required_approving_review_count": fixture.rulesetReviewCount, + "dismiss_stale_reviews_on_push": fixture.rulesetDismissStale, + "require_last_push_approval": fixture.rulesetLastPushApproval, + "required_review_thread_resolution": fixture.rulesetReviewThreads, + "allowed_merge_methods": fixture.rulesetAllowedMergeMethods, + }}) + } + rules = append(rules, map[string]any{"type": "required_status_checks", "parameters": map[string]any{ + "strict_required_status_checks_policy": fixture.rulesetStrict, + "do_not_enforce_on_create": fixture.rulesetDoNotEnforceOnCreate, + "required_status_checks": []any{map[string]any{"context": "test", "integration_id": testIntegration}}, + }}) + value = map[string]any{ + "id": testRulesetID, "name": "Protect main", "target": "branch", "enforcement": fixture.rulesetEnforcement, + "bypass_actors": bypassActors, + "conditions": map[string]any{"ref_name": map[string]any{"include": []string{"~DEFAULT_BRANCH"}, "exclude": []string{}}}, + "rules": rules, + } + case fmt.Sprintf("repos/%s/actions/runs/%d/jobs?filter=latest&per_page=100", testTarget, testPullRun): + value = map[string]any{"jobs": []any{map[string]any{"id": testCheckRun, "name": "test", "status": "completed", "conclusion": "success"}}} + case fmt.Sprintf("repos/%s/check-runs/%d", testTarget, testCheckRun): + value = map[string]any{"id": testCheckRun, "name": "test", "status": "completed", "conclusion": fixture.checkConclusion, "app": map[string]any{"id": fixture.checkIntegration}} + default: + prefix := "repos/" + testTarget + "/actions/runs/" + if strings.HasPrefix(endpoint, prefix) { + id, err := strconv.ParseInt(strings.TrimPrefix(endpoint, prefix), 10, 64) + run, ok := fixture.runs[id] + if err != nil || !ok { + return "", "not found", 1, nil + } + value = map[string]any{ + "id": run.ID, "event": run.Event, "head_branch": run.HeadBranch, "head_sha": run.HeadSHA, + "status": run.Status, "conclusion": run.Conclusion, "run_attempt": run.Attempt, "name": run.Name, + } + } else { + return "", "", -1, fmt.Errorf("unexpected GitHub endpoint %q", endpoint) + } + } + body, err := json.Marshal(value) + if err != nil { + return "", "", -1, err + } + return string(body), "", 0, nil +} + +func runFixture(t *testing.T, fixture *correctionFixture, phase string) string { + t.Helper() + var stdout strings.Builder + if err := runWithDependencies(context.Background(), fixture.arguments(phase), &stdout, fixture.dependencies()); err != nil { + t.Fatalf("run: %s: %v", errorCode(err), err) + } + return stdout.String() +} + +func expectFixtureFailure(t *testing.T, fixture *correctionFixture, phase, code string) { + t.Helper() + err := runWithDependencies(context.Background(), fixture.arguments(phase), io.Discard, fixture.dependencies()) + assertTypedError(t, err, code) + assertNoFile(t, fixture.out) +} + +func assertTypedError(t *testing.T, err error, code string) { + t.Helper() + if err == nil || errorCode(err) != code { + t.Fatalf("error = %v (%s), want %s", err, errorCode(err), code) + } +} + +func assertNoFile(t *testing.T, name string) { + t.Helper() + if _, err := os.Lstat(name); !errors.Is(err, os.ErrNotExist) { + t.Fatalf("unexpected output %s: %v", name, err) + } +} + +func replaceFlag(arguments []string, name, value string) { + for index := 0; index+1 < len(arguments); index++ { + if arguments[index] == name { + arguments[index+1] = value + return + } + } +} + +func writeCorrectionFile(t *testing.T, root, name, body string) { + t.Helper() + path := filepath.Join(root, filepath.FromSlash(name)) + if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(path, []byte(body), 0o600); err != nil { + t.Fatal(err) + } +} + +func writeJSONFile(t *testing.T, name string, value any, mode os.FileMode) { + t.Helper() + body, err := json.MarshalIndent(value, "", " ") + if err != nil { + t.Fatal(err) + } + if err := os.WriteFile(name, append(body, '\n'), mode); err != nil { + t.Fatal(err) + } +} + +func readJSONFile(t *testing.T, name string, target any) { + t.Helper() + body, err := os.ReadFile(name) + if err != nil { + t.Fatal(err) + } + if err := json.Unmarshal(body, target); err != nil { + t.Fatal(err) + } +} + +func correctionGit(t *testing.T, directory string, arguments ...string) string { + t.Helper() + command := exec.Command("git", arguments...) + command.Dir = directory + command.Env = gitx.Environment(nil) + output, err := command.CombinedOutput() + if err != nil { + t.Fatalf("git %v: %v\n%s", arguments, err, output) + } + return strings.TrimSpace(string(output)) +} diff --git a/scripts/publication-handoff/main_test.go b/scripts/publication-handoff/main_test.go index 27665ee..b7ae1fb 100644 --- a/scripts/publication-handoff/main_test.go +++ b/scripts/publication-handoff/main_test.go @@ -61,7 +61,7 @@ func TestCollectGitEvidenceRejectsUnexpectedHistoryState(t *testing.T) { }) t.Run("tag", func(t *testing.T) { repo, bootstrap := publicationCandidate(t) - publicationGit(t, repo.Root, "tag", "v0.1.0-beta.1") + publicationGit(t, repo.Root, "tag", "v0.2.0-beta.1") if _, err := collectGitEvidence(context.Background(), repo, bootstrap, []string{"docs/handoff.md"}); err == nil || !strings.Contains(err.Error(), "local tags") { t.Fatalf("tag error = %v", err) } diff --git a/scripts/release/main.go b/scripts/release/main.go index 0287ac6..c8121a0 100644 --- a/scripts/release/main.go +++ b/scripts/release/main.go @@ -89,7 +89,7 @@ func main() { func run(args []string) error { flags := flag.NewFlagSet("release", flag.ContinueOnError) flags.SetOutput(os.Stderr) - version := flags.String("version", "", "release tag, for example v0.1.0-beta.1") + version := flags.String("version", "", "release tag, for example v0.2.0-beta.1") out := flags.String("out", "", "new output directory") var rawTargets targetList flags.Var(&rawTargets, "target", "supported GOOS/GOARCH pair; repeatable") @@ -121,8 +121,8 @@ func run(args []string) error { if err != nil { return err } - if *version != "v"+commandVersion { - return fmt.Errorf("release tag %q does not match command version %q", *version, "v"+commandVersion) + if err := validateReleaseLine(*version, commandVersion); err != nil { + return err } commit, err := gitOutput(root, "rev-parse", "HEAD") if err != nil { @@ -236,7 +236,7 @@ func buildRelease(root, outPath, version, commit string, epoch int64, targets [] binaryName += ".exe" } binaryPath := filepath.Join(buildDir, item.OS+"-"+item.Arch+"-"+binaryName) - if err := buildBinary(root, binaryPath, strings.TrimPrefix(version, "v"), item); err != nil { + if err := buildBinary(root, binaryPath, version, commit, epoch, item); err != nil { return err } entries, err := releaseEntries(root, binaryPath, binaryName) @@ -292,13 +292,15 @@ func buildRelease(root, outPath, version, commit string, epoch int64, targets [] return nil } -func buildBinary(root, output, version string, item target) error { +func buildBinary(root, output, releaseTag, commit string, epoch int64, item target) error { + vcsTime := time.Unix(epoch, 0).UTC().Format(time.RFC3339) + version := strings.TrimPrefix(releaseTag, "v") args := []string{ "build", "-mod=readonly", "-trimpath", "-buildvcs=false", - "-ldflags=-s -w -buildid= -X main.version=" + version, + "-ldflags=-s -w -buildid= -X main.version=" + version + " -X main.buildReleaseTag=" + releaseTag + " -X main.buildRevision=" + commit + " -X main.buildSourceState=clean -X main.buildVCSTime=" + vcsTime, "-o", output, commandPackage, } @@ -312,6 +314,19 @@ func buildBinary(root, output, version string, item target) error { return nil } +func validateReleaseLine(tag, source string) error { + match := semverTagPattern.FindStringSubmatch(tag) + if len(match) < 4 { + return errors.New("release tag is not valid SemVer") + } + core := strings.Join(match[1:4], ".") + wanted := core + "-dev" + if source != wanted { + return fmt.Errorf("release tag %q requires source development version %q, found %q", tag, wanted, source) + } + return nil +} + func releaseEnvironment(current []string, item target) []string { blocked := map[string]bool{ "CGO_ENABLED": true, diff --git a/scripts/release/main_test.go b/scripts/release/main_test.go index e7a9b9e..f5f1275 100644 --- a/scripts/release/main_test.go +++ b/scripts/release/main_test.go @@ -144,10 +144,12 @@ func TestWriteChecksumsUsesSortedArtifactInput(t *testing.T) { func TestBuildHostBinary(t *testing.T) { root := moduleRoot(t) binary := filepath.Join(t.TempDir(), "wip") + commit := strings.Repeat("b", 40) + epoch := int64(1_700_000_000) if runtime.GOOS == "windows" { binary += ".exe" } - if err := buildBinary(root, binary, "0.1.0-test", target{OS: runtime.GOOS, Arch: runtime.GOARCH}); err != nil { + if err := buildBinary(root, binary, "v0.2.0-test", commit, epoch, target{OS: runtime.GOOS, Arch: runtime.GOARCH}); err != nil { t.Fatal(err) } info, err := os.Stat(binary) @@ -157,6 +159,29 @@ func TestBuildHostBinary(t *testing.T) { if info.Size() == 0 { t.Fatal("built binary is empty") } + output, err := exec.Command(binary, "--json", "version").Output() + if err != nil { + t.Fatal(err) + } + var result struct { + OK bool `json:"ok"` + Data struct { + SchemaVersion string `json:"schema_version"` + Version string `json:"version"` + Channel string `json:"channel"` + ReleaseTag string `json:"release_tag"` + SourceStamped bool `json:"source_stamped"` + Revision string `json:"revision"` + SourceState string `json:"source_state"` + VCSTime string `json:"vcs_time"` + } `json:"data"` + } + if err := json.Unmarshal(output, &result); err != nil { + t.Fatal(err) + } + if !result.OK || result.Data.SchemaVersion != "2.0.0" || result.Data.Version != "0.2.0-test" || result.Data.Channel != "release" || result.Data.ReleaseTag != "v0.2.0-test" || !result.Data.SourceStamped || result.Data.Revision != commit || result.Data.SourceState != "clean" || result.Data.VCSTime != time.Unix(epoch, 0).UTC().Format(time.RFC3339) { + t.Fatalf("built binary provenance = %#v", result) + } } func TestBuildReleaseIsAtomicAndDeterministic(t *testing.T) { @@ -164,7 +189,7 @@ func TestBuildReleaseIsAtomicAndDeterministic(t *testing.T) { parent := t.TempDir() first := filepath.Join(parent, "first") second := filepath.Join(parent, "second") - version := "v0.1.0-test" + version := "v0.2.0-test" commit := strings.Repeat("a", 40) epoch := int64(1_700_000_000) targets := []target{{OS: runtime.GOOS, Arch: runtime.GOARCH}} @@ -231,7 +256,7 @@ func TestSourceVersionAndExclusiveFileCreation(t *testing.T) { if err != nil { t.Fatal(err) } - if version != "0.1.0-beta.1" { + if version != "0.2.0-dev" { t.Fatalf("source version = %q", version) } path := filepath.Join(t.TempDir(), "exclusive.txt") @@ -254,7 +279,7 @@ func TestSourceVersionAcceptsWindowsLineEndings(t *testing.T) { t.Fatal(err) } path := filepath.Join(commandDir, "main.go") - body := []byte("package main\r\n\r\nvar version = \"0.1.0-beta.1\"\r\n") + body := []byte("package main\r\n\r\nvar version = \"0.2.0-dev\"\r\n") if err := os.WriteFile(path, body, 0o600); err != nil { t.Fatal(err) } @@ -262,11 +287,28 @@ func TestSourceVersionAcceptsWindowsLineEndings(t *testing.T) { if err != nil { t.Fatal(err) } - if version != "0.1.0-beta.1" { + if version != "0.2.0-dev" { t.Fatalf("source version = %q", version) } } +func TestReleaseTagMustMatchSourceDevelopmentLine(t *testing.T) { + for _, test := range []struct { + tag, source string + allowed bool + }{ + {"v0.2.0-beta.1", "0.2.0-dev", true}, + {"v0.2.0", "0.2.0-dev", true}, + {"v0.3.0-beta.1", "0.2.0-dev", false}, + {"v0.2.0-beta.1", "0.2.0-beta.1", false}, + {"not-a-tag", "0.2.0-dev", false}, + } { + if allowed := validateReleaseLine(test.tag, test.source) == nil; allowed != test.allowed { + t.Errorf("validateReleaseLine(%q, %q) = %v, want %v", test.tag, test.source, allowed, test.allowed) + } + } +} + func TestRequireCleanFailsClosed(t *testing.T) { repository := t.TempDir() releaseGit(t, repository, "init", "-b", "main") diff --git a/skills/wip-commit/SKILL.md b/skills/wip-commit/SKILL.md index facd04c..eb02fec 100644 --- a/skills/wip-commit/SKILL.md +++ b/skills/wip-commit/SKILL.md @@ -1,12 +1,12 @@ --- name: wip-commit -description: Safely capture one agent's exact staged paths into an isolated local Git ref. Use for concurrent agents in one repository or checkout. Use for split Conventional Commits and linked worktrees. +description: Safely capture one agent's exact staged-index or worktree source into an isolated local Git ref. Use for concurrent agents, split Conventional Commits, and linked worktrees. --- # WIP Commit Capture only the paths that belong to the current task. Keep the checked-out -branch, source `HEAD`, complete source index, and other agents' staged entries +branch, source `HEAD`, caller index, and other agents' staged entries unchanged. ## Inspect before changing state @@ -19,14 +19,32 @@ unchanged. operator to finish or cancel that Git operation. 4. Identify the exact paths owned by this task. Do not claim or stage a broad directory. When another agent can change a child path, use a narrower claim. -5. Run `wip version`. If the command is absent, build or install it by using +5. Run `wip --json contract`. Require every identity and capability in + [contract.json](contract.json), including the portable payload digest. Then + run `wip --json version`. Require schema `2.0.0`. Record its channel, exact + revision, and source state. Do not + use an unstamped binary with existing coordination state. If the command is + absent or has no revision, build or install a source-stamped binary by using this repository's documented method. 6. Run `wip --json doctor`. If it reports another coordination domain, stop. - Preserve both state roots and select one domain before setup. + Preserve both state roots. Use `wip --json migrate --preview` to create an + immutable migration plan. Do not apply it before a writer freeze and an + exact review. If + `data.upgrade_required` is true, stop lane setup. Follow the reviewed + `wip --json upgrade --state` preview/apply procedure first. Run `wip --json + status --observe` only when doctor reports healthy initialized state with no + required upgrade. `LANE_NOT_ACTIVE` means this standalone domain remains + authoritative and a new standalone lane is required. Run `wip init`. Never + fall through to a legacy coordination implementation. Never stash, reset, restore, clean, merge, push, or force-update a ref. Do not delete another lane, worktree, lock, profile, intent, or receipt. +If the installed binary or portable skill differs, preview exactly one target +with `wip --json upgrade --binary` or `wip --json upgrade --skill`. Apply only +the reviewed `plan_digest` with `--apply --yes`. Never combine targets or treat +upgrade as first installation. + ## Initialize one lane For an interactive setup, run: @@ -42,16 +60,16 @@ changes. If setup stops, use the reported resume command. It pins the absolute repository and worktree paths and the exact base commit. A matching partial skill installation is resumable. -When agents edit the same checkout, accept the recommended `shared` mode. When -the task has a dedicated linked worktree, use `worktree` mode. Both modes use -the same private-index capture transaction and write only to an agent-owned -local ref. +Use the recommended `worktree` mode for one agent per task. Use `shared` mode +only when lanes must use the same checkout and index. Both modes use the same +private-source and private-index capture transaction. For automation, make the identity and paths explicit: ```text wip --json init \ - --mode shared \ + --mode worktree \ + --create-worktree \ --lane \ --agent \ --session \ @@ -64,78 +82,163 @@ wip --json init \ Repeat `--path` for each disjoint claim. If `PATH_LEASE_CONFLICT` occurs, do not override it. Narrow the claim or wait for the owner to release it. +Initialization can create a linked worktree. Continue in the exact worktree +reported by the command. Run `wip env` and all later lane commands there. A +call from another checkout fails before lease renewal. + Load the saved identity in an interactive shell: ```text eval "$(wip env --lane )" ``` +Run `wip env` from the checkout recorded for the lane. A worktree-bound lane +must return `WORKTREE_MISMATCH` from any other checkout without renewing its +lease. + When shell environment changes are not suitable, pass `--lane`, `--agent`, and `--session` explicitly. -## Stage and capture exact paths +## Select and capture an exact source -Stage each owned path explicitly: +Use `worktree_snapshot` in a dedicated worktree. This mode does not require +staging. It is the preferred agent source: + +```text +wip --json status +wip --json plan \ + --source worktree_snapshot \ + --untracked forbid \ + --path \ + --observe +wip --json plan --out \ + --source worktree_snapshot \ + --untracked forbid \ + --path +``` + +The observed plan is a byte-for-byte read. It does not renew leases or write a +plan file. Review its source selection. Then create the no-overwrite plan file +from current state. + +Use `--untracked include` only after you review every untracked path in the +selected scope. The default `forbid` policy stops when an untracked path is +present. + +Use `staged_index` for the controlled shared-checkout exception. Stage each +owned path explicitly, and then inspect the staged names and diff: ```text git add -- +wip --json plan \ + --source staged_index \ + --untracked not_applicable \ + --path \ + --out ``` -Inspect the staged names and diff before capture. Foreign staged entries can -remain in the source index. +Foreign staged entries can remain in the caller index. The capture transaction +does not stage, unstage, or rewrite that index. -Run `wip --json plan` for a read-only component split proposal. Review each -group for semantic intent and dependency closure. The proposed prefix is a -naming hint, not a commit message. +Review each group for intent and dependency closure. Add a message to every +group. Then set the top-level `state` to `reviewed`. -Use split commits by default. Interactive work can run `wip commit` and accept -or refine the proposed groups. Automation must use a reviewed JSON plan: +Capture the reviewed plan: ```text -wip --json commit --plan +wip --json capture --plan ``` -Each group needs a distinct Conventional Commit message and an exact file -list. Add bounded commands in `verify` to the group that owns the affected code. -When one commit is a deliberate, coherent unit, use `--single --message`. +Each group needs an exact file list. The lane profile selects the message +policy. Add bounded `verify` commands to the group that owns the code. Set +`directory` to the smallest candidate subtree that can run the command. Add +only required repository-relative dependencies in `materialize`. A command +with neither field requests the full candidate tree and can fail the fixed +materialization limit. + +Use `wip commit --single --message` only for a deliberate one-commit +compatibility capture. Do not use it in the guided automation path. Read [references/automation.md](references/automation.md) before an automated capture. -For long editing work, run `wip renew` before the 15-minute lease expires. Use -`wip claim --path ` before staging a newly owned path. `wip commit` -snapshots and renews the lane's complete active lease set during long hooks and -verification commands. +Use `wip commit --dry-run` only for a no-exec structure preview. It snapshots +hook bytes but does not execute hooks or verification commands. Require result +schema `3.0.0`, `gate_outcome: "skipped"`, `execution.policy: "no-exec"`, and +zero executed counts. Do not treat this result as gate or capture evidence. + +Authenticated `status`, `env`, `claim`, `plan`, non-dry `commit`, `capture`, and +`handoff` renew the complete active lease set. A released-lane handoff remains +a pure read. `wip commit --dry-run` does not renew. Use `--observe` for a status +or environment read that must not renew. Use `plan --observe` for a source +preview that must not renew or write a file. Use `wip claim --path ` +before you select a newly owned path. ## Check the result -For a complete capture, require all of these facts in the JSON result: +For a complete guided capture, require all of these facts in the JSON result: - `ok` is `true`. -- `ref_updated` is `true`. -- `gate_outcome` is `passed`. -- `intent_state` is `complete`. - -Also check that the reported groups, paths, messages, old commit, new -commit, and lane ref match the reviewed plan. A successful capture leaves the -captured entries staged in the source index by design. +- `data.capture.ref_updated` is `true`. +- `data.capture.gate_outcome` is `passed`. +- `data.capture.intent_state` is `complete`. +- `data.handoff.capture_only` is `true`. +- `data.handoff.landing_authorized` is `false`. +- `data.handoff.handoff_digest` is a SHA-256 digest. +- `data.handoff.review_eligible` is `true`. +- Every item in `data.handoff.segments` has `intent_state: "complete"`, an + exact capture-intent digest, an exact reviewed-plan digest, a bound message + policy, and a private-source binding. + +Check that the segments form one continuous chain from `lane_base_commit` to +`lane_tip`. Check the final tree, messages, and paths against every reviewed +plan. A staged-index capture leaves captured entries staged by design. A +worktree-source capture leaves the caller index unchanged. If a failed result reports `ref_updated: true`, preserve its exact `plan_id` and `plan_digest`. Run `wip reconcile` with both values. Do not edit an intent or guess a digest. Do not rerun the plan until reconciliation proves that the ref did not move. +## Run the product benchmark + +If the task changes a safety contract, run the benchmark from the repository +root: + +```text +go run ./skills/wip-commit/benchmark/regression.go +``` + +Require all 16 checks and the reviewed baseline comparison to pass. The runner +uses disposable repositories and makes no network or AI calls. + +Run the weakened-candidate proof after benchmark or harness changes: + +```text +go run ./skills/wip-commit/benchmark/regression.go --prove-weakened +``` + +Do not change `skills/wip-commit/benchmark/baseline.json` to admit a failure. +The runner writes mutable reports outside the repository. + ## Finish without landing -Run `wip status`, record the lane ref and new commit, and then run: +Run `wip --json handoff` to validate the cumulative base-to-tip capture +receipt. Then run: ```text wip release ``` Release removes the active coordination claim and preserves the lane ref and -commits. It does not land, merge, or push them. Hand the exact ref and commit -to the repository's separate review and landing process. +commits. It does not land or merge them. Give the typed handoff to the +repository's separate review and landing process. + +For the last capture, `wip --json capture --final --plan ` performs +the validated handoff and lane release under one lane lock. It does not +authorize landing. Run `wip doctor` before you archive old state. Use `wip archive` without -`--apply` first. Reuse the exact cutoff and plan digest only after review. If -apply returns a prepared receipt, use its exact ID with `wip archive --resume`. +`--apply` first. Reuse the exact cutoff and plan digest only after review, and +repeat every `--lane` filter from the preview. JSON previews return the sorted +filters as `lane_filters`. If apply returns a prepared receipt, use its exact +ID with `wip archive --resume`. diff --git a/skills/wip-commit/agents/openai.yaml b/skills/wip-commit/agents/openai.yaml index bd43ace..72b879b 100644 --- a/skills/wip-commit/agents/openai.yaml +++ b/skills/wip-commit/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "WIP Commit" - short_description: "Capture owned staged paths on an isolated ref." - default_prompt: "Use $wip-commit to capture this task as safe split commits without moving the source branch or index." + short_description: "Capture an exact private source on an isolated ref." + default_prompt: "Use $wip-commit to capture this task from an exact reviewed source without moving the source branch or caller index." diff --git a/skills/wip-commit/benchmark/README.md b/skills/wip-commit/benchmark/README.md new file mode 100644 index 0000000..d3e6f9a --- /dev/null +++ b/skills/wip-commit/benchmark/README.md @@ -0,0 +1,60 @@ +# WIP Commit Portable Behavioral Benchmark + +This deterministic, zero-AI benchmark runs the shipped `wip` entrypoints in +disposable Git repositories. It checks the same semantic cases on Linux, +macOS, and Windows: + +- shared and linked-worktree setup. +- concurrent disjoint lanes and an overlapping-lease refusal. +- reviewed split-plan defaults and draft-plan refusal. +- the explicit `--single` opt-out. +- complete caller-index and foreign-stage preservation. +- dry-run no-exec reporting and non-publication, plus a non-dry sensitivity + control. +- failed verification non-publication and a passing-gate sensitivity control. +- reconciliation of a reproduced applied-intent crash boundary. + +Every case has one positive assertion and one negative control. All 16 checks +must pass for a report to match the reviewed baseline. Reports contain no +fixture paths, credentials, file contents, network results, or AI output. + +## Run + +From this repository: + +```text +go run ./skills/wip-commit/benchmark/regression.go +``` + +The default mutable report is: + +```text +~/.nicos-dev/benchmarks/wip-commit/latest-report.json +``` + +Use `--out-dir ` for an isolated report directory. Use +`--candidate ` to evaluate an already-built executable. + +## Prove the negative control + +```text +go run ./skills/wip-commit/benchmark/regression.go --prove-weakened +``` + +This builds the deliberately unsafe no-op candidate under +`testdata/weakened` and runs the full case matrix. The proof requires the +normal benchmark to reject that candidate. It writes `weakened-report.json`. +Running the unsafe executable through the ordinary `--candidate` path exits +nonzero. + +## Baseline policy + +`baseline.json` is reviewed repository data. The runner never writes or +promotes it. Review the case IDs, required check counts, and minimum score for +each baseline change. A failing candidate can write only mutable artifacts +outside the repository. Thus, it cannot replace the reviewed baseline. + +When a candidate falls below baseline, the runner writes `proposal.json` with +the failed case IDs and exits nonzero. The report schema, benchmark version, +score, cases, elapsed milliseconds, and zero-AI counters are bounded and +versioned. diff --git a/skills/wip-commit/benchmark/baseline.json b/skills/wip-commit/benchmark/baseline.json new file mode 100644 index 0000000..0290ed7 --- /dev/null +++ b/skills/wip-commit/benchmark/baseline.json @@ -0,0 +1,20 @@ +{ + "schema_version": "1.0.0", + "benchmark": "wip-commit-portable-behavior", + "benchmark_version": "1.0.0", + "review_status": "reviewed", + "minimum_score": 1, + "required_positive_checks": 8, + "required_negative_controls": 8, + "zero_ai_required": true, + "required_cases": [ + "setup-shared-linked", + "disjoint-parallel-lanes", + "reviewed-split-default", + "explicit-single-opt-out", + "foreign-index-preservation", + "dry-run-no-publication", + "failed-verification-no-publication", + "reconcile-interrupted-publication" + ] +} diff --git a/skills/wip-commit/benchmark/regression.go b/skills/wip-commit/benchmark/regression.go new file mode 100644 index 0000000..f588a9d --- /dev/null +++ b/skills/wip-commit/benchmark/regression.go @@ -0,0 +1,1294 @@ +package main + +import ( + "bytes" + "context" + "crypto/sha256" + "encoding/hex" + "encoding/json" + "errors" + "flag" + "fmt" + "io" + "os" + "os/exec" + "path/filepath" + "runtime" + "sort" + "strings" + "sync" + "time" +) + +const ( + benchmarkName = "wip-commit-portable-behavior" + benchmarkVersion = "1.0.0" + reportSchemaVersion = "1.0.0" + defaultCommandTimeout = 45 * time.Second + maxCommandOutputBytes = 256 * 1024 + maxJSONArtifactBytes = 1 << 20 + maxCandidateBytes = 256 << 20 + benchmarkAgent = "bench" + benchmarkSession = "portable" + weakenedCandidateLabel = "deliberately-weakened" +) + +var requiredCaseIDs = []string{ + "setup-shared-linked", + "disjoint-parallel-lanes", + "reviewed-split-default", + "explicit-single-opt-out", + "foreign-index-preservation", + "dry-run-no-publication", + "failed-verification-no-publication", + "reconcile-interrupted-publication", +} + +type baseline struct { + SchemaVersion string `json:"schema_version"` + Benchmark string `json:"benchmark"` + BenchmarkVersion string `json:"benchmark_version"` + ReviewStatus string `json:"review_status"` + MinimumScore float64 `json:"minimum_score"` + RequiredPositiveChecks int `json:"required_positive_checks"` + RequiredNegativeControls int `json:"required_negative_controls"` + ZeroAIRequired bool `json:"zero_ai_required"` + RequiredCases []string `json:"required_cases"` +} + +type assertion struct { + Passed bool `json:"passed"` + Detail string `json:"detail"` +} + +type caseResult struct { + ID string `json:"id"` + Passed bool `json:"passed"` + Positive assertion `json:"positive"` + NegativeControl assertion `json:"negative_control"` + ElapsedMS int64 `json:"elapsed_ms"` +} + +type overallResult struct { + TotalChecks int `json:"total_checks"` + PassedChecks int `json:"passed_checks"` + FailedChecks int `json:"failed_checks"` + PassedPositiveChecks int `json:"passed_positive_checks"` + PassedNegativeControls int `json:"passed_negative_controls"` + Score float64 `json:"score"` + MeetsReviewedBaseline bool `json:"meets_reviewed_baseline"` +} + +type candidateInfo struct { + Kind string `json:"kind"` + SHA256 string `json:"sha256"` + Version string `json:"version,omitempty"` + Revision string `json:"revision,omitempty"` + SourceState string `json:"source_state,omitempty"` +} + +type aiUsage struct { + Calls int `json:"calls"` + Tokens int `json:"tokens"` +} + +type report struct { + SchemaVersion string `json:"schema_version"` + Benchmark string `json:"benchmark"` + BenchmarkVersion string `json:"benchmark_version"` + Platform string `json:"platform"` + Candidate candidateInfo `json:"candidate"` + BaselineSHA256 string `json:"baseline_sha256"` + Cases []caseResult `json:"cases"` + Overall overallResult `json:"overall"` + ElapsedMS int64 `json:"elapsed_ms"` + AIUsage aiUsage `json:"ai_usage"` + ZeroAI bool `json:"zero_ai"` +} + +type proposal struct { + SchemaVersion string `json:"schema_version"` + Benchmark string `json:"benchmark"` + BenchmarkVersion string `json:"benchmark_version"` + BaselineScore float64 `json:"baseline_score"` + CandidateScore float64 `json:"candidate_score"` + FailedCaseIDs []string `json:"failed_case_ids"` + Action string `json:"action"` +} + +type envelopeError struct { + Code string `json:"code"` +} + +type envelope struct { + OK bool `json:"ok"` + Action string `json:"action"` + Data json.RawMessage `json:"data"` + Error *envelopeError `json:"error"` +} + +type rawCommand struct { + ExitCode int + Stdout string + Stderr string + TimedOut bool + Err error +} + +type wipRun struct { + Raw rawCommand + Envelope envelope + Decoded bool +} + +func (result wipRun) succeeded() bool { + return result.Raw.ExitCode == 0 && result.Decoded && result.Envelope.OK +} + +func (result wipRun) failedWith(code string) bool { + return result.Raw.ExitCode != 0 && result.Decoded && !result.Envelope.OK && result.Envelope.Error != nil && result.Envelope.Error.Code == code +} + +type fixture struct { + repo string + home string +} + +type harness struct { + candidate string + root string +} + +type directCapture struct { + FinalCommit string `json:"final_commit"` + RefUpdated bool `json:"ref_updated"` + DryRun bool `json:"dry_run"` + PlanID string `json:"plan_id"` + PlanDigest string `json:"plan_digest"` + IntentState string `json:"intent_state"` + GateOutcome string `json:"gate_outcome"` + Execution *struct { + Policy string `json:"policy"` + PreCommitHooks executionCount `json:"pre_commit_hooks"` + PostCommitHooks executionCount `json:"post_commit_hooks"` + VerifyCommands executionCount `json:"verify_commands"` + } `json:"execution"` + Commits []struct { + Commit string `json:"commit"` + } `json:"commits"` +} + +type executionCount struct { + Planned int `json:"planned"` + Executed int `json:"executed"` + Skipped int `json:"skipped"` +} + +type guidedCapture struct { + Capture directCapture `json:"capture"` + Handoff struct { + CaptureOnly bool `json:"capture_only"` + LandingAuthorized bool `json:"landing_authorized"` + } `json:"handoff"` +} + +type reconcileData struct { + IntentState string `json:"intent_state"` + AlreadyClean bool `json:"already_clean"` +} + +func main() { + candidateFlag := flag.String("candidate", "", "evaluate an existing candidate executable") + outDirFlag := flag.String("out-dir", "", "directory for mutable benchmark artifacts") + proveWeakened := flag.Bool("prove-weakened", false, "prove that the reviewed baseline rejects the deliberately weakened candidate") + flag.Parse() + if flag.NArg() != 0 || (*proveWeakened && *candidateFlag != "") { + fmt.Fprintln(os.Stderr, "invalid benchmark arguments") + os.Exit(3) + } + + root, err := repositoryRoot() + if err != nil { + fmt.Fprintf(os.Stderr, "resolve repository root: %v\n", err) + os.Exit(3) + } + benchmarkDir := filepath.Join(root, "skills", "wip-commit", "benchmark") + baselinePath := filepath.Join(benchmarkDir, "baseline.json") + reviewed, baselineBody, err := loadBaseline(baselinePath) + if err != nil { + fmt.Fprintf(os.Stderr, "load reviewed baseline: %v\n", err) + os.Exit(3) + } + baselineDigest := sha256Text(baselineBody) + artifactDir, err := resolveArtifactDir(*outDirFlag) + if err != nil { + fmt.Fprintf(os.Stderr, "resolve artifact directory: %v\n", err) + os.Exit(3) + } + if err := prepareArtifactDir(artifactDir); err != nil { + fmt.Fprintf(os.Stderr, "prepare artifact directory: %v\n", err) + os.Exit(3) + } + + workspace, err := os.MkdirTemp("", "wip-portable-benchmark-") + if err != nil { + fmt.Fprintf(os.Stderr, "create disposable benchmark workspace: %v\n", err) + os.Exit(3) + } + defer func() { _ = os.RemoveAll(workspace) }() + + candidate := *candidateFlag + candidateKind := "repository-build" + if *proveWeakened { + candidateKind = weakenedCandidateLabel + candidate = filepath.Join(workspace, executableName("wip-weakened")) + source := filepath.Join(benchmarkDir, "testdata", "weakened", "main.go") + if err := buildGoCandidate(root, candidate, source); err != nil { + fmt.Fprintf(os.Stderr, "build weakened candidate: %v\n", err) + os.Exit(3) + } + } else if candidate == "" { + candidate = filepath.Join(workspace, executableName("wip-candidate")) + if err := buildGoCandidate(root, candidate, "./cmd/wip"); err != nil { + fmt.Fprintf(os.Stderr, "build repository candidate without network access: %v\n", err) + os.Exit(3) + } + } else { + candidateKind = "external-binary" + candidate, err = filepath.Abs(candidate) + if err != nil { + fmt.Fprintf(os.Stderr, "resolve candidate: %v\n", err) + os.Exit(3) + } + } + candidate, candidateDigest, err := freezeCandidate(candidate, workspace) + if err != nil { + fmt.Fprintf(os.Stderr, "freeze candidate: %v\n", err) + os.Exit(3) + } + + candidateMetadata, err := inspectCandidate(candidate, candidateKind, candidateDigest, workspace) + if err != nil { + fmt.Fprintf(os.Stderr, "inspect candidate: %v\n", err) + os.Exit(3) + } + started := time.Now() + results := runCases(harness{candidate: candidate, root: workspace}) + report := assembleReport(results, candidateMetadata, baselineDigest, elapsedMilliseconds(time.Since(started))) + report.Overall.MeetsReviewedBaseline = meetsBaseline(report, reviewed) + + if *proveWeakened { + if err := validateReport(report, reviewed); err != nil { + fmt.Fprintf(os.Stderr, "validate weakened report: %v\n", err) + os.Exit(3) + } + if err := writeBoundedJSON(filepath.Join(artifactDir, "weakened-report.json"), report); err != nil { + fmt.Fprintf(os.Stderr, "write weakened report: %v\n", err) + os.Exit(3) + } + _, afterBody, err := loadBaseline(baselinePath) + if err != nil || sha256Text(afterBody) != baselineDigest { + fmt.Fprintln(os.Stderr, "reviewed baseline changed during weakened-candidate proof") + os.Exit(1) + } + if report.Overall.MeetsReviewedBaseline { + fmt.Fprintln(os.Stderr, "deliberately weakened candidate unexpectedly met the reviewed baseline") + os.Exit(1) + } + fmt.Printf("wip-commit weakened candidate rejected: %d/%d checks passed (score %.3f)\n", report.Overall.PassedChecks, report.Overall.TotalChecks, report.Overall.Score) + return + } + + if err := writeRunArtifacts(artifactDir, report, reviewed); err != nil { + fmt.Fprintf(os.Stderr, "write benchmark artifacts: %v\n", err) + os.Exit(3) + } + fmt.Printf("wip-commit portable benchmark: %d/%d checks passed (score %.3f, baseline %.3f, zero AI)\n", report.Overall.PassedChecks, report.Overall.TotalChecks, report.Overall.Score, reviewed.MinimumScore) + if !report.Overall.MeetsReviewedBaseline { + os.Exit(1) + } +} + +func runCases(h harness) []caseResult { + cases := []func(harness) caseResult{ + caseSetupSharedLinked, + caseDisjointParallelLanes, + caseReviewedSplitDefault, + caseExplicitSingleOptOut, + caseForeignIndexPreservation, + caseDryRunNoPublication, + caseFailedVerificationNoPublication, + caseReconcileInterruptedPublication, + } + results := make([]caseResult, 0, len(cases)) + for _, run := range cases { + results = append(results, run(h)) + } + return results +} + +func caseSetupSharedLinked(h harness) caseResult { + started := time.Now() + shared, sharedErr := newFixture(h.root, "setup-shared", map[string]string{"core.txt": "base\n"}) + linked, linkedErr := newFixture(h.root, "setup-linked", map[string]string{"core.txt": "base\n"}) + anchor, anchorErr := newFixture(h.root, "setup-anchor-negative", map[string]string{"core.txt": "base\n"}) + if sharedErr != nil || linkedErr != nil || anchorErr != nil { + return failedFixtureCase("setup-shared-linked", started) + } + sharedRun := h.initLane(shared, "shared", "shared-setup", "", "core.txt") + linkedWorktree := filepath.Join(h.root, "setup-linked-worktree") + linkedRun := h.initLane(linked, "worktree", "linked-setup", linkedWorktree, "core.txt") + inside, insideErr := runGitAt(linked, linkedWorktree, "rev-parse", "--is-inside-work-tree") + negative := h.initLane(anchor, "worktree", "anchor-refused", "", "core.txt") + positivePassed := sharedRun.succeeded() && linkedRun.succeeded() && insideErr == nil && inside == "true" + negativePassed := negative.failedWith("WORKTREE_REQUIRED") + return resultCase( + "setup-shared-linked", started, + positivePassed, "shared and linked-worktree initialization used shipped entrypoints", "shared or linked-worktree initialization contract was not observed", + negativePassed, "anchor worktree mode without a destination was refused", "expected WORKTREE_REQUIRED refusal was not observed", + ) +} + +func caseDisjointParallelLanes(h harness) caseResult { + started := time.Now() + fix, err := newFixture(h.root, "parallel-lanes", map[string]string{"a.txt": "base a\n", "b.txt": "base b\n"}) + if err != nil { + return failedFixtureCase("disjoint-parallel-lanes", started) + } + if writeAndStage(fix, "a.txt", "changed a\n") != nil || writeAndStage(fix, "b.txt", "changed b\n") != nil { + return failedFixtureCase("disjoint-parallel-lanes", started) + } + indexBefore, beforeErr := runGit(fix, "write-tree") + leftInit := h.initLane(fix, "shared", "parallel-left", "", "a.txt") + rightInit := h.initLane(fix, "shared", "parallel-right", "", "b.txt") + overlap := h.initLane(fix, "shared", "parallel-overlap", "", "a.txt") + + var leftCapture, rightCapture wipRun + var group sync.WaitGroup + group.Add(2) + go func() { + defer group.Done() + leftCapture = h.commitSingle(fix, "parallel-left", "fix(left): capture disjoint path", false, "a.txt") + }() + go func() { + defer group.Done() + rightCapture = h.commitSingle(fix, "parallel-right", "fix(right): capture disjoint path", false, "b.txt") + }() + group.Wait() + indexAfter, afterErr := runGit(fix, "write-tree") + leftBody, leftErr := runGit(fix, "show", "refs/heads/wip/bench/parallel-left:a.txt") + rightBody, rightErr := runGit(fix, "show", "refs/heads/wip/bench/parallel-right:b.txt") + positivePassed := beforeErr == nil && afterErr == nil && indexBefore == indexAfter && leftInit.succeeded() && rightInit.succeeded() && leftCapture.succeeded() && rightCapture.succeeded() && leftErr == nil && rightErr == nil && leftBody == "changed a" && rightBody == "changed b" + negativePassed := overlap.failedWith("PATH_LEASE_CONFLICT") + return resultCase( + "disjoint-parallel-lanes", started, + positivePassed, "two disjoint shared lanes captured concurrently and preserved the source index", "parallel disjoint capture or source-index preservation failed", + negativePassed, "an overlapping third lease was refused", "expected PATH_LEASE_CONFLICT refusal was not observed", + ) +} + +func caseReviewedSplitDefault(h harness) caseResult { + started := time.Now() + fix, err := newFixture(h.root, "reviewed-split", map[string]string{".staticcheck-version": "v0.7.0\n", "cmd/tool.txt": "base tool\n", "docs/guide.md": "base guide\n"}) + if err != nil { + return failedFixtureCase("reviewed-split-default", started) + } + if writeAndStage(fix, ".staticcheck-version", "v0.8.0-rc.1\n") != nil || writeAndStage(fix, "cmd/tool.txt", "changed tool\n") != nil || writeAndStage(fix, "docs/guide.md", "changed guide\n") != nil { + return failedFixtureCase("reviewed-split-default", started) + } + initialized := h.initLane(fix, "shared", "reviewed-split", "", ".staticcheck-version", "cmd/tool.txt", "docs/guide.md") + planPath := filepath.Join(h.root, "reviewed-split-plan.json") + planned := h.runWIP(fix, append([]string{"plan"}, append(identityArgs("reviewed-split"), "--out", planPath)...)...) + state, groupCount, rootConfigGuidance, inspectErr := inspectPlan(planPath) + draftCapture := h.runWIP(fix, append([]string{"capture"}, append(identityArgs("reviewed-split"), "--plan", planPath)...)...) + reviewErr := reviewPlan(planPath, nil) + captured := h.runWIP(fix, append([]string{"capture"}, append(identityArgs("reviewed-split"), "--plan", planPath)...)...) + var data guidedCapture + decodeErr := decodeEnvelopeData(captured.Envelope, &data) + positivePassed := initialized.succeeded() && planned.succeeded() && inspectErr == nil && state == "draft" && groupCount >= 3 && rootConfigGuidance && reviewErr == nil && captured.succeeded() && decodeErr == nil && data.Capture.RefUpdated && data.Capture.GateOutcome == "passed" && len(data.Capture.Commits) == groupCount && data.Handoff.CaptureOnly && !data.Handoff.LandingAuthorized + negativePassed := draftCapture.failedWith("PLAN_NOT_REVIEWED") + return resultCase( + "reviewed-split-default", started, + positivePassed, "the draft guided root config and component groups before a capture-only handoff", "reviewed split-plan behavior or root-config guidance was not observed", + negativePassed, "capture refused the unreviewed draft", "expected PLAN_NOT_REVIEWED refusal was not observed", + ) +} + +func caseExplicitSingleOptOut(h harness) caseResult { + started := time.Now() + fix, err := newFixture(h.root, "single-opt-out", map[string]string{"core.txt": "base\n"}) + if err != nil || writeAndStage(fix, "core.txt", "changed\n") != nil { + return failedFixtureCase("explicit-single-opt-out", started) + } + initialized := h.initLane(fix, "shared", "single-opt-out", "", "core.txt") + withoutSingle := h.runWIP(fix, append([]string{"commit"}, append(identityArgs("single-opt-out"), "--message", "fix(core): capture one path", "--path", "core.txt", "--non-interactive")...)...) + withSingle := h.commitSingle(fix, "single-opt-out", "fix(core): capture one path", false, "core.txt") + var captured directCapture + decodeErr := decodeEnvelopeData(withSingle.Envelope, &captured) + positivePassed := initialized.succeeded() && withSingle.succeeded() && decodeErr == nil && captured.RefUpdated && len(captured.Commits) == 1 + negativePassed := withoutSingle.failedWith("SPLIT_PLAN_REQUIRED") + return resultCase( + "explicit-single-opt-out", started, + positivePassed, "--single explicitly selected one compatibility commit", "explicit single-commit capture failed", + negativePassed, "a message and path without --single were refused", "expected SPLIT_PLAN_REQUIRED refusal was not observed", + ) +} + +func caseForeignIndexPreservation(h harness) caseResult { + started := time.Now() + fix, err := newFixture(h.root, "foreign-index", map[string]string{"owned.txt": "base owned\n", "foreign.txt": "base foreign\n"}) + if err != nil || writeAndStage(fix, "owned.txt", "changed owned\n") != nil || writeAndStage(fix, "foreign.txt", "changed foreign\n") != nil { + return failedFixtureCase("foreign-index-preservation", started) + } + initialized := h.initLane(fix, "shared", "foreign-index", "", "owned.txt") + indexBefore, indexBeforeErr := runGit(fix, "write-tree") + headBefore, headBeforeErr := runGit(fix, "rev-parse", "HEAD") + foreignBefore, foreignBeforeErr := runGit(fix, "ls-files", "--stage", "--", "foreign.txt") + foreignAttempt := h.commitSingle(fix, "foreign-index", "fix(foreign): forbidden scope", false, "foreign.txt") + ownedCapture := h.commitSingle(fix, "foreign-index", "fix(owned): capture exact scope", false, "owned.txt") + indexAfter, indexAfterErr := runGit(fix, "write-tree") + headAfter, headAfterErr := runGit(fix, "rev-parse", "HEAD") + foreignAfter, foreignAfterErr := runGit(fix, "ls-files", "--stage", "--", "foreign.txt") + ownedBody, ownedErr := runGit(fix, "show", "refs/heads/wip/bench/foreign-index:owned.txt") + positivePassed := initialized.succeeded() && ownedCapture.succeeded() && indexBeforeErr == nil && indexAfterErr == nil && indexBefore == indexAfter && headBeforeErr == nil && headAfterErr == nil && headBefore == headAfter && foreignBeforeErr == nil && foreignAfterErr == nil && foreignBefore == foreignAfter && ownedErr == nil && ownedBody == "changed owned" + negativePassed := foreignAttempt.failedWith("LEASE_REQUIRED") + return resultCase( + "foreign-index-preservation", started, + positivePassed, "owned capture preserved source HEAD, the complete index tree, and the foreign stage entry", "source HEAD or index preservation failed", + negativePassed, "capture of an unleased foreign path was refused", "expected LEASE_REQUIRED refusal was not observed", + ) +} + +func caseDryRunNoPublication(h harness) caseResult { + started := time.Now() + fix, err := newFixture(h.root, "dry-run", map[string]string{"core.txt": "base\n"}) + if err != nil || writeAndStage(fix, "core.txt", "changed\n") != nil { + return failedFixtureCase("dry-run-no-publication", started) + } + initialized := h.initLane(fix, "shared", "dry-run", "", "core.txt") + refName := "refs/heads/wip/bench/dry-run" + refBefore, beforeErr := runGit(fix, "rev-parse", refName) + dry := h.commitSingle(fix, "dry-run", "fix(core): prove dry run", true, "core.txt") + refAfterDry, dryRefErr := runGit(fix, "rev-parse", refName) + var dryData directCapture + dryDecodeErr := decodeEnvelopeData(dry.Envelope, &dryData) + actual := h.commitSingle(fix, "dry-run", "fix(core): prove dry run", false, "core.txt") + refAfterActual, actualRefErr := runGit(fix, "rev-parse", refName) + var actualData directCapture + actualDecodeErr := decodeEnvelopeData(actual.Envelope, &actualData) + positivePassed := initialized.succeeded() && beforeErr == nil && dry.succeeded() && dryDecodeErr == nil && dryData.DryRun && dryData.GateOutcome == "skipped" && dryData.Execution != nil && dryData.Execution.Policy == "no-exec" && dryData.Execution.PreCommitHooks.Executed == 0 && dryData.Execution.PostCommitHooks.Executed == 0 && dryData.Execution.VerifyCommands.Executed == 0 && !dryData.RefUpdated && dryRefErr == nil && refBefore == refAfterDry + negativePassed := actual.succeeded() && actualDecodeErr == nil && actualData.RefUpdated && actualRefErr == nil && refAfterActual != refBefore + return resultCase( + "dry-run-no-publication", started, + positivePassed, "dry-run validated the candidate without executing gates or moving the lane ref", "dry-run executed a gate, moved the ref, or did not report the no-exec preview", + negativePassed, "the same plan without --dry-run moved the ref, proving detector sensitivity", "the non-dry sensitivity control did not move the ref", + ) +} + +func caseFailedVerificationNoPublication(h harness) caseResult { + started := time.Now() + fix, err := newFixture(h.root, "failed-verification", map[string]string{"core.txt": "base\n"}) + if err != nil || writeAndStage(fix, "core.txt", "changed\n") != nil { + return failedFixtureCase("failed-verification-no-publication", started) + } + initialized := h.initLane(fix, "shared", "verify-gate", "", "core.txt") + planPath := filepath.Join(h.root, "failed-verification-plan.json") + planned := h.runWIP(fix, append([]string{"plan"}, append(identityArgs("verify-gate"), "--out", planPath)...)...) + failedPlanErr := reviewPlan(planPath, []string{"git", "--definitely-not-a-real-option"}) + refName := "refs/heads/wip/bench/verify-gate" + refBefore, beforeErr := runGit(fix, "rev-parse", refName) + failed := h.runWIP(fix, append([]string{"capture"}, append(identityArgs("verify-gate"), "--plan", planPath)...)...) + refAfterFailure, failedRefErr := runGit(fix, "rev-parse", refName) + passingPlanErr := reviewPlan(planPath, []string{"git", "--version"}) + passed := h.runWIP(fix, append([]string{"capture"}, append(identityArgs("verify-gate"), "--plan", planPath)...)...) + refAfterPass, passedRefErr := runGit(fix, "rev-parse", refName) + var passedData guidedCapture + passedDecodeErr := decodeEnvelopeData(passed.Envelope, &passedData) + positivePassed := initialized.succeeded() && planned.succeeded() && failedPlanErr == nil && beforeErr == nil && failed.failedWith("VERIFY_FAILED") && failedRefErr == nil && refAfterFailure == refBefore + negativePassed := passingPlanErr == nil && passed.succeeded() && passedDecodeErr == nil && passedData.Capture.RefUpdated && passedRefErr == nil && refAfterPass != refBefore + return resultCase( + "failed-verification-no-publication", started, + positivePassed, "a failing typed verify command left the lane ref unchanged", "failed verification published or did not return VERIFY_FAILED", + negativePassed, "a passing verify command published, proving gate-outcome sensitivity", "the passing verification sensitivity control did not publish", + ) +} + +func caseReconcileInterruptedPublication(h harness) caseResult { + started := time.Now() + fix, err := newFixture(h.root, "reconcile", map[string]string{"core.txt": "base\n"}) + if err != nil || writeAndStage(fix, "core.txt", "changed\n") != nil { + return failedFixtureCase("reconcile-interrupted-publication", started) + } + base, baseErr := runGit(fix, "rev-parse", "HEAD") + initialized := h.initLane(fix, "shared", "reconcile", "", "core.txt") + captured := h.commitSingle(fix, "reconcile", "fix(core): create recoverable receipt", false, "core.txt") + var capture directCapture + decodeErr := decodeEnvelopeData(captured.Envelope, &capture) + fixtureErr := errors.New("capture receipt unavailable") + if baseErr == nil && initialized.succeeded() && captured.succeeded() && decodeErr == nil && capture.PlanID != "" && capture.PlanDigest != "" && capture.FinalCommit != "" { + fixtureErr = reproduceAppliedIntentBoundary(fix, "reconcile", capture.PlanID, base) + } + wrongDigest := "sha256:" + strings.Repeat("0", 64) + wrong := h.runWIP(fix, append([]string{"reconcile"}, append(identityArgs("reconcile"), "--plan-id", capture.PlanID, "--plan-digest", wrongDigest)...)...) + cursorAfterWrong, cursorWrongErr := readLaneCursor(fix, "reconcile") + correct := h.runWIP(fix, append([]string{"reconcile"}, append(identityArgs("reconcile"), "--plan-id", capture.PlanID, "--plan-digest", capture.PlanDigest)...)...) + var first reconcileData + firstDecodeErr := decodeEnvelopeData(correct.Envelope, &first) + second := h.runWIP(fix, append([]string{"reconcile"}, append(identityArgs("reconcile"), "--plan-id", capture.PlanID, "--plan-digest", capture.PlanDigest)...)...) + var repeated reconcileData + secondDecodeErr := decodeEnvelopeData(second.Envelope, &repeated) + finalCursor, finalCursorErr := readLaneCursor(fix, "reconcile") + positivePassed := fixtureErr == nil && correct.succeeded() && firstDecodeErr == nil && first.IntentState == "complete" && !first.AlreadyClean && second.succeeded() && secondDecodeErr == nil && repeated.AlreadyClean && finalCursorErr == nil && finalCursor == capture.FinalCommit + negativePassed := fixtureErr == nil && wrong.failedWith("INTENT_DIGEST_MISMATCH") && cursorWrongErr == nil && cursorAfterWrong == base + return resultCase( + "reconcile-interrupted-publication", started, + positivePassed, "reconcile completed a reproduced applied-intent boundary and an exact retry was idempotent", "reconciliation or its idempotent retry failed", + negativePassed, "a wrong immutable receipt digest was refused without advancing the lane cursor", "expected INTENT_DIGEST_MISMATCH refusal was not observed", + ) +} + +func (h harness) initLane(f fixture, mode, lane, worktree string, paths ...string) wipRun { + args := []string{"init", "--mode", mode, "--lane", lane, "--agent", benchmarkAgent, "--session", benchmarkSession, "--non-interactive", "--no-install", "--no-install-skill"} + if worktree != "" { + args = append(args, "--create-worktree", worktree) + } + for _, path := range paths { + args = append(args, "--path", path) + } + return h.runWIP(f, args...) +} + +func (h harness) commitSingle(f fixture, lane, message string, dryRun bool, paths ...string) wipRun { + args := append([]string{"commit"}, identityArgs(lane)...) + args = append(args, "--single", "--message", message, "--non-interactive") + if dryRun { + args = append(args, "--dry-run") + } + for _, path := range paths { + args = append(args, "--path", path) + } + return h.runWIP(f, args...) +} + +func (h harness) runWIP(f fixture, args ...string) wipRun { + all := append([]string{"--json", "--repo-dir", f.repo}, args...) + raw := runCommand(defaultCommandTimeout, f.repo, isolatedEnvironment(f.home), h.candidate, all...) + result := wipRun{Raw: raw} + if err := json.Unmarshal([]byte(strings.TrimSpace(raw.Stdout)), &result.Envelope); err == nil { + result.Decoded = true + } + return result +} + +func identityArgs(lane string) []string { + return []string{"--lane", lane, "--agent", benchmarkAgent, "--session", benchmarkSession} +} + +func resultCase(id string, started time.Time, positive bool, positivePass, positiveFail string, negative bool, negativePass, negativeFail string) caseResult { + positiveDetail := positiveFail + if positive { + positiveDetail = positivePass + } + negativeDetail := negativeFail + if negative { + negativeDetail = negativePass + } + return caseResult{ + ID: id, Passed: positive && negative, + Positive: assertion{Passed: positive, Detail: positiveDetail}, + NegativeControl: assertion{Passed: negative, Detail: negativeDetail}, + ElapsedMS: elapsedMilliseconds(time.Since(started)), + } +} + +func failedFixtureCase(id string, started time.Time) caseResult { + return resultCase(id, started, false, "", "disposable fixture setup failed", false, "", "negative control could not run because fixture setup failed") +} + +func newFixture(root, id string, files map[string]string) (fixture, error) { + base := filepath.Join(root, id) + repo := filepath.Join(base, "repo") + home := filepath.Join(base, "home") + if err := os.MkdirAll(repo, 0o755); err != nil { + return fixture{}, err + } + if err := os.MkdirAll(home, 0o700); err != nil { + return fixture{}, err + } + fix := fixture{repo: repo, home: home} + if _, err := runGit(fix, "init", "-b", "main"); err != nil { + return fixture{}, err + } + for _, config := range [][2]string{ + {"user.name", "WIP Benchmark"}, + {"user.email", "wip-benchmark@example.invalid"}, + {"commit.gpgsign", "false"}, + {"core.autocrlf", "false"}, + } { + if _, err := runGit(fix, "config", config[0], config[1]); err != nil { + return fixture{}, err + } + } + paths := make([]string, 0, len(files)) + for path := range files { + paths = append(paths, path) + } + sort.Strings(paths) + for _, path := range paths { + if err := writeFixtureFile(fix.repo, path, files[path]); err != nil { + return fixture{}, err + } + } + if _, err := runGit(fix, "add", "--", "."); err != nil { + return fixture{}, err + } + if _, err := runGit(fix, "commit", "--no-gpg-sign", "-m", "test: create disposable benchmark fixture"); err != nil { + return fixture{}, err + } + return fix, nil +} + +func writeAndStage(f fixture, path, body string) error { + if err := writeFixtureFile(f.repo, path, body); err != nil { + return err + } + _, err := runGit(f, "add", "--", filepath.ToSlash(path)) + return err +} + +func writeFixtureFile(root, name, body string) error { + path := filepath.Join(root, filepath.FromSlash(name)) + if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil { + return err + } + return os.WriteFile(path, []byte(body), 0o600) +} + +func runGit(f fixture, args ...string) (string, error) { + return runGitAt(f, f.repo, args...) +} + +func runGitAt(f fixture, directory string, args ...string) (string, error) { + all := append([]string{"-C", directory}, args...) + result := runCommand(defaultCommandTimeout, directory, isolatedEnvironment(f.home), "git", all...) + if result.ExitCode != 0 || result.TimedOut || result.Err != nil { + return "", fmt.Errorf("git command failed") + } + return strings.TrimSpace(result.Stdout), nil +} + +func inspectPlan(path string) (string, int, bool, error) { + var plan map[string]any + if err := readBoundedJSON(path, &plan); err != nil { + return "", 0, false, err + } + state, _ := plan["state"].(string) + groups, ok := plan["groups"].([]any) + if !ok || len(groups) == 0 { + return state, 0, false, errors.New("plan groups missing") + } + rootConfig := false + for _, raw := range groups { + group, ok := raw.(map[string]any) + if !ok { + return state, len(groups), false, errors.New("plan group is invalid") + } + for _, field := range []string{"key", "suggested_scope", "suggested_prefix", "rationale"} { + value, ok := group[field].(string) + if !ok || strings.TrimSpace(value) == "" { + return state, len(groups), false, errors.New("plan review guidance is missing") + } + } + if group["key"] == "repository-config" { + rootConfig = true + } + } + return state, len(groups), rootConfig, nil +} + +func reviewPlan(path string, verifyArgv []string) error { + var plan map[string]any + if err := readBoundedJSON(path, &plan); err != nil { + return err + } + groups, ok := plan["groups"].([]any) + if !ok || len(groups) == 0 { + return errors.New("plan groups missing") + } + for index, raw := range groups { + group, ok := raw.(map[string]any) + if !ok { + return errors.New("plan group is invalid") + } + group["message"] = fmt.Sprintf("chore(benchmark): capture reviewed group %d", index+1) + delete(group, "verify") + } + if len(verifyArgv) > 0 { + first := groups[0].(map[string]any) + first["verify"] = []any{map[string]any{"argv": verifyArgv, "timeout_ms": float64(30_000)}} + } + plan["state"] = "reviewed" + return writeBoundedJSON(path, plan) +} + +func reproduceAppliedIntentBoundary(f fixture, lane, planID, base string) error { + common, err := runGit(f, "rev-parse", "--git-common-dir") + if err != nil { + return err + } + if !filepath.IsAbs(common) { + common = filepath.Join(f.repo, common) + } + stateRoot := filepath.Join(filepath.Clean(common), "wip", "v1") + lanePath := filepath.Join(stateRoot, "lanes", lane+".json") + intentPath := filepath.Join(stateRoot, "intents", planID+".json") + if err := mutateJSONObject(lanePath, func(value map[string]any) error { + value["current_sha"] = base + delete(value, "last_commit") + return nil + }); err != nil { + return err + } + return mutateJSONObject(intentPath, func(value map[string]any) error { + value["state"] = "applied" + return nil + }) +} + +func readLaneCursor(f fixture, lane string) (string, error) { + common, err := runGit(f, "rev-parse", "--git-common-dir") + if err != nil { + return "", err + } + if !filepath.IsAbs(common) { + common = filepath.Join(f.repo, common) + } + var value map[string]any + if err := readBoundedJSON(filepath.Join(filepath.Clean(common), "wip", "v1", "lanes", lane+".json"), &value); err != nil { + return "", err + } + cursor, ok := value["current_sha"].(string) + if !ok || cursor == "" { + return "", errors.New("lane cursor missing") + } + return cursor, nil +} + +func mutateJSONObject(path string, mutate func(map[string]any) error) error { + var value map[string]any + if err := readBoundedJSON(path, &value); err != nil { + return err + } + if err := mutate(value); err != nil { + return err + } + return writeBoundedJSON(path, value) +} + +func decodeEnvelopeData(value envelope, target any) error { + if len(value.Data) == 0 { + return errors.New("envelope data missing") + } + return json.Unmarshal(value.Data, target) +} + +func assembleReport(cases []caseResult, candidate candidateInfo, baselineDigest string, elapsedMS int64) report { + positivePassed, negativePassed := 0, 0 + for _, result := range cases { + if result.Positive.Passed { + positivePassed++ + } + if result.NegativeControl.Passed { + negativePassed++ + } + } + passed := positivePassed + negativePassed + total := len(cases) * 2 + score := 0.0 + if total > 0 { + score = float64(passed) / float64(total) + } + return report{ + SchemaVersion: reportSchemaVersion, Benchmark: benchmarkName, BenchmarkVersion: benchmarkVersion, + Platform: runtime.GOOS + "/" + runtime.GOARCH, Candidate: candidate, BaselineSHA256: baselineDigest, + Cases: cases, + Overall: overallResult{TotalChecks: total, PassedChecks: passed, FailedChecks: total - passed, PassedPositiveChecks: positivePassed, PassedNegativeControls: negativePassed, Score: score}, + ElapsedMS: elapsedMS, AIUsage: aiUsage{}, ZeroAI: true, + } +} + +func meetsBaseline(current report, reviewed baseline) bool { + if current.SchemaVersion != reportSchemaVersion || current.Benchmark != reviewed.Benchmark || current.BenchmarkVersion != reviewed.BenchmarkVersion || reviewed.ReviewStatus != "reviewed" { + return false + } + if reviewed.ZeroAIRequired && (!current.ZeroAI || current.AIUsage.Calls != 0 || current.AIUsage.Tokens != 0) { + return false + } + if current.Overall.Score < reviewed.MinimumScore || current.Overall.PassedPositiveChecks < reviewed.RequiredPositiveChecks || current.Overall.PassedNegativeControls < reviewed.RequiredNegativeControls { + return false + } + byID := make(map[string]caseResult, len(current.Cases)) + for _, result := range current.Cases { + if _, exists := byID[result.ID]; exists { + return false + } + byID[result.ID] = result + } + for _, id := range reviewed.RequiredCases { + result, exists := byID[id] + if !exists || !result.Passed || !result.Positive.Passed || !result.NegativeControl.Passed { + return false + } + } + return true +} + +func loadBaseline(path string) (baseline, []byte, error) { + info, err := os.Lstat(path) + if err != nil { + return baseline{}, nil, err + } + if !info.Mode().IsRegular() || info.Mode()&os.ModeSymlink != 0 { + return baseline{}, nil, errors.New("baseline is not a regular non-symlink file") + } + file, err := os.Open(path) + if err != nil { + return baseline{}, nil, err + } + defer func() { _ = file.Close() }() + opened, err := file.Stat() + if err != nil || !os.SameFile(info, opened) { + return baseline{}, nil, errors.New("baseline changed while opening") + } + body, err := io.ReadAll(io.LimitReader(file, maxJSONArtifactBytes+1)) + if err != nil { + return baseline{}, nil, err + } + if len(body) == 0 || len(body) > maxJSONArtifactBytes { + return baseline{}, nil, errors.New("baseline size is invalid") + } + current, err := os.Lstat(path) + if err != nil || !os.SameFile(opened, current) { + return baseline{}, nil, errors.New("baseline changed while reading") + } + var value baseline + decoder := json.NewDecoder(bytes.NewReader(body)) + decoder.DisallowUnknownFields() + if err := decoder.Decode(&value); err != nil { + return baseline{}, nil, err + } + if err := decoder.Decode(&struct{}{}); !errors.Is(err, io.EOF) { + return baseline{}, nil, errors.New("baseline contains trailing JSON data") + } + if value.SchemaVersion != reportSchemaVersion || value.Benchmark != benchmarkName || value.BenchmarkVersion != benchmarkVersion || value.ReviewStatus != "reviewed" || value.MinimumScore != 1 || !value.ZeroAIRequired { + return baseline{}, nil, errors.New("baseline identity or review policy is invalid") + } + if value.RequiredPositiveChecks != len(requiredCaseIDs) || value.RequiredNegativeControls != len(requiredCaseIDs) || !sameStrings(value.RequiredCases, requiredCaseIDs) { + return baseline{}, nil, errors.New("baseline case coverage is invalid") + } + return value, body, nil +} + +func sameStrings(left, right []string) bool { + if len(left) != len(right) { + return false + } + for index := range left { + if left[index] != right[index] { + return false + } + } + return true +} + +func writeRunArtifacts(directory string, current report, reviewed baseline) error { + if err := validateReport(current, reviewed); err != nil { + return err + } + if err := writeBoundedJSON(filepath.Join(directory, "latest-report.json"), current); err != nil { + return err + } + proposalPath := filepath.Join(directory, "proposal.json") + if current.Overall.MeetsReviewedBaseline { + if err := os.Remove(proposalPath); err != nil && !errors.Is(err, os.ErrNotExist) { + return err + } + return nil + } + failed := make([]string, 0) + for _, result := range current.Cases { + if !result.Passed { + failed = append(failed, result.ID) + } + } + return writeBoundedJSON(proposalPath, proposal{ + SchemaVersion: reportSchemaVersion, Benchmark: benchmarkName, BenchmarkVersion: benchmarkVersion, + BaselineScore: reviewed.MinimumScore, CandidateScore: current.Overall.Score, FailedCaseIDs: failed, + Action: "Repair the candidate and rerun every case. Do not change the reviewed baseline to admit a regression.", + }) +} + +func validateReport(current report, reviewed baseline) error { + if current.SchemaVersion != reportSchemaVersion || current.Benchmark != benchmarkName || current.BenchmarkVersion != benchmarkVersion { + return errors.New("report identity is invalid") + } + if current.Candidate.Kind == "" || !validSHA256(current.Candidate.SHA256) || !validSHA256(current.BaselineSHA256) { + return errors.New("report candidate or baseline identity is invalid") + } + if current.ElapsedMS < 1 || current.AIUsage.Calls != 0 || current.AIUsage.Tokens != 0 || !current.ZeroAI { + return errors.New("report elapsed-time or zero-AI contract is invalid") + } + if len(current.Cases) != len(requiredCaseIDs) || current.Overall.TotalChecks != len(requiredCaseIDs)*2 { + return errors.New("report case coverage is invalid") + } + positivePassed, negativePassed := 0, 0 + for index, result := range current.Cases { + if result.ID != requiredCaseIDs[index] || result.ElapsedMS < 1 { + return errors.New("report case identity or elapsed time is invalid") + } + if result.Passed != (result.Positive.Passed && result.NegativeControl.Passed) { + return errors.New("report case outcome is inconsistent") + } + if result.Positive.Passed { + positivePassed++ + } + if result.NegativeControl.Passed { + negativePassed++ + } + for _, detail := range []string{result.Positive.Detail, result.NegativeControl.Detail} { + if detail == "" || len(detail) > 512 || strings.ContainsAny(detail, "\r\n/\\") { + return errors.New("report detail is empty, oversized, or path-like") + } + } + } + passed := positivePassed + negativePassed + total := len(requiredCaseIDs) * 2 + expectedScore := float64(passed) / float64(total) + if current.Overall.PassedChecks != passed || current.Overall.FailedChecks != total-passed || current.Overall.PassedPositiveChecks != positivePassed || current.Overall.PassedNegativeControls != negativePassed || current.Overall.Score != expectedScore { + return errors.New("report aggregate outcome is inconsistent") + } + if current.Overall.MeetsReviewedBaseline != meetsBaseline(current, reviewed) { + return errors.New("report baseline outcome is inconsistent") + } + body, err := json.Marshal(current) + if err != nil { + return err + } + if len(body) > maxJSONArtifactBytes { + return errors.New("report exceeds benchmark limit") + } + return nil +} + +func validSHA256(value string) bool { + encoded, found := strings.CutPrefix(value, "sha256:") + if !found || len(encoded) != sha256.Size*2 { + return false + } + _, err := hex.DecodeString(encoded) + return err == nil +} + +func resolveArtifactDir(flagValue string) (string, error) { + if strings.TrimSpace(flagValue) != "" { + return filepath.Abs(flagValue) + } + home, err := os.UserHomeDir() + if err != nil { + return "", err + } + return filepath.Join(home, ".nicos-dev", "benchmarks", "wip-commit"), nil +} + +func prepareArtifactDir(path string) error { + if info, err := os.Lstat(path); err == nil { + if !info.IsDir() || info.Mode()&os.ModeSymlink != 0 { + return errors.New("artifact path is not a regular directory") + } + return nil + } else if !errors.Is(err, os.ErrNotExist) { + return err + } + return os.MkdirAll(path, 0o700) +} + +func readBoundedJSON(path string, target any) error { + file, err := os.Open(path) + if err != nil { + return err + } + defer func() { _ = file.Close() }() + body, err := io.ReadAll(io.LimitReader(file, maxJSONArtifactBytes+1)) + if err != nil { + return err + } + if len(body) > maxJSONArtifactBytes { + return errors.New("JSON input exceeds benchmark limit") + } + return json.Unmarshal(body, target) +} + +func writeBoundedJSON(path string, value any) error { + body, err := json.MarshalIndent(value, "", " ") + if err != nil { + return err + } + body = append(body, '\n') + if len(body) > maxJSONArtifactBytes { + return errors.New("JSON artifact exceeds benchmark limit") + } + if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil { + return err + } + temporary, err := os.CreateTemp(filepath.Dir(path), ".wip-benchmark-*.tmp") + if err != nil { + return err + } + temporaryPath := temporary.Name() + defer func() { _ = os.Remove(temporaryPath) }() + if err := temporary.Chmod(0o600); err != nil { + _ = temporary.Close() + return err + } + if _, err := temporary.Write(body); err != nil { + _ = temporary.Close() + return err + } + if err := temporary.Sync(); err != nil { + _ = temporary.Close() + return err + } + if err := temporary.Close(); err != nil { + return err + } + if err := os.Rename(temporaryPath, path); err == nil { + return nil + } + if err := os.Remove(path); err != nil && !errors.Is(err, os.ErrNotExist) { + return err + } + return os.Rename(temporaryPath, path) +} + +func repositoryRoot() (string, error) { + result := runCommand(10*time.Second, "", os.Environ(), "git", "rev-parse", "--show-toplevel") + if result.ExitCode != 0 || result.TimedOut || result.Err != nil { + return "", errors.New("current directory is not a Git repository") + } + root := strings.TrimSpace(result.Stdout) + if root == "" { + return "", errors.New("git returned an empty repository root") + } + return filepath.Abs(root) +} + +func buildGoCandidate(root, output, source string) error { + environment := withoutEnvironment(os.Environ(), "GOFLAGS", "GONOPROXY", "GONOSUMDB", "GOPRIVATE", "GOPROXY", "GOSUMDB", "GOTOOLCHAIN", "GOVCS", "GOWORK") + environment = append(environment, "GOFLAGS=", "GOPROXY=off", "GOSUMDB=off", "GOTOOLCHAIN=local", "GOWORK=off") + result := runCommand(2*time.Minute, root, environment, "go", "build", "-trimpath", "-ldflags=-buildid=", "-o", output, source) + if result.ExitCode != 0 || result.TimedOut || result.Err != nil { + return errors.New("go build failed; prefetch modules before running the offline benchmark") + } + return nil +} + +func freezeCandidate(source, workspace string) (string, string, error) { + info, err := os.Lstat(source) + if err != nil { + return "", "", err + } + if !info.Mode().IsRegular() || info.Mode()&os.ModeSymlink != 0 { + return "", "", errors.New("candidate is not a regular non-symlink file") + } + if info.Size() <= 0 || info.Size() > maxCandidateBytes { + return "", "", errors.New("candidate size is outside the benchmark limit") + } + + input, err := os.Open(source) + if err != nil { + return "", "", err + } + defer func() { _ = input.Close() }() + opened, err := input.Stat() + if err != nil || !os.SameFile(info, opened) || !opened.Mode().IsRegular() { + return "", "", errors.New("candidate changed while opening") + } + + destinationPath := filepath.Join(workspace, executableName("wip-evaluated")) + destination, err := os.OpenFile(destinationPath, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o700) + if err != nil { + return "", "", err + } + keep := false + defer func() { + _ = destination.Close() + if !keep { + _ = os.Remove(destinationPath) + } + }() + + digest := sha256.New() + written, err := io.Copy(io.MultiWriter(destination, digest), io.LimitReader(input, maxCandidateBytes+1)) + if err != nil { + return "", "", err + } + if written <= 0 || written > maxCandidateBytes { + return "", "", errors.New("candidate size is outside the benchmark limit") + } + if err := destination.Sync(); err != nil { + return "", "", err + } + if err := destination.Close(); err != nil { + return "", "", err + } + if err := os.Chmod(destinationPath, 0o700); err != nil { + return "", "", err + } + keep = true + return destinationPath, "sha256:" + hex.EncodeToString(digest.Sum(nil)), nil +} + +func inspectCandidate(path, kind, digest, workspace string) (candidateInfo, error) { + metadata := candidateInfo{Kind: kind, SHA256: digest} + home := filepath.Join(workspace, "candidate-home") + if err := os.MkdirAll(home, 0o700); err != nil { + return candidateInfo{}, err + } + raw := runCommand(10*time.Second, workspace, isolatedEnvironment(home), path, "--json", "version") + if raw.ExitCode != 0 { + return metadata, nil + } + var value envelope + if json.Unmarshal([]byte(strings.TrimSpace(raw.Stdout)), &value) != nil || !value.OK { + return metadata, nil + } + var version struct { + Version string `json:"version"` + Revision string `json:"revision"` + SourceState string `json:"source_state"` + } + if json.Unmarshal(value.Data, &version) == nil { + metadata.Version = safeMetadata(version.Version) + metadata.Revision = safeMetadata(version.Revision) + metadata.SourceState = safeMetadata(version.SourceState) + } + return metadata, nil +} + +func safeMetadata(value string) string { + value = strings.TrimSpace(value) + if len(value) > 128 || strings.ContainsAny(value, "\r\n/\\") { + return "" + } + return value +} + +func isolatedEnvironment(home string) []string { + allowed := map[string]bool{ + "COMSPEC": true, + "PATH": true, + "PATHEXT": true, + "SYSTEMROOT": true, + "WINDIR": true, + } + filtered := make([]string, 0, len(allowed)+11) + for _, entry := range os.Environ() { + name, _, _ := strings.Cut(entry, "=") + upper := strings.ToUpper(name) + if allowed[upper] { + filtered = append(filtered, entry) + } + } + return append(filtered, + "HOME="+home, + "USERPROFILE="+home, + "TEMP="+home, + "TMP="+home, + "TMPDIR="+home, + "LANG=C", + "LC_ALL=C", + "TZ=UTC", + "GIT_CONFIG_NOSYSTEM=1", + "GIT_TERMINAL_PROMPT=0", + ) +} + +func withoutEnvironment(environment []string, names ...string) []string { + blocked := make(map[string]bool, len(names)) + for _, name := range names { + blocked[strings.ToUpper(name)] = true + } + result := make([]string, 0, len(environment)) + for _, entry := range environment { + name, _, _ := strings.Cut(entry, "=") + if !blocked[strings.ToUpper(name)] { + result = append(result, entry) + } + } + return result +} + +type cappedBuffer struct { + buffer bytes.Buffer + limit int +} + +func (buffer *cappedBuffer) Write(value []byte) (int, error) { + original := len(value) + remaining := buffer.limit - buffer.buffer.Len() + if remaining > 0 { + if len(value) > remaining { + value = value[:remaining] + } + _, _ = buffer.buffer.Write(value) + } + return original, nil +} + +func (buffer *cappedBuffer) String() string { return buffer.buffer.String() } + +func runCommand(timeout time.Duration, directory string, environment []string, executable string, args ...string) rawCommand { + ctx, cancel := context.WithTimeout(context.Background(), timeout) + defer cancel() + command := exec.CommandContext(ctx, executable, args...) + if directory != "" { + command.Dir = directory + } + command.Env = environment + stdout := &cappedBuffer{limit: maxCommandOutputBytes} + stderr := &cappedBuffer{limit: maxCommandOutputBytes} + command.Stdout, command.Stderr = stdout, stderr + err := command.Run() + result := rawCommand{ExitCode: 0, Stdout: stdout.String(), Stderr: stderr.String(), TimedOut: errors.Is(ctx.Err(), context.DeadlineExceeded), Err: err} + if err == nil { + return result + } + var exitErr *exec.ExitError + if errors.As(err, &exitErr) { + result.ExitCode = exitErr.ExitCode() + result.Err = nil + return result + } + result.ExitCode = -1 + return result +} + +func elapsedMilliseconds(duration time.Duration) int64 { + value := duration.Milliseconds() + if value < 1 { + return 1 + } + return value +} + +func executableName(base string) string { + if runtime.GOOS == "windows" { + return base + ".exe" + } + return base +} + +func sha256Text(body []byte) string { + digest := sha256.Sum256(body) + return "sha256:" + hex.EncodeToString(digest[:]) +} diff --git a/skills/wip-commit/benchmark/regression_test.go b/skills/wip-commit/benchmark/regression_test.go new file mode 100644 index 0000000..97f3115 --- /dev/null +++ b/skills/wip-commit/benchmark/regression_test.go @@ -0,0 +1,190 @@ +package main + +import ( + "os" + "path/filepath" + "strings" + "testing" +) + +func TestReviewedBaselineCoversEverySemanticCase(t *testing.T) { + reviewed, body, err := loadBaseline("baseline.json") + if err != nil { + t.Fatal(err) + } + if len(body) == 0 || reviewed.MinimumScore != 1 || !reviewed.ZeroAIRequired { + t.Fatalf("baseline = %#v", reviewed) + } + if !sameStrings(reviewed.RequiredCases, requiredCaseIDs) { + t.Fatalf("baseline cases = %#v, want %#v", reviewed.RequiredCases, requiredCaseIDs) + } +} + +func TestReportValidationRejectsPathsAndAIMisreporting(t *testing.T) { + cases := make([]caseResult, 0, len(requiredCaseIDs)) + for _, id := range requiredCaseIDs { + cases = append(cases, caseResult{ + ID: id, Passed: true, ElapsedMS: 1, + Positive: assertion{Passed: true, Detail: "portable positive evidence"}, + NegativeControl: assertion{Passed: true, Detail: "portable negative evidence"}, + }) + } + reviewed := reviewedBaselineForTest() + value := assembleReport(cases, candidateInfo{Kind: "repository-build", SHA256: "sha256:" + strings.Repeat("a", 64)}, "sha256:"+strings.Repeat("b", 64), 1) + value.Overall.MeetsReviewedBaseline = meetsBaseline(value, reviewed) + if err := validateReport(value, reviewed); err != nil { + t.Fatal(err) + } + value.Cases[0].Positive.Detail = "/private/fixture/path" + if err := validateReport(value, reviewed); err == nil { + t.Fatal("path-bearing report detail was accepted") + } + value.Cases[0].Positive.Detail = "portable positive evidence" + value.AIUsage.Calls = 1 + if err := validateReport(value, reviewed); err == nil { + t.Fatal("nonzero AI usage was accepted as a zero-AI report") + } +} + +func TestReportValidationRejectsInconsistentAggregates(t *testing.T) { + cases := make([]caseResult, 0, len(requiredCaseIDs)) + for _, id := range requiredCaseIDs { + cases = append(cases, caseResult{ + ID: id, Passed: true, ElapsedMS: 1, + Positive: assertion{Passed: true, Detail: "portable positive evidence"}, + NegativeControl: assertion{Passed: true, Detail: "portable negative evidence"}, + }) + } + reviewed := reviewedBaselineForTest() + value := assembleReport(cases, candidateInfo{Kind: "repository-build", SHA256: "sha256:" + strings.Repeat("a", 64)}, "sha256:"+strings.Repeat("b", 64), 1) + value.Overall.MeetsReviewedBaseline = meetsBaseline(value, reviewed) + value.Overall.PassedChecks-- + if err := validateReport(value, reviewed); err == nil { + t.Fatal("inconsistent aggregate outcome was accepted") + } +} + +func TestFreezeCandidateHashesExactExecutableCopy(t *testing.T) { + sourceDir := t.TempDir() + workspace := t.TempDir() + source := filepath.Join(sourceDir, executableName("candidate")) + original := []byte("candidate bytes\n") + if err := os.WriteFile(source, original, 0o700); err != nil { + t.Fatal(err) + } + frozen, digest, err := freezeCandidate(source, workspace) + if err != nil { + t.Fatal(err) + } + if frozen == source || digest != sha256Text(original) { + t.Fatalf("frozen = %q, digest = %q", frozen, digest) + } + if err := os.WriteFile(source, []byte("changed source\n"), 0o700); err != nil { + t.Fatal(err) + } + body, err := os.ReadFile(frozen) + if err != nil { + t.Fatal(err) + } + if string(body) != string(original) { + t.Fatalf("frozen candidate changed with source: %q", body) + } +} + +func TestIsolatedEnvironmentDropsCredentialsAndAmbientGitState(t *testing.T) { + t.Setenv("PATH", "/benchmark/bin") + t.Setenv("AWS_SECRET_ACCESS_KEY", "do-not-pass") + t.Setenv("GIT_DIR", "/ambient/git") + t.Setenv("SSH_AUTH_SOCK", "/ambient/agent") + home := t.TempDir() + environment := environmentMap(isolatedEnvironment(home)) + for _, name := range []string{"AWS_SECRET_ACCESS_KEY", "GIT_DIR", "SSH_AUTH_SOCK"} { + if _, exists := environment[name]; exists { + t.Fatalf("isolated environment retained %s", name) + } + } + for name, expected := range map[string]string{ + "HOME": home, "USERPROFILE": home, "TEMP": home, "TMP": home, "TMPDIR": home, + "PATH": "/benchmark/bin", "GIT_CONFIG_NOSYSTEM": "1", "GIT_TERMINAL_PROMPT": "0", + } { + if environment[name] != expected { + t.Fatalf("%s = %q, want %q", name, environment[name], expected) + } + } +} + +func environmentMap(environment []string) map[string]string { + result := make(map[string]string, len(environment)) + for _, entry := range environment { + name, value, _ := strings.Cut(entry, "=") + result[strings.ToUpper(name)] = value + } + return result +} + +func reviewedBaselineForTest() baseline { + return baseline{ + SchemaVersion: reportSchemaVersion, Benchmark: benchmarkName, BenchmarkVersion: benchmarkVersion, + ReviewStatus: "reviewed", MinimumScore: 1, RequiredPositiveChecks: len(requiredCaseIDs), + RequiredNegativeControls: len(requiredCaseIDs), ZeroAIRequired: true, RequiredCases: append([]string(nil), requiredCaseIDs...), + } +} + +func TestMutableArtifactsCannotReplaceReviewedBaseline(t *testing.T) { + directory := t.TempDir() + baselinePath := filepath.Join(directory, "baseline.json") + original, err := os.ReadFile("baseline.json") + if err != nil { + t.Fatal(err) + } + if err := os.WriteFile(baselinePath, original, 0o600); err != nil { + t.Fatal(err) + } + reviewed, _, err := loadBaseline(baselinePath) + if err != nil { + t.Fatal(err) + } + cases := make([]caseResult, 0, len(requiredCaseIDs)) + for _, id := range requiredCaseIDs { + cases = append(cases, caseResult{ + ID: id, ElapsedMS: 1, + Positive: assertion{Detail: "candidate regression"}, + NegativeControl: assertion{Detail: "negative control regression"}, + }) + } + value := assembleReport(cases, candidateInfo{Kind: weakenedCandidateLabel, SHA256: "sha256:" + strings.Repeat("a", 64)}, sha256Text(original), 1) + value.Overall.MeetsReviewedBaseline = meetsBaseline(value, reviewed) + artifactDir := filepath.Join(directory, "artifacts") + if err := prepareArtifactDir(artifactDir); err != nil { + t.Fatal(err) + } + if err := writeRunArtifacts(artifactDir, value, reviewed); err != nil { + t.Fatal(err) + } + after, err := os.ReadFile(baselinePath) + if err != nil { + t.Fatal(err) + } + if string(after) != string(original) { + t.Fatal("mutable artifact write changed the reviewed baseline") + } + if _, err := os.Stat(filepath.Join(artifactDir, "proposal.json")); err != nil { + t.Fatalf("failing candidate did not produce a proposal: %v", err) + } +} + +func TestDeliberatelyWeakenedCandidateContainsNoSafetyBehavior(t *testing.T) { + body, err := os.ReadFile(filepath.Join("testdata", "weakened", "main.go")) + if err != nil { + t.Fatal(err) + } + text := string(body) + if !strings.Contains(text, "unsafe-noop") { + t.Fatal("weakened candidate identity is missing") + } + for _, forbidden := range []string{"WORKTREE_REQUIRED", "PATH_LEASE_CONFLICT", "PLAN_NOT_REVIEWED", "SPLIT_PLAN_REQUIRED", "LEASE_REQUIRED", "VERIFY_FAILED", "INTENT_DIGEST_MISMATCH", "os/exec"} { + if strings.Contains(text, forbidden) { + t.Fatalf("weakened candidate unexpectedly contains %q", forbidden) + } + } +} diff --git a/skills/wip-commit/benchmark/testdata/weakened/main.go b/skills/wip-commit/benchmark/testdata/weakened/main.go new file mode 100644 index 0000000..2a48845 --- /dev/null +++ b/skills/wip-commit/benchmark/testdata/weakened/main.go @@ -0,0 +1,9 @@ +package main + +import "fmt" + +// This candidate deliberately ignores every safety contract. The behavioral +// benchmark must reject it, and the runner has no baseline-promotion mode. +func main() { + fmt.Println(`{"ok":true,"action":"unsafe-noop","data":{}}`) +} diff --git a/skills/wip-commit/bundle.go b/skills/wip-commit/bundle.go index b46f76e..82812ae 100644 --- a/skills/wip-commit/bundle.go +++ b/skills/wip-commit/bundle.go @@ -3,15 +3,76 @@ // checkout or a private toolchain. package skillbundle -import "embed" +import ( + "crypto/sha256" + "embed" + "encoding/binary" + "encoding/hex" + "fmt" + "slices" +) // FS contains the complete portable runtime surface. // -//go:embed SKILL.md references/automation.md agents/openai.yaml +//go:embed SKILL.md contract.json references/automation.md agents/openai.yaml var FS embed.FS var Paths = []string{ "SKILL.md", "references/automation.md", "agents/openai.yaml", + // Publish the contract last so it acts as the bundle's commit marker. + "contract.json", +} + +var PayloadPaths = []string{ + "SKILL.md", + "references/automation.md", + "agents/openai.yaml", +} + +// PayloadDigest binds the portable instructions without creating a self-hash +// cycle through contract.json. Each sorted path and byte length is framed. +func PayloadDigest() (string, error) { + return embeddedDigest(PayloadPaths) +} + +func BundleDigest() (string, error) { + return embeddedDigest(Paths) +} + +func embeddedDigest(paths []string) (string, error) { + files := make(map[string][]byte, len(paths)) + for _, path := range paths { + body, err := FS.ReadFile(path) + if err != nil { + return "", fmt.Errorf("read embedded skill file %s: %w", path, err) + } + files[path] = body + } + return DigestFiles(files) +} + +// DigestFiles binds a complete named file set with sorted path and length +// framing. Callers must first reject unsafe or unexpected filesystem entries. +func DigestFiles(files map[string][]byte) (string, error) { + paths := make([]string, 0, len(files)) + for path := range files { + if path == "" { + return "", fmt.Errorf("portable bundle contains an empty path") + } + paths = append(paths, path) + } + slices.Sort(paths) + hash := sha256.New() + var length [8]byte + for _, path := range paths { + body := files[path] + _, _ = hash.Write([]byte(path)) + _, _ = hash.Write([]byte{0}) + binary.BigEndian.PutUint64(length[:], uint64(len(body))) + _, _ = hash.Write(length[:]) + _, _ = hash.Write(body) + } + return "sha256:" + hex.EncodeToString(hash.Sum(nil)), nil } diff --git a/skills/wip-commit/bundle_test.go b/skills/wip-commit/bundle_test.go new file mode 100644 index 0000000..8aa0d74 --- /dev/null +++ b/skills/wip-commit/bundle_test.go @@ -0,0 +1,52 @@ +package skillbundle + +import ( + "testing" + + "github.com/nstranquist/wip-commit/internal/contract" + "github.com/nstranquist/wip-commit/internal/strictjson" +) + +func TestEmbeddedContractMatchesCommandContract(t *testing.T) { + body, err := FS.ReadFile("contract.json") + if err != nil { + t.Fatal(err) + } + var embedded struct { + contract.Document + PortableBundleSHA256 string `json:"portable_bundle_sha256"` + } + if err := strictjson.Decode(body, &embedded); err != nil { + t.Fatal(err) + } + wanted, got := contract.Current(), embedded + if wanted.SchemaVersion != got.SchemaVersion || wanted.Protocol != got.Protocol || wanted.PortableSkillContract != got.PortableSkillContract { + t.Fatalf("embedded contract = %#v, want %#v", got, wanted) + } + if len(wanted.Capabilities) != len(got.Capabilities) { + t.Fatalf("embedded capabilities = %v, want %v", got.Capabilities, wanted.Capabilities) + } + for index := range wanted.Capabilities { + if wanted.Capabilities[index] != got.Capabilities[index] { + t.Fatalf("embedded capabilities = %v, want %v", got.Capabilities, wanted.Capabilities) + } + } + if digest, err := PayloadDigest(); err != nil || len(digest) != len("sha256:")+64 { + t.Fatalf("payload digest = %q, %v", digest, err) + } + payloadValue, payloadErr := PayloadDigest() + bundleValue, bundleErr := BundleDigest() + if payload, bundle := mustDigest(t, payloadValue, payloadErr), mustDigest(t, bundleValue, bundleErr); payload == bundle { + t.Fatalf("payload and complete bundle digests unexpectedly match: %s", payload) + } else if embedded.PortableBundleSHA256 != payload { + t.Fatalf("embedded portable digest = %s, want %s", embedded.PortableBundleSHA256, payload) + } +} + +func mustDigest(t *testing.T, digest string, err error) string { + t.Helper() + if err != nil { + t.Fatal(err) + } + return digest +} diff --git a/skills/wip-commit/contract.json b/skills/wip-commit/contract.json new file mode 100644 index 0000000..2652690 --- /dev/null +++ b/skills/wip-commit/contract.json @@ -0,0 +1,31 @@ +{ + "schema_version": "1.0.0", + "protocol": "wip.command/3.0.0", + "capabilities": [ + "capture.v3.private-source-cas", + "capture.v3.review-digest", + "commit.dry-run.no-exec.v1", + "coordination.migration.v1", + "doctor.v1", + "handoff.v2.cumulative-capture-only", + "hook.environment.v1", + "install.digest-upgrade.v1", + "lane.init.anchor-recovery.v1", + "lane.init.v1", + "lease.claim.v1", + "plan.v3.observe", + "plan.v3.private-source-no-overwrite", + "source.worktree-snapshot.v1", + "state.archive-history.v1", + "state.capture-intent.v2", + "state.capture-intent.v3", + "state.init-intent.v2", + "state.profile.v2", + "state.reader-floor.v1", + "status.v2.observe", + "verify.materialization.v1", + "version.v2.provenance" + ], + "portable_skill_contract": "wip.portable-skill/2.0.0", + "portable_bundle_sha256": "sha256:c0f6b0b3bdf6d4895c6878abed14a9a00c745d8e257969330bbc45441f47148c" +} diff --git a/skills/wip-commit/references/automation.md b/skills/wip-commit/references/automation.md index 4bdea5b..49cb2e6 100644 --- a/skills/wip-commit/references/automation.md +++ b/skills/wip-commit/references/automation.md @@ -5,19 +5,29 @@ status as the only proof of capture. ## Preflight and setup -Run `wip --json doctor` before setup. Stop if it reports an unsafe state record, -an incomplete recovery, or another coordination domain. +Run `wip --json contract`, then `wip --json doctor` before setup. Stop if the +contract is incompatible or doctor reports an unsafe state record, an +incomplete recovery, or another coordination domain. If +`data.upgrade_required` is true, complete a reviewed state-upgrade preview and +apply before lane setup. For healthy initialized state with no required +upgrade, run `wip --json status --observe`. `LANE_NOT_ACTIVE` selects a new +standalone `wip init` lane. It does not authorize a legacy fallback. -Inspect the staged path set with -`git diff --cached --no-renames --name-only -z`. Parse NUL-delimited paths so -tabs, spaces, and newlines in file names stay exact. +Validate the complete contract document and portable payload digest. If a +binary or skill upgrade is required, review the target-specific `wip --json +upgrade` preview and apply only its exact digest. Do not upgrade more than one +target in one command. -Use explicit setup values. Disable installation when a separate bootstrap step -owns installation: +Inspect the worktree and staged path sets. Parse NUL-delimited Git output so +tabs, spaces, and newlines in file names stay exact. Do not use the full staged +index as implicit authority. + +Use explicit setup values. Use one linked worktree for each automated task: ```text wip --json init \ - --mode shared \ + --mode worktree \ + --create-worktree \ --lane \ --agent \ --session \ @@ -31,64 +41,86 @@ If initialization fails after it writes an intent, parse `intent_id`, `intent_state`, `completed_steps`, and `recovery`. Retry only the exact command in `recovery`. -Run `wip --json plan` after staging. Treat its component groups and subject -prefixes as review hints. Check semantic intent and dependency closure before -you write the commit plan. - -## Plan shape - -Write one ordered object for each coherent commit: - -```json -[ - { - "message": "fix(parser): preserve source locations", - "files": ["internal/parser/errors.go"], - "verify": [ - { - "argv": ["go", "test", "./internal/parser"], - "timeout_ms": 120000 - } - ] - }, - { - "message": "docs(parser): explain source locations", - "files": ["docs/parser-errors.md"] - } -] +Run `wip --json status`. Check `capture_candidates`, +`foreign_staged`, `lease_expires_at`, `ref_health`, and `last_intent`. + +Write one no-overwrite draft: + +```text +wip --json plan \ + --source worktree_snapshot \ + --untracked forbid \ + --path \ + --observe + +wip --json plan \ + --source worktree_snapshot \ + --untracked forbid \ + --path \ + --out plan.json ``` -Keep every file in exactly one group. Use repository-relative paths. Do not -include an unclaimed path. Keep each verification timeout finite. +The observed command must change no repository bytes. It cannot use `--out`. +Use it to check the selected source before the operational plan renews leases +and creates `plan.json`. -Pass a file or standard input: +Use `--untracked include` only when the reviewed source must contain the exact +untracked paths. For a controlled shared-index exception, use `--source +staged_index --untracked not_applicable` after you stage only the owned paths. + +Review the component groups and path ownership. Add messages and bounded +verification commands. Then set `state` to `reviewed`. + +## Review the generated plan + +Edit only the object that `wip plan --out` created. Do not copy a partial JSON +example or create a second plan format. Add each `message` and optional typed +`verify` command. Give each verification command a bounded `timeout_ms`. Set +`directory` to its smallest runnable candidate subtree. Use `materialize` only +for reviewed repository-relative dependencies that the command needs. A root +command with neither field requests the full candidate tree and can exceed the +fixed materialization limit. Set `state` to `reviewed` after the complete +object passes review. Keep the +generated lane, source mode, untracked policy, source digest, source scopes, +lease, policy, guidance, path, group key, scope, prefix, and rationale fields +exact. Keep every source path in exactly one group. + +Capture the exact reviewed file: ```text -wip --json commit --plan plan.json -wip --json commit --plan - < plan.json +wip --json capture --plan plan.json ``` +Do not use `wip commit --dry-run` as gate evidence. That command validates the +candidate structure without executing hooks or verification commands. Its +schema `3.0.0` result reports `gate_outcome: "skipped"`, a `no-exec` policy, +and zero executed counts. It does not renew the lease or emit a handoff. + ## Result checks -Parse the single JSON envelope. Require `ok: true`. In `data`, require -`ref_updated: true`, `gate_outcome: "passed"`, and -`intent_state: "complete"`. Check the returned commit sequence and lane ref -against the plan and the lane recorded before capture. +Parse the single JSON envelope. Require `ok: true`. In `data.capture`, require +`ref_updated: true`, `gate_outcome: "passed"`, and `intent_state: "complete"`. + +In `data.handoff`, require `capture_only: true`, `landing_authorized: false`, +`review_eligible: true`, and an exact `handoff_digest`. Validate every segment +and its intent digest. Require a continuous parent chain from the lane base to +the lane tip. Check the final tree, commit sequences, and paths against all +reviewed plans. The handoff does not authorize landing. If the command fails before the compare-and-swap ref update, fix the reported cause and run the full plan again. If it fails after the ref update, use only the returned `plan_id` and `plan_digest` with `wip reconcile`. Do not run two captures for the same lane at once. Separate lanes with -disjoint leases can capture in parallel. `wip commit` keeps the complete active -lane lease set captured at its start alive during hooks and verification. Use -`wip renew` only for editing time between captures. +disjoint leases can capture in parallel. `wip capture` renews the complete +active set during hooks and verification. ## State maintenance Run `wip --json doctor` before archival. Archive only a reviewed preview. Reuse -the exact `cutoff` and `plan_digest` with `--apply --yes`. If a failed apply -returns a prepared receipt, continue only with: +the exact `cutoff` and `plan_digest` with `--apply --yes`, and repeat every lane +in the preview's `lane_filters`. If a failed apply returns a prepared receipt, +continue only with: ```text wip --json archive --resume --apply --yes