worktree-controller 1.32.16__tar.gz → 1.33.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/PKG-INFO +5 -5
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/README.md +4 -4
- worktree_controller-1.33.0/docs/build-resources.md +91 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/docs/operations.md +16 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/docs/reference.md +5 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/pyproject.toml +1 -1
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/pyproject.toml.orig +1 -1
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/__init__.py +1 -1
- worktree_controller-1.33.0/src/worktree_controller/build_resources.py +156 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/cli.py +25 -1
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/controller.py +2 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/convergence.py +18 -1
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/disposable.py +43 -26
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/git_backend.py +13 -3
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/integration_cleanup.py +75 -1
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/lifecycle.py +8 -3
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/record_updates.py +10 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/semantics.py +10 -4
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/tool_cli_contract.json +11 -2
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/tool_cli_contract.json +11 -2
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/LICENSE +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/docs/architecture.md +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/docs/client-integration.md +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/docs/daily-workflow.md +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/docs/first-change.md +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/docs/getting-started.md +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/docs/integration-boundaries.md +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/docs/publishing.md +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/docs/roadmap.md +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/docs/scope.md +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/examples/change_task.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/examples/client_continuation.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/examples/quickstart.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/activation_layout.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/branch_retirement.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/canonical_refresh.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/canonical_transition.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/cleanup_attempts.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/cleanup_evidence.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/cleanup_recovery.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/delivered_closeout.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/environment.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/frozen_recovery.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/governance.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/hardlinks.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/integration_conflict.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/integration_retry.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/keyed_document_scope.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/lifecycle_history.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/lifecycle_observation.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/metadata_codec.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/metadata_relocation.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/models.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/mount_diagnostics.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/multiple_cleanup_recovery.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/namespace_migration.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/native_session_recovery.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/owner_actions.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/policy.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/preservation.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/preserved_cleanup.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/publication_execution.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/reconciler.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/recovery_guidance.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/registration_backfill.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/registration_prune.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/release_intents.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/rendering.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/resource_admission.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/retirement_adapters.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/retirement_execution.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/session.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/session_admission.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/source_cleanup.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/source_preservation.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/source_recovery.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/store.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/task_workflow.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/transaction_scope.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/writer_lease.py +0 -0
- {worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/writer_session.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: worktree-controller
|
|
3
|
-
Version: 1.
|
|
3
|
+
Version: 1.33.0
|
|
4
4
|
Summary: Govern Git worktree budgets, authority, ownership, and lifecycle
|
|
5
5
|
License-Expression: Apache-2.0
|
|
6
6
|
License-File: LICENSE
|
|
@@ -23,7 +23,7 @@ It checks repository policy before allocating a worktree, grants writing authori
|
|
|
23
23
|
process, and records handoff, integration, recovery and release evidence. Git remains the source
|
|
24
24
|
of truth for files, branches, commits and registered worktrees.
|
|
25
25
|
|
|
26
|
-
**Current release: 1.32.
|
|
26
|
+
**Current release: 1.32.18 · Linux · Python 3.12 · Apache-2.0**
|
|
27
27
|
|
|
28
28
|
## Install
|
|
29
29
|
|
|
@@ -32,7 +32,7 @@ Use a virtual environment in a new directory:
|
|
|
32
32
|
```bash
|
|
33
33
|
python3.12 -m venv .venv
|
|
34
34
|
. .venv/bin/activate
|
|
35
|
-
python -m pip install worktree-controller==1.32.
|
|
35
|
+
python -m pip install worktree-controller==1.32.18
|
|
36
36
|
worktree-controller --version
|
|
37
37
|
worktree-controller capabilities --json
|
|
38
38
|
```
|
|
@@ -41,7 +41,7 @@ WC requires Git and readable Linux `/proc`. Other operating systems and Python v
|
|
|
41
41
|
supported by this release. Its one runtime dependency is `websockets>=15,<16`.
|
|
42
42
|
On Ubuntu, if creating the environment reports that `ensurepip` is unavailable, install the
|
|
43
43
|
distribution's `python3.12-venv` package first (for example, `sudo apt install python3.12-venv`).
|
|
44
|
-
Software version 1.32.
|
|
44
|
+
Software version 1.32.18 uses CLI contract **61** and storage layout **5**.
|
|
45
45
|
|
|
46
46
|
## Try it in a disposable repository
|
|
47
47
|
|
|
@@ -50,7 +50,7 @@ With the environment above active:
|
|
|
50
50
|
```bash
|
|
51
51
|
git clone https://github.com/xuanheng-tech/worktree-controller.git wc
|
|
52
52
|
cd wc
|
|
53
|
-
git checkout v1.32.
|
|
53
|
+
git checkout v1.32.18
|
|
54
54
|
python examples/quickstart.py --workspace "$HOME/wc-first-run"
|
|
55
55
|
```
|
|
56
56
|
|
|
@@ -6,7 +6,7 @@ It checks repository policy before allocating a worktree, grants writing authori
|
|
|
6
6
|
process, and records handoff, integration, recovery and release evidence. Git remains the source
|
|
7
7
|
of truth for files, branches, commits and registered worktrees.
|
|
8
8
|
|
|
9
|
-
**Current release: 1.32.
|
|
9
|
+
**Current release: 1.32.18 · Linux · Python 3.12 · Apache-2.0**
|
|
10
10
|
|
|
11
11
|
## Install
|
|
12
12
|
|
|
@@ -15,7 +15,7 @@ Use a virtual environment in a new directory:
|
|
|
15
15
|
```bash
|
|
16
16
|
python3.12 -m venv .venv
|
|
17
17
|
. .venv/bin/activate
|
|
18
|
-
python -m pip install worktree-controller==1.32.
|
|
18
|
+
python -m pip install worktree-controller==1.32.18
|
|
19
19
|
worktree-controller --version
|
|
20
20
|
worktree-controller capabilities --json
|
|
21
21
|
```
|
|
@@ -24,7 +24,7 @@ WC requires Git and readable Linux `/proc`. Other operating systems and Python v
|
|
|
24
24
|
supported by this release. Its one runtime dependency is `websockets>=15,<16`.
|
|
25
25
|
On Ubuntu, if creating the environment reports that `ensurepip` is unavailable, install the
|
|
26
26
|
distribution's `python3.12-venv` package first (for example, `sudo apt install python3.12-venv`).
|
|
27
|
-
Software version 1.32.
|
|
27
|
+
Software version 1.32.18 uses CLI contract **61** and storage layout **5**.
|
|
28
28
|
|
|
29
29
|
## Try it in a disposable repository
|
|
30
30
|
|
|
@@ -33,7 +33,7 @@ With the environment above active:
|
|
|
33
33
|
```bash
|
|
34
34
|
git clone https://github.com/xuanheng-tech/worktree-controller.git wc
|
|
35
35
|
cd wc
|
|
36
|
-
git checkout v1.32.
|
|
36
|
+
git checkout v1.32.18
|
|
37
37
|
python examples/quickstart.py --workspace "$HOME/wc-first-run"
|
|
38
38
|
```
|
|
39
39
|
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
# Explicit build resources
|
|
2
|
+
|
|
3
|
+
Controller 1.33.0 advertises `registered_build_resources_version=1` with CLI 61
|
|
4
|
+
and storage 5. This adds an owner attestation for existing outputs in a frozen
|
|
5
|
+
Node project. It does not execute a build, prove reproducibility by rebuilding,
|
|
6
|
+
or authorize research evidence deletion. The recorded owner must first confirm
|
|
7
|
+
that the exact outputs contain only rebuildable material and no unique evidence.
|
|
8
|
+
|
|
9
|
+
The initial contract accepts immediate `.astro`, `.generated`, `dist` and
|
|
10
|
+
`node_modules` children of an explicit project. Names alone grant no permission:
|
|
11
|
+
registration requires the original owner, exact HEAD and record CAS, a committed
|
|
12
|
+
`package.json` with the named nonempty script, matching `package-lock.json`,
|
|
13
|
+
Git-ignored and untracked outputs, real directory ancestors and idle runtime.
|
|
14
|
+
Project paths under `research`, `experiments` or `evidence` are refused.
|
|
15
|
+
Other build systems, absent outputs and other paths require the existing exact
|
|
16
|
+
preservation flow. A recipe is recorded, never executed by Controller.
|
|
17
|
+
|
|
18
|
+
Registration is allowed for `HANDOFF_READY` feature/audit/hotfix and eligible
|
|
19
|
+
`RETAINED` sources after writers end. It is not allowed for an integration
|
|
20
|
+
candidate, including aborted/published candidates: their exact preservation
|
|
21
|
+
requirements remain unchanged. Registered root `.venv` must first finish its
|
|
22
|
+
existing supported cleanup. Bindings, pending transactions, stale owner/CAS,
|
|
23
|
+
head drift, missing retained refs and runtime references remain blockers.
|
|
24
|
+
|
|
25
|
+
## One checkout, then a batch owned by the maintenance task
|
|
26
|
+
|
|
27
|
+
Read current status and capabilities. Substitute the observed values; no example
|
|
28
|
+
CAS or HEAD is authority for another checkout. First review the registration plan:
|
|
29
|
+
|
|
30
|
+
```sh
|
|
31
|
+
worktree-controller build-resource-register --repo "$repo" --path "$checkout" \
|
|
32
|
+
--owner "$owner" --expected-head "$head" --expected-record-version "$cas" \
|
|
33
|
+
--project apps/qp_docs --recipe build --attest-rebuildable \
|
|
34
|
+
--resource-path apps/qp_docs/.astro --resource-path apps/qp_docs/.generated \
|
|
35
|
+
--resource-path apps/qp_docs/dist --resource-path apps/qp_docs/node_modules \
|
|
36
|
+
--dry-run --json
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
List only the existing, reviewed outputs. Apply the exact same request, replacing
|
|
40
|
+
`--dry-run` with `--expected-plan-id <returned-plan-id>`. Registration is one
|
|
41
|
+
append-only allocation-history event and increments CAS once. It preserves the
|
|
42
|
+
frozen source and Finalizer identity; it invalidates an old release intent rather
|
|
43
|
+
than silently carrying old release authority forward. It does not remove files.
|
|
44
|
+
|
|
45
|
+
Use the returned CAS for the normal typed plan and reviewed apply:
|
|
46
|
+
|
|
47
|
+
```sh
|
|
48
|
+
worktree-controller resource-clean --repo "$repo" --path "$checkout" \
|
|
49
|
+
--owner "$owner" --expected-record-version "$new_cas" --typed --dry-run --json
|
|
50
|
+
worktree-controller resource-clean --repo "$repo" --path "$checkout" \
|
|
51
|
+
--owner "$owner" --expected-record-version "$new_cas" --typed \
|
|
52
|
+
--expected-plan-id "$cleanup_plan_id" --json
|
|
53
|
+
worktree-controller release --repo "$repo" --path "$checkout" \
|
|
54
|
+
--owner-release "$owner" --expected-record-version "$new_cas" --dry-run --json
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Inspect the complete `cleanup_paths` list: typed cleanup can also include existing
|
|
58
|
+
recognized resources. Unknown ignored paths block the transaction. Only a clean
|
|
59
|
+
plan is executable. Verify `TYPED_DISPOSABLE_CLEANED` and the formal receipt before
|
|
60
|
+
the separate guarded release. Release keeps the retained branch and is not an
|
|
61
|
+
integration or publication receipt. The QP maintenance owner performs the live
|
|
62
|
+
single-checkout canary and decides whether to proceed with its exact batch.
|
|
63
|
+
|
|
64
|
+
## Integrity and recovery
|
|
65
|
+
|
|
66
|
+
Cleanup rechecks the registered input identities, all resource content and the
|
|
67
|
+
hardlink topology at existing action boundaries. It uses pinned directory FDs,
|
|
68
|
+
before/after action evidence, exact external-survivor checks and the existing
|
|
69
|
+
transaction journal. Registration does not permit direct `rm`, `git clean`, or
|
|
70
|
+
the legacy `resource-clean --resource-path` remover. Changed root inodes, changed
|
|
71
|
+
HEAD/record, replaced inputs, escaping symlinks and concurrent drift fail closed.
|
|
72
|
+
One registration covers the allocation's complete reviewed output set. Later
|
|
73
|
+
record changes invalidate it; do not append another registration to refresh stale
|
|
74
|
+
authority. Preserve failed transaction evidence and use the existing advertised
|
|
75
|
+
recovery flow; unsupported partial states remain blocked.
|
|
76
|
+
|
|
77
|
+
The performance benefit is eliminating separate preservation plan/copy/verify
|
|
78
|
+
cycles for every explicitly rebuildable output. The shared-lock typed cleanup
|
|
79
|
+
still scans and hashes resources and can remain expensive for large trees. No
|
|
80
|
+
cross-call verdict cache or validation exemption is introduced. Older runtimes
|
|
81
|
+
can read the history event but cannot classify these outputs; they continue to
|
|
82
|
+
refuse unknown ignored content. Do not alternate runtimes during cleanup.
|
|
83
|
+
|
|
84
|
+
## Retention preview
|
|
85
|
+
|
|
86
|
+
`retention_release_preflight_version=1` changes the preview meaning:
|
|
87
|
+
`WOULD_RELEASE` requires the exact release dry-run to succeed at observation time.
|
|
88
|
+
Its decision is attached as `release_preflight`. `CLOSEOUT_REQUIRED` means a park,
|
|
89
|
+
archive or other closeout must occur before release eligibility can be evaluated;
|
|
90
|
+
it is not counted in `would_release`. Neither preview is a reservation: execution
|
|
91
|
+
rechecks all guards, and concurrent changes can still block release.
|
|
@@ -224,6 +224,17 @@ Require `aborted_integration_preserved_cleanup_version` 1 from `capabilities --j
|
|
|
224
224
|
Use the same version's Python for the public `worktree_controller.preservation` module.
|
|
225
225
|
No consumer computes Controller digests or opens its private ledger.
|
|
226
226
|
|
|
227
|
+
Capability 2 also verifies registered environment transitions after the abort. The
|
|
228
|
+
original abort receipt remains immutable. New resource events identify their exact
|
|
229
|
+
resource; historical events are accepted only when the allocation's unique `.venv`
|
|
230
|
+
registration and optional cleanup form an unambiguous ordered chain with unchanged
|
|
231
|
+
owner and lifecycle. A cleaned environment must still be absent (including dangling
|
|
232
|
+
symlinks); a registered environment must retain its Python marker and local identity.
|
|
233
|
+
Other events, ambiguous resources, changed proofs or reconstructed environments block.
|
|
234
|
+
This verifies the current producer history; it does not invent a historical resource
|
|
235
|
+
receipt or attest unrecorded bytes. Re-run preservation at the current record CAS;
|
|
236
|
+
normal guarded release, not environment cleanup, settles the admission reservation.
|
|
237
|
+
|
|
227
238
|
1. Read `status`, `integration-queue`, `admission-queue` and `doctor`. Identify the exact owner,
|
|
228
239
|
allocation, branch, HEAD, record version and failed intent. Retain the candidate's branch and
|
|
229
240
|
original source/failure evidence. A clean checkout or expired lease grants no removal authority.
|
|
@@ -430,3 +441,8 @@ For each external consumer, distinguish three outcomes:
|
|
|
430
441
|
|
|
431
442
|
Record an unobserved client invocation as unobserved. A copied hook, passing doctor or successful
|
|
432
443
|
direct probe does not establish that a running client has reloaded its discovery metadata.
|
|
444
|
+
# Explicit build-output closeout
|
|
445
|
+
|
|
446
|
+
See [build-resource registration and cleanup](build-resources.md) for the
|
|
447
|
+
owner-attested frozen Node output contract, limits, single-checkout canary and
|
|
448
|
+
retention preview semantics introduced in 1.33.0.
|
|
@@ -118,6 +118,11 @@ Every removed tree needs immutable preservation coverage; quarantine, request id
|
|
|
118
118
|
leases, runtime, ownership and release guards remain mandatory. Only formal checkout release
|
|
119
119
|
settles its admission reservation. See the [operational flow](operations.md#aborted-integration-with-preserved-build-output).
|
|
120
120
|
|
|
121
|
+
Capability 2 additionally validates post-abort registered `.venv` resource lineage,
|
|
122
|
+
including the unambiguous legacy single-resource history. New resource events bind
|
|
123
|
+
the exact resource payload. No other post-abort lifecycle transition is accepted,
|
|
124
|
+
and no historical abort receipt or failure event is rewritten.
|
|
125
|
+
|
|
121
126
|
The supported runtime is Python 3.12 on Linux with Git and readable procfs. Writer identity,
|
|
122
127
|
runtime evidence and repository locking depend on Linux process interfaces and POSIX flock;
|
|
123
128
|
other operating systems are not supported by this release.
|
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
"""Owner-attested, frozen Node project outputs; cleanup remains the typed executor."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import hashlib
|
|
6
|
+
import json
|
|
7
|
+
from dataclasses import replace
|
|
8
|
+
from pathlib import Path
|
|
9
|
+
from typing import Any
|
|
10
|
+
|
|
11
|
+
from .disposable import path_identity, project_identity, project_json
|
|
12
|
+
from .git_backend import head_paths, inventory, path_is_ignored, tracked_paths
|
|
13
|
+
from .models import ControllerError, MetadataRecord, WorktreeGitState
|
|
14
|
+
from .preservation import source_relative_path
|
|
15
|
+
from .record_updates import updated_record
|
|
16
|
+
from .semantics import assert_record_version, managed_record
|
|
17
|
+
from .store import MetadataStore
|
|
18
|
+
|
|
19
|
+
CONTRACT = "registered-build-resources/v1"
|
|
20
|
+
EVENT = "BUILD_RESOURCES_REGISTERED"
|
|
21
|
+
OUTPUTS = {".astro", ".generated", "dist", "node_modules"}
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def _fail(message: str) -> ControllerError:
|
|
25
|
+
return ControllerError("BUILD_RESOURCE_INVALID", message)
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def project_inputs(root: Path, project: str, recipe: str) -> dict[str, str]:
|
|
29
|
+
"""Pin committed build recipes and dependency inputs without running any command."""
|
|
30
|
+
source_relative_path(project)
|
|
31
|
+
if any(part in {"research", "evidence", "experiments"} for part in Path(project).parts):
|
|
32
|
+
raise _fail("research evidence is outside the build-resource contract")
|
|
33
|
+
names = [f"{project}/package.json", f"{project}/package-lock.json"]
|
|
34
|
+
values = {name: project_identity(root, name) for name in names}
|
|
35
|
+
package = project_json(values[names[0]])
|
|
36
|
+
lock = project_json(values[names[1]])
|
|
37
|
+
scripts = package.get("scripts")
|
|
38
|
+
if not isinstance(scripts, dict) or not isinstance(scripts.get(recipe), str) or not scripts[recipe].strip():
|
|
39
|
+
raise _fail("recipe must name a nonempty committed package.json script")
|
|
40
|
+
if not package.get("name") or lock.get("name") != package["name"]:
|
|
41
|
+
raise _fail("package and dependency lock identities differ")
|
|
42
|
+
return {name: hashlib.sha256(value).hexdigest() for name, value in values.items()}
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def declarations(item: WorktreeGitState, record: MetadataRecord) -> dict[str, dict[str, Any]]:
|
|
46
|
+
rows = [row["build_resources"] for row in record.history if row.get("event") == EVENT]
|
|
47
|
+
if not rows:
|
|
48
|
+
return {}
|
|
49
|
+
if len(rows) != 1:
|
|
50
|
+
raise _fail("ambiguous build registration history")
|
|
51
|
+
proof = rows[0]
|
|
52
|
+
if (proof["head"] != item.head or proof["owner"] != record.owner
|
|
53
|
+
or proof["allocation_id"] != record.allocation_id
|
|
54
|
+
or proof["record_version"] != record.record_version
|
|
55
|
+
or proof["contract"] != CONTRACT
|
|
56
|
+
or proof["inputs"] != project_inputs(item.path, proof["project"], proof["recipe"])):
|
|
57
|
+
raise _fail("build registration identity or committed inputs changed")
|
|
58
|
+
return {path: {"registration": proof, "path": path} for path in proof["paths"]}
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def check_resource(root: Path, relative: str, declaration: dict[str, Any]) -> None:
|
|
62
|
+
proof = declaration["registration"]
|
|
63
|
+
if (proof["contract"] != CONTRACT or declaration["path"] != relative
|
|
64
|
+
or relative not in proof["paths"]
|
|
65
|
+
or Path(relative).parent.as_posix() != proof["project"]
|
|
66
|
+
or Path(relative).name not in OUTPUTS):
|
|
67
|
+
raise _fail("resource is outside the registered exact project outputs")
|
|
68
|
+
if proof["inputs"] != project_inputs(root, proof["project"], proof["recipe"]):
|
|
69
|
+
raise _fail("registered build inputs changed")
|
|
70
|
+
for name, expected in proof["anchors"].items():
|
|
71
|
+
# A completed action can remove another registered output; retain all ancestors.
|
|
72
|
+
if name in proof["paths"] and name != relative:
|
|
73
|
+
continue
|
|
74
|
+
path = root if name == "." else root / name
|
|
75
|
+
if path.is_symlink() or path_identity(path) != expected:
|
|
76
|
+
raise _fail("registered resource or ancestor identity changed")
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def register(
|
|
80
|
+
repository_path: Path, *, target: Path, owner: str, expected_record_version: int,
|
|
81
|
+
expected_head: str, project: str, recipe: str, paths: tuple[str, ...],
|
|
82
|
+
attest_rebuildable: bool, dry_run: bool = True, expected_plan_id: str | None = None,
|
|
83
|
+
) -> dict[str, Any]:
|
|
84
|
+
from . import lifecycle as life
|
|
85
|
+
from .controller import envelope
|
|
86
|
+
|
|
87
|
+
if not attest_rebuildable or not paths or len(set(paths)) != len(paths):
|
|
88
|
+
raise _fail("explicit owner rebuildability attestation and unique outputs are required")
|
|
89
|
+
repo = inventory(repository_path)
|
|
90
|
+
store = MetadataStore(repo.common_dir)
|
|
91
|
+
with store.lock(exclusive=not dry_run):
|
|
92
|
+
repo = inventory(repository_path)
|
|
93
|
+
snapshot = store._load_unlocked()
|
|
94
|
+
item, record = managed_record(repo, snapshot, target)
|
|
95
|
+
assert_record_version(record, expected_record_version)
|
|
96
|
+
if owner != record.owner:
|
|
97
|
+
raise ControllerError("OWNER_MISMATCH", "build registration requires the recorded owner")
|
|
98
|
+
if expected_head != item.head:
|
|
99
|
+
raise ControllerError("HEAD_MISMATCH", "build registration HEAD changed")
|
|
100
|
+
if record.role not in {"feature", "audit", "hotfix"} or record.lifecycle not in {"RETAINED", "HANDOFF_READY"}:
|
|
101
|
+
raise ControllerError("INVALID_LIFECYCLE", "build registration requires an idle retained or frozen source")
|
|
102
|
+
if any(row.get("event") == EVENT for row in record.history):
|
|
103
|
+
raise _fail("allocation already has its exact build registration")
|
|
104
|
+
life._validate_release_core(
|
|
105
|
+
repo, snapshot, item, record, store=store, owner_release=owner,
|
|
106
|
+
strict_identity=True, allow_registered_venv=False,
|
|
107
|
+
allow_retained_cleanup=record.lifecycle == "RETAINED",
|
|
108
|
+
)
|
|
109
|
+
if record.allocation_id in snapshot.writer_leases:
|
|
110
|
+
raise ControllerError("WRITER_LEASE_PRESENT", "end the writer before build registration")
|
|
111
|
+
if snapshot.publication_lease and snapshot.publication_lease.allocation_id == record.allocation_id:
|
|
112
|
+
raise ControllerError("PUBLICATION_LEASE_PRESENT", "publication lease blocks registration")
|
|
113
|
+
if not item.branch or life.resolve_commit(repo.canonical_path, f"refs/heads/{item.branch}") != item.head:
|
|
114
|
+
raise ControllerError("MISSING_RETAINED_REF", "registration requires an exact retained branch")
|
|
115
|
+
if life._release_transaction(store, target_path=str(item.path), allocation_id=record.allocation_id):
|
|
116
|
+
raise ControllerError("TRANSACTION_PENDING", "finish existing cleanup before registration")
|
|
117
|
+
life._validate_runtime_clear(item, strict=True)
|
|
118
|
+
blockers = life._typed_runtime_blockers(life._typed_runtime_evidence(item, record, snapshot))
|
|
119
|
+
if blockers:
|
|
120
|
+
raise ControllerError(blockers[0]["code"], blockers[0]["message"])
|
|
121
|
+
inputs = project_inputs(item.path, project, recipe)
|
|
122
|
+
anchors = {".": path_identity(item.path)}
|
|
123
|
+
for relative in paths:
|
|
124
|
+
source_relative_path(relative)
|
|
125
|
+
if Path(relative).parent.as_posix() != project or Path(relative).name not in OUTPUTS:
|
|
126
|
+
raise _fail("only explicitly attested immediate Node project outputs are supported")
|
|
127
|
+
absolute = item.path / relative
|
|
128
|
+
if tracked_paths(item.path, relative) or head_paths(item.path, relative):
|
|
129
|
+
raise ControllerError("TRACKED_RESOURCE", "build output contains tracked content")
|
|
130
|
+
if not path_is_ignored(item.path, relative) or not absolute.is_dir():
|
|
131
|
+
raise _fail("registered output must exist and be Git-ignored")
|
|
132
|
+
for path in (absolute, *absolute.parents):
|
|
133
|
+
if path == item.path:
|
|
134
|
+
break
|
|
135
|
+
if path.is_symlink() or path.is_mount():
|
|
136
|
+
raise _fail("build output ancestors must be local real directories")
|
|
137
|
+
anchors[path.relative_to(item.path).as_posix()] = path_identity(path)
|
|
138
|
+
proof = {"contract": CONTRACT, "allocation_id": record.allocation_id, "owner": owner,
|
|
139
|
+
"head": item.head, "record_version": record.record_version + 1,
|
|
140
|
+
"project": project, "recipe": recipe, "paths": sorted(paths),
|
|
141
|
+
"inputs": inputs, "anchors": anchors, "attestation": "owner-rebuildable-no-evidence"}
|
|
142
|
+
plan_id = hashlib.sha256((json.dumps(proof, sort_keys=True, ensure_ascii=True,
|
|
143
|
+
separators=(",", ":")) + "\n").encode()).hexdigest()
|
|
144
|
+
if not dry_run:
|
|
145
|
+
if expected_plan_id != plan_id:
|
|
146
|
+
raise ControllerError("RESOURCE_PLAN_MISMATCH", "build registration plan changed")
|
|
147
|
+
updated = updated_record(record, EVENT)
|
|
148
|
+
updated = replace(updated, history=(*record.history, {**updated.history[-1], "build_resources": proof}))
|
|
149
|
+
life._cancel_release_intents(store, snapshot, record.allocation_id,
|
|
150
|
+
event=EVENT, blocker="RESOURCE_IDENTITY_CHANGED")
|
|
151
|
+
store.replace_record(updated)
|
|
152
|
+
result = envelope("build-resource-register")
|
|
153
|
+
result["decision"] = {"code": "BUILD_RESOURCE_PLAN" if dry_run else EVENT,
|
|
154
|
+
"plan_id": plan_id, "registration": proof,
|
|
155
|
+
"record_version": record.record_version if dry_run else updated.record_version}
|
|
156
|
+
return result
|
|
@@ -612,6 +612,19 @@ def build_parser() -> argparse.ArgumentParser:
|
|
|
612
612
|
externalize_parser.add_argument("--expected-recovery-record-version", type=int, required=True)
|
|
613
613
|
externalize_parser.add_argument("--owner", required=True)
|
|
614
614
|
|
|
615
|
+
build_register = commands.add_parser("build-resource-register", parents=[common],
|
|
616
|
+
help="register exact owner-attested frozen Node build outputs")
|
|
617
|
+
build_register.add_argument("--path", type=Path, required=True)
|
|
618
|
+
build_register.add_argument("--owner", required=True)
|
|
619
|
+
build_register.add_argument("--expected-record-version", type=int, required=True)
|
|
620
|
+
build_register.add_argument("--expected-head", required=True)
|
|
621
|
+
build_register.add_argument("--project", required=True)
|
|
622
|
+
build_register.add_argument("--recipe", required=True)
|
|
623
|
+
build_register.add_argument("--resource-path", action="append", required=True)
|
|
624
|
+
build_register.add_argument("--attest-rebuildable", action="store_true", required=True)
|
|
625
|
+
build_register.add_argument("--dry-run", action="store_true")
|
|
626
|
+
build_register.add_argument("--expected-plan-id")
|
|
627
|
+
|
|
615
628
|
resource_register_parser = commands.add_parser(
|
|
616
629
|
"resource-register", parents=[common], help="register a rebuildable task-local resource"
|
|
617
630
|
)
|
|
@@ -1043,11 +1056,13 @@ def _main(argv: list[str] | None) -> int:
|
|
|
1043
1056
|
"tracked_source_progress_recovery_version": 1,
|
|
1044
1057
|
"published_checkout_recovery_version": 1,
|
|
1045
1058
|
"published_handoff_resource_registration_version": 1,
|
|
1059
|
+
"registered_build_resources_version": 1,
|
|
1060
|
+
"retention_release_preflight_version": 1,
|
|
1046
1061
|
"multiple_preservation_cleanup_version": 1,
|
|
1047
1062
|
"multiple_preservation_recovery_version": 1,
|
|
1048
1063
|
"preservation_supersession_version": 1,
|
|
1049
1064
|
"retained_typed_cleanup_version": 1,
|
|
1050
|
-
"aborted_integration_preserved_cleanup_version":
|
|
1065
|
+
"aborted_integration_preserved_cleanup_version": 2,
|
|
1051
1066
|
"terminal_preserved_cleanup_version": 1,
|
|
1052
1067
|
"preservation_leaf_version": 1,
|
|
1053
1068
|
"integration_publication_execution_version": 1,
|
|
@@ -1525,6 +1540,15 @@ def _main(argv: list[str] | None) -> int:
|
|
|
1525
1540
|
recovery_owner=parsed.recovery_owner,
|
|
1526
1541
|
scope_paths=tuple(parsed.scope),
|
|
1527
1542
|
)
|
|
1543
|
+
elif parsed.command == "build-resource-register":
|
|
1544
|
+
from .build_resources import register
|
|
1545
|
+
|
|
1546
|
+
payload = register(parsed.repo, target=parsed.path, owner=parsed.owner,
|
|
1547
|
+
expected_record_version=parsed.expected_record_version,
|
|
1548
|
+
expected_head=parsed.expected_head, project=parsed.project,
|
|
1549
|
+
recipe=parsed.recipe, paths=tuple(parsed.resource_path),
|
|
1550
|
+
attest_rebuildable=parsed.attest_rebuildable,
|
|
1551
|
+
dry_run=parsed.dry_run, expected_plan_id=parsed.expected_plan_id)
|
|
1528
1552
|
elif parsed.command == "resource-register":
|
|
1529
1553
|
payload = register_disposable(
|
|
1530
1554
|
parsed.repo,
|
{worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/controller.py
RENAMED
|
@@ -1243,6 +1243,7 @@ def _semantic_warnings(
|
|
|
1243
1243
|
repository: RepositoryInventory, snapshot: MetadataSnapshot, policy: WorktreePolicy
|
|
1244
1244
|
) -> list[dict[str, str]]:
|
|
1245
1245
|
warnings: list[dict[str, str]] = []
|
|
1246
|
+
verified_edges: set[tuple[Path, str, str]] = set()
|
|
1246
1247
|
items_by_allocation: dict[str, tuple[WorktreeGitState, MetadataRecord]] = {}
|
|
1247
1248
|
for item in repository.worktrees:
|
|
1248
1249
|
record = _record_for(item, snapshot)
|
|
@@ -1260,6 +1261,7 @@ def _semantic_warnings(
|
|
|
1260
1261
|
record,
|
|
1261
1262
|
item.head,
|
|
1262
1263
|
publication_ref=publication_ref(item.path, policy),
|
|
1264
|
+
verified_edges=verified_edges,
|
|
1263
1265
|
)
|
|
1264
1266
|
)
|
|
1265
1267
|
warnings.extend(issues)
|
{worktree_controller-1.32.16 → worktree_controller-1.33.0}/src/worktree_controller/convergence.py
RENAMED
|
@@ -66,12 +66,14 @@ ATTENTION = "ATTENTION_REQUIRED"
|
|
|
66
66
|
WAITING = "IDLE_BELOW_THRESHOLD"
|
|
67
67
|
BLOCKED = "BLOCKED"
|
|
68
68
|
PLANNED = "WOULD_RELEASE"
|
|
69
|
+
PREREQUISITE = "CLOSEOUT_REQUIRED"
|
|
69
70
|
RELEASED = "RELEASED"
|
|
70
71
|
SKIPPED = "OUT_OF_SCOPE"
|
|
71
72
|
|
|
72
73
|
# Summary order and wording; the reason names what actually kept checkouts on disk.
|
|
73
74
|
OUTCOME_LABELS = (
|
|
74
75
|
(PLANNED, "would be released"),
|
|
76
|
+
(PREREQUISITE, "require closeout before release can be checked"),
|
|
75
77
|
(LIVE, "in use"),
|
|
76
78
|
(ATTENTION, "need owner action"),
|
|
77
79
|
(BLOCKED, "blocked"),
|
|
@@ -722,7 +724,22 @@ def _converge(
|
|
|
722
724
|
row.update(outcome=WAITING, reason="idle time is below the current threshold")
|
|
723
725
|
continue
|
|
724
726
|
if dry_run:
|
|
725
|
-
|
|
727
|
+
if dormant or route not in {"release", "release-published-handoff", "release-retained-handoff"}:
|
|
728
|
+
row.update(outcome=PREREQUISITE, reason=f"{route} must complete before exact release preflight")
|
|
729
|
+
continue
|
|
730
|
+
try:
|
|
731
|
+
checked = release(
|
|
732
|
+
repository_path, target=Path(item.path),
|
|
733
|
+
expected_record_version=record.record_version, owner_release=record.owner,
|
|
734
|
+
teardown_reproducible_venv=any(
|
|
735
|
+
resource["state"] == "registered" for resource in record.disposable_resources
|
|
736
|
+
), dry_run=True,
|
|
737
|
+
)
|
|
738
|
+
except ControllerError as exc:
|
|
739
|
+
row.update(outcome=BLOCKED, reason=str(exc), code=exc.code)
|
|
740
|
+
continue
|
|
741
|
+
row.update(outcome=PLANNED, reason="exact guarded release preflight passed",
|
|
742
|
+
release_preflight=checked["decision"])
|
|
726
743
|
continue
|
|
727
744
|
try:
|
|
728
745
|
current = record
|