worktree-controller 1.34.0__tar.gz → 1.34.1__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 (82) hide show
  1. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/PKG-INFO +1 -1
  2. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/docs/build-resources.md +35 -0
  3. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/pyproject.toml +1 -1
  4. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/pyproject.toml.orig +1 -1
  5. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/__init__.py +1 -1
  6. worktree_controller-1.34.1/src/worktree_controller/build_preservation.py +108 -0
  7. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/cleanup_recovery.py +9 -2
  8. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/cli.py +1 -0
  9. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/lifecycle.py +14 -2
  10. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/multiple_cleanup_recovery.py +60 -16
  11. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/preserved_cleanup.py +36 -2
  12. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/tool_cli_contract.json +10 -1
  13. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/tool_cli_contract.json +10 -1
  14. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/LICENSE +0 -0
  15. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/README.md +0 -0
  16. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/docs/architecture.md +0 -0
  17. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/docs/client-integration.md +0 -0
  18. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/docs/daily-workflow.md +0 -0
  19. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/docs/first-change.md +0 -0
  20. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/docs/getting-started.md +0 -0
  21. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/docs/integration-boundaries.md +0 -0
  22. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/docs/operations.md +0 -0
  23. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/docs/publishing.md +0 -0
  24. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/docs/reference.md +0 -0
  25. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/docs/roadmap.md +0 -0
  26. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/docs/scope.md +0 -0
  27. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/examples/change_task.py +0 -0
  28. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/examples/client_continuation.py +0 -0
  29. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/examples/quickstart.py +0 -0
  30. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/activation_layout.py +0 -0
  31. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/branch_retirement.py +0 -0
  32. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/build_resources.py +0 -0
  33. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/canonical_refresh.py +0 -0
  34. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/canonical_transition.py +0 -0
  35. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/cleanup_attempts.py +0 -0
  36. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/cleanup_evidence.py +0 -0
  37. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/controller.py +0 -0
  38. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/convergence.py +0 -0
  39. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/delivered_closeout.py +0 -0
  40. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/disposable.py +0 -0
  41. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/environment.py +0 -0
  42. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/frozen_recovery.py +0 -0
  43. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/git_backend.py +0 -0
  44. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/governance.py +0 -0
  45. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/hardlinks.py +0 -0
  46. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/integration_cleanup.py +0 -0
  47. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/integration_conflict.py +0 -0
  48. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/integration_retry.py +0 -0
  49. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/keyed_document_scope.py +0 -0
  50. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/lifecycle_history.py +0 -0
  51. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/lifecycle_observation.py +0 -0
  52. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/metadata_codec.py +0 -0
  53. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/metadata_relocation.py +0 -0
  54. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/models.py +0 -0
  55. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/mount_diagnostics.py +0 -0
  56. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/namespace_migration.py +0 -0
  57. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/native_session_recovery.py +0 -0
  58. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/owner_actions.py +0 -0
  59. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/policy.py +0 -0
  60. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/preservation.py +0 -0
  61. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/publication_execution.py +0 -0
  62. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/reconciler.py +0 -0
  63. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/record_updates.py +0 -0
  64. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/recovery_guidance.py +0 -0
  65. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/registration_backfill.py +0 -0
  66. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/registration_prune.py +0 -0
  67. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/release_intents.py +0 -0
  68. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/rendering.py +0 -0
  69. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/resource_admission.py +0 -0
  70. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/retirement_adapters.py +0 -0
  71. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/retirement_execution.py +0 -0
  72. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/semantics.py +0 -0
  73. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/session.py +0 -0
  74. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/session_admission.py +0 -0
  75. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/source_cleanup.py +0 -0
  76. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/source_preservation.py +0 -0
  77. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/source_recovery.py +0 -0
  78. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/store.py +0 -0
  79. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/task_workflow.py +0 -0
  80. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/transaction_scope.py +0 -0
  81. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/src/worktree_controller/writer_lease.py +0 -0
  82. {worktree_controller-1.34.0 → worktree_controller-1.34.1}/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.34.0
3
+ Version: 1.34.1
4
4
  Summary: Govern Git worktree budgets, authority, ownership, and lifecycle
5
5
  License-Expression: Apache-2.0
6
6
  License-File: LICENSE
@@ -81,6 +81,41 @@ record changes invalidate it; do not append another registration to refresh stal
81
81
  authority. Preserve failed transaction evidence and use the existing advertised
82
82
  recovery flow; unsupported partial states remain blocked.
83
83
 
