worktree-controller 1.32.15__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.
Files changed (81) hide show
  1. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/PKG-INFO +5 -5
  2. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/README.md +4 -4
  3. worktree_controller-1.33.0/docs/build-resources.md +91 -0
  4. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/docs/operations.md +16 -0
  5. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/docs/reference.md +5 -0
  6. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/pyproject.toml +1 -1
  7. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/pyproject.toml.orig +1 -1
  8. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/__init__.py +1 -1
  9. worktree_controller-1.33.0/src/worktree_controller/build_resources.py +156 -0
  10. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/cli.py +25 -1
  11. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/controller.py +2 -0
  12. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/convergence.py +18 -1
  13. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/disposable.py +49 -30
  14. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/git_backend.py +13 -3
  15. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/integration_cleanup.py +75 -1
  16. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/lifecycle.py +8 -3
  17. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/record_updates.py +10 -0
  18. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/semantics.py +10 -4
  19. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/tool_cli_contract.json +11 -2
  20. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/tool_cli_contract.json +11 -2
  21. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/LICENSE +0 -0
  22. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/docs/architecture.md +0 -0
  23. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/docs/client-integration.md +0 -0
  24. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/docs/daily-workflow.md +0 -0
  25. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/docs/first-change.md +0 -0
  26. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/docs/getting-started.md +0 -0
  27. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/docs/integration-boundaries.md +0 -0
  28. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/docs/publishing.md +0 -0
  29. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/docs/roadmap.md +0 -0
  30. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/docs/scope.md +0 -0
  31. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/examples/change_task.py +0 -0
  32. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/examples/client_continuation.py +0 -0
  33. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/examples/quickstart.py +0 -0
  34. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/activation_layout.py +0 -0
  35. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/branch_retirement.py +0 -0
  36. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/canonical_refresh.py +0 -0
  37. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/canonical_transition.py +0 -0
  38. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/cleanup_attempts.py +0 -0
  39. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/cleanup_evidence.py +0 -0
  40. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/cleanup_recovery.py +0 -0
  41. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/delivered_closeout.py +0 -0
  42. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/environment.py +0 -0
  43. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/frozen_recovery.py +0 -0
  44. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/governance.py +0 -0
  45. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/hardlinks.py +0 -0
  46. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/integration_conflict.py +0 -0
  47. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/integration_retry.py +0 -0
  48. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/keyed_document_scope.py +0 -0
  49. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/lifecycle_history.py +0 -0
  50. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/lifecycle_observation.py +0 -0
  51. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/metadata_codec.py +0 -0
  52. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/metadata_relocation.py +0 -0
  53. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/models.py +0 -0
  54. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/mount_diagnostics.py +0 -0
  55. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/multiple_cleanup_recovery.py +0 -0
  56. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/namespace_migration.py +0 -0
  57. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/native_session_recovery.py +0 -0
  58. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/owner_actions.py +0 -0
  59. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/policy.py +0 -0
  60. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/preservation.py +0 -0
  61. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/preserved_cleanup.py +0 -0
  62. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/publication_execution.py +0 -0
  63. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/reconciler.py +0 -0
  64. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/recovery_guidance.py +0 -0
  65. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/registration_backfill.py +0 -0
  66. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/registration_prune.py +0 -0
  67. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/release_intents.py +0 -0
  68. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/rendering.py +0 -0
  69. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/resource_admission.py +0 -0
  70. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/retirement_adapters.py +0 -0
  71. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/retirement_execution.py +0 -0
  72. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/session.py +0 -0
  73. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/session_admission.py +0 -0
  74. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/source_cleanup.py +0 -0
  75. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/source_preservation.py +0 -0
  76. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/source_recovery.py +0 -0
  77. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/store.py +0 -0
  78. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/task_workflow.py +0 -0
  79. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/transaction_scope.py +0 -0
  80. {worktree_controller-1.32.15 → worktree_controller-1.33.0}/src/worktree_controller/writer_lease.py +0 -0
  81. {worktree_controller-1.32.15 → 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.32.15
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.14 · Linux · Python 3.12 · Apache-2.0**
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.14
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.14 uses CLI contract **61** and storage layout **5**.
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.14
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.14 · Linux · Python 3.12 · Apache-2.0**
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.14
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.14 uses CLI contract **61** and storage layout **5**.
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.14
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.
@@ -4,7 +4,7 @@ build-backend = "uv_build"
4
4
 
5
5
  [project]
6
6
  name = "worktree-controller"
7
- version = "1.32.15"
7
+ version = "1.33.0"
8
8
  description = "Govern Git worktree budgets, authority, ownership, and lifecycle"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.12,<3.13"
@@ -4,7 +4,7 @@ build-backend = "uv_build"
4
4
 
5
5
  [project]
6
6
  name = "worktree-controller"
7
- version = "1.32.15"
7
+ version = "1.33.0"
8
8
  description = "Govern Git worktree budgets, authority, ownership, and lifecycle"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.12,<3.13"
@@ -1,3 +1,3 @@
1
1
  """Worktree lifecycle controller."""
2
2
 
3
- __version__ = "1.32.15"
3
+ __version__ = "1.33.0"
@@ -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": 1,
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,
@@ -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)
@@ -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
- row.update(outcome=PLANNED, reason=f"{route} then guarded release")
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