Merge pull request #174 from AgriciDaniel/codex/public-fix-legacy-batch-migration

fix(migration): preserve unresolved legacy batch labels

Author: AgriciDaniel

CHANGELOG.md

@@ -20,6 +20,14 @@ implementation record for older releases.
 - The `UNSUPPORTED_PLATFORM` refusal message now points to
   `docs/windows-wsl.md` for users whose WSL setup is itself misbehaving.
 
+### Fixed
+
+- Legacy migration and adoption no longer fail when a manifest source key is a
+  valid batch label rather than a file. Unresolved labels are preserved as
+  unreviewed manual sources without inventing payload mappings or hashes.
+  Apply now rejects a reviewed migration if a legacy locator's file state
+  changes or becomes unsafe before the transaction writes.
+
 ## [2.1.0] - 2026-07-31
 
 Native Windows compatibility.

claude_obsidian/ledgers.py

@@ -1236,7 +1236,14 @@ def migrate_legacy_manifest(
                 }
             )
             continue
-        source_id = stable_source_id("file", locator, digest)
+        # Some legacy generators used a canonical path-shaped batch label
+        # rather than a file locator.  _safe_hash returns None only when that
+        # safely inspected path is absent; unsafe and non-regular nodes raise.
+        # Preserve an absent legacy identity without inventing a payload or
+        # treating its short legacy hash as SHA-256.
+        origin_kind = "file" if digest is not None else "manual"
+        content_kind = "document" if digest is not None else "other"
+        source_id = stable_source_id(origin_kind, locator, digest)
         if source_id in source_ledger["sources"]:
             migration_errors.append(
                 {
@@ -1274,8 +1281,8 @@ def migrate_legacy_manifest(
             )
             continue
         source_ledger["sources"][source_id] = {
-            "origin": {"kind": "file", "locator": locator},
-            "content_kind": "document",
+            "origin": {"kind": origin_kind, "locator": locator},
+            "content_kind": content_kind,
             "title": Path(locator).stem,
             "authority": "unknown",
             "content_sha256": digest,
@@ -1306,6 +1313,10 @@ def migration_bundle(
 ) -> dict[str, Any]:
     root = canonical(vault_root)
     sources, claims = migrate_legacy_manifest(root, generated_at=generated_at)
+    read_preconditions = {
+        record["origin"]["locator"]: record["content_sha256"]
+        for record in sources["sources"].values()
+    }
     validate_existing_canonical_state(root, fallback_source_ledger=sources)
     writes: list[dict[str, Any]] = []
     expected: dict[str, str | None] = {}
@@ -1342,10 +1353,13 @@ def migration_bundle(
                 + "\n",
             }
         )
-    return {
+    bundle = {
         "schema": BUNDLE_SCHEMA,
         "operation_id": operation_id,
         "operation_type": "migration",
         "expected_hashes": expected,
         "writes": writes,
     }
+    if SOURCE_PATH in expected:
+        bundle["read_preconditions"] = read_preconditions
+    return bundle

claude_obsidian/transaction.py

@@ -2311,11 +2311,21 @@ def _remove_pinned_runtime_tree_at(
         )
     if remaining is None:
         remaining = [MAX_TRANSACTION_RUNTIME_TREE_ENTRIES]
-    child_names = _bounded_runtime_names(
-        directory_fd,
-        limit=remaining[0],
-        label=f"transaction runtime {component}",
-    )
+    scan_fd = _open_runtime_directory_at(parent_fd, component, create=False)
+    try:
+        pinned = os.fstat(directory_fd)
+        scanned = os.fstat(scan_fd)
+        if (pinned.st_dev, pinned.st_ino) != (scanned.st_dev, scanned.st_ino):
+            raise _LockIdentityChanged(
+                f"runtime directory changed before enumeration: {component}"
+            )
+        child_names = _bounded_runtime_names(
+            scan_fd,
+            limit=remaining[0],
+            label=f"transaction runtime {component}",
+        )
+    finally:
+        os.close(scan_fd)
     remaining[0] -= len(child_names)
     for child_name in child_names:
         metadata = os.stat(child_name, dir_fd=directory_fd, follow_symlinks=False)
@@ -3329,6 +3339,12 @@ def _prepare_writes(
                 f"expected hash for {normalized_path} must be SHA-256 or null",
             )
         normalized_expected[normalized_path] = digest
+    _assert_read_preconditions(
+        vault_root,
+        bundle,
+        root_fd=root_fd,
+        meta_fd=meta_fd,
+    )
     seen: set[str] = set()
     seen_casefold: dict[str, str] = {}
     prepared: list[PreparedWrite] = []
@@ -3503,6 +3519,75 @@ def _prepare_writes(
     return prepared
 
 
+def _assert_read_preconditions(
+    vault_root: Path,
+    bundle: Mapping[str, Any],
+    *,
+    root_fd: int | None = None,
+    meta_fd: int | None = None,
+) -> None:
+    """Require non-write inputs to retain their reviewed file state."""
+
+    raw = bundle.get("read_preconditions", {})
+    if not isinstance(raw, dict):
+        raise TransactionValidationError(
+            "INVALID_READ_PRECONDITIONS",
+            "read_preconditions must be an object",
+        )
+    if len(raw) > MAX_TRANSACTION_WRITES:
+        raise TransactionValidationError(
+            "TRANSACTION_WRITE_LIMIT",
+            f"read preconditions exceed the {MAX_TRANSACTION_WRITES}-path limit",
+        )
+    normalized: dict[str, str | None] = {}
+    casefolded: dict[str, str] = {}
+    for raw_path, digest in raw.items():
+        path = (
+            _normalize_vault_path(raw_path)
+            if root_fd is not None
+            else _safe_vault_path(vault_root, raw_path)[0]
+        )
+        folded = _portable_name_key(path)
+        prior = casefolded.get(folded)
+        if prior is not None and prior != path:
+            raise TransactionValidationError(
+                "CASEFOLD_PATH_COLLISION",
+                f"read preconditions contain case-colliding paths: {prior}, {path}",
+            )
+        casefolded[folded] = path
+        if digest is not None and (
+            not isinstance(digest, str)
+            or len(digest) != 64
+            or digest != digest.lower()
+            or any(character not in "0123456789abcdef" for character in digest)
+        ):
+            raise TransactionValidationError(
+                "INVALID_READ_PRECONDITION",
+                f"read precondition for {path} must be SHA-256 or null",
+            )
+        normalized[path] = digest
+    for path, expected in normalized.items():
+        try:
+            observed = _safe_hash(
+                vault_root,
+                path,
+                root_fd=root_fd,
+                meta_fd=meta_fd,
+            )
+        except TransactionValidationError:
+            raise
+        except OSError as exc:
+            raise TransactionValidationError(
+                "UNSAFE_READ_PRECONDITION",
+                f"cannot inspect read precondition {path}: {exc}",
+            ) from exc
+        if observed != expected:
+            raise TransactionConflict(
+                "READ_PRECONDITION_MISMATCH",
+                f"{path} changed since the operation was drafted",
+            )
+
+
 def _validate_provenance_writes(
     vault_root: Path,
     prepared: Iterable[PreparedWrite],
@@ -4591,6 +4676,12 @@ def apply_bundle(
                 _assert_transaction_namespaces(mutation_lock, runtime, operation)
 
                 try:
+                    _assert_read_preconditions(
+                        vault,
+                        bundle,
+                        root_fd=runtime.root_fd,
+                        meta_fd=runtime.meta_fd,
+                    )
                     for index, write in enumerate(prepared, start=1):
                         _assert_transaction_namespaces(
                             mutation_lock, runtime, operation

claude_obsidian/vault_ops.py

@@ -105,10 +105,15 @@ def build_vault_bundle(
         source_ledger, claim_ledger = migrate_legacy_manifest(
             vault, generated_at=generated_at
         )
+        read_preconditions = {
+            record["origin"]["locator"]: record["content_sha256"]
+            for record in source_ledger["sources"].values()
+        }
         validate_existing_canonical_state(vault, fallback_source_ledger=source_ledger)
     else:
         source_ledger = empty_source_ledger(generated_at=generated_at)
         claim_ledger = empty_claim_ledger(generated_at=generated_at)
+        read_preconditions = {}
     planned[SOURCE_PATH] = (
         json.dumps(
             source_ledger,
@@ -150,10 +155,13 @@ def build_vault_bundle(
                 "sha256": new_hash,
             }
         )
-    return {
+    bundle = {
         "schema": BUNDLE_SCHEMA,
         "operation_id": operation_id,
         "operation_type": operation_type,
         "expected_hashes": expected,
         "writes": writes,
     }
+    if adopt and SOURCE_PATH in expected:
+        bundle["read_preconditions"] = read_preconditions
+    return bundle

skills/wiki/references/provenance.md

@@ -62,4 +62,13 @@ python3 "$CORE" migrate --vault VAULT \
 
 Migration leaves `.raw/.manifest.json` byte-for-byte unchanged, creates missing
 ledgers, defaults unknown evidence fields honestly, and never extracts claims
-from legacy prose automatically.
+from legacy prose automatically. A legacy source key that resolves to a regular
+file remains a file source with its computed SHA-256. A valid key with no file
+is preserved as an unreviewed manual source with unknown authority and no
+verified payload hash. This unresolved record preserves the legacy identity,
+date, and page links; it does not prove a batch-to-file relationship. Migration
+never enumerates raw payloads to invent that relationship or promotes the
+legacy short hash to SHA-256.
+The reviewed migration bundle also pins each legacy locator's observed file
+state. Apply fails if an unresolved label appears, becomes unsafe, cannot be
+inspected, or if a file source changes after review.