worktree-controller 1.32.12__tar.gz → 1.32.13__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.12 → worktree_controller-1.32.13}/PKG-INFO +5 -5
  2. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/README.md +4 -4
  3. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/docs/reference.md +18 -0
  4. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/pyproject.toml +1 -1
  5. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/pyproject.toml.orig +1 -1
  6. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/__init__.py +1 -1
  7. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/cleanup_evidence.py +30 -1
  8. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/delivered_closeout.py +5 -2
  9. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/preserved_cleanup.py +2 -32
  10. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/tool_cli_contract.json +1 -1
  11. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/tool_cli_contract.json +1 -1
  12. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/LICENSE +0 -0
  13. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/docs/architecture.md +0 -0
  14. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/docs/client-integration.md +0 -0
  15. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/docs/daily-workflow.md +0 -0
  16. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/docs/first-change.md +0 -0
  17. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/docs/getting-started.md +0 -0
  18. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/docs/integration-boundaries.md +0 -0
  19. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/docs/operations.md +0 -0
  20. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/docs/publishing.md +0 -0
  21. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/docs/roadmap.md +0 -0
  22. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/docs/scope.md +0 -0
  23. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/examples/change_task.py +0 -0
  24. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/examples/client_continuation.py +0 -0
  25. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/examples/quickstart.py +0 -0
  26. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/activation_layout.py +0 -0
  27. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/branch_retirement.py +0 -0
  28. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/canonical_refresh.py +0 -0
  29. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/canonical_transition.py +0 -0
  30. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/cleanup_attempts.py +0 -0
  31. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/cleanup_recovery.py +0 -0
  32. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/cli.py +0 -0
  33. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/controller.py +0 -0
  34. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/convergence.py +0 -0
  35. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/disposable.py +0 -0
  36. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/environment.py +0 -0
  37. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/frozen_recovery.py +0 -0
  38. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/git_backend.py +0 -0
  39. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/governance.py +0 -0
  40. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/hardlinks.py +0 -0
  41. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/integration_cleanup.py +0 -0
  42. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/integration_conflict.py +0 -0
  43. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/integration_retry.py +0 -0
  44. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/keyed_document_scope.py +0 -0
  45. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/lifecycle.py +0 -0
  46. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/lifecycle_history.py +0 -0
  47. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/lifecycle_observation.py +0 -0
  48. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/metadata_codec.py +0 -0
  49. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/metadata_relocation.py +0 -0
  50. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/models.py +0 -0
  51. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/mount_diagnostics.py +0 -0
  52. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/multiple_cleanup_recovery.py +0 -0
  53. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/namespace_migration.py +0 -0
  54. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/native_session_recovery.py +0 -0
  55. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/owner_actions.py +0 -0
  56. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/policy.py +0 -0
  57. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/preservation.py +0 -0
  58. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/publication_execution.py +0 -0
  59. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/reconciler.py +0 -0
  60. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/record_updates.py +0 -0
  61. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/recovery_guidance.py +0 -0
  62. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/registration_backfill.py +0 -0
  63. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/registration_prune.py +0 -0
  64. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/release_intents.py +0 -0
  65. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/rendering.py +0 -0
  66. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/resource_admission.py +0 -0
  67. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/retirement_adapters.py +0 -0
  68. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/retirement_execution.py +0 -0
  69. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/semantics.py +0 -0
  70. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/session.py +0 -0
  71. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/session_admission.py +0 -0
  72. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/source_cleanup.py +0 -0
  73. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/source_preservation.py +0 -0
  74. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/source_recovery.py +0 -0
  75. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/store.py +0 -0
  76. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/task_workflow.py +0 -0
  77. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/transaction_scope.py +0 -0
  78. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/src/worktree_controller/writer_lease.py +0 -0
  79. {worktree_controller-1.32.12 → worktree_controller-1.32.13}/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.12
3
+ Version: 1.32.13
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.12 · Linux · Python 3.12 · Apache-2.0**
26
+ **Current release: 1.32.13 · 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.12
35
+ python -m pip install worktree-controller==1.32.13
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.12 uses CLI contract **61** and storage layout **5**.
44
+ Software version 1.32.13 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.12
53
+ git checkout v1.32.13
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.12 · Linux · Python 3.12 · Apache-2.0**
9
+ **Current release: 1.32.13 · 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.12
18
+ python -m pip install worktree-controller==1.32.13
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.12 uses CLI contract **61** and storage layout **5**.
27
+ Software version 1.32.13 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.12
36
+ git checkout v1.32.13
37
37
  python examples/quickstart.py --workspace "$HOME/wc-first-run"
