worktree-controller 1.32.7__tar.gz → 1.32.8__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 (79) hide show
  1. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/PKG-INFO +5 -5
  2. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/README.md +4 -4
  3. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/docs/operations.md +8 -0
  4. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/docs/roadmap.md +16 -8
  5. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/pyproject.toml +1 -1
  6. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/pyproject.toml.orig +1 -1
  7. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/__init__.py +1 -1
  8. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/activation_layout.py +1 -1
  9. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/cleanup_evidence.py +27 -3
  10. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/metadata_relocation.py +3 -3
  11. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/multiple_cleanup_recovery.py +1 -2
  12. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/preserved_cleanup.py +7 -27
  13. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/source_preservation.py +4 -4
  14. {worktree_controller-1.32.7 → worktree_controller-1.32.8/src/worktree_controller}/tool_cli_contract.json +1 -1
  15. {worktree_controller-1.32.7/src/worktree_controller → worktree_controller-1.32.8}/tool_cli_contract.json +1 -1
  16. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/LICENSE +0 -0
  17. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/docs/architecture.md +0 -0
  18. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/docs/client-integration.md +0 -0
  19. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/docs/daily-workflow.md +0 -0
  20. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/docs/first-change.md +0 -0
  21. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/docs/getting-started.md +0 -0
  22. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/docs/integration-boundaries.md +0 -0
  23. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/docs/publishing.md +0 -0
  24. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/docs/reference.md +0 -0
  25. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/docs/scope.md +0 -0
  26. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/examples/change_task.py +0 -0
  27. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/examples/client_continuation.py +0 -0
  28. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/examples/quickstart.py +0 -0
  29. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/branch_retirement.py +0 -0
  30. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/canonical_refresh.py +0 -0
  31. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/canonical_transition.py +0 -0
  32. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/cleanup_attempts.py +0 -0
  33. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/cleanup_recovery.py +0 -0
  34. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/cli.py +0 -0
  35. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/controller.py +0 -0
  36. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/convergence.py +0 -0
  37. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/delivered_closeout.py +0 -0
  38. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/disposable.py +0 -0
  39. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/environment.py +0 -0
  40. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/frozen_recovery.py +0 -0
  41. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/git_backend.py +0 -0
  42. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/governance.py +0 -0
  43. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/hardlinks.py +0 -0
  44. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/integration_cleanup.py +0 -0
  45. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/integration_conflict.py +0 -0
  46. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/integration_retry.py +0 -0
  47. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/keyed_document_scope.py +0 -0
  48. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/lifecycle.py +0 -0
  49. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/lifecycle_history.py +0 -0
  50. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/lifecycle_observation.py +0 -0
  51. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/metadata_codec.py +0 -0
  52. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/models.py +0 -0
  53. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/mount_diagnostics.py +0 -0
  54. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/namespace_migration.py +0 -0
  55. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/native_session_recovery.py +0 -0
  56. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/owner_actions.py +0 -0
  57. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/policy.py +0 -0
  58. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/preservation.py +0 -0
  59. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/publication_execution.py +0 -0
  60. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/reconciler.py +0 -0
  61. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/record_updates.py +0 -0
  62. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/recovery_guidance.py +0 -0
  63. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/registration_backfill.py +0 -0
  64. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/registration_prune.py +0 -0
  65. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/release_intents.py +0 -0
  66. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/rendering.py +0 -0
  67. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/resource_admission.py +0 -0
  68. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/retirement_adapters.py +0 -0
  69. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/retirement_execution.py +0 -0
  70. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/semantics.py +0 -0
  71. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/session.py +0 -0
  72. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/session_admission.py +0 -0
  73. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/source_cleanup.py +0 -0
  74. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/source_recovery.py +0 -0
  75. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/store.py +0 -0
  76. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/task_workflow.py +0 -0
  77. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/transaction_scope.py +0 -0
  78. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/src/worktree_controller/writer_lease.py +0 -0
  79. {worktree_controller-1.32.7 → worktree_controller-1.32.8}/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.7