84
+ With `build_preservation_recovery_version=1`, typed cleanup verifies existing
85
+ preservation generations before deleting any registered output. The only accepted
86
+ CAS bridge is the unchanged allocation/owner/HEAD immediately before its one
87
+ `BUILD_RESOURCES_REGISTERED` event. Original source/root anchors and preserved
88
+ bytes must match. The plan freezes the verified generation hashes; each completed
89
+ action supplies its original before/after topology proof. Old receipts are never
90
+ rewritten or promoted to the new CAS.
91
+
92
+ An interrupted typed transaction with an exact completed prefix and an untouched
93
+ pending suffix uses the existing prefix recovery engine:
94
+
95
+ ```sh
96
+ worktree-controller resource-recover --repo "$repo" --stage prepare-multiple \
97
+ --path "$checkout" --owner "$owner" --expected-record-version "$new_cas" \
98
+ --transaction-id "$transaction_id" --transaction-sha256 "$journal_sha256" \
99
+ --cleanup-receipt-sha256 "$failed_receipt_sha256" --dry-run --json
100
+ ```
101
+
102
+ Review the remaining paths, then repeat with `--expected-plan-id` instead of
103
+ `--dry-run`. Use the returned `recovery_receipt.path` and `.sha256` with
104
+ `resource-recover --stage resume --recovery-receipt PATH
105
+ --recovery-receipt-sha256 SHA --dry-run --json`, then the same request without
106
+ `--dry-run`. Require `MULTIPLE_RECOVERY_CLEANED` and its completion receipt.
107
+ Recovery preserves the old journal, failed receipt and completed action proofs,
108
+ adds a verified baseline, and executes only the pending suffix. An old 1.33.1 plan
109
+ without generation bindings is accepted only after full verification against its
110
+ original registration and action topology; the new baseline is explicitly a new
111
+ observation. Started/uncertain actions, changed bytes, recreated completed paths,
112
+ unknown outputs or identity drift remain refused. A started recovery never
113
+ blindly replays; a completed one may only reconcile its exact terminal receipt.
114
+ This grants no release or batch authority. CLI 61 and storage 5 remain unchanged.
115
+ Version 1.33.1 cannot verify this combined generation/action lineage and continues
116
+ to refuse it. Recovery and subsequent release require the advertised capability;
117
+ any runtime rollback must still pass the normal transaction compatibility gate.
118
+
84
119
  The performance benefit is eliminating separate preservation plan/copy/verify
85
120
  cycles for every explicitly rebuildable output. The shared-lock typed cleanup
86
121
  still scans and hashes resources and can remain expensive for large trees. No
@@ -4,7 +4,7 @@ build-backend = "uv_build"
4
4
 
5
5
  [project]
6
6
  name = "worktree-controller"