38
38
  ```
39
39
 
@@ -41,6 +41,24 @@ exits. An isolated six-check fixture with sixteen 1 MiB unrelated receipts reduc
41
41
  reads from 96 to 16 with equal results; this does not establish a production latency bound or
42
42
  explain every historical long-held lock.
43
43
 
44
+ ## No-change preservation history reads (1.32.13)
45
+
46
+ Terminal no-change checks now use the same lock-scoped allocation filter as preserved
47
+ cleanup. This includes the check for cleanup completed before the original no-change
48
+ transition: it previously decoded unrelated completion documents again in each nested
49
+ verification. Relevant documents are still read and checked on every lookup. Only unrelated
50
+ allocation scopes with unchanged file identities may be reused, never a receipt verdict;
51
+ the map expires at the end of the outermost flock. A new authority lock reads those bytes again.
52
+
53
+ An isolated preservation plan for five files totaling 27,479 bytes, with eight unrelated
54
+ 2 MiB completion documents, reduced unrelated full-document reads from 64 to 16
55
+ (approximately 128 MiB to 32 MiB decoded). Both authority observations, the source scan,
56
+ original completion proof and existing refusal conditions remain mandatory. The fixture
57
+ also included 16 MiB of ignored files outside the selected source. This addresses repeated
58
+ history decoding; the first scan, preservation-tree verification, Git observation and
59
+ retirement authority scans retain their existing costs. It establishes no site latency
60
+ bound and does not identify the cause of a historical timeout.
61
+
44
62
  ## Optional integrations and dependencies
45
63
 
46
64
  The core control plane has a single runtime dependency (`websockets>=15,<16`) and works standalone
@@ -4,7 +4,7 @@ build-backend = "uv_build"
4
4
 
5
5
  [project]
6
6
  name = "worktree-controller"
7
- version = "1.32.12"
7
+ version = "1.32.13"
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.12"
7
+ version = "1.32.13"
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.12"
3
+ __version__ = "1.32.13"
@@ -9,7 +9,7 @@ from typing import Any
9
9
  from . import hardlinks
10
10
  from . import preservation as p
11
11
  from .models import ControllerError
12
- from .store import now_iso
12
+ from .store import MetadataStore, now_iso
13
13
 
14
14
  MAX_EVIDENCE_BYTES = 64 * 1024 * 1024
15
15
 
@@ -33,6 +33,35 @@ def read_document(directory: p._Directory, name: str) -> tuple[dict[str, Any], s
33
33
  return value, hashlib.sha256(raw).hexdigest()
34
34
 
35
35
 
36
+ def completion_for_allocation(
37
+ store: MetadataStore, path: Path, allocation: str,
38
+ ) -> tuple[dict[str, Any], str] | None:
39
+ """Reuse only unrelated scope, never a receipt or a validation verdict.
40
+
41
+ Cleanup rechecks its plan between actions. Large unrelated completions need
42
+ not be decoded on each check while the same repository flock is held. Pin
43
+ and recheck their complete inode identity even on a negative scope hit;
44
+ relevant bytes and every preservation generation still receive full checks.
45
+ """
46
+ with p._absolute_directory(path.parent) as chain:
47
+ directory = chain[-1]
48
+ identity = p._identity(os.stat(path.name, dir_fd=directory.fd, follow_symlinks=False))
49
+ scopes = store._completion_scopes
50
+ previous = None if scopes is None else scopes.get(path)
51
+ if previous is not None and previous[0] == tuple(identity) and previous[1] != allocation:
52
+ with p._regular_fd(directory.fd, path.name, identity):
53
+ return None
54
+ receipt, raw_sha = read_document(directory, path.name)
55
+ if scopes is not None:
56
+ scope = receipt.get("plan", {}).get("allocation_id")
57
+ # Allocation IDs are canonical UUIDs. Unknown larger/nonstring values
58
+ # cannot match one; do not retain arbitrary payloads in this small map.
59
+ scopes[path] = (
60
+ tuple(identity), scope if isinstance(scope, str) and len(scope) == 36 else None
61
+ )
62
+ return receipt, raw_sha
63
+
64
+
36
65
  def write(directory: Path, name: str, value: dict[str, Any]) -> dict[str, str]:
37
66
  with p._absolute_directory(directory, create=True) as chain:
38
67
  digest = p._write_once(chain[-1], name, value)
@@ -137,10 +137,13 @@ def _legacy_no_change(store: MetadataStore, item: WorktreeGitState, record: Meta
137
137
 
138
138
 
139
139
  def _has_pre_completion_cleanup(store: MetadataStore, record: MetadataRecord) -> bool:
140
- from .cleanup_evidence import read
140
+ from .cleanup_evidence import completion_for_allocation
141
141
 
142
142
  for path in sorted(store.completion_receipts_dir.glob("*.json")):
143
- value, _ = read(path)
143
+ entry = completion_for_allocation(store, path, record.allocation_id)
144
+ if entry is None:
145
+ continue
146
+ value, _ = entry
144
147
  plan = value.get("plan", {})
145
148
  if plan.get("allocation_id") == record.allocation_id and plan.get("terminal_evidence") is None:
146
149
  return True
@@ -10,11 +10,10 @@ from pathlib import Path
10
10
  from typing import Any
11
11
 
12
12
  from . import preservation as p
13
- from .cleanup_evidence import read_document
13
+ from .cleanup_evidence import completion_for_allocation, read_document
14
14
  from .disposable import _delete_fd_tree, _fd_inventory, _unlink_leaf
15
15
  from .git_backend import head_paths, path_is_ignored, tracked_paths
16
16
  from .models import ControllerError, MetadataRecord
17
- from .store import MetadataStore
18
17
 
19
18
  CONTRACT = "legacy-preserved-state-cleanup/v1"
20
19
 
@@ -23,35 +22,6 @@ def _blocked(message: str) -> ControllerError:
23
22
  return ControllerError("PRESERVATION_COVERAGE_INVALID", message)
24
23
 
25
24
 
26
- def _completion_for_allocation(
27
- store: MetadataStore, path: Path, allocation: str,
28
- ) -> tuple[dict[str, Any], str] | None:
29
- """Reuse only unrelated scope, never a receipt or a validation verdict.
30
-
31
- Cleanup rechecks its plan between actions. Large unrelated completions need
32
- not be decoded on each check while the same repository flock is held. Pin
33
- and recheck their complete inode identity even on a negative scope hit;
34
- relevant bytes and every preservation generation still receive full checks.
35
- """
36
- with p._absolute_directory(path.parent) as chain:
37
- directory = chain[-1]
38
- identity = p._identity(os.stat(path.name, dir_fd=directory.fd, follow_symlinks=False))
39
- scopes = store._completion_scopes
40
- previous = None if scopes is None else scopes.get(path)
41
- if previous is not None and previous[0] == tuple(identity) and previous[1] != allocation:
42
- with p._regular_fd(directory.fd, path.name, identity):
43
- return None
44
- receipt, raw_sha = read_document(directory, path.name)
45
- if scopes is not None:
46
- scope = receipt.get("plan", {}).get("allocation_id")
47
- # Allocation IDs are canonical UUIDs. Unknown larger/nonstring values
48
- # cannot match one; do not retain arbitrary payloads in this small map.
49
- scopes[path] = (
50
- tuple(identity), scope if isinstance(scope, str) and len(scope) == 36 else None
51
- )
52
- return receipt, raw_sha
53
-
54
-
55
25
  def coverage(
56
26
  receipt_path: Path,
57
27
  receipt_sha256: str,
@@ -645,7 +615,7 @@ def cleanup_receipts(
645
615
  if _preservation_source_relative(plan, item.path) in original_completed
646
616
  )
647
617
  for path in sorted(store.completion_receipts_dir.glob("*.json")):
648
- completion_entry = _completion_for_allocation(store, path, record.allocation_id)
618
+ completion_entry = completion_for_allocation(store, path, record.allocation_id)
649
619
  if completion_entry is None:
650
620
  continue
651
621
  receipt, raw_sha = completion_entry
@@ -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.12",
1074
+ "tool_version": "1.32.13",
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.12",
1074
+ "tool_version": "1.32.13",
1075
1075
  "delivered_closeout_version": 1,
1076
1076
  "retained_archive_version": 1,
1077
1077
  "retention_convergence_version": 2,