3
+ Version: 1.32.8
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.7 · Linux · Python 3.12 · Apache-2.0**
26
+ **Current release: 1.32.8 · 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.7
35
+ python -m pip install worktree-controller==1.32.8
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.7 uses CLI contract **61** and storage layout **5**.
44
+ Software version 1.32.8 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.7
53
+ git checkout v1.32.8
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.7 · Linux · Python 3.12 · Apache-2.0**
9
+ **Current release: 1.32.8 · 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.7
18
+ python -m pip install worktree-controller==1.32.8
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.7 uses CLI contract **61** and storage layout **5**.
27
+ Software version 1.32.8 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.7
36
+ git checkout v1.32.8
37
37
  python examples/quickstart.py --workspace "$HOME/wc-first-run"
38
38
  ```
39
39
 
@@ -285,6 +285,14 @@ the output directory for diagnosis. Keep that evidence outside the checkout and
285
285
  its owning temporary-directory workflow after review. `scripts/check-project` remains the complete
286
286
  release gate, including builds and installed smokes.
287
287
 
288
+ The development [cross-tool acceptance cohorts](../CONTRIBUTING.md#cross-tool-acceptance)
289
+ declare staging provenance and distinguish ordinary predecessors from historical capability/CLI
290
+ migrations. An explicitly selected cohort with unmet prerequisites refuses before dependency or
291
+ output changes. Every selected case must pass without skips; unrequested cohorts are reported
292
+ separately. This does not replace the deployment gate or grant activation authority.
293
+ Test/check-script and documentation maintenance can be integrated on main for a later release;
294
+ keep the installed runtime pin when its payload and public contracts are unchanged.
295
+
288
296
  Deliver tool changes through reviewed source, contracts and source-owned Skills, then supported
289
297
  stage, rollout and activation. CLI, capability and storage versions are independent checks.
290
298
  Use the existing rollback flow; never repoint the active runtime by hand or activate another
@@ -1,12 +1,17 @@
1
1
  # Maintenance roadmap
2
2
 
3
- Execution baseline: 2026-10-24. This is the WC portion of the approved four-tool maintenance
3
+ Execution baseline: 2026-10-25. This is the WC portion of the approved four-tool maintenance
4
4
  direction. Each stage needs its own tested deliverable; later ideas are not current behavior.
5
5
 
6
6
  ## Current baseline
7
7
 
8
8
  WC 1.32.6 completed the runtime-visibility fix and the previously planned allocation-to-intent
9
- query extraction. Private cross-module imports remain at 76. Software version 1.32.7 retains
9
+ query extraction. The 1.32.8 maintenance candidate places shared bounded, FD-bound document reads
10
+ in the existing cleanup evidence module, removing four private imports (76 to 72). Raw-byte
11
+ hashes, file/ancestor checks, limits and refusal codes stay unchanged; mutation and crash hooks
12
+ retain their original owners. Release acceptance covers the exact installed candidate, ordinary
13
+ 1.32.7 upgrades and historical 1.30.4 restoration. Publication and local activation remain
14
+ separate verified steps. Software version 1.32.8 retains
10
15
  CLI contract 61, the existing capability versions and storage layout 5, and serializes doctor
11
16
  snapshot reads with normal Controller mutations. Diagnostics refresh Git inventory after taking
12
17
  the shared repository lock, then retain it through semantic, transaction and retirement checks.
@@ -31,8 +36,9 @@ acceptance gates, and historical temporary-file impact. No historical evidence i
31
36
  | Stage | Deliverable | Exit evidence | Stop or rollback boundary |
32
37
  | --- | --- | --- | --- |
33
38
  | Now: boundaries | Current protocol and consumer inventory, including legacy adapters | Named owner per interface, source references, explicit unknowns; no changes to supported commands | Conflicting evidence keeps the interface supported |
34
- | WC structure: delivered | Pure release-intent, scope and allocation-to-intent queries | Existing behavior retained; private-import baseline 76; CLI 61/storage 5 unchanged | Preserve clocks, mutation and crash-hook ownership |
35
- | Now: diagnostic stability | One coherent doctor snapshot across guarded lifecycle changes | Real concurrent release, fresh inventory and negative API/CLI controls; full integration gate | Retain missing-commit and ownership refusals; preserve original incident uncertainty |
39
+ | WC structure: delivered | Pure release-intent, scope and allocation-to-intent queries; shared FD-bound evidence reader | Existing behavior retained; private-import baseline 72; CLI 61/storage 5 unchanged; reader byte/race characterizations | Preserve clocks, mutation and crash-hook ownership; verify the planned maintenance release |
40
+ | Diagnostic stability: delivered | One coherent doctor snapshot across guarded lifecycle changes | 1.32.7 released and installed; real concurrent release, fresh inventory and negative API/CLI controls | Retain missing-commit and ownership refusals; preserve original incident uncertainty |
41
+ | Upgrade acceptance: delivered | Ordinary and historical cohorts with declared staging provenance | Matching installed pins, all selected cases pass; explicit prerequisite refusals and source/identity negative controls | Never infer provenance from origin, skip a selected failure or relax activation gates |
36
42
  | Shared quality checks: delivered | CL/SR adopt release-tools with a reviewed full commit pin | Both hosted parallel pilots and final three-version checks passed; SR retains its package check | Restore the pinned original consumer workflow; PyPI/Gitea flows remain owned by consumers |
37
43
  | Next 2–6 weeks | Further WC extraction only where a shared responsibility is clear; measure maintenance burden and failures | One behavior-preserving batch at a time, consumer gates, shrinking private-import baseline | Keep injected clocks, transaction and crash hooks with their owner until an explicit migration is tested |
38
44
  | Following 6–12 weeks | Evaluate moving manifests, compatibility catalog and shared Skills from GF to a dedicated toolchain owner | Full ownership inventory, staged installer/migration, exactly one active writer, historical pin and rollback tests | No second simultaneous Skill authority; no ownership switch on file-copy evidence |
@@ -54,9 +60,11 @@ Python floor, move host-specific defaults without migration, or replace existing
54
60
  GitHub-first release consolidation and a future toolchain repository remain design decisions,
55
61
  not permission to disable existing Gitea delivery or platform controls.
56
62
 
57
- The allocation-to-intent maintenance task and the 1.32.6 delivery are complete. Use the real
58
- diagnostic-stability maintenance task to observe checkpoint pause, fresh-executor resume,
59
- Finalizer handoff, integration and release; preserve pending results instead of interpreting
60
- an advisory success as completion. The released publication visibility window keeps exact bytes,
63
+ The allocation-to-intent maintenance task and the 1.32.7 delivery are complete. The real
64
+ diagnostic-stability task verified checkpoint pause, fresh-executor resume, Finalizer handoff,
65
+ integration and release. Use normal maintenance tasks for further observations; preserve pending
66
+ results instead of interpreting an advisory success as completion. Batch test-only maintenance
67
+ on main without republishing or activating an unchanged runtime.
68
+ The released publication visibility window keeps exact bytes,
61
69
  identities, failed-command outcomes and same-bundle recovery mandatory. CL/SR shared quality checks
62
70
  have passed their hosted parallel and final matrices.
@@ -4,7 +4,7 @@ build-backend = "uv_build"
4
4
 
5
5
  [project]
6
6
  name = "worktree-controller"
7
- version = "1.32.7"
7
+ version = "1.32.8"
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.7"
7
+ version = "1.32.8"
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.7"
3
+ __version__ = "1.32.8"
@@ -441,7 +441,7 @@ class LayoutMigration:
441
441
  # Original journals/receipts are moved back byte for byte.
442
442
  with p._absolute_directory(old) as chain:
443
443
  if relocation.RECORD in os.listdir(chain[-1].fd):
444
- value, _ = relocation._document(chain[-1], relocation.RECORD)
444
+ value, _ = evidence.read_document(chain[-1], relocation.RECORD)
445
445
  if value != row["references"]:
446
446
  raise LayoutError("relocation evidence changed before rollback")
447
447
  os.unlink(relocation.RECORD, dir_fd=chain[-1].fd)
@@ -1,13 +1,37 @@
1
- """Exclusive, FD-relative immutable cleanup action evidence."""
1
+ """FD-relative immutable evidence reads and exclusive cleanup action evidence."""
2
2
 
3
+ import hashlib
4
+ import json
5
+ import os
3
6
  from pathlib import Path
4
7
  from typing import Any
5
8
 
6
9
  from . import hardlinks
7
10
  from . import preservation as p
8
- from .preserved_cleanup import _document
11
+ from .models import ControllerError
9
12
  from .store import now_iso
10
13
 
14
+ MAX_EVIDENCE_BYTES = 64 * 1024 * 1024
15
+
16
+
17
+ def read_document(directory: p._Directory, name: str) -> tuple[dict[str, Any], str]:
18
+ """Read exact FD-bound bytes, retaining the existing preservation refusals."""
19
+ metadata = os.stat(name, dir_fd=directory.fd, follow_symlinks=False)
20
+ if metadata.st_size > MAX_EVIDENCE_BYTES:
21
+ raise ControllerError("PRESERVATION_COVERAGE_INVALID", "preservation evidence exceeds its bound")
22
+ with (
23
+ p._regular_fd(directory.fd, name, p._identity(metadata)) as fd,
24
+ os.fdopen(os.dup(fd), "rb") as stream,
25
+ ):
26
+ raw = stream.read(MAX_EVIDENCE_BYTES + 1)
27
+ if len(raw) > MAX_EVIDENCE_BYTES:
28
+ raise ControllerError("PRESERVATION_COVERAGE_INVALID", "preservation evidence exceeds its bound")
29
+ directory.check()
30
+ value = json.loads(raw)
31
+ if not isinstance(value, dict):
32
+ raise ControllerError("PRESERVATION_COVERAGE_INVALID", "invalid preservation document")
33
+ return value, hashlib.sha256(raw).hexdigest()
34
+
11
35
 
12
36
  def write(directory: Path, name: str, value: dict[str, Any]) -> dict[str, str]:
13
37
  with p._absolute_directory(directory, create=True) as chain:
@@ -20,7 +44,7 @@ def read(path: Path, digest: str | None = None) -> tuple[dict[str, Any], str]:
20
44
 
21
45
  path = relocated(path, digest)
22
46
  with p._absolute_directory(path.parent) as chain:
23
- value, actual = _document(chain[-1], path.name)
47
+ value, actual = read_document(chain[-1], path.name)
24
48
  if digest is not None and actual != digest:
25
49
  raise hardlinks._blocked("immutable cleanup evidence bytes changed")
26
50
  return value, actual
@@ -12,9 +12,9 @@ import stat
12
12
  from pathlib import Path
13
13
 
14
14
  from . import preservation as p
15
+ from .cleanup_evidence import read_document
15
16
  from .disposable import _inode, _open_directory
16
17
  from .models import ControllerError
17
- from .preserved_cleanup import _document
18
18
  from .store import ROOT_NAME, VERSION_NAME
19
19
 
20
20
  CONTRACT = "metadata-reference-relocation/v1"
@@ -46,7 +46,7 @@ def inventory(root: Path) -> dict[str, str]:
46
46
  with _open_directory(directory.fd, name, _inode(info)) as child:
47
47
  walk(child, relative)
48
48
  elif stat.S_ISREG(info.st_mode) and name.endswith(".json"):
49
- _, result[relative] = _document(directory, name)
49
+ _, result[relative] = read_document(directory, name)
50
50
  else:
51
51
  raise _blocked()
52
52
  directory.check()
@@ -78,7 +78,7 @@ def prepare(old: Path, new: Path) -> dict:
78
78
 
79
79
  def _record(root: Path) -> dict:
80
80
  with p._absolute_directory(root) as chain:
81
- value, _ = _document(chain[-1], RECORD)
81
+ value, _ = read_document(chain[-1], RECORD)
82
82
  info = os.fstat(chain[-1].fd)
83
83
  old = Path(value["previous_root"])
84
84
  if (
@@ -14,7 +14,6 @@ from . import preservation as p
14
14
  from .git_backend import inventory
15
15
  from .models import ControllerError, MetadataRecord
16
16
  from .preserved_cleanup import (
17
- _document,
18
17
  common_source_root,
19
18
  completed_actions,
20
19
  coverage,
@@ -99,7 +98,7 @@ def _generation_metadata(bound: dict[str, Any]) -> list[dict[str, Any]]:
99
98
  if filename != "manifest.json":
100
99
  raise _blocked("completed generation metadata is missing") from None
101
100
  continue
102
- metadata, digest = _document(directory, filename)
101
+ metadata, digest = e.read_document(directory, filename)
103
102
  if filename == "receipt.json" and (
104
103
  metadata.get("receipt_id") != name
105
104
  or metadata.get("generation") != str(allocation / name)
@@ -2,8 +2,6 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
- import hashlib
6
- import json
7
5
  import os
8
6
  import re
9
7
  import stat
@@ -12,36 +10,18 @@ from pathlib import Path
12
10
  from typing import Any
13
11
 
14
12
  from . import preservation as p
13
+ from .cleanup_evidence import read_document
15
14
  from .disposable import _delete_fd_tree, _fd_inventory, _unlink_leaf
16
15
  from .git_backend import head_paths, path_is_ignored, tracked_paths
17
16
  from .models import ControllerError, MetadataRecord
18
17
 
19
18
  CONTRACT = "legacy-preserved-state-cleanup/v1"
20
- MAX_EVIDENCE_BYTES = 64 * 1024 * 1024
21
19
 
22
20
 
23
21
  def _blocked(message: str) -> ControllerError:
24
22
  return ControllerError("PRESERVATION_COVERAGE_INVALID", message)
25
23
 
26
24
 
27
- def _document(directory: p._Directory, name: str) -> tuple[dict[str, Any], str]:
28
- metadata = os.stat(name, dir_fd=directory.fd, follow_symlinks=False)
29
- if metadata.st_size > MAX_EVIDENCE_BYTES:
30
- raise _blocked("preservation evidence exceeds its bound")
31
- with (
32
- p._regular_fd(directory.fd, name, p._identity(metadata)) as fd,
33
- os.fdopen(os.dup(fd), "rb") as stream,
34
- ):
35
- raw = stream.read(MAX_EVIDENCE_BYTES + 1)
36
- if len(raw) > MAX_EVIDENCE_BYTES:
37
- raise _blocked("preservation evidence exceeds its bound")
38
- directory.check()
39
- value = json.loads(raw)
40
- if not isinstance(value, dict):
41
- raise _blocked("invalid preservation document")
42
- return value, hashlib.sha256(raw).hexdigest()
43
-
44
-
45
25
  def coverage(
46
26
  receipt_path: Path,
47
27
  receipt_sha256: str,
@@ -80,11 +60,11 @@ def _coverage(
80
60
  generation = receipt_path.parent
81
61
  with p._absolute_directory(generation) as chain:
82
62
  directory = chain[-1]
83
- receipt, actual_receipt_sha = _document(directory, "receipt.json")
63
+ receipt, actual_receipt_sha = read_document(directory, "receipt.json")
84
64
  if actual_receipt_sha != receipt_sha256:
85
65
  raise _blocked("preservation receipt bytes changed")
86
- plan, _ = _document(directory, "plan.json")
87
- manifest, manifest_sha = _document(directory, "manifest.json")
66
+ plan, _ = read_document(directory, "plan.json")
67
+ manifest, manifest_sha = read_document(directory, "manifest.json")
88
68
  bound = plan["authority"]["identity"]
89
69
  if identity is not None and bound != identity:
90
70
  raise _blocked("preservation belongs to another allocation/worktree identity")
@@ -453,8 +433,8 @@ def _require_completion_coverage(
453
433
  os.stat("receipt.json", dir_fd=directory.fd, follow_symlinks=False)
454
434
  except FileNotFoundError:
455
435
  continue
456
- receipt, _raw_sha = _document(directory, "receipt.json")
457
- plan, _ = _document(directory, "plan.json")
436
+ receipt, _raw_sha = read_document(directory, "receipt.json")
437
+ plan, _ = read_document(directory, "plan.json")
458
438
  if (
459
439
  receipt.get("contract") not in {p.CONTRACT, SOURCE_CONTRACT}
460
440
  or receipt.get("contract") != plan.get("contract")
@@ -636,7 +616,7 @@ def cleanup_receipts(
636
616
  )
637
617
  for path in sorted(store.completion_receipts_dir.glob("*.json")):
638
618
  with p._absolute_directory(path.parent) as chain:
639
- receipt, raw_sha = _document(chain[-1], path.name)
619
+ receipt, raw_sha = read_document(chain[-1], path.name)
640
620
  plan = receipt.get("plan", {})
641
621
  if plan.get("allocation_id") != record.allocation_id:
642
622
  continue
@@ -21,10 +21,10 @@ from pathlib import Path, PurePosixPath
21
21
  from typing import Any
22
22
 
23
23
  from . import preservation as p
24
+ from .cleanup_evidence import read_document
24
25
  from .disposable import _Directory, _inode, _open_directory
25
26
  from .git_backend import _git
26
27
  from .models import ControllerError
27
- from .preserved_cleanup import _document
28
28
  from .store import MetadataStore
29
29
 
30
30
  CONTRACT = "tracked-source-preservation/v1"
@@ -579,9 +579,9 @@ def _verify_generation(plan: dict, receipt_sha256: str, state_root: Path | None
579
579
  or st.st_nlink != 1
580
580
  ):
581
581
  raise _fail("SOURCE_GENERATION_NOT_SEALED")
582
- receipt, receipt_digest = _document(generation, "receipt.json")
583
- manifest, manifest_digest = _document(generation, "manifest.json")
584
- saved_plan, saved_plan_digest = _document(generation, "plan.json")
582
+ receipt, receipt_digest = read_document(generation, "receipt.json")
583
+ manifest, manifest_digest = read_document(generation, "manifest.json")
584
+ saved_plan, saved_plan_digest = read_document(generation, "plan.json")
585
585
  if (
586
586
  receipt_digest != receipt_sha256
587
587
  or receipt.get("contract") != CONTRACT
@@ -1071,7 +1071,7 @@
1071
1071
  "session_launcher_entrypoint": "worktree-session",
1072
1072
  "session_entrypoint": "worktree-session-end",
1073
1073
  "tool_name": "worktree-controller",
1074
- "tool_version": "1.32.7",
1074
+ "tool_version": "1.32.8",
1075
1075
  "delivered_closeout_version": 1,
1076
1076
  "retained_archive_version": 1,
1077
1077
  "retention_convergence_version": 2,
@@ -1071,7 +1071,7 @@
1071
1071
  "session_launcher_entrypoint": "worktree-session",
1072
1072
  "session_entrypoint": "worktree-session-end",
1073
1073
  "tool_name": "worktree-controller",
1074
- "tool_version": "1.32.7",
1074
+ "tool_version": "1.32.8",
1075
1075
  "delivered_closeout_version": 1,
1076
1076
  "retained_archive_version": 1,
1077
1077
  "retention_convergence_version": 2,