7
- version = "1.34.0"
7
+ version = "1.34.1"
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.34.0"
7
+ version = "1.34.1"
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.34.0"
3
+ __version__ = "1.34.1"
@@ -0,0 +1,108 @@
1
+ """Bind old preservation generations to one exact build registration transition."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import os
6
+ from pathlib import Path
7
+
8
+ from . import preservation as p
9
+ from .build_resources import CONTRACT, EVENT
10
+ from .models import ControllerError
11
+
12
+
13
+ def _blocked(message):
14
+ return ControllerError("PRESERVATION_COVERAGE_INVALID", message)
15
+
16
+
17
+ def identity_matches(previous, current, record):
18
+ """Only the unchanged predecessor of the exact registration may cross CAS."""
19
+ if previous == current:
20
+ return True
21
+ version = current.get("expected_record_version")
22
+ if (record is None or type(version) is not int or version < 2
23
+ or record.record_version != version or len(record.history) != version
24
+ or previous != {**current, "expected_record_version": version - 1}):
25
+ return False
26
+ event = record.history[-1]
27
+ proof = event.get("build_resources", {})
28
+ return bool(
29
+ event.get("event") == EVENT and event.get("from") == event.get("to") == record.lifecycle
30
+ and record.lifecycle in {"HANDOFF_READY", "RETAINED"}
31
+ and event.get("owner") == record.owner == current["owner"]
32
+ and proof.get("contract") == CONTRACT and proof.get("record_version") == version
33
+ and proof.get("allocation_id") == record.allocation_id == current["allocation_id"]
34
+ and proof.get("owner") == current["owner"] and proof.get("head") == current["expected_head"]
35
+ and record.authority_key == current["authority_key"]
36
+ )
37
+
38
+
39
+ def generations(bound, record, *, topology=None, completed=(), completed_topology=None,
40
+ verify_live=True):
41
+ """Verify copies before deletion; recover absent sources only from pinned topology.
42
+
43
+ Discovery reads official generation metadata. Returned raw hashes are frozen
44
+ into the cleanup plan; they are never claimed to be historical observations.
45
+ """
46
+ from . import hardlinks
47
+ from .cleanup_evidence import read_document
48
+ from .preserved_cleanup import coverage, source_absent
49
+
50
+ events = [event for event in record.history if event.get("event") == EVENT]
51
+ if not events:
52
+ return [], []
53
+ if len(events) != 1 or events[0] != record.history[-1]:
54
+ raise _blocked("build preservation requires the exact registration record")
55
+ registration = events[0]["build_resources"]
56
+ if not identity_matches({**bound, "expected_record_version": record.record_version - 1}, bound, record):
57
+ raise _blocked("build preservation registration identity changed")
58
+ allocation = p.evidence_root() / bound["repository_id"] / bound["allocation_id"]
59
+ if not os.path.lexists(allocation):
60
+ return [], []
61
+ entries, plans = [], []
62
+ with p._absolute_directory(allocation) as chain:
63
+ for name in sorted(os.listdir(chain[-1].fd)):
64
+ with p._absolute_directory(allocation / name) as generation:
65
+ try:
66
+ os.stat("receipt.json", dir_fd=generation[-1].fd, follow_symlinks=False)
67
+ except FileNotFoundError:
68
+ continue
69
+ receipt, digest = read_document(generation[-1], "receipt.json")
70
+ if receipt.get("contract") != p.CONTRACT:
71
+ continue
72
+ source = Path(receipt["source"])
73
+ relative = p.source_relative_path(source.relative_to(bound["target_path"]).as_posix())
74
+ if relative not in registration["paths"]:
75
+ continue
76
+ previous = receipt["allocation_source_identity"]
77
+ if not identity_matches(previous, bound, record):
78
+ raise _blocked("preserved build output has no exact registration CAS lineage")
79
+ absent = relative in completed
80
+ evidence, plan = coverage(
81
+ allocation / name / "receipt.json", digest, identity=previous,
82
+ verify_source=verify_live and not absent, source_topology=topology if not absent else None,
83
+ )
84
+ anchors = registration["anchors"]
85
+ if (plan["source_anchor"]["source"] != anchors[relative]
86
+ or plan.get("source_ancestor_identities", {}).get(bound["target_path"]) != anchors["."]):
87
+ raise _blocked("preservation and registration source/root anchors differ")
88
+ if absent or not verify_live:
89
+ original = completed_topology if completed_topology is not None else topology
90
+ if original is None or (verify_live and not source_absent(plan, Path(bound["target_path"]))):
91
+ raise _blocked("absent build output needs its exact completed action proof")
92
+ hardlinks.source_baseline(plan["source_tree"], original, resource=relative)
93
+ anchor = original["anchors"][relative]
94
+ if anchor != {"worktree": anchors["."], "resource": anchors[relative]}:
95
+ raise _blocked("completed build output topology anchors changed")
96
+ leaf_identities = hardlinks.identities(original, relative)
97
+ expected_contents = {
98
+ row["path"]: {key: row[key] for key in ("content_sha256", "target") if key in row}
99
+ for row in plan["source_tree"]["manifest"]
100
+ if row["path"] in leaf_identities
101
+ }
102
+ observed = {path: group["content"] for group in original["groups"].values()
103
+ for resource, path in group["members"] if resource == relative}
104
+ if observed != expected_contents:
105
+ raise _blocked("completed build bytes differ from the preserved generation")
106
+ entries.append({"source_relative": relative, "evidence": evidence})
107
+ plans.append(plan)
108
+ return entries, plans
@@ -159,6 +159,10 @@ class RolloutTransactionError(ControllerError):
159
159
  elif command == "resource-clean" and isinstance(plan, dict):
160
160
  contract = plan.get("contract")
161
161
  entry = entries.get(contract) if isinstance(contract, str) else None
162
+ if contract == "typed-disposable-resource/v1" and any(
163
+ row.get("status") == "COMPLETED" for row in journal.get("actions", [])
164
+ ):
165
+ entry = "resource-recover --stage prepare-multiple --dry-run"
162
166
  code = cause.code if isinstance(cause, ControllerError) else "FILESYSTEM_ERROR"
163
167
  self.transaction_diagnostic = {
164
168
  "transaction_id": transaction,
@@ -400,7 +404,10 @@ def _rollout_transaction(
400
404
  "ROLLOUT_TRANSACTION_UNSUPPORTED", "unfinished transaction has no supported cleanup recovery"
401
405
  )
402
406
  contract = cleanup_plan.get("contract")
403
- if contract == "typed-disposable-resource/v1":
407
+ typed_prefix = contract == "typed-disposable-resource/v1" and any(
408
+ row.get("status") == "COMPLETED" for row in journal.get("actions", [])
409
+ )
410
+ if contract == "typed-disposable-resource/v1" and not typed_prefix:
404
411
  _, digest = e.read(path)
405
412
  current = attempts.typed_plan(repo, store, path.stem, digest)
406
413
  return {"transaction_id": path.stem, "state": "TYPED_NO_ACTION_RECOVERABLE",
@@ -417,7 +424,7 @@ def _rollout_transaction(
417
424
  "plan_id": current["plan_id"],
418
425
  "completion_receipt_sha256": completion_sha,
419
426
  }
420
- if contract == "legacy-preserved-state-multiple-cleanup/v1":
427
+ if contract == "legacy-preserved-state-multiple-cleanup/v1" or typed_prefix:
421
428
  from . import multiple_cleanup_recovery as multi_recovery
422
429
 
423
430
  _, journal_sha = e.read(path)
@@ -1057,6 +1057,7 @@ def _main(argv: list[str] | None) -> int:
1057
1057
  "published_checkout_recovery_version": 1,
1058
1058
  "published_handoff_resource_registration_version": 1,
1059
1059
  "registered_build_resources_version": 1,
1060
+ "build_preservation_recovery_version": 1,
1060
1061
  "retention_release_preflight_version": 1,
1061
1062
  "multiple_preservation_cleanup_version": 1,
1062
1063
  "multiple_preservation_recovery_version": 1,
@@ -4676,7 +4676,7 @@ def _typed_cleanup_plan_locked(
4676
4676
  from .cleanup_recovery import original
4677
4677
 
4678
4678
  old, _ = original(store, recovery, target=item.path, allocation_id=record.allocation_id)
4679
- if "preservation_evidences" in old["plan"]:
4679
+ if "preservation_evidences" in old["plan"] or old["plan"]["contract"] == TYPED_RESOURCE_CONTRACT:
4680
4680
  from . import multiple_cleanup_recovery as multi_recovery
4681
4681
 
4682
4682
  if recovery.get("contract") != multi_recovery.CONTRACT:
@@ -4698,6 +4698,7 @@ def _typed_cleanup_plan_locked(
4698
4698
  terminal_evidence = None
4699
4699
  preserved_evidence = None
4700
4700
  preserved_evidences: list[dict[str, Any]] = []
4701
+ build_preservations: list[dict[str, Any]] = []
4701
4702
  multiple = bool(additional_preservation_receipts or additional_preservation_receipt_sha256)
4702
4703
  try:
4703
4704
  completed_sources: set[str] = set()
@@ -4752,7 +4753,7 @@ def _typed_cleanup_plan_locked(
4752
4753
  additional_preservation_receipts,
4753
4754
  additional_preservation_receipt_sha256,
4754
4755
  )
4755
- if original_completed_sources:
4756
+ if original_completed_sources and "preservation_evidences" in old["plan"]:
4756
4757
  expected_inputs = {
4757
4758
  (entry["evidence"]["receipt_path"], entry["evidence"]["receipt_sha256"])
4758
4759
  for entry in old["plan"]["preservation_evidences"]
@@ -4822,6 +4823,15 @@ def _typed_cleanup_plan_locked(
4822
4823
  preserved_evidences.sort(key=lambda row: row["source_relative"])
4823
4824
  if preserved_evidences:
4824
4825
  preserved_evidence = preserved_evidences[0]["evidence"]
4826
+ from .build_preservation import generations
4827
+
4828
+ build_preservations, _ = generations(
4829
+ bound, record, topology=source_topology, completed=completed_sources,
4830
+ completed_topology=(old["plan"]["hardlink_topology"] if original_completed_sources
4831
+ else cleanup_plan["hardlink_topology"] if cleanup_transaction_id else None),
4832
+ )
4833
+ if cleanup_transaction_id and build_preservations != cleanup_plan.get("build_preservation_evidences", []):
4834
+ raise ControllerError("PRESERVATION_COVERAGE_INVALID", "build preservation baseline changed during cleanup")
4825
4835
  except (ControllerError, OSError, ValueError, TypeError, KeyError) as exc:
4826
4836
  blockers.append(
4827
4837
  {
@@ -4987,6 +4997,8 @@ def _typed_cleanup_plan_locked(
4987
4997
  identity["integration_abort_evidence"] = integration_abort_evidence
4988
4998
  if recovery is not None:
4989
4999
  identity["recovery"] = recovery
5000
+ if build_preservations:
5001
+ identity["build_preservation_evidences"] = build_preservations
4990
5002
  return {**identity, "plan_id": _release_plan_id(identity)}
4991
5003
 
4992
5004
 
@@ -23,6 +23,7 @@ from .store import MetadataStore, now_iso, record_from_dict, record_to_dict
23
23
 
24
24
  CONTRACT = "multiple-preservation-cleanup-recovery/v1"
25
25
  CLEANUP_CONTRACT = "legacy-preserved-state-multiple-cleanup/v1"
26
+ TYPED_CONTRACT = "typed-disposable-resource/v1"
26
27
  IDENTITY_KEYS = (
27
28
  "repository_id", "allocation_id", "target_path", "expected_head",
28
29
  "expected_record_version", "owner", "authority_key",
@@ -283,6 +284,35 @@ def _proofset(plan: dict[str, Any], target: Path) -> list[dict[str, Any]]:
283
284
  return preserved
284
285
 
285
286
 
287
+ def _typed_preservations(store, plan, recovery):
288
+ from .build_preservation import generations
289
+
290
+ record = record_from_dict(store._read_json(store.records_dir / f"{plan['allocation_id']}.json"))
291
+ if recovery.get("recovery_id"):
292
+ directory = _directory(store, recovery["original_transaction_id"], recovery["recovery_id"])
293
+ frozen, _ = e.read(directory / "record.json", recovery["recovery_record_sha256"])
294
+ record = _frozen_authority(frozen)
295
+ rows = [row for row in plan["resources"] if row["path"] in plan["cleanup_paths"]]
296
+ registration = record.history[-1].get("build_resources")
297
+ if (not registration or plan.get("preservation_evidence") is not None
298
+ or "preservation_evidences" in plan
299
+ or any(row.get("cleanup_action") != "none" or row.get("blocker") is not None
300
+ or row.get("classification") != "existing-release-policy"
301
+ for row in plan["resources"] if row["path"] not in plan["cleanup_paths"])
302
+ or any(row.get("resource_type") != "registered-build-output"
303
+ or row.get("classification") != "disposable"
304
+ or row.get("cleanup_action") != "remove-tree"
305
+ or row.get("evidence", {}).get("build_declaration") != {
306
+ "registration": registration, "path": row["path"]} for row in rows)):
307
+ raise _blocked("typed prefix recovery requires exact registered build outputs")
308
+ entries, preserved = generations(_identity(plan), record, topology=plan["hardlink_topology"],
309
+ verify_live=False)
310
+ if not preserved or ("build_preservation_evidences" in plan
311
+ and entries != plan["build_preservation_evidences"]):
312
+ raise _blocked("typed recovery requires verified original build preservation lineage")
313
+ return preserved
314
+
315
+
286
316
  def details(
287
317
  store: MetadataStore, recovery: dict[str, Any],
288
318
  ) -> tuple[dict[str, Any], list[dict[str, Any]], set[str], dict[str, Any]]:
@@ -320,7 +350,8 @@ def details(
320
350
  row["path"] for row in rows if row["cleanup_action"] == "remove-preserved-tree"
321
351
  ]
322
352
  if (receipt.get("receipt_id") != transaction or receipt.get("result") != "FAILED_OR_PARTIAL"
323
- or receipt.get("contract") != CLEANUP_CONTRACT or plan.get("contract") != CLEANUP_CONTRACT
353
+ or plan.get("contract") not in {CLEANUP_CONTRACT, TYPED_CONTRACT}
354
+ or receipt.get("contract") != plan.get("contract")
324
355
  or not _plan_hash(plan) or plan.get("blockers") != [] or not target.is_absolute()
325
356
  or not paths or paths != planned_paths or len(set(paths)) != len(paths)
326
357
  or not prefix or len(prefix) >= len(paths) or prefix != paths[:len(prefix)]
@@ -343,6 +374,14 @@ def details(
343
374
  _action_files(store, transaction, len(prefix))
344
375
  if done != set(prefix):
345
376
  raise _blocked("pending actions have evidence or original action files are incomplete")
377
+ if plan["contract"] == TYPED_CONTRACT:
378
+ preserved = _typed_preservations(store, plan, recovery)
379
+ root = _common_root(store, preserved, target, transaction)
380
+ if any(anchor["worktree"] != root for anchor in plan["hardlink_topology"]["anchors"].values()):
381
+ raise _blocked("original typed graph belongs to another checkout root")
382
+ if any(os.path.lexists(target / name) for name in done):
383
+ raise _blocked("completed typed output reappeared")
384
+ return receipt, preserved, done, topology
346
385
  preserved = _proofset(plan, target)
347
386
  preserved_rows = {row["path"]: row for row in rows if row["cleanup_action"] == "remove-preserved-tree"}
348
387
  if set(preserved_rows) != {row["source_relative"] for row in plan["preservation_evidences"]}:
@@ -401,6 +440,8 @@ def _guard(store: MetadataStore, recovery: dict[str, Any], *, allow_successor: b
401
440
 
402
441
 
403
442
  def _inputs(plan: dict[str, Any]) -> dict[str, Any]:
443
+ if plan["contract"] == TYPED_CONTRACT:
444
+ return {}
404
445
  proofs = plan["preservation_evidences"]
405
446
  return {
406
447
  "preservation_receipt": Path(proofs[0]["evidence"]["receipt_path"]),
@@ -427,8 +468,8 @@ def _plan_locked(repo: Path, store: MetadataStore, target: Path, owner: str, ver
427
468
  old_rows = {row["path"]: row for row in expected["resources"]}
428
469
  if (current["blockers"] or _identity(current) != _identity(expected)
429
470
  or item.branch != store._read_json(store.transactions_dir / f"{recovery['original_transaction_id']}.json")["branch"]
430
- or current.get("contract") != CLEANUP_CONTRACT or current["cleanup_paths"] != suffix
431
- or current.get("preservation_evidences") != expected["preservation_evidences"]
471
+ or current.get("contract") != expected["contract"] or current["cleanup_paths"] != suffix
472
+ or current.get("preservation_evidences") != expected.get("preservation_evidences")
432
473
  or current["hardlink_topology"] != topology
433
474
  or any(row != old_rows.get(row["path"]) for row in current["resources"] if row["path"] in suffix)):
434
475
  raise _blocked("current resource, topology, identity or runtime guards differ from the proven suffix")
@@ -470,7 +511,7 @@ def prepare(repo: Path, *, target: Path, owner: str, version: int, recovery: dic
470
511
  "contract": CONTRACT, "result": "MULTIPLE_CLEANUP_RECOVERABLE",
471
512
  "recovery_id": recovery_id, "plan": current,
472
513
  "original_plan_id": old["plan"]["plan_id"],
473
- "original_preservation_evidences": old["plan"]["preservation_evidences"],
514
+ "original_preservation_evidences": old["plan"].get("preservation_evidences"),
474
515
  "completed_resources": old["plan"]["cleanup_paths"][:len(done)],
475
516
  "remaining_resources": current["cleanup_paths"],
476
517
  "prefix_topology_sha256": topology["sha256"],
@@ -501,7 +542,9 @@ def _load_record(store: MetadataStore, recovery_path: Path,
501
542
  _frozen_authority(record)
502
543
  recovery = record["plan"]["recovery"]
503
544
  directory = _directory(store, recovery["original_transaction_id"], record["recovery_id"])
504
- old, _, done, topology = details(store, recovery)
545
+ old, _, done, topology = details(store, {
546
+ **recovery, "recovery_id": record["recovery_id"], "recovery_record_sha256": recovery_sha,
547
+ })
505
548
  baseline = record["plan"]
506
549
  suffix = old["plan"]["cleanup_paths"][len(done):]
507
550
  old_rows = {row["path"]: row for row in old["plan"]["resources"]}
@@ -510,15 +553,15 @@ def _load_record(store: MetadataStore, recovery_path: Path,
510
553
  or record.get("old_transaction_remains_immutable") is not True
511
554
  or record.get("completed_action_will_replay") is not False
512
555
  or record.get("original_plan_id") != old["plan"]["plan_id"]
513
- or record.get("original_preservation_evidences") != old["plan"]["preservation_evidences"]
556
+ or record.get("original_preservation_evidences") != old["plan"].get("preservation_evidences")
514
557
  or record.get("completed_resources") != old["plan"]["cleanup_paths"][:len(done)]
515
558
  or record.get("remaining_resources") != old["plan"]["cleanup_paths"][len(done):]
516
559
  or record.get("prefix_topology_sha256") != topology["sha256"]
517
- or not _plan_hash(baseline) or baseline.get("contract") != CLEANUP_CONTRACT
560
+ or not _plan_hash(baseline) or baseline.get("contract") != old["plan"]["contract"]
518
561
  or _identity(baseline) != _identity(old["plan"])
519
562
  or baseline.get("cleanup_paths") != suffix or baseline.get("hardlink_topology") != topology
520
- or baseline.get("preservation_evidences") != old["plan"]["preservation_evidences"]
521
- or baseline.get("preservation_evidence") != old["plan"]["preservation_evidence"]
563
+ or baseline.get("preservation_evidences") != old["plan"].get("preservation_evidences")
564
+ or baseline.get("preservation_evidence") != old["plan"].get("preservation_evidence")
522
565
  or baseline.get("blockers") != []
523
566
  or any(row != old_rows.get(row["path"]) for row in baseline["resources"] if row["path"] in suffix)):
524
567
  raise _blocked("invalid immutable multiple recovery record")
@@ -549,21 +592,22 @@ def _recovered_receipt(store: MetadataStore, receipt: dict[str, Any],
549
592
  old, preserved, done, topology = details(store, expected_recovery)
550
593
  suffix = old["plan"]["cleanup_paths"][len(done):]
551
594
  post = receipt["post_scan"]
552
- if (receipt.get("contract") != CLEANUP_CONTRACT or receipt.get("result") != "CLEANED"
553
- or successor.get("contract") != CLEANUP_CONTRACT or executing != expected_recovery
595
+ if (receipt.get("contract") != old["plan"]["contract"] or receipt.get("result") != "CLEANED"
596
+ or successor.get("contract") != old["plan"]["contract"] or executing != expected_recovery
554
597
  or _identity(successor) != _identity(old["plan"])
555
598
  or (bound is not None and _identity(successor) != bound)
556
599
  or successor.get("blockers") != [] or not _plan_hash(successor)
557
- or successor.get("preservation_evidences") != old["plan"]["preservation_evidences"]
558
- or successor.get("preservation_evidence") != old["plan"]["preservation_evidence"]
600
+ or successor.get("preservation_evidences") != old["plan"].get("preservation_evidences")
601
+ or successor.get("preservation_evidence") != old["plan"].get("preservation_evidence")
559
602
  or successor.get("hardlink_topology") != topology or successor.get("cleanup_paths") != suffix
560
603
  or receipt.get("actions") != [{"path": name, "status": "COMPLETED"} for name in suffix]
561
604
  or len(receipt.get("action_evidence", [])) != len(suffix)
562
605
  or any(successor.get(key) != value for key, value in baseline.items() if key not in {"plan_id", "recovery", "runtime_evidence", "warnings"})
563
- or post.get("contract") != CLEANUP_CONTRACT or post.get("recovery") != expected_recovery
606
+ or post.get("contract") != old["plan"]["contract"] or post.get("recovery") != expected_recovery
564
607
  or _identity(post) != _identity(successor) or not _plan_hash(post)
565
- or post.get("preservation_evidences") != old["plan"]["preservation_evidences"]
566
- or post.get("preservation_evidence") != old["plan"]["preservation_evidence"]
608
+ or post.get("preservation_evidences") != old["plan"].get("preservation_evidences")
609
+ or post.get("preservation_evidence") != old["plan"].get("preservation_evidence")
610
+ or post.get("build_preservation_evidences") != baseline.get("build_preservation_evidences")
567
611
  or post.get("blockers") != [] or post.get("cleanup_paths") != []):
568
612
  raise _blocked("successful suffix completion differs from its immutable recovery baseline")
569
613
  completed, final = completed_actions(store, receipt["receipt_id"], tuple(receipt["action_evidence"]),
@@ -408,6 +408,7 @@ def _require_completion_coverage(
408
408
  Inspect only this allocation's official generation metadata. Unreferenced
409
409
  generation payloads are not opened, and source absence grants no authority.
410
410
  """
