mindslice 0.1.0__py3-none-any.whl

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 (50) hide show
  1. mindslice/__init__.py +58 -0
  2. mindslice/__main__.py +5 -0
  3. mindslice/baking/__init__.py +1 -0
  4. mindslice/baking/archive.py +66 -0
  5. mindslice/baking/bake.py +299 -0
  6. mindslice/baking/bake_batch.py +537 -0
  7. mindslice/baking/slice_transfer.py +265 -0
  8. mindslice/errors.py +104 -0
  9. mindslice/interfaces/__init__.py +1 -0
  10. mindslice/interfaces/bake_review.py +230 -0
  11. mindslice/interfaces/cli.py +392 -0
  12. mindslice/interfaces/cli_addressing.py +52 -0
  13. mindslice/interfaces/doctor.py +184 -0
  14. mindslice/interfaces/mcp_server.py +536 -0
  15. mindslice/interfaces/render.py +346 -0
  16. mindslice/interfaces/staging_review.py +92 -0
  17. mindslice/model/__init__.py +1 -0
  18. mindslice/model/addressing.py +251 -0
  19. mindslice/model/card.py +641 -0
  20. mindslice/model/lineage.py +228 -0
  21. mindslice/model/text.py +19 -0
  22. mindslice/model/tomlfmt.py +129 -0
  23. mindslice/operations/__init__.py +1 -0
  24. mindslice/operations/audit.py +195 -0
  25. mindslice/operations/boot.py +183 -0
  26. mindslice/operations/impact.py +98 -0
  27. mindslice/operations/recovery.py +113 -0
  28. mindslice/operations/staging.py +641 -0
  29. mindslice/operations/status.py +137 -0
  30. mindslice/operations/validation.py +250 -0
  31. mindslice/operations/writer.py +481 -0
  32. mindslice/retrieval/__init__.py +1 -0
  33. mindslice/retrieval/index.py +634 -0
  34. mindslice/retrieval/lexical.py +215 -0
  35. mindslice/retrieval/query.py +593 -0
  36. mindslice/storage/__init__.py +1 -0
  37. mindslice/storage/card_io.py +14 -0
  38. mindslice/storage/config.py +192 -0
  39. mindslice/storage/fsutil.py +141 -0
  40. mindslice/storage/history.py +182 -0
  41. mindslice/storage/locking.py +125 -0
  42. mindslice/storage/snapshots.py +262 -0
  43. mindslice/workspace.py +385 -0
  44. mindslice-0.1.0.dist-info/METADATA +98 -0
  45. mindslice-0.1.0.dist-info/RECORD +50 -0
  46. mindslice-0.1.0.dist-info/WHEEL +5 -0
  47. mindslice-0.1.0.dist-info/entry_points.txt +2 -0
  48. mindslice-0.1.0.dist-info/licenses/LICENSE +202 -0
  49. mindslice-0.1.0.dist-info/licenses/NOTICE +22 -0
  50. mindslice-0.1.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,641 @@
