worktree-controller 1.36.0__tar.gz → 1.36.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.
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/PKG-INFO +1 -1
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/pyproject.toml +1 -1
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/pyproject.toml.orig +1 -1
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/__init__.py +1 -1
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/canonical_transition.py +2 -3
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/cleanup_attempts.py +2 -2
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/cleanup_recovery.py +8 -8
- worktree_controller-1.36.1/src/worktree_controller/cleanup_retention.py +475 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/cli.py +48 -4
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/controller.py +306 -17
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/convergence.py +12 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/delivered_closeout.py +2 -2
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/frozen_recovery.py +2 -3
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/git_backend.py +21 -4
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/integration_conflict.py +2 -3
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/integration_retry.py +2 -3
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/lifecycle.py +117 -56
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/multiple_cleanup_recovery.py +4 -4
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/reconciler.py +2 -3
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/recovery_guidance.py +1 -1
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/registration_prune.py +2 -3
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/session.py +1 -1
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/store.py +3 -1
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/task_workflow.py +1 -1
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/tool_cli_contract.json +1 -1
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/writer_lease.py +8 -4
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/tool_cli_contract.json +1 -1
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/LICENSE +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/README.md +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/docs/architecture.md +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/docs/build-resources.md +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/docs/client-integration.md +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/docs/daily-workflow.md +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/docs/first-change.md +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/docs/getting-started.md +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/docs/integration-boundaries.md +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/docs/operations.md +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/docs/publishing.md +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/docs/reference.md +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/docs/roadmap.md +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/docs/scope.md +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/examples/change_task.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/examples/client_continuation.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/examples/quickstart.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/activation_layout.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/branch_retirement.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/build_preservation.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/build_resources.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/canonical_refresh.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/cleanup_evidence.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/disposable.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/environment.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/frontier.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/governance.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/hardlinks.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/integration_cleanup.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/keyed_document_scope.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/lifecycle_history.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/lifecycle_observation.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/metadata_codec.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/metadata_relocation.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/models.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/mount_diagnostics.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/namespace_migration.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/native_session_recovery.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/owner_actions.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/policy.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/preservation.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/preserved_cleanup.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/publication_execution.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/record_updates.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/registration_backfill.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/release_intents.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/rendering.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/resource_admission.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/retirement_adapters.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/retirement_execution.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/semantics.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/session_admission.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/source_cleanup.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/source_preservation.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/source_recovery.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/transaction_scope.py +0 -0
- {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/writer_session.py +0 -0
|
@@ -7,7 +7,7 @@ from dataclasses import replace
|
|
|
7
7
|
from pathlib import Path
|
|
8
8
|
from typing import Any
|
|
9
9
|
|
|
10
|
-
from .controller import
|
|
10
|
+
from .controller import compact_status
|
|
11
11
|
from .git_backend import (
|
|
12
12
|
_git,
|
|
13
13
|
fetch_remote_branch,
|
|
@@ -354,8 +354,7 @@ def transition_canonical(
|
|
|
354
354
|
}
|
|
355
355
|
updated = replace(updated, history=(*updated.history[:-1], event))
|
|
356
356
|
store.replace_record(updated)
|
|
357
|
-
payload =
|
|
358
|
-
payload["command"] = "canonical-transition"
|
|
357
|
+
payload = compact_status(repository_path, command="canonical-transition", target=target)
|
|
359
358
|
payload["decision"] = {
|
|
360
359
|
"code": "CANONICAL_MAIN_REFRESHED" if refresh_main else "CANONICAL_TRANSITIONED",
|
|
361
360
|
"allocation_id": updated.allocation_id,
|
|
@@ -202,14 +202,14 @@ def reconcile_typed_locked(repo: Path, store: MetadataStore, transaction: str, d
|
|
|
202
202
|
|
|
203
203
|
def reconcile_typed(repo: Path, transaction: str, digest: str, *, dry_run: bool,
|
|
204
204
|
expected_plan_id: str | None = None) -> dict:
|
|
205
|
-
from .controller import
|
|
205
|
+
from .controller import compact_status
|
|
206
206
|
from .git_backend import inventory
|
|
207
207
|
|
|
208
208
|
store = MetadataStore(inventory(repo).common_dir)
|
|
209
209
|
with store.lock(exclusive=not dry_run):
|
|
210
210
|
decision = reconcile_typed_locked(repo, store, transaction, digest, dry_run=dry_run,
|
|
211
211
|
expected_plan_id=expected_plan_id)
|
|
212
|
-
result =
|
|
212
|
+
result = compact_status(repo, command="resource-recover")
|
|
213
213
|
result.update(command="resource-recover", decision=decision)
|
|
214
214
|
return result
|
|
215
215
|
|
|
@@ -348,7 +348,7 @@ def prepare(
|
|
|
348
348
|
dry_run: bool,
|
|
349
349
|
expected_plan_id: str | None = None,
|
|
350
350
|
) -> dict[str, Any]:
|
|
351
|
-
from .controller import
|
|
351
|
+
from .controller import compact_status
|
|
352
352
|
|
|
353
353
|
store = MetadataStore(inventory(repo).common_dir)
|
|
354
354
|
decision: dict[str, Any]
|
|
@@ -379,7 +379,7 @@ def prepare(
|
|
|
379
379
|
}
|
|
380
380
|
reference = e.write(directory, "record.json", document)
|
|
381
381
|
decision.update(recovery_id=recovery_id, recovery_receipt=reference)
|
|
382
|
-
result =
|
|
382
|
+
result = compact_status(repo, command="resource-recover")
|
|
383
383
|
result.update(command="resource-recover", decision=decision)
|
|
384
384
|
return result
|
|
385
385
|
|
|
@@ -470,7 +470,7 @@ def rollout_check(
|
|
|
470
470
|
repo: Path, *, receipt_path: Path | None = None, receipt_sha: str | None = None
|
|
471
471
|
) -> dict[str, Any]:
|
|
472
472
|
"""Read-only installation compatibility, never a transaction state transition."""
|
|
473
|
-
from .controller import
|
|
473
|
+
from .controller import compact_status
|
|
474
474
|
from .transaction_scope import is_atomic_temp
|
|
475
475
|
|
|
476
476
|
store = MetadataStore(inventory(repo).common_dir)
|
|
@@ -495,7 +495,7 @@ def rollout_check(
|
|
|
495
495
|
"ROLLOUT_TRANSACTION_UNSUPPORTED", f"transaction recovery evidence is malformed: {exc}"
|
|
496
496
|
)
|
|
497
497
|
raise RolloutTransactionError(cause, path.stem, journal) from exc
|
|
498
|
-
result =
|
|
498
|
+
result = compact_status(repo, command="resource-recover")
|
|
499
499
|
result.update(
|
|
500
500
|
command="resource-recover",
|
|
501
501
|
decision={
|
|
@@ -552,7 +552,7 @@ def reconcile_attempt(
|
|
|
552
552
|
dry_run: bool,
|
|
553
553
|
expected_plan_id: str | None = None,
|
|
554
554
|
) -> dict[str, Any]:
|
|
555
|
-
from .controller import
|
|
555
|
+
from .controller import compact_status
|
|
556
556
|
|
|
557
557
|
store = MetadataStore(inventory(repo).common_dir)
|
|
558
558
|
with store.lock(exclusive=not dry_run):
|
|
@@ -606,7 +606,7 @@ def reconcile_attempt(
|
|
|
606
606
|
decision["reconciliation"] = e.write(
|
|
607
607
|
path.parent, path.name, {**plan, "plan_id": plan_id, "timestamp": now_iso()}
|
|
608
608
|
)
|
|
609
|
-
result =
|
|
609
|
+
result = compact_status(repo, command="resource-recover")
|
|
610
610
|
result.update(command="resource-recover", decision=decision)
|
|
611
611
|
return result
|
|
612
612
|
|
|
@@ -681,7 +681,7 @@ def _incomplete(
|
|
|
681
681
|
|
|
682
682
|
|
|
683
683
|
def resume(repo: Path, *, recovery_path: Path, recovery_sha: str, dry_run: bool) -> dict[str, Any]:
|
|
684
|
-
from .controller import
|
|
684
|
+
from .controller import compact_status
|
|
685
685
|
from .lifecycle import cleanup_typed_disposable
|
|
686
686
|
|
|
687
687
|
store = MetadataStore(inventory(repo).common_dir)
|
|
@@ -806,7 +806,7 @@ def resume(repo: Path, *, recovery_path: Path, recovery_sha: str, dry_run: bool)
|
|
|
806
806
|
)
|
|
807
807
|
except Exception as exc:
|
|
808
808
|
return _incomplete(repo, store, document, attempt_directory, attempt_id, underlying, exc)
|
|
809
|
-
result =
|
|
809
|
+
result = compact_status(repo, command="resource-recover")
|
|
810
810
|
result.update(
|
|
811
811
|
command="resource-recover",
|
|
812
812
|
decision={
|
|
@@ -0,0 +1,475 @@
|
|
|
1
|
+
"""Safe, fail-closed retention and pruning for terminal RELEASED cleanup evidence.
|
|
2
|
+
|
|
3
|
+
Typed and preserved disposable cleanups record pre/post hardlink topologies
|
|
4
|
+
(``cleanup-actions/<tx>/`` and ``completion-receipts/<tx>.json``) so an
|
|
5
|
+
interrupted cleanup can be verified and recovered. Once the owning allocation
|
|
6
|
+
has reached terminal ``RELEASED`` with an exact matching ``ReleaseReceipt``,
|
|
7
|
+
no live checkout or active lease/intent remains, and no retained transaction
|
|
8
|
+
journal or recovery record references that evidence, those multi-megabyte
|
|
9
|
+
topology artifacts are no longer required by any runtime or recovery path.
|
|
10
|
+
|
|
11
|
+
Pruning ALWAYS removes ``cleanup-actions/<id>/`` before removing
|
|
12
|
+
``completion-receipts/<id>.json`` so ``cleanup_attempts.no_action_evidence``
|
|
13
|
+
never observes an unbound cleanup-actions directory.
|
|
14
|
+
"""
|
|
15
|
+
|
|
16
|
+
from __future__ import annotations
|
|
17
|
+
|
|
18
|
+
import json
|
|
19
|
+
import os
|
|
20
|
+
import stat
|
|
21
|
+
import uuid
|
|
22
|
+
from contextlib import suppress
|
|
23
|
+
from dataclasses import dataclass
|
|
24
|
+
from datetime import UTC, datetime, timedelta
|
|
25
|
+
from pathlib import Path
|
|
26
|
+
from typing import Any
|
|
27
|
+
|
|
28
|
+
from .git_backend import inventory
|
|
29
|
+
from .models import ControllerError, MetadataSnapshot, RepositoryInventory
|
|
30
|
+
from .semantics import effective_intent_state
|
|
31
|
+
from .store import MetadataStore
|
|
32
|
+
|
|
33
|
+
PRUNABLE_CLEANUP_CONTRACTS = frozenset(
|
|
34
|
+
{
|
|
35
|
+
"typed-disposable-resource/v1",
|
|
36
|
+
"legacy-preserved-state-cleanup/v1",
|
|
37
|
+
"legacy-preserved-state-multiple-cleanup/v1",
|
|
38
|
+
}
|
|
39
|
+
)
|
|
40
|
+
TERMINAL_INTENT_STATES = frozenset({"RELEASED", "ABANDONED"})
|
|
41
|
+
DEFAULT_AUTO_KEEP_RECENT = 5
|
|
42
|
+
DEFAULT_AUTO_MAX_BYTES = 64 * 1024 * 1024
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
@dataclass(frozen=True)
|
|
46
|
+
class PrunableCleanupEntry:
|
|
47
|
+
receipt_id: str
|
|
48
|
+
allocation_id: str
|
|
49
|
+
contract: str
|
|
50
|
+
receipt_path: Path
|
|
51
|
+
receipt_bytes: int
|
|
52
|
+
action_dir: Path | None
|
|
53
|
+
action_files: int
|
|
54
|
+
action_bytes: int
|
|
55
|
+
timestamp: str
|
|
56
|
+
|
|
57
|
+
@property
|
|
58
|
+
def total_bytes(self) -> int:
|
|
59
|
+
return self.receipt_bytes + self.action_bytes
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
def _is_canonical_uuid(value: object) -> bool:
|
|
63
|
+
if not isinstance(value, str) or not value:
|
|
64
|
+
return False
|
|
65
|
+
try:
|
|
66
|
+
return str(uuid.UUID(value)) == value
|
|
67
|
+
except ValueError:
|
|
68
|
+
return False
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
def _parse_iso(value: object) -> datetime | None:
|
|
72
|
+
if not isinstance(value, str) or not value:
|
|
73
|
+
return None
|
|
74
|
+
try:
|
|
75
|
+
parsed = datetime.fromisoformat(value)
|
|
76
|
+
except ValueError:
|
|
77
|
+
return None
|
|
78
|
+
return parsed.astimezone(UTC) if parsed.tzinfo is not None else parsed.replace(tzinfo=UTC)
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
def _protected_receipt_ids(store: MetadataStore) -> set[str]:
|
|
82
|
+
"""Collect every receipt/transaction id referenced by retained journals or recoveries."""
|
|
83
|
+
protected: set[str] = set()
|
|
84
|
+
if store.transactions_dir.is_dir():
|
|
85
|
+
for entry in store.transactions_dir.iterdir():
|
|
86
|
+
if entry.name.endswith(".json"):
|
|
87
|
+
protected.add(entry.stem)
|
|
88
|
+
if store.cleanup_recoveries_dir.is_dir():
|
|
89
|
+
for tx_dir in store.cleanup_recoveries_dir.iterdir():
|
|
90
|
+
if not tx_dir.is_dir() or tx_dir.is_symlink():
|
|
91
|
+
continue
|
|
92
|
+
protected.add(tx_dir.name)
|
|
93
|
+
for candidate in tx_dir.rglob("*.json"):
|
|
94
|
+
if candidate.is_symlink() or not candidate.is_file():
|
|
95
|
+
continue
|
|
96
|
+
try:
|
|
97
|
+
doc = json.loads(candidate.read_bytes())
|
|
98
|
+
except (OSError, UnicodeError, json.JSONDecodeError):
|
|
99
|
+
# Fail closed: unreadable recovery evidence protects its subtree.
|
|
100
|
+
protected.add(candidate.stem)
|
|
101
|
+
continue
|
|
102
|
+
if not isinstance(doc, dict):
|
|
103
|
+
continue
|
|
104
|
+
for key in ("completion_receipt_id", "original_transaction_id", "transaction_id"):
|
|
105
|
+
val = doc.get(key)
|
|
106
|
+
if isinstance(val, str) and val:
|
|
107
|
+
protected.add(val)
|
|
108
|
+
ref = doc.get("refusal_receipt")
|
|
109
|
+
if isinstance(ref, dict) and isinstance(ref.get("path"), str):
|
|
110
|
+
protected.add(Path(ref["path"]).stem)
|
|
111
|
+
return protected
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
def _non_terminal_intent_allocations(snapshot: MetadataSnapshot) -> set[str]:
|
|
115
|
+
active: set[str] = set()
|
|
116
|
+
for intent in snapshot.integration_intents.values():
|
|
117
|
+
if effective_intent_state(snapshot, intent) not in TERMINAL_INTENT_STATES:
|
|
118
|
+
if intent.allocation_id:
|
|
119
|
+
active.add(intent.allocation_id)
|
|
120
|
+
active.update(intent.source_allocations)
|
|
121
|
+
return active
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
def _measure_action_dir(action_dir: Path) -> tuple[int, int] | None:
|
|
125
|
+
"""Measure regular files inside a cleanup-actions/<id> directory; return None if unsafe."""
|
|
126
|
+
try:
|
|
127
|
+
info = os.lstat(action_dir)
|
|
128
|
+
except FileNotFoundError:
|
|
129
|
+
return 0, 0
|
|
130
|
+
except OSError:
|
|
131
|
+
return None
|
|
132
|
+
if not stat.S_ISDIR(info.st_mode):
|
|
133
|
+
return None
|
|
134
|
+
files = 0
|
|
135
|
+
total = 0
|
|
136
|
+
try:
|
|
137
|
+
for entry in os.scandir(action_dir):
|
|
138
|
+
st = entry.stat(follow_symlinks=False)
|
|
139
|
+
if not stat.S_ISREG(st.st_mode):
|
|
140
|
+
return None
|
|
141
|
+
files += 1
|
|
142
|
+
total += st.st_size
|
|
143
|
+
except OSError:
|
|
144
|
+
return None
|
|
145
|
+
return files, total
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
def _remove_action_dir_safe(action_dir: Path) -> tuple[int, int]:
|
|
149
|
+
"""Safely remove regular files in cleanup-actions/<id>/ and rmdir it."""
|
|
150
|
+
removed_files = 0
|
|
151
|
+
removed_bytes = 0
|
|
152
|
+
try:
|
|
153
|
+
info = os.lstat(action_dir)
|
|
154
|
+
except FileNotFoundError:
|
|
155
|
+
return 0, 0
|
|
156
|
+
if not stat.S_ISDIR(info.st_mode):
|
|
157
|
+
raise ControllerError(
|
|
158
|
+
"CLEANUP_RETENTION_UNSAFE", f"cleanup action entry is not a directory: {action_dir}"
|
|
159
|
+
)
|
|
160
|
+
entries = list(os.scandir(action_dir))
|
|
161
|
+
for entry in entries:
|
|
162
|
+
st = entry.stat(follow_symlinks=False)
|
|
163
|
+
if not stat.S_ISREG(st.st_mode):
|
|
164
|
+
raise ControllerError(
|
|
165
|
+
"CLEANUP_RETENTION_UNSAFE", f"unexpected non-regular cleanup file: {entry.path}"
|
|
166
|
+
)
|
|
167
|
+
for entry in entries:
|
|
168
|
+
st = entry.stat(follow_symlinks=False)
|
|
169
|
+
os.unlink(entry.path)
|
|
170
|
+
removed_files += 1
|
|
171
|
+
removed_bytes += st.st_size
|
|
172
|
+
os.rmdir(action_dir)
|
|
173
|
+
_fsync_dir(action_dir.parent)
|
|
174
|
+
return removed_files, removed_bytes
|
|
175
|
+
|
|
176
|
+
|
|
177
|
+
def _fsync_dir(directory: Path) -> None:
|
|
178
|
+
try:
|
|
179
|
+
fd = os.open(directory, os.O_RDONLY | os.O_DIRECTORY | os.O_CLOEXEC)
|
|
180
|
+
except OSError:
|
|
181
|
+
return
|
|
182
|
+
try:
|
|
183
|
+
os.fsync(fd)
|
|
184
|
+
finally:
|
|
185
|
+
os.close(fd)
|
|
186
|
+
|
|
187
|
+
|
|
188
|
+
def plan_terminal_cleanup_retention_locked(
|
|
189
|
+
repository: RepositoryInventory,
|
|
190
|
+
store: MetadataStore,
|
|
191
|
+
snapshot: MetadataSnapshot,
|
|
192
|
+
*,
|
|
193
|
+
keep_recent: int = 0,
|
|
194
|
+
older_than_days: float = 0.0,
|
|
195
|
+
max_total_bytes: int | None = None,
|
|
196
|
+
keep_allocations: frozenset[str] = frozenset(),
|
|
197
|
+
) -> dict[str, Any]:
|
|
198
|
+
"""Identify strictly proven terminal RELEASED cleanup evidence eligible for pruning."""
|
|
199
|
+
if keep_recent < 0 or older_than_days < 0:
|
|
200
|
+
raise ControllerError(
|
|
201
|
+
"INVALID_REQUEST", "keep_recent and older_than_days must be non-negative"
|
|
202
|
+
)
|
|
203
|
+
if max_total_bytes is not None and max_total_bytes < 0:
|
|
204
|
+
raise ControllerError("INVALID_REQUEST", "max_total_bytes must be non-negative")
|
|
205
|
+
|
|
206
|
+
protected_ids = _protected_receipt_ids(store)
|
|
207
|
+
active_intent_allocs = _non_terminal_intent_allocations(snapshot)
|
|
208
|
+
bound_allocs = set(snapshot.bindings.values())
|
|
209
|
+
leased_allocs = set(snapshot.writer_leases)
|
|
210
|
+
pub_alloc = snapshot.publication_lease.allocation_id if snapshot.publication_lease else None
|
|
211
|
+
live_worktree_paths = {str(item.path.resolve(strict=False)) for item in repository.worktrees}
|
|
212
|
+
|
|
213
|
+
release_receipts_by_alloc: dict[str, list[Any]] = {}
|
|
214
|
+
for rr in snapshot.release_receipts.values():
|
|
215
|
+
if rr.result == "RELEASED":
|
|
216
|
+
release_receipts_by_alloc.setdefault(rr.allocation_id, []).append(rr)
|
|
217
|
+
|
|
218
|
+
candidates: list[PrunableCleanupEntry] = []
|
|
219
|
+
skipped: dict[str, int] = {}
|
|
220
|
+
scanned_receipts = 0
|
|
221
|
+
|
|
222
|
+
def skip(reason: str) -> None:
|
|
223
|
+
skipped[reason] = skipped.get(reason, 0) + 1
|
|
224
|
+
|
|
225
|
+
if store.completion_receipts_dir.is_dir():
|
|
226
|
+
for entry in sorted(os.scandir(store.completion_receipts_dir), key=lambda e: e.name):
|
|
227
|
+
if not entry.name.endswith(".json") or entry.name.startswith("."):
|
|
228
|
+
continue
|
|
229
|
+
scanned_receipts += 1
|
|
230
|
+
path = Path(entry.path)
|
|
231
|
+
receipt_id = path.stem
|
|
232
|
+
try:
|
|
233
|
+
st = entry.stat(follow_symlinks=False)
|
|
234
|
+
except OSError:
|
|
235
|
+
skip("unreadable")
|
|
236
|
+
continue
|
|
237
|
+
if not stat.S_ISREG(st.st_mode):
|
|
238
|
+
skip("non_regular")
|
|
239
|
+
continue
|
|
240
|
+
if not _is_canonical_uuid(receipt_id):
|
|
241
|
+
skip("non_uuid")
|
|
242
|
+
continue
|
|
243
|
+
if receipt_id in protected_ids:
|
|
244
|
+
skip("referenced_by_transaction_or_recovery")
|
|
245
|
+
continue
|
|
246
|
+
try:
|
|
247
|
+
doc = json.loads(path.read_bytes())
|
|
248
|
+
except (OSError, UnicodeError, json.JSONDecodeError):
|
|
249
|
+
skip("unreadable")
|
|
250
|
+
continue
|
|
251
|
+
if not isinstance(doc, dict):
|
|
252
|
+
skip("invalid_document")
|
|
253
|
+
continue
|
|
254
|
+
contract = doc.get("contract")
|
|
255
|
+
if contract not in PRUNABLE_CLEANUP_CONTRACTS:
|
|
256
|
+
skip("non_prunable_contract")
|
|
257
|
+
continue
|
|
258
|
+
if doc.get("receipt_id") != receipt_id:
|
|
259
|
+
skip("receipt_id_mismatch")
|
|
260
|
+
continue
|
|
261
|
+
plan_obj = doc.get("plan") if isinstance(doc.get("plan"), dict) else {}
|
|
262
|
+
allocation_id = doc.get("allocation_id") or plan_obj.get("allocation_id")
|
|
263
|
+
if not _is_canonical_uuid(allocation_id):
|
|
264
|
+
skip("missing_allocation_id")
|
|
265
|
+
continue
|
|
266
|
+
assert isinstance(allocation_id, str)
|
|
267
|
+
if allocation_id in keep_allocations:
|
|
268
|
+
skip("explicitly_kept_allocation")
|
|
269
|
+
continue
|
|
270
|
+
record = snapshot.records.get(allocation_id)
|
|
271
|
+
if record is None or record.lifecycle != "RELEASED":
|
|
272
|
+
skip("allocation_not_released")
|
|
273
|
+
continue
|
|
274
|
+
if (
|
|
275
|
+
allocation_id in bound_allocs
|
|
276
|
+
or allocation_id in leased_allocs
|
|
277
|
+
or allocation_id == pub_alloc
|
|
278
|
+
or allocation_id in active_intent_allocs
|
|
279
|
+
):
|
|
280
|
+
skip("allocation_still_referenced")
|
|
281
|
+
continue
|
|
282
|
+
matching_releases = [
|
|
283
|
+
rr
|
|
284
|
+
for rr in release_receipts_by_alloc.get(allocation_id, ())
|
|
285
|
+
if rr.released_record_version == record.record_version
|
|
286
|
+
]
|
|
287
|
+
if len(matching_releases) != 1:
|
|
288
|
+
skip("missing_exact_release_receipt")
|
|
289
|
+
continue
|
|
290
|
+
target_path = plan_obj.get("target_path")
|
|
291
|
+
if isinstance(target_path, str) and target_path:
|
|
292
|
+
resolved_target = str(Path(target_path).resolve(strict=False))
|
|
293
|
+
if resolved_target in live_worktree_paths or os.path.lexists(target_path):
|
|
294
|
+
skip("target_still_present")
|
|
295
|
+
continue
|
|
296
|
+
action_dir = store.cleanup_actions_dir / receipt_id
|
|
297
|
+
action_info = _measure_action_dir(action_dir)
|
|
298
|
+
if action_info is None:
|
|
299
|
+
skip("unsafe_action_dir")
|
|
300
|
+
continue
|
|
301
|
+
action_files, action_bytes = action_info
|
|
302
|
+
timestamp = str(matching_releases[0].released_at or doc.get("created_at") or "")
|
|
303
|
+
candidates.append(
|
|
304
|
+
PrunableCleanupEntry(
|
|
305
|
+
receipt_id=receipt_id,
|
|
306
|
+
allocation_id=allocation_id,
|
|
307
|
+
contract=str(contract),
|
|
308
|
+
receipt_path=path,
|
|
309
|
+
receipt_bytes=st.st_size,
|
|
310
|
+
action_dir=action_dir if action_dir.exists() else None,
|
|
311
|
+
action_files=action_files,
|
|
312
|
+
action_bytes=action_bytes,
|
|
313
|
+
timestamp=timestamp,
|
|
314
|
+
)
|
|
315
|
+
)
|
|
316
|
+
|
|
317
|
+
# Sort newest-first so retention windows always preserve the freshest receipts.
|
|
318
|
+
candidates.sort(key=lambda item: (item.timestamp, item.receipt_id), reverse=True)
|
|
319
|
+
cutoff = datetime.now(UTC) - timedelta(days=older_than_days) if older_than_days > 0 else None
|
|
320
|
+
|
|
321
|
+
eligible: list[PrunableCleanupEntry] = []
|
|
322
|
+
kept: list[PrunableCleanupEntry] = []
|
|
323
|
+
kept_bytes = 0
|
|
324
|
+
for item in candidates:
|
|
325
|
+
if cutoff is not None:
|
|
326
|
+
ts = _parse_iso(item.timestamp)
|
|
327
|
+
if ts is None or ts > cutoff:
|
|
328
|
+
kept.append(item)
|
|
329
|
+
kept_bytes += item.total_bytes
|
|
330
|
+
continue
|
|
331
|
+
if len(kept) < keep_recent and (
|
|
332
|
+
max_total_bytes is None or kept_bytes + item.total_bytes <= max_total_bytes
|
|
333
|
+
):
|
|
334
|
+
kept.append(item)
|
|
335
|
+
kept_bytes += item.total_bytes
|
|
336
|
+
continue
|
|
337
|
+
eligible.append(item)
|
|
338
|
+
|
|
339
|
+
return {
|
|
340
|
+
"scanned_receipts": scanned_receipts,
|
|
341
|
+
"protected_ids_count": len(protected_ids),
|
|
342
|
+
"skipped": dict(sorted(skipped.items())),
|
|
343
|
+
"kept": kept,
|
|
344
|
+
"kept_bytes": kept_bytes,
|
|
345
|
+
"eligible": eligible,
|
|
346
|
+
"eligible_receipts": len(eligible),
|
|
347
|
+
"eligible_action_dirs": sum(1 for item in eligible if item.action_dir is not None),
|
|
348
|
+
"eligible_action_files": sum(item.action_files for item in eligible),
|
|
349
|
+
"eligible_receipt_bytes": sum(item.receipt_bytes for item in eligible),
|
|
350
|
+
"eligible_action_bytes": sum(item.action_bytes for item in eligible),
|
|
351
|
+
"eligible_total_bytes": sum(item.total_bytes for item in eligible),
|
|
352
|
+
}
|
|
353
|
+
|
|
354
|
+
|
|
355
|
+
def apply_terminal_cleanup_plan_locked(plan: dict[str, Any]) -> dict[str, Any]:
|
|
356
|
+
"""Execute a verified retention plan while the caller holds exclusive repo lock.
|
|
357
|
+
|
|
358
|
+
Removes ``cleanup-actions/<id>/`` strictly before ``completion-receipts/<id>.json``
|
|
359
|
+
so no orphaned cleanup-actions directory can ever exist.
|
|
360
|
+
"""
|
|
361
|
+
pruned_receipts = 0
|
|
362
|
+
pruned_action_dirs = 0
|
|
363
|
+
pruned_action_files = 0
|
|
364
|
+
reclaimed_action_bytes = 0
|
|
365
|
+
reclaimed_receipt_bytes = 0
|
|
366
|
+
receipt_parent: Path | None = None
|
|
367
|
+
|
|
368
|
+
for item in plan["eligible"]:
|
|
369
|
+
assert isinstance(item, PrunableCleanupEntry)
|
|
370
|
+
if item.action_dir is not None and item.action_dir.exists():
|
|
371
|
+
files_removed, bytes_removed = _remove_action_dir_safe(item.action_dir)
|
|
372
|
+
pruned_action_dirs += 1
|
|
373
|
+
pruned_action_files += files_removed
|
|
374
|
+
reclaimed_action_bytes += bytes_removed
|
|
375
|
+
with suppress(FileNotFoundError):
|
|
376
|
+
os.unlink(item.receipt_path)
|
|
377
|
+
pruned_receipts += 1
|
|
378
|
+
reclaimed_receipt_bytes += item.receipt_bytes
|
|
379
|
+
receipt_parent = item.receipt_path.parent
|
|
380
|
+
if receipt_parent is not None:
|
|
381
|
+
_fsync_dir(receipt_parent)
|
|
382
|
+
|
|
383
|
+
return {
|
|
384
|
+
"pruned_receipts": pruned_receipts,
|
|
385
|
+
"pruned_action_dirs": pruned_action_dirs,
|
|
386
|
+
"pruned_action_files": pruned_action_files,
|
|
387
|
+
"reclaimed_action_bytes": reclaimed_action_bytes,
|
|
388
|
+
"reclaimed_receipt_bytes": reclaimed_receipt_bytes,
|
|
389
|
+
"bytes_reclaimed": reclaimed_action_bytes + reclaimed_receipt_bytes,
|
|
390
|
+
}
|
|
391
|
+
|
|
392
|
+
|
|
393
|
+
def auto_prune_terminal_cleanup_locked(
|
|
394
|
+
repository: RepositoryInventory,
|
|
395
|
+
store: MetadataStore,
|
|
396
|
+
snapshot: MetadataSnapshot,
|
|
397
|
+
*,
|
|
398
|
+
keep_allocations: frozenset[str] = frozenset(),
|
|
399
|
+
keep_recent: int | None = None,
|
|
400
|
+
max_total_bytes: int | None = None,
|
|
401
|
+
) -> dict[str, Any]:
|
|
402
|
+
"""Bound historical RELEASED cleanup bloat automatically under an already-held exclusive lock."""
|
|
403
|
+
if not store.completion_receipts_dir.is_dir():
|
|
404
|
+
return {"pruned_receipts": 0, "pruned_action_dirs": 0, "bytes_reclaimed": 0}
|
|
405
|
+
effective_keep_recent = DEFAULT_AUTO_KEEP_RECENT if keep_recent is None else keep_recent
|
|
406
|
+
effective_max_bytes = DEFAULT_AUTO_MAX_BYTES if max_total_bytes is None else max_total_bytes
|
|
407
|
+
plan = plan_terminal_cleanup_retention_locked(
|
|
408
|
+
repository,
|
|
409
|
+
store,
|
|
410
|
+
snapshot,
|
|
411
|
+
keep_recent=effective_keep_recent,
|
|
412
|
+
max_total_bytes=effective_max_bytes,
|
|
413
|
+
keep_allocations=keep_allocations,
|
|
414
|
+
)
|
|
415
|
+
if not plan["eligible"]:
|
|
416
|
+
return {"pruned_receipts": 0, "pruned_action_dirs": 0, "bytes_reclaimed": 0}
|
|
417
|
+
return apply_terminal_cleanup_plan_locked(plan)
|
|
418
|
+
|
|
419
|
+
|
|
420
|
+
def reconcile_cleanup_evidence(
|
|
421
|
+
repository_path: Path,
|
|
422
|
+
*,
|
|
423
|
+
apply: bool = False,
|
|
424
|
+
keep_recent: int = 0,
|
|
425
|
+
older_than_days: float = 0.0,
|
|
426
|
+
max_total_bytes: int | None = None,
|
|
427
|
+
) -> dict[str, Any]:
|
|
428
|
+
"""Dry-run plan or apply pruning of terminal RELEASED cleanup-actions & completion-receipts."""
|
|
429
|
+
from .controller import compact_status
|
|
430
|
+
|
|
431
|
+
repository = inventory(repository_path, observe_paths=frozenset())
|
|
432
|
+
store = MetadataStore(repository.common_dir)
|
|
433
|
+
with store.lock(exclusive=apply):
|
|
434
|
+
live_repo = inventory(repository.canonical_path, observe_paths=frozenset())
|
|
435
|
+
snapshot = store._load_unlocked()
|
|
436
|
+
plan = plan_terminal_cleanup_retention_locked(
|
|
437
|
+
live_repo,
|
|
438
|
+
store,
|
|
439
|
+
snapshot,
|
|
440
|
+
keep_recent=keep_recent,
|
|
441
|
+
older_than_days=older_than_days,
|
|
442
|
+
max_total_bytes=max_total_bytes,
|
|
443
|
+
)
|
|
444
|
+
applied = apply_terminal_cleanup_plan_locked(plan) if apply else None
|
|
445
|
+
|
|
446
|
+
payload = compact_status(repository.canonical_path, command="reconcile")
|
|
447
|
+
payload["decision"] = {
|
|
448
|
+
"code": "CLEANUP_EVIDENCE_PRUNED" if apply else "CLEANUP_EVIDENCE_PLAN",
|
|
449
|
+
"reason": (
|
|
450
|
+
"verified terminal RELEASED cleanup evidence pruned"
|
|
451
|
+
if apply
|
|
452
|
+
else "verified terminal RELEASED cleanup evidence plan (dry-run)"
|
|
453
|
+
),
|
|
454
|
+
"apply": apply,
|
|
455
|
+
"dry_run": not apply,
|
|
456
|
+
"policy": {
|
|
457
|
+
"keep_recent": keep_recent,
|
|
458
|
+
"older_than_days": older_than_days,
|
|
459
|
+
"max_total_bytes": max_total_bytes,
|
|
460
|
+
"prunable_contracts": sorted(PRUNABLE_CLEANUP_CONTRACTS),
|
|
461
|
+
},
|
|
462
|
+
"scanned_receipts": plan["scanned_receipts"],
|
|
463
|
+
"protected_ids_count": plan["protected_ids_count"],
|
|
464
|
+
"skipped": plan["skipped"],
|
|
465
|
+
"kept_count": len(plan["kept"]),
|
|
466
|
+
"kept_bytes": plan["kept_bytes"],
|
|
467
|
+
"eligible_receipts": plan["eligible_receipts"],
|
|
468
|
+
"eligible_action_dirs": plan["eligible_action_dirs"],
|
|
469
|
+
"eligible_action_files": plan["eligible_action_files"],
|
|
470
|
+
"eligible_receipt_bytes": plan["eligible_receipt_bytes"],
|
|
471
|
+
"eligible_action_bytes": plan["eligible_action_bytes"],
|
|
472
|
+
"eligible_total_bytes": plan["eligible_total_bytes"],
|
|
473
|
+
**({"result": applied} if applied is not None else {}),
|
|
474
|
+
}
|
|
475
|
+
return payload
|