411
+ from .build_preservation import identity_matches
411
412
  from .source_preservation import CONTRACT as SOURCE_CONTRACT
412
413
 
413
414
  allocation = p.evidence_root() / bound["repository_id"] / bound["allocation_id"]
@@ -416,6 +417,7 @@ def _require_completion_coverage(
416
417
  if any(
417
418
  plan["authority"]["identity"] != bound
418
419
  and not _resumed_cleanup_identity(plan["authority"]["identity"], bound, record)
420
+ and not identity_matches(plan["authority"]["identity"], bound, record)
419
421
  for plan in plans
420
422
  ):
421
423
  raise _blocked("completed preservation belongs to another exact allocation identity")
@@ -505,6 +507,7 @@ def _require_completion_coverage(
505
507
 
506
508
  def _pending_preservation_plans(
507
509
  store, item, bound: dict[str, Any], transaction: str, cleanup_recovery: dict[str, Any] | None,
510
+ record: MetadataRecord,
508
511
  ) -> list[dict[str, Any]]:
509
512
  from . import cleanup_evidence as e
510
513
  from .lifecycle import _release_plan_id
@@ -535,7 +538,7 @@ def _pending_preservation_plans(
535
538
  "resource": relative, "before": after["before"],
536
539
  "after": {"path": str(path), "sha256": digest},
537
540
  })
538
- done, _ = completed_actions(
541
+ done, preceding = completed_actions(
539
542
  store, transaction, tuple(proofs), initial_topology=plan["hardlink_topology"], cleanup_paths=plan["cleanup_paths"],
540
543
  )
541
544
  evidence_set = plan.get("preservation_evidences")
@@ -558,6 +561,22 @@ def _pending_preservation_plans(
558
561
  completed_plans.append(preserved)
559
562
  if preserved_plans:
560
563
  common_source_root(preserved_plans, item.path)
564
+ if plan.get("build_preservation_evidences"):
565
+ from .build_preservation import generations
566
+
567
+ original_topology = plan["hardlink_topology"]
568
+ if cleanup_recovery is not None:
569
+ from .multiple_cleanup_recovery import details
570
+
571
+ old, _, prefix, _ = details(store, cleanup_recovery)
572
+ done.update(prefix)
573
+ original_topology = old["plan"]["hardlink_topology"]
574
+ entries, plans = generations(bound, record, topology=preceding, completed=done,
575
+ completed_topology=original_topology)
576
+ if entries != plan["build_preservation_evidences"]:
577
+ raise _blocked("in-progress build preservation baseline changed")
578
+ completed_plans.extend(preserved for preserved in plans
579
+ if Path(preserved["source"]).relative_to(item.path).as_posix() in done)
561
580
  return completed_plans
562
581
 
563
582
 
@@ -576,6 +595,7 @@ def cleanup_receipts(
576
595
  """
577
596
  from . import cleanup_evidence as e
578
597
  from . import hardlinks
598
+ from .build_preservation import identity_matches
579
599
  from .lifecycle import (
580
600
  MULTIPLE_PRESERVED_CLEANUP_CONTRACT,
581
601
  TYPED_RESOURCE_CONTRACT,
@@ -601,7 +621,9 @@ def cleanup_receipts(
601
621
  )
602
622
  if (
603
623
  any(recovered_receipt["plan"].get(key) != value for key, value in bound.items())
604
- or recovered_plan["authority"]["identity"] != bound
624
+ or (recovered_plan["authority"]["identity"] != bound
625
+ and not identity_matches(
626
+ recovered_plan["authority"]["identity"], bound, record))
605
627
  ):
606
628
  raise _blocked("original recovery identity or exact CAS changed")
607
629
  from . import multiple_cleanup_recovery as multi_recovery
@@ -662,6 +684,9 @@ def cleanup_receipts(
662
684
  from .cleanup_recovery import completed
663
685
 
664
686
  if receipt.get("contract") == TYPED_RESOURCE_CONTRACT:
687
+ if multi_recovery.completed(store, path.stem, verify_generations=True):
688
+ completed_preservation_plans.extend(multi_recovery.verified_completion(store, path.stem, bound=bound))
689
+ continue
665
690
  from .cleanup_attempts import _typed_journal, typed_terminal
666
691
 
667
692
  if typed_terminal(store, path.stem) or allow_pending_typed_no_action:
@@ -762,6 +787,14 @@ def cleanup_receipts(
762
787
  for preserved in preservation_plans:
763
788
  if not source_absent(preserved, item.path):
764
789
  raise _blocked("completed preserved source reappeared")
790
+ if plan.get("build_preservation_evidences"):
791
+ from .build_preservation import generations
792
+
793
+ entries, build_plans = generations(receipt_bound, record,
794
+ topology=plan["hardlink_topology"], completed=done)
795
+ if entries != plan["build_preservation_evidences"]:
796
+ raise _blocked("completed build preservation baseline changed")
797
+ preservation_plans.extend(build_plans)
765
798
  completed_preservation_plans.extend(preservation_plans)
766
799
  if preservation_plans:
767
800
  original_root = common_source_root(preservation_plans, item.path)
@@ -774,6 +807,7 @@ def cleanup_receipts(
774
807
  if cleanup_transaction_id is not None:
775
808
  completed_preservation_plans.extend(_pending_preservation_plans(
776
809
  store, item, bound, cleanup_transaction_id, cleanup_recovery,
810
+ record,
777
811
  ))
778
812
  _require_completion_coverage(bound, completed_preservation_plans, record=record)
779
813
  if expected_refs is not None:
@@ -416,6 +416,15 @@
416
416
  "cleanup_hardlink_topology_version": 2,
417
417
  "contract_version": 61,
418
418
  "registered_build_resources_version": 1,
419
+ "build_preservation_recovery_version": 1,
420
+ "build_preservation_recovery_contract": {
421
+ "stages": ["prepare-multiple", "resume"],
422
+ "cleanup_contract": "typed-disposable-resource/v1",
423
+ "recovery_contract": "multiple-preservation-cleanup-recovery/v1",
424
+ "scope": "exact registered build outputs with verified preservation lineage across one unchanged BUILD_RESOURCES_REGISTERED CAS transition",
425
+ "guards": "immutable journal/failed receipt digests; nonempty COMPLETED prefix with exact action proofs; untouched PENDING suffix; fresh owner/HEAD/CAS/runtime/resource/topology guards",
426
+ "effects": "append-only recovery baseline and completion; preserve original receipts; execute only untouched suffix; no release authorization"
427
+ },
419
428
  "retention_release_preflight_version": 1,
420
429
  "task_workflow_version": 1,
421
430
  "release_recovery_inspection_version": 1,
@@ -1078,7 +1087,7 @@
1078
1087
  "session_launcher_entrypoint": "worktree-session",
1079
1088
  "session_entrypoint": "worktree-session-end",
1080
1089
  "tool_name": "worktree-controller",
1081
- "tool_version": "1.34.0",
1090
+ "tool_version": "1.34.1",
1082
1091
  "delivered_closeout_version": 1,
1083
1092
  "retained_archive_version": 1,
1084
1093
  "retention_convergence_version": 2,
@@ -416,6 +416,15 @@
416
416
  "cleanup_hardlink_topology_version": 2,
417
417
  "contract_version": 61,
418
418
  "registered_build_resources_version": 1,
419
+ "build_preservation_recovery_version": 1,
420
+ "build_preservation_recovery_contract": {
421
+ "stages": ["prepare-multiple", "resume"],
422
+ "cleanup_contract": "typed-disposable-resource/v1",
423
+ "recovery_contract": "multiple-preservation-cleanup-recovery/v1",
424
+ "scope": "exact registered build outputs with verified preservation lineage across one unchanged BUILD_RESOURCES_REGISTERED CAS transition",
425
+ "guards": "immutable journal/failed receipt digests; nonempty COMPLETED prefix with exact action proofs; untouched PENDING suffix; fresh owner/HEAD/CAS/runtime/resource/topology guards",
426
+ "effects": "append-only recovery baseline and completion; preserve original receipts; execute only untouched suffix; no release authorization"
427
+ },
419
428
  "retention_release_preflight_version": 1,
420
429
  "task_workflow_version": 1,
421
430
  "release_recovery_inspection_version": 1,
@@ -1078,7 +1087,7 @@
1078
1087
  "session_launcher_entrypoint": "worktree-session",
1079
1088
  "session_entrypoint": "worktree-session-end",
1080
1089
  "tool_name": "worktree-controller",
1081
- "tool_version": "1.34.0",
1090
+ "tool_version": "1.34.1",
1082
1091
  "delivered_closeout_version": 1,
1083
1092
  "retained_archive_version": 1,
1084
1093
  "retention_convergence_version": 2,