1
+ """Transactional sandbox: ``staging/`` buffer, ``diff()``, journaled ``apply()`` and ``discard()``.
2
+
3
+ ``staging/<id>.md`` is the complete prospective content of ``overlay/<id>.md``.
4
+ ``staging/.manifest.json`` records, per id, the ``base_sha256`` of the overlay
5
+ file when it was first staged (``null`` = "must still be absent") and
6
+ deletion tombstones. ``staging/.apply_journal.json`` exists only while an
7
+ ``apply()`` batch is in flight and is removed strictly last, so any process
8
+ that finds it can finish the batch idempotently.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import difflib
14
+ import hashlib
15
+ import json
16
+ import os
17
+ import time
18
+ from pathlib import Path
19
+ from typing import TYPE_CHECKING, Any
20
+
21
+ from ..model.addressing import format_address, parse_address, resolve_ref
22
+ from ..model.card import ParsedCard, parse_card
23
+ from ..errors import ApplyConflictError, InvalidArgumentsError, LineageCycleError
24
+ from ..storage.fsutil import atomic_write_text, durable_move, fsync_dir, iter_markdown, prune_empty_dirs, unlink_if_exists
25
+ from ..storage.history import change, file_action, transitions
26
+ from .writer import check_cycles, prospective_successors
27
+ from .impact import inbound_impact, supersede_targets
28
+ from ..storage.card_io import read_card_file
29
+
30
+ if TYPE_CHECKING: # pragma: no cover
31
+ from ..storage.config import MountTable
32
+ from ..workspace import Workspace
33
+
34
+ MANIFEST_FILE = ".manifest.json"
35
+ JOURNAL_FILE = ".apply_journal.json"
36
+
37
+
38
+ def _now() -> str:
39
+ return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
40
+
41
+
42
+ def _short(sha: str | None) -> str:
43
+ return sha[:12] if sha else "absent"
44
+
45
+
46
+ def precondition_conflict(base: str | None, current: str | None) -> str | None:
47
+ if base == current:
48
+ return None
49
+ if base is None:
50
+ return f"expected absent, found {_short(current)}"
51
+ if current is None:
52
+ return f"expected {_short(base)}, found absent"
53
+ return f"expected {_short(base)}, found {_short(current)}"
54
+
55
+
56
+ def unified(before: str | None, after: str | None, before_label: str, after_label: str) -> str:
57
+ a = (before or "").splitlines(keepends=True)
58
+ b = (after or "").splitlines(keepends=True)
59
+ lines = difflib.unified_diff(
60
+ a, b, fromfile=before_label if before is not None else "/dev/null",
61
+ tofile=after_label if after is not None else "/dev/null",
62
+ )
63
+ out = []
64
+ for line in lines:
65
+ out.append(line if line.endswith("\n") else line + "\n\\n")
66
+ return "".join(out)
67
+
68
+
69
+ class StagingArea:
70
+ def __init__(self, root: Path) -> None:
71
+ self.root = root
72
+
73
+ # -- files -----------------------------------------------------------
74
+ @property
75
+ def manifest_path(self) -> Path:
76
+ return self.root / MANIFEST_FILE
77
+
78
+ @property
79
+ def journal_path(self) -> Path:
80
+ return self.root / JOURNAL_FILE
81
+
82
+ def file(self, path: str) -> Path:
83
+ return self.root / f"{path}.md"
84
+
85
+ def has_journal(self) -> bool:
86
+ return self.journal_path.exists()
87
+
88
+ def load_manifest(self) -> dict[str, dict[str, Any]]:
89
+ try:
90
+ data = json.loads(self.manifest_path.read_text(encoding="utf-8"))
91
+ except FileNotFoundError:
92
+ return {}
93
+ entries = data.get("entries", {}) if isinstance(data, dict) else {}
94
+ return {k: dict(v) for k, v in entries.items() if isinstance(v, dict)}
95
+
96
+ def manifest_text(self, entries: dict[str, dict[str, Any]]) -> str | None:
97
+ if not entries:
98
+ return None
99
+ payload = {"version": 1, "entries": dict(sorted(entries.items()))}
100
+ return json.dumps(payload, indent=2, ensure_ascii=False) + "\n"
101
+
102
+ def save_manifest(self, entries: dict[str, dict[str, Any]]) -> None:
103
+ if not entries:
104
+ unlink_if_exists(self.manifest_path)
105
+ return
106
+ atomic_write_text(self.manifest_path, self.manifest_text(entries))
107
+
108
+ def staged_files(self) -> dict[str, Path]:
109
+ return {rel: self.file(rel) for rel, _ in iter_markdown(self.root)}
110
+
111
+ def entries(self) -> dict[str, dict[str, Any]]:
112
+ """Manifest entries plus orphan staged files (treated as creates that require absence)."""
113
+ out = self.load_manifest()
114
+ for path in self.staged_files():
115
+ if path not in out:
116
+ out[path] = {"op": "write", "base_sha256": None, "history": [], "orphan": True}
117
+ return dict(sorted(out.items()))
118
+
119
+ # -- prospective state ----------------------------------------------
120
+ def prospective_state(self, path: str, overlay_root: Path) -> tuple[str | None, str | None]:
121
+ entry = self.load_manifest().get(path)
122
+ if entry is not None and entry.get("op") == "delete":
123
+ return None, None
124
+ staged = read_card_file(self.file(path))
125
+ if staged[0] is not None:
126
+ return staged
127
+ return read_card_file(overlay_root / f"{path}.md")
128
+
129
+ def prospective_overrides(self, overlay_root: Path) -> dict[str, ParsedCard | None]:
130
+ overrides: dict[str, ParsedCard | None] = {}
131
+ for path, entry in self.entries().items():
132
+ if entry.get("op") == "delete":
133
+ overrides[path] = None
134
+ continue
135
+ text, _ = read_card_file(self.file(path))
136
+ if text is not None:
137
+ overrides[path] = parse_card(text)
138
+ return overrides
139
+
140
+ # -- staged mutations -------------------------------------------------
141
+ def _mutate(self, path, manifest, text, audit=None, events=None):
142
+ if audit is None:
143
+ self.save_manifest(manifest)
144
+ if text is None:
145
+ self._drop_file(self.file(path))
146
+ else:
147
+ atomic_write_text(self.file(path), text)
148
+ else:
149
+ audit.transact([file_action(self.manifest_path, self.manifest_text(manifest)),
150
+ file_action(self.file(path), text, self.root)], events or [])
151
+
152
+ def stage_write(self, path: str, text: str, overlay_root: Path, op: str, requires_approval: str | None = None,
153
+ *, audit=None, event=None) -> None:
154
+ manifest = self.load_manifest()
155
+ entry = manifest.get(path)
156
+ if entry is None:
157
+ _, base = read_card_file(overlay_root / f"{path}.md")
158
+ entry = {"op": "write", "base_sha256": base, "history": []}
159
+ entry["op"] = "write"
160
+ entry["history"] = list(entry.get("history") or []) + [op]
161
+ entry["updated_at"] = _now()
162
+ if requires_approval:
163
+ entry["requires_approval"] = requires_approval
164
+ if event:
165
+ entry["change_ids"] = list(entry.get("change_ids", [])) + [event["change_id"]]
166
+ manifest[path] = entry
167
+ self._mutate(path, manifest, text, audit, [event] if event else [])
168
+
169
+ def stage_delete(self, path: str, overlay_root: Path, requires_approval: str | None = None,
170
+ *, audit=None, event=None) -> bool:
171
+ manifest = self.load_manifest()
172
+ entry = manifest.get(path)
173
+ if entry is None:
174
+ _, base = read_card_file(overlay_root / f"{path}.md")
175
+ entry = {"op": "write", "base_sha256": base, "history": []}
176
+ events = [event] if event else []
177
+ ids = list(entry.get("change_ids", []))
178
+ if event:
179
+ ids.append(event["change_id"])
180
+ if entry.get("base_sha256") is None:
181
+ # Cancel the entire proposed revision chain, including this delete request.
182
+ manifest.pop(path, None)
183
+ events += transitions("discarded", ids, cause="staged_create_deleted")
184
+ else:
185
+ if entry.get("op") == "delete":
186
+ return self._drop_file(self.file(path))
187
+ entry["op"] = "delete"
188
+ entry["history"] = list(entry.get("history") or []) + ["delete"]
189
+ entry["updated_at"] = _now()
190
+ if requires_approval:
191
+ entry["requires_approval"] = requires_approval
192
+ if ids:
193
+ entry["change_ids"] = ids
194
+ manifest[path] = entry
195
+ self._mutate(path, manifest, None, audit, events)
196
+ return True
197
+
198
+ def _drop_file(self, file: Path) -> bool:
199
+ removed = unlink_if_exists(file)
200
+ if removed:
201
+ prune_empty_dirs(self.root, file.parent)
202
+ return removed
203
+
204
+ # -- journal ----------------------------------------------------------
205
+ def write_journal(self, journal: dict[str, Any]) -> None:
206
+ self.root.mkdir(parents=True, exist_ok=True)
207
+ atomic_write_text(self.journal_path, json.dumps(journal, indent=2, ensure_ascii=False) + "\n")
208
+
209
+ def read_journal(self) -> dict[str, Any] | None:
210
+ try:
211
+ return json.loads(self.journal_path.read_text(encoding="utf-8"))
212
+ except FileNotFoundError:
213
+ return None
214
+ except (json.JSONDecodeError, UnicodeDecodeError):
215
+ # The journal is written atomically, so this means on-disk corruption. Nothing
216
+ # can be safely replayed; the caller quarantines it and leaves staging untouched.
217
+ return {"actions": [], "corrupt": True}
218
+
219
+ def quarantine_journal(self) -> Path:
220
+ target = self.root / f".apply_journal.corrupt-{time.strftime('%Y%m%dT%H%M%S', time.gmtime())}.json"
221
+ os.replace(self.journal_path, target)
222
+ fsync_dir(self.root)
223
+ return target
224
+
225
+ def remove_empty_subdirs(self) -> None:
226
+ if not self.root.is_dir():
227
+ return
228
+ for dirpath, dirnames, filenames in os.walk(self.root, topdown=False):
229
+ if Path(dirpath) == self.root:
230
+ continue
231
+ try:
232
+ os.rmdir(dirpath)
233
+ except OSError:
234
+ pass
235
+ fsync_dir(self.root)
236
+
237
+
238
+ # ---------------------------------------------------------------------------
239
+ # diff()
240
+ # ---------------------------------------------------------------------------
241
+
242
+
243
+ def diff(ws: "Workspace", scope: str = "staging") -> dict[str, Any]:
244
+ if scope not in ("staging", "overlay"):
245
+ raise ValueError("scope must be 'staging' or 'overlay'")
246
+ with ws._reading() as table:
247
+ if scope == "staging":
248
+ return _diff_staging(ws, table)
249
+ return _diff_overlay(ws, table)
250
+
251
+
252
+ def _diff_staging(ws: "Workspace", table: "MountTable") -> dict[str, Any]:
253
+ overlay = table.overlay
254
+ items = []
255
+ counts = {"create": 0, "modify": 0, "delete": 0, "conflicts": 0}
256
+ history_details = ws.history.details()
257
+ catalogs = ws.index.catalogs()
258
+ for path, entry in ws.staging.entries().items():
259
+ address = format_address(overlay.alias, path)
260
+ current_text, current_sha = read_card_file(overlay.root / f"{path}.md")
261
+ op = entry.get("op", "write")
262
+ staged_text, staged_sha = (None, None) if op == "delete" else read_card_file(ws.staging.file(path))
263
+ base = entry.get("base_sha256")
264
+ conflict = precondition_conflict(base, current_sha)
265
+ if op == "write" and staged_text is None:
266
+ conflict = conflict or "staged file missing"
267
+ change = "delete" if op == "delete" else ("create" if current_text is None else "modify")
268
+ counts[change] += 1
269
+ if conflict:
270
+ counts["conflicts"] += 1
271
+ item: dict[str, Any] = {
272
+ "id": path,
273
+ "address": address,
274
+ "op": op,
275
+ "change": change,
276
+ "history": entry.get("history", []),
277
+ "base_sha256": base,
278
+ "current_sha256": current_sha,
279
+ "staged_sha256": staged_sha,
280
+ "conflict": conflict,
281
+ "diff": unified(current_text, staged_text, f"a/{address}.md", f"b/{address}.md"),
282
+ }
283
+ parsed = parse_card(staged_text) if staged_text is not None else None
284
+ targets = [address] + (supersede_targets(parsed, overlay.alias, catalogs) if parsed else [])
285
+ item["impact"] = inbound_impact(ws.index, overlay.alias, overlay.precedence, targets, exclude=[address])
286
+ item["references"] = {"extends": parsed.extends, "supersedes": parsed.supersedes,
287
+ "wikilinks": parsed.wikilink_targets()} if parsed else {}
288
+ if entry.get("change_ids"):
289
+ item["change_ids"] = entry["change_ids"]
290
+ item["changes"] = ws.history.descriptions(entry["change_ids"], records=history_details)
291
+ if entry.get("orphan"):
292
+ item["orphan"] = True
293
+ if entry.get("requires_approval"):
294
+ item["requires_approval"] = entry["requires_approval"]
295
+ items.append(item)
296
+ return {
297
+ "revision": hashlib.sha256(json.dumps(items, sort_keys=True, ensure_ascii=False).encode()).hexdigest(),
298
+ "scope": "staging",
299
+ "items": items,
300
+ "summary": {"total": len(items), **counts},
301
+ "clean": counts["conflicts"] == 0,
302
+ "patch": "".join(i["diff"] for i in items),
303
+ }
304
+
305
+
306
+ def _diff_overlay(ws: "Workspace", table: "MountTable") -> dict[str, Any]:
307
+ idx = ws.index
308
+ overlay = table.overlay
309
+ items = []
310
+ counts = {"new": 0, "shadow": 0, "extends": 0, "supersedes": 0, "unrebased": 0}
311
+ history_details = ws.history.details()
312
+ active = ws.history.applied()
313
+ for row in idx.all_cards(overlay.alias):
314
+ path = row["path"]
315
+ address = format_address(overlay.alias, path)
316
+ resolved: dict[str, list[str]] = {"extends": [], "supersedes": []}
317
+ broken: list[str] = []
318
+ for link in idx.outbound(overlay.alias, path):
319
+ if link["kind"] not in resolved:
320
+ continue
321
+ if link["resolved"]:
322
+ resolved[link["kind"]].append(format_address(link["dst_mount"], link["dst_path"]))
323
+ else:
324
+ broken.append(f"{link['kind']}: {link['raw']}")
325
+ linked = set(resolved["extends"]) | set(resolved["supersedes"])
326
+ shadows = [
327
+ format_address(r["mount"], r["path"])
328
+ for r in idx.cards_at_path(path)
329
+ if r["mount"] != overlay.alias and format_address(r["mount"], r["path"]) not in linked
330
+ ]
331
+ if resolved["supersedes"]:
332
+ kind, counterpart = "supersedes", resolved["supersedes"][0]
333
+ elif resolved["extends"]:
334
+ kind, counterpart = "extends", None
335
+ elif shadows:
336
+ kind, counterpart = "shadow", shadows[0]
337
+ else:
338
+ kind, counterpart = "new", None
339
+ counts[kind] += 1
340
+ current_text, _ = read_card_file(overlay.root / f"{path}.md")
341
+ before_text = None
342
+ if counterpart:
343
+ mount, _, cpath = counterpart.partition("/")
344
+ m = table.get(mount)
345
+ if m is not None:
346
+ before_text, _ = read_card_file(m.root / f"{cpath}.md")
347
+ item: dict[str, Any] = {
348
+ "id": path,
349
+ "address": address,
350
+ "kind": kind,
351
+ "title": row["title"],
352
+ "extends": resolved["extends"],
353
+ "supersedes": resolved["supersedes"],
354
+ "shadows": shadows,
355
+ "sha256": row["sha256"],
356
+ }
357
+ tip, ids = active.get(address, (None, []))
358
+ changes = ws.history.descriptions(ids, records=history_details) if tip == row["sha256"] else []
359
+ if changes:
360
+ item["changes"] = changes
361
+ item["change_ids"] = [c["change_id"] for c in changes]
362
+ if broken:
363
+ item["unresolved"] = broken
364
+ unrebased = []
365
+ for base in resolved["extends"]:
366
+ bmount, _, bpath = base.partition("/")
367
+ replacements = [format_address(r["src_mount"], r["src_path"]) for r in idx.inbound("supersedes", bmount, bpath)]
368
+ if replacements:
369
+ unrebased.append({"baseline": base, "superseded_by": replacements})
370
+ if unrebased:
371
+ item["unrebased"] = unrebased
372
+ counts["unrebased"] += 1
373
+ before_label = f"a/{counterpart}.md" if counterpart else "/dev/null"
374
+ item["diff"] = unified(before_text, current_text, before_label, f"b/{address}.md")
375
+ items.append(item)
376
+ return {"scope": "overlay", "items": items, "summary": {"total": len(items), **counts}}
377
+
378
+
379
+ # ---------------------------------------------------------------------------
380
+ # apply() / discard() / journal replay
381
+ # ---------------------------------------------------------------------------
382
+
383
+
384
+ def select_entries(entries: dict[str, Any], ids: list[str] | None) -> dict[str, Any]:
385
+ """Select exact staging IDs; None means all, an empty list means none."""
386
+ if ids is None:
387
+ return dict(entries)
388
+ if not isinstance(ids, (list, tuple)) or any(not isinstance(value, str) for value in ids):
389
+ raise InvalidArgumentsError("card IDs must be a list of staging paths")
390
+ selected = set()
391
+ for value in ids:
392
+ alias, path = parse_address(value)
393
+ if alias not in (None, "@overlay"):
394
+ raise InvalidArgumentsError("review targets must be staging IDs or @overlay/path", address=value)
395
+ if path not in entries:
396
+ raise InvalidArgumentsError("no pending change for this card; run mindslice diff", address=value)
397
+ selected.add(path)
398
+ return {path: entry for path, entry in entries.items() if path in selected}
399
+
400
+
401
+ def dependency_conflicts(ws, table, overrides):
402
+ """Reject newly broken live links and references that need an unaccepted proposal.
403
+
404
+ Existing unresolved links remain lint concerns, not blockers for unrelated reviews.
405
+ Catalogs include aliases and obey the same slice-local resolution as normal reads.
406
+ """
407
+ alias = table.overlay.alias
408
+ before = ws.index.catalogs()
409
+ _, after = prospective_successors(ws.index, alias, overrides)
410
+ _, proposed = prospective_successors(ws.index, alias, ws.staging.prospective_overrides(table.overlay.root))
411
+ refs = []
412
+ for mount in table.all():
413
+ for row in ws.index.all_cards(mount.alias):
414
+ path = row["path"]
415
+ if mount.alias == alias and path in overrides:
416
+ continue
417
+ refs.extend((mount.alias, path, edge["kind"], edge["raw"])
418
+ for edge in ws.index.outbound(mount.alias, path))
419
+ for path, parsed in overrides.items():
420
+ if parsed is not None:
421
+ for kind, values in (("extends", parsed.extends), ("supersedes", parsed.supersedes),
422
+ ("wikilink", parsed.wikilink_targets())):
423
+ refs.extend((alias, path, kind, raw) for raw in values)
424
+ conflicts = []
425
+ for source, path, kind, raw in refs:
426
+ if resolve_ref(raw, source, after).resolved:
427
+ continue
428
+ previous = resolve_ref(raw, source, before)
429
+ pending = resolve_ref(raw, source, proposed)
430
+ selected = source == alias and path in overrides
431
+ if previous.resolved or (selected and pending.resolved):
432
+ target = previous.address if previous.resolved else pending.address
433
+ conflicts.append({"address": format_address(source, path), "reason": "dependency",
434
+ "kind": kind, "target": target,
435
+ "detail": f"{kind} {raw!r} would not resolve. Accept its pending target or dependent "
436
+ "edit together, or revise the reference before applying."})
437
+ return conflicts
438
+
439
+
440
+ def apply(ws: "Workspace", ids: list[str] | None = None, *, reject: list[str] | None = None,
441
+ revision: str | None = None, dry_run: bool = False) -> dict[str, Any]:
442
+ with ws._writing() as table:
443
+ overlay = table.overlay
444
+ staging = ws.staging
445
+ all_entries = staging.entries()
446
+ entries = select_entries(all_entries, ids)
447
+ rejected = select_entries(all_entries, reject or [])
448
+ if entries.keys() & rejected.keys():
449
+ raise InvalidArgumentsError("a pending card cannot be both accepted and rejected")
450
+ if revision is not None and revision != _diff_staging(ws, table)["revision"]:
451
+ raise ApplyConflictError("review changed; run mindslice review again before accepting or rejecting",
452
+ conflicts=[{"reason": "stale_review"}])
453
+ if not entries and not rejected and not dry_run:
454
+ return {"applied": 0, "created": [], "modified": [], "deleted": [], "skipped": []}
455
+ conflicts: list[dict[str, Any]] = []
456
+ overrides: dict[str, ParsedCard | None] = {}
457
+ actions: list[dict[str, Any]] = []
458
+ for path, entry in entries.items():
459
+ address = format_address(overlay.alias, path)
460
+ _, current_sha = read_card_file(overlay.root / f"{path}.md")
461
+ base = entry.get("base_sha256")
462
+ reason = precondition_conflict(base, current_sha)
463
+ if reason:
464
+ conflicts.append({"address": address, "reason": "precondition", "detail": reason,
465
+ "base_sha256": base, "current_sha256": current_sha})
466
+ if entry.get("op") == "delete":
467
+ overrides[path] = None
468
+ actions.append({"op": "delete", "id": path, "base_sha256": base})
469
+ continue
470
+ staged_text, staged_sha = read_card_file(staging.file(path))
471
+ if staged_text is None:
472
+ conflicts.append({"address": address, "reason": "staged_file_missing"})
473
+ continue
474
+ parsed = parse_card(staged_text)
475
+ if parsed.errors:
476
+ conflicts.append({"address": address, "reason": "invalid_card", "detail": "; ".join(parsed.errors)})
477
+ overrides[path] = parsed
478
+ actions.append({
479
+ "op": "move", "id": path, "base_sha256": base, "sha256": staged_sha,
480
+ "change": "create" if current_sha is None else "modify",
481
+ })
482
+ for path in [p for p, parsed in overrides.items() if parsed is not None]:
483
+ try:
484
+ check_cycles(ws.index, overlay.alias, overrides, [path])
485
+ except LineageCycleError as exc:
486
+ conflicts.append({"address": exc.details.get("address"), "reason": "lineage_cycle",
487
+ "cycle": exc.details.get("cycle")})
488
+ break
489
+ # Legacy apply-all still allows deliberately dangling references, as write() does.
490
+ # A selective review must not split a dependency across the approval boundary.
491
+ if ids is not None or rejected:
492
+ conflicts.extend(dependency_conflicts(ws, table, overrides))
493
+ if dry_run:
494
+ return {"ready": not conflicts, "conflicts": conflicts, "accept": list(entries),
495
+ "reject": list(rejected), "pending": sorted(set(all_entries) - entries.keys() - rejected.keys())}
496
+ if conflicts:
497
+ raise ApplyConflictError(
498
+ f"apply aborted before touching overlay: {len(conflicts)} conflict(s)", conflicts=conflicts
499
+ )
500
+ for action in actions:
501
+ action["entry"] = entries[action["id"]]
502
+ ids = action["entry"].get("change_ids", [])
503
+ fields = {"address": format_address(overlay.alias, action["id"]), "op": action["op"],
504
+ "before_sha256": action.get("base_sha256"), "after_sha256": action.get("sha256"),
505
+ "origin": "apply"}
506
+ action["history_events"] = transitions("applied", ids, **fields) if ids else [change("applied", reason=None, **fields)]
507
+ for path, entry in rejected.items():
508
+ ids = entry.get("change_ids", [])
509
+ fields = {"address": format_address(overlay.alias, path), "cause": "review"}
510
+ events = transitions("discarded", ids, **fields) if ids else [change("discarded", **fields)]
511
+ actions.append({"op": "discard", "id": path, "entry": entry,
512
+ "sha256": read_card_file(staging.file(path))[1], "history_events": events})
513
+ journal = {"version": 1, "started_at": _now(), "overlay_root": str(overlay.root), "actions": actions}
514
+ staging.write_journal(journal)
515
+ return replay(ws, table, journal)
516
+
517
+
518
+ def replay(ws: "Workspace", table: "MountTable", journal: dict[str, Any]) -> dict[str, Any]:
519
+ """Execute (or finish) a journaled batch idempotently. Caller holds ``LOCK_EX``.
520
+
521
+ An action whose overlay target changed since it was journaled is skipped, never forced: it
522
+ stays staged with its original ``base_sha256``, so ``diff()`` reports the conflict against the
523
+ version the change was based on.
524
+ """
525
+ staging = ws.staging
526
+ overlay_root = Path(journal.get("overlay_root") or table.overlay.root)
527
+ alias = table.overlay.alias
528
+ report: dict[str, Any] = {"applied": 0, "created": [], "modified": [], "deleted": [], "skipped": []}
529
+ if any(a["op"] == "discard" for a in journal.get("actions", [])):
530
+ report["discarded"] = 0
531
+ report["discarded_ids"] = []
532
+ skipped: list[dict[str, Any]] = []
533
+ updated = False
534
+ entries = staging.load_manifest()
535
+ for action in journal.get("actions", []):
536
+ if "history_events" not in action:
537
+ action["entry"] = entries.get(action["id"], {})
538
+ fields = {"address": format_address(alias, action["id"]), "op": action["op"],
539
+ "before_sha256": action.get("base_sha256"), "after_sha256": action.get("sha256"), "origin": "apply"}
540
+ ids = action["entry"].get("change_ids", [])
541
+ action["history_events"] = transitions("applied", ids, **fields) if ids else [change("applied", reason=None, **fields)]
542
+ updated = True
543
+ if updated:
544
+ staging.write_journal(journal)
545
+ recorded = {e["event_id"] for e in ws.history.events()}
546
+ for action in journal.get("actions", []):
547
+ path = action["id"]
548
+ address = format_address(alias, path)
549
+ dst = overlay_root / f"{path}.md"
550
+ completed = all(e["event_id"] in recorded for e in action["history_events"])
551
+ if completed and action["op"] == "discard":
552
+ report["discarded"] += 1
553
+ report["discarded_ids"].append(path)
554
+ continue
555
+ if completed:
556
+ key = "deleted" if action["op"] == "delete" else ("created" if action.get("change") == "create" else "modified")
557
+ report[key].append(address)
558
+ report["applied"] += 1
559
+ continue
560
+ if action["op"] == "discard":
561
+ current = read_card_file(staging.file(path))[1]
562
+ if current is not None and current != action.get("sha256"):
563
+ report["skipped"].append({"address": address, "reason": "staged file changed during recovery; kept"})
564
+ skipped.append(action)
565
+ continue
566
+ staging._drop_file(staging.file(path))
567
+ ws.history.append(action["history_events"])
568
+ report["discarded"] += 1
569
+ report["discarded_ids"].append(path)
570
+ continue
571
+ if action["op"] == "move":
572
+ src = staging.file(path)
573
+ if src.is_file():
574
+ _, dst_sha = read_card_file(dst)
575
+ if dst_sha not in (action.get("base_sha256"), action.get("sha256")):
576
+ report["skipped"].append({"address": address, "reason": "overlay changed during recovery; staged file kept"})
577
+ skipped.append(action)
578
+ continue
579
+ if read_card_file(src)[1] != action.get("sha256"):
580
+ report["skipped"].append({"address": address, "reason": "staged file changed during recovery; kept"})
581
+ skipped.append(action)
582
+ continue
583
+ durable_move(src, dst)
584
+ elif read_card_file(dst)[1] != action.get("sha256"):
585
+ report["skipped"].append({"address": address, "reason": "applied content missing or changed; history not confirmed"})
586
+ skipped.append(action)
587
+ continue
588
+ report["created" if action.get("change") == "create" else "modified"].append(address)
589
+ elif action["op"] == "delete":
590
+ _, dst_sha = read_card_file(dst)
591
+ if dst_sha is not None and dst_sha != action.get("base_sha256"):
592
+ report["skipped"].append({"address": address, "reason": "overlay changed during recovery; delete kept staged"})
593
+ skipped.append(action)
594
+ continue
595
+ if dst_sha is not None:
596
+ unlink_if_exists(dst)
597
+ prune_empty_dirs(overlay_root, dst.parent)
598
+ report["deleted"].append(address)
599
+ ws.history.append(action["history_events"])
600
+ report["applied"] += 1
601
+ ws._sync(table) # (c) one SQLite transaction
602
+ manifest = staging.load_manifest()
603
+ remaining = {p: entry for p, entry in manifest.items()
604
+ if p not in {a["id"] for a in journal.get("actions", [])}}
605
+ remaining.update(_skipped_entries(manifest, skipped))
606
+ staging.save_manifest(remaining) # preserve every unselected proposal, including during replay
607
+ staging.remove_empty_subdirs()
608
+ unlink_if_exists(staging.journal_path) # (e) strictly last
609
+ return report
610
+
611
+
612
+ def _skipped_entries(manifest: dict[str, dict[str, Any]], skipped: list[dict[str, Any]]) -> dict[str, dict[str, Any]]:
613
+ """Manifest entries to keep for skipped actions; rebuilt from the journal if an earlier pass removed them."""
614
+ kept: dict[str, dict[str, Any]] = {}
615
+ for action in skipped:
616
+ entry = manifest.get(action["id"]) or action.get("entry")
617
+ if not entry:
618
+ entry = {"op": "delete" if action["op"] == "delete" else "write",
619
+ "base_sha256": action.get("base_sha256"), "history": [], "updated_at": _now()}
620
+ kept[action["id"]] = entry
621
+ return kept
622
+
623
+
624
+ def discard(ws: "Workspace", ids: list[str] | None = None) -> dict[str, Any]:
625
+ with ws._writing():
626
+ entries = select_entries(ws.staging.entries(), ids)
627
+ events = []
628
+ for path, entry in entries.items():
629
+ ids = entry.get("change_ids", [])
630
+ fields = {"address": format_address(ws.table().overlay.alias, path), "cause": "discard"}
631
+ events += transitions("discarded", ids, **fields) if ids else [change("discarded", **fields)]
632
+ remaining = {p: entry for p, entry in ws.staging.load_manifest().items() if p not in entries}
633
+ actions = [file_action(ws.staging.file(p), None, ws.staging.root) for p in entries]
634
+ if entries:
635
+ actions.append(file_action(ws.staging.manifest_path, ws.staging.manifest_text(remaining)))
636
+ if ids is None:
637
+ actions = [file_action(p, None, ws.staging.root) for p in sorted(ws.staging.root.rglob("*")) if p.is_file()]
638
+ if actions or events:
639
+ ws.history.transact(actions, events)
640
+ ws.staging.remove_empty_subdirs()
641
+ return {"discarded": len(entries), "ids": list(entries)}