promptmigrate-cli 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 (42) hide show
  1. promptmigrate/__init__.py +21 -0
  2. promptmigrate/__main__.py +3 -0
  3. promptmigrate/apply.py +116 -0
  4. promptmigrate/cli.py +123 -0
  5. promptmigrate/commands/__init__.py +5 -0
  6. promptmigrate/commands/check.py +65 -0
  7. promptmigrate/commands/current.py +25 -0
  8. promptmigrate/commands/diff.py +19 -0
  9. promptmigrate/commands/downgrade.py +36 -0
  10. promptmigrate/commands/env.py +35 -0
  11. promptmigrate/commands/get.py +48 -0
  12. promptmigrate/commands/history.py +41 -0
  13. promptmigrate/commands/init.py +43 -0
  14. promptmigrate/commands/plan.py +51 -0
  15. promptmigrate/commands/restamp.py +47 -0
  16. promptmigrate/commands/revision.py +97 -0
  17. promptmigrate/commands/upgrade.py +36 -0
  18. promptmigrate/commands/validate.py +96 -0
  19. promptmigrate/core.py +30 -0
  20. promptmigrate/draftdiff.py +41 -0
  21. promptmigrate/errors.py +91 -0
  22. promptmigrate/output.py +122 -0
  23. promptmigrate/plan.py +112 -0
  24. promptmigrate/project.py +160 -0
  25. promptmigrate/protocol/__init__.py +9 -0
  26. promptmigrate/protocol/equality.py +15 -0
  27. promptmigrate/protocol/jsonloader.py +92 -0
  28. promptmigrate/protocol/limits.py +9 -0
  29. promptmigrate/protocol/rules.py +80 -0
  30. promptmigrate/revisions.py +181 -0
  31. promptmigrate/secretscan.py +195 -0
  32. promptmigrate/store/__init__.py +13 -0
  33. promptmigrate/store/environments.py +181 -0
  34. promptmigrate/store/events.py +70 -0
  35. promptmigrate/store/lock.py +66 -0
  36. promptmigrate/store/sqlite.py +147 -0
  37. promptmigrate_cli-0.1.0.dist-info/METADATA +247 -0
  38. promptmigrate_cli-0.1.0.dist-info/RECORD +42 -0
  39. promptmigrate_cli-0.1.0.dist-info/WHEEL +5 -0
  40. promptmigrate_cli-0.1.0.dist-info/entry_points.txt +2 -0
  41. promptmigrate_cli-0.1.0.dist-info/licenses/LICENSE +21 -0
  42. promptmigrate_cli-0.1.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,160 @@
1
+ """The .promptmigrate/ project directory: layout, drafts and the reviewed secret allowlist."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import errno
6
+ import json
7
+ import os
8
+ import secrets
9
+ from pathlib import Path
10
+ from typing import Any
11
+
12
+ from . import protocol, secretscan
13
+ from .errors import InitializationError, SchemaError, StorageError
14
+
15
+ ALLOWLIST_FILE = "secret-allowlist.json"
16
+ # os.link failures that mean "this filesystem has no hard links" (e.g. FAT/exFAT), not "the publish failed".
17
+ _NO_LINKS = {errno.EPERM, errno.ENOTSUP, errno.EOPNOTSUPP}
18
+ # CreateHardLink's own "not supported" codes (FAT/exFAT, many SMB shares); CPython maps these failures to errno
19
+ # EINVAL, which isn't in _NO_LINKS above, so the winerror has to be checked too on Windows.
20
+ _NO_LINKS_WINERROR = {1, 50} # ERROR_INVALID_FUNCTION, ERROR_NOT_SUPPORTED
21
+ # Exclusive create in binary mode. Mode 0o666 lets the OS apply the umask (and any default ACL) at creation, so the
22
+ # process never has to read the umask: os.umask is process-wide and reading it means setting it.
23
+ _NEW_FILE_FLAGS = os.O_CREAT | os.O_EXCL | os.O_WRONLY | getattr(os, "O_BINARY", 0)
24
+ _NEW_FILE_MODE = 0o666
25
+ _TEMP_ATTEMPTS = 100
26
+
27
+
28
+ def pretty(obj: Any) -> str:
29
+ return json.dumps(obj, sort_keys=True, ensure_ascii=False, indent=2) + "\n"
30
+
31
+
32
+ def _write_all(fd: int, data: bytes) -> None:
33
+ view = memoryview(data)
34
+ while view:
35
+ view = view[os.write(fd, view):]
36
+
37
+
38
+ def _create_temp(directory: Path) -> tuple[int, Path]:
39
+ """Create a new hidden `.<hex>.tmp` file in `directory`; the `*.json` glob in load_revisions never sees it.
40
+
41
+ Not tempfile.mkstemp: it always creates mode 0600, and a hard link shares that mode, so the published file would
42
+ be unreadable to others; fixing it afterwards needs the umask.
43
+ """
44
+ for _ in range(_TEMP_ATTEMPTS):
45
+ temp = directory / f".{secrets.token_hex(8)}.tmp"
46
+ try:
47
+ return os.open(temp, _NEW_FILE_FLAGS, _NEW_FILE_MODE), temp
48
+ except FileExistsError:
49
+ continue # someone else's temp file: never touch it, try another name
50
+ raise StorageError(f"Cannot create a temporary file in {directory.name}: every name tried exists")
51
+
52
+
53
+ def _fsync_dir(directory: Path) -> None:
54
+ if os.name != "nt": # Windows cannot open a directory for fsync; NTFS journals the new entry itself
55
+ fd = os.open(directory, os.O_RDONLY)
56
+ try:
57
+ os.fsync(fd)
58
+ finally:
59
+ os.close(fd)
60
+
61
+
62
+ def _link_unsupported(exc: OSError) -> bool:
63
+ """Whether `exc` means "this filesystem has no hard links", on POSIX or on Windows."""
64
+ if exc.errno in _NO_LINKS:
65
+ return True
66
+ return os.name == "nt" and getattr(exc, "winerror", None) in _NO_LINKS_WINERROR
67
+
68
+
69
+ def _write_exclusive(path: Path, data: bytes) -> None:
70
+ """No-clobber fallback without hard links: still never overwrites, but a crash can leave a partial file."""
71
+ fd = os.open(path, _NEW_FILE_FLAGS, _NEW_FILE_MODE)
72
+ try:
73
+ try:
74
+ _write_all(fd, data)
75
+ os.fsync(fd)
76
+ finally:
77
+ os.close(fd)
78
+ except BaseException:
79
+ path.unlink(missing_ok=True) # we created it (O_EXCL), so removing it removes only our partial bytes
80
+ raise
81
+
82
+
83
+ def write_new_file(path: Path, text: str) -> None:
84
+ """Publish `text` as UTF-8 at `path` (a new file) atomically, never overwriting an existing one.
85
+
86
+ Raises FileExistsError if `path` exists; any other OSError becomes StorageError. No temp file survives.
87
+ """
88
+ data = text.encode("utf-8")
89
+ try:
90
+ fd, temp = _create_temp(path.parent)
91
+ try:
92
+ try:
93
+ _write_all(fd, data)
94
+ os.fsync(fd)
95
+ finally:
96
+ os.close(fd)
97
+ try:
98
+ os.link(temp, path)
99
+ except FileExistsError:
100
+ raise
101
+ except OSError as exc:
102
+ if not _link_unsupported(exc):
103
+ raise
104
+ _write_exclusive(path, data)
105
+ finally:
106
+ # Best-effort: once published, a leftover/failed-to-remove temp file must not turn success into
107
+ # StorageError, nor replace an in-flight exception (e.g. the FileExistsError above) with its own.
108
+ try:
109
+ temp.unlink(missing_ok=True)
110
+ except OSError:
111
+ pass
112
+ except FileExistsError:
113
+ raise
114
+ except OSError as exc:
115
+ raise StorageError(f"Cannot write {path.name}: {exc}") from exc
116
+ try:
117
+ _fsync_dir(path.parent) # the file is already visible; directory durability beyond this is best effort
118
+ except OSError:
119
+ pass
120
+
121
+
122
+ def root_dir(project_dir: Path) -> Path:
123
+ return Path(project_dir).resolve() / ".promptmigrate"
124
+
125
+
126
+ def require_init(project_dir: Path) -> Path:
127
+ """Return the .promptmigrate directory, or raise InitializationError if the project is not initialized."""
128
+ root = root_dir(project_dir)
129
+ if not (root / "versions").is_dir() or not (root / "drafts").is_dir():
130
+ raise InitializationError("Not initialized. Run: promptmigrate init")
131
+ return root
132
+
133
+
134
+ def read_drafts(project_dir: Path) -> dict[str, dict[str, Any]]:
135
+ root = require_init(project_dir)
136
+ drafts = {}
137
+ for path in sorted((root / "drafts").iterdir()):
138
+ if path.is_dir() or path.suffix != ".json":
139
+ continue
140
+ name = path.stem
141
+ value, _raw, _rules = protocol.load_json(path, kind="draft", root=root)
142
+ protocol.validate_config(name, value)
143
+ found = protocol.config_violations(name, value)
144
+ if found:
145
+ raise SchemaError(f"Invalid draft {path.name}: {', '.join(found)}")
146
+ drafts[name] = value
147
+ collisions = protocol.case_collisions(drafts)
148
+ if collisions:
149
+ raise SchemaError(f"Invalid drafts: case-collision {collisions[0]}")
150
+ return drafts
151
+
152
+
153
+ def load_allowlist(project_dir: Path) -> list[secretscan.AllowEntry]:
154
+ """The reviewed secret allowlist (.promptmigrate/secret-allowlist.json); empty when the file is absent."""
155
+ root = require_init(project_dir)
156
+ path = root / ALLOWLIST_FILE
157
+ if not path.exists() and not path.is_symlink():
158
+ return []
159
+ value, _raw, _rules = protocol.load_json(path, kind="allowlist", root=root)
160
+ return secretscan.parse_allowlist(value, path.name)
@@ -0,0 +1,9 @@
1
+ """Source-file protocol: strict JSON loading, limits, canonical equality and config validation.
2
+
3
+ Names are defined in the submodules and re-exported here. Patch a limit on `protocol.limits`, not on this package.
4
+ """
5
+
6
+ from .equality import canonical, same
7
+ from .jsonloader import _PREFIX, _StrictJSONError, _finite_float, _reject_constant, _unique_pairs, load_json
8
+ from .limits import MAX_CONFIG_DEPTH, MAX_CONTROL_FILE_BYTES, MAX_DRAFT_BYTES, MAX_REVISION_BYTES
9
+ from .rules import _NAME, RESERVED_TYPES, case_collisions, config_depth, config_violations, validate_config
@@ -0,0 +1,15 @@
1
+ """Canonical JSON text and equality by it."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ from typing import Any
7
+
8
+
9
+ def canonical(obj: Any) -> str:
10
+ return json.dumps(obj, sort_keys=True, ensure_ascii=False, separators=(",", ":"))
11
+
12
+
13
+ def same(a: Any, b: Any) -> bool:
14
+ """Equality by canonical JSON, so 1, 1.0 and true are pairwise distinct (Python's == conflates them)."""
15
+ return canonical(a) == canonical(b)
@@ -0,0 +1,92 @@
1
+ """Strict JSON loading of source files: duplicate keys, non-finite numbers, size limits, symlinks."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import math
7
+ from pathlib import Path
8
+ from typing import Any
9
+
10
+ from ..errors import SchemaError
11
+ from . import limits
12
+
13
+ _PREFIX = {
14
+ "draft": "Invalid JSON draft",
15
+ "revision": "Unreadable migration",
16
+ "allowlist": "Invalid secret allowlist",
17
+ "environments": "Invalid environments file",
18
+ }
19
+
20
+
21
+ class _StrictJSONError(ValueError):
22
+ pass
23
+
24
+
25
+ def _unique_pairs(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
26
+ obj: dict[str, Any] = {}
27
+ for key, value in pairs:
28
+ if key in obj:
29
+ raise _StrictJSONError(f"duplicate key {key!r}")
30
+ obj[key] = value
31
+ return obj
32
+
33
+
34
+ def _reject_constant(name: str) -> Any:
35
+ raise _StrictJSONError(f"non-finite number {name} is not allowed")
36
+
37
+
38
+ def _finite_float(text: str) -> float:
39
+ value = float(text)
40
+ if not math.isfinite(value):
41
+ raise _StrictJSONError("number out of range")
42
+ return value
43
+
44
+
45
+ def load_json(path: Path, *, kind: str, root: Path) -> tuple[Any, bytes, list[str]]:
46
+ """Strictly read one source file under root (.promptmigrate/).
47
+
48
+ Returns (value, raw bytes, tier-B file rules). Tier-A problems always raise SchemaError. Drafts, the allowlist,
49
+ and the environment manifest raise on symlinks and size; an existing revision returns those rules so that the
50
+ caller can warn.
51
+ """
52
+ prefix = _PREFIX[kind]
53
+ rules: list[str] = []
54
+ try:
55
+ if not path.resolve().is_relative_to(root.resolve()):
56
+ raise SchemaError(f"{prefix} {path.name}: resolves outside .promptmigrate/")
57
+ if path.is_symlink():
58
+ if kind == "draft":
59
+ raise SchemaError(f"{prefix} {path.name}: drafts must not be symlinks")
60
+ if kind in {"allowlist", "environments"}:
61
+ raise SchemaError(f"{prefix} {path.name}: must not be a symlink")
62
+ rules.append("symlink")
63
+ size = path.stat().st_size
64
+ limit = {
65
+ "draft": limits.MAX_DRAFT_BYTES,
66
+ "allowlist": limits.MAX_CONTROL_FILE_BYTES,
67
+ "environments": limits.MAX_CONTROL_FILE_BYTES,
68
+ }.get(kind)
69
+ if limit is not None and size > limit:
70
+ raise SchemaError(f"{prefix} {path.name}: {size} bytes exceeds the {limit}-byte limit")
71
+ raw = path.read_bytes()
72
+ except SchemaError:
73
+ raise
74
+ except RuntimeError as exc:
75
+ # Path.resolve() raises an untyped RuntimeError for a symlink loop on Python 3.10-3.12.
76
+ raise SchemaError(f"{prefix} {path.name}: symlink loop") from exc
77
+ except OSError as exc:
78
+ raise SchemaError(f"{prefix} {path.name}: {exc}") from exc
79
+ if kind == "revision" and len(raw) > limits.MAX_REVISION_BYTES:
80
+ rules.append("revision-size")
81
+ try:
82
+ # Drafts and control files are decoded as UTF-8 text, so a BOM is rejected; revisions are parsed from bytes,
83
+ # so a BOM is accepted. Both are unchanged from the starter (spec §3). A UnicodeDecodeError is a ValueError.
84
+ document = raw if kind == "revision" else raw.decode("utf-8")
85
+ value = json.loads(
86
+ document, object_pairs_hook=_unique_pairs, parse_constant=_reject_constant, parse_float=_finite_float
87
+ )
88
+ except RecursionError as exc:
89
+ raise SchemaError(f"{prefix} {path.name}: nested too deep to parse") from exc
90
+ except ValueError as exc:
91
+ raise SchemaError(f"{prefix} {path.name}: {exc}") from exc
92
+ return value, raw, rules
@@ -0,0 +1,9 @@
1
+ """Size and depth limits for source files and configs.
2
+
3
+ Module globals, read at call time (as `limits.NAME`) so tests can patch them here.
4
+ """
5
+
6
+ MAX_DRAFT_BYTES = 1 << 20 # 1 MiB per draft file
7
+ MAX_REVISION_BYTES = 16 << 20 # 16 MiB per revision file
8
+ MAX_CONFIG_DEPTH = 64 # nesting depth of one config: a draft's root, or one before/after value
9
+ MAX_CONTROL_FILE_BYTES = 1 << 20 # 1 MiB for secret-allowlist.json and environments.json
@@ -0,0 +1,80 @@
1
+ """Config validation: tier-A rules enforced everywhere, tier-B rules enforced on new content."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import re
6
+ from collections.abc import Iterable
7
+ from typing import Any
8
+
9
+ from ..errors import SchemaError
10
+ from . import limits
11
+
12
+ RESERVED_TYPES: dict[str, tuple[type, ...]] = {
13
+ "model": (str,),
14
+ "parameters": (dict,),
15
+ "tools": (list,),
16
+ "response_schema": (dict, type(None)),
17
+ }
18
+
19
+ _NAME = re.compile(r"[a-zA-Z][a-zA-Z0-9_-]{0,127}")
20
+ _ENV_NAME = re.compile(r"[A-Za-z][A-Za-z0-9_-]{0,63}")
21
+
22
+
23
+ def validate_config(name: str, value: Any) -> None:
24
+ """Tier-A config rules, enforced everywhere."""
25
+ if not _NAME.fullmatch(name):
26
+ raise SchemaError(f"Invalid prompt name: {name!r}")
27
+ if not isinstance(value, dict):
28
+ raise SchemaError(f"Prompt {name!r} must contain a JSON object")
29
+ # Minimal structural validation; intentionally no framework-specific constraints.
30
+ if "messages" in value:
31
+ msgs = value["messages"]
32
+ if not isinstance(msgs, list) or any(
33
+ not isinstance(msg, dict)
34
+ or not isinstance(msg.get("role"), str)
35
+ or not isinstance(msg.get("content"), str)
36
+ for msg in msgs
37
+ ):
38
+ raise SchemaError(f"Prompt {name!r} has invalid messages")
39
+
40
+
41
+ def config_depth(value: Any) -> int:
42
+ """Nesting depth of JSON containers: a scalar is 0, {} or [] is 1. Iterative, so deep input can't overflow."""
43
+ deepest, stack = 0, [(value, 1)]
44
+ while stack:
45
+ item, depth = stack.pop()
46
+ if isinstance(item, dict):
47
+ children = list(item.values())
48
+ elif isinstance(item, list):
49
+ children = item
50
+ else:
51
+ continue
52
+ deepest = max(deepest, depth)
53
+ stack.extend((child, depth + 1) for child in children)
54
+ return deepest
55
+
56
+
57
+ def config_violations(name: str, value: dict[str, Any]) -> list[str]:
58
+ """Tier-B rules for one config, as rule ids plus subject. Enforced on new content, warned about in history."""
59
+ found = []
60
+ if config_depth(value) > limits.MAX_CONFIG_DEPTH:
61
+ found.append(f"config-depth {name}")
62
+ for field, types in RESERVED_TYPES.items():
63
+ if field in value and not isinstance(value[field], types):
64
+ found.append(f"reserved-field-type {name}.{field}")
65
+ return found
66
+
67
+
68
+ def case_collisions(names: Iterable[str]) -> list[str]:
69
+ """Each group of names that are equal case-insensitively, as 'A/a'."""
70
+ groups: dict[str, list[str]] = {}
71
+ for name in names:
72
+ groups.setdefault(name.lower(), []).append(name)
73
+ return sorted("/".join(sorted(group)) for group in groups.values() if len(group) > 1)
74
+
75
+
76
+ def validate_environment_name(name: str) -> None:
77
+ if not isinstance(name, str) or not _ENV_NAME.fullmatch(name):
78
+ raise SchemaError("Environment must be alphanumeric, starting with a letter")
79
+ if re.fullmatch(r"(?i:CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])", name):
80
+ raise SchemaError("Environment name is reserved on Windows")
@@ -0,0 +1,181 @@
1
+ """Source history: revision files, the linear revision graph, and replay of changes from the empty state."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import hashlib
6
+ import json
7
+ import re
8
+ import warnings
9
+ from dataclasses import dataclass
10
+ from pathlib import Path
11
+ from typing import Any
12
+
13
+ from . import project, protocol
14
+ from .errors import LegacyRevisionWarning, MigrationConflictError, RevisionGraphError, SchemaError
15
+
16
+ _V0_KEYS = ("revision", "down_revision", "message", "created_at", "changes")
17
+ _V1_KEYS = frozenset({"format_version", *_V0_KEYS})
18
+ _LEGACY = "revision {rid}: {rule} (accepted for compatibility; create a new revision to fix)"
19
+
20
+
21
+ @dataclass(frozen=True)
22
+ class Revision:
23
+ revision: str
24
+ down_revision: str | None
25
+ message: str
26
+ created_at: str
27
+ changes: dict[str, dict[str, Any]]
28
+ checksum: str
29
+ path: Path
30
+ format_version: int = 0
31
+ line_ending_checksums: frozenset[str] = frozenset() # v0 only: raw-byte digests of the LF and CRLF re-saves
32
+
33
+
34
+ def _hash(data: bytes) -> str:
35
+ return hashlib.sha256(data).hexdigest()
36
+
37
+
38
+ def line_ending_variants(raw: bytes) -> set[str]:
39
+ """Raw-byte digests of `raw` re-saved with LF and with CRLF line endings (ADR-027). The v0 checksum is unchanged."""
40
+ lf = raw.replace(b"\r\n", b"\n")
41
+ return {_hash(lf), _hash(lf.replace(b"\n", b"\r\n"))}
42
+
43
+
44
+ def _v1_checksum(item: dict[str, Any]) -> str:
45
+ """Protocol v1 (ADR-026): SHA-256 of the canonical JSON of the whole parsed file, tagged so it never equals v0."""
46
+ return "v1:" + _hash(protocol.canonical(item).encode("utf-8"))
47
+
48
+
49
+ def _format_version(item: dict[str, Any], name: str) -> int:
50
+ """0 for a file without `format_version` (frozen, ADR-025), 1 for the JSON integer 1; anything else is tier A."""
51
+ if "format_version" not in item:
52
+ return 0
53
+ if type(item["format_version"]) is not int or item["format_version"] != 1:
54
+ raise SchemaError(f"Unsupported format_version in {name}")
55
+ unknown = sorted(set(item) - _V1_KEYS)
56
+ if unknown:
57
+ raise SchemaError(f"Unknown top-level key in {name}: {', '.join(unknown)}")
58
+ return 1
59
+
60
+
61
+ def load_revisions(project_dir: Path) -> list[Revision]:
62
+ root = project.require_init(project_dir)
63
+ unsorted: dict[str, Revision] = {}
64
+ violations: dict[str, list[str]] = {}
65
+ for path in sorted((root / "versions").glob("*.json")):
66
+ item, raw, file_rules = protocol.load_json(path, kind="revision", root=root)
67
+ if not isinstance(item, dict):
68
+ raise SchemaError(f"Invalid migration format: {path.name}")
69
+ version = _format_version(item, path.name)
70
+ if not all(k in item for k in _V0_KEYS):
71
+ raise SchemaError(f"Invalid migration format: {path.name}")
72
+ rid, parent, changes = item["revision"], item["down_revision"], item["changes"]
73
+ if not isinstance(rid, str) or not re.fullmatch(r"[a-f0-9]{12}", rid):
74
+ raise SchemaError(f"Invalid revision id in {path.name}")
75
+ if parent is not None and (not isinstance(parent, str) or not re.fullmatch(r"[a-f0-9]{12}", parent)):
76
+ raise SchemaError(f"Invalid down_revision in {path.name}")
77
+ if not isinstance(item["message"], str) or not isinstance(item["created_at"], str):
78
+ raise SchemaError(f"Invalid metadata in {path.name}")
79
+ if not isinstance(changes, dict) or not changes:
80
+ raise SchemaError(f"Migration must contain nonempty changes: {path.name}")
81
+ for name, change in changes.items():
82
+ if not isinstance(change, dict) or set(change) != {"before", "after"}:
83
+ raise SchemaError(f"Invalid change operation in {path.name}: {name}")
84
+ for field in ("before", "after"):
85
+ if change[field] is not None:
86
+ protocol.validate_config(name, change[field])
87
+ if rid in unsorted:
88
+ raise RevisionGraphError(f"Duplicate revision id: {rid}")
89
+ found = list(file_rules)
90
+ for name, change in changes.items():
91
+ if protocol.same(change["before"], change["after"]):
92
+ found.append(f"no-op-change {name}")
93
+ # Only after values: replay makes every before equal an earlier after, so each violation shows once.
94
+ if change["after"] is not None:
95
+ found.extend(protocol.config_violations(name, change["after"]))
96
+ violations[rid] = found
97
+ variants: frozenset[str] = frozenset()
98
+ if version == 0:
99
+ checksum = _hash(raw)
100
+ # CR/LF bytes (b"\r\n") are only ever whitespace in UTF-8 JSON. `json.loads` also auto-detects and
101
+ # accepts UTF-16/32, where a single code unit such as U+0D0A encodes as the same two bytes as a byte-
102
+ # level CR LF; replacing it would treat a real value change as a line-ending-only edit (Finding 1,
103
+ # 2026-11-13 final review). `raw.decode("utf-8")` alone is not a reliable test here: a mostly-ASCII
104
+ # UTF-16 file is full of null bytes, which are themselves valid (if meaningless) UTF-8, so it can
105
+ # decode without error even though `json.loads` did not read it as UTF-8. Ask the same question
106
+ # `json.loads` asks of these bytes (`json.detect_encoding`, the encoding-sniffing it uses for bytes
107
+ # input) instead, so "UTF-8" here means what it means to the loader, with or without a BOM.
108
+ if json.detect_encoding(raw) in ("utf-8", "utf-8-sig"):
109
+ variants = frozenset(line_ending_variants(raw))
110
+ else:
111
+ try:
112
+ checksum = _v1_checksum(item)
113
+ except UnicodeEncodeError as exc:
114
+ raise SchemaError(f"Invalid string in {path.name}: unpaired surrogate") from exc
115
+ unsorted[rid] = Revision(
116
+ rid, parent, item["message"], item["created_at"], changes, checksum, path, version, variants
117
+ )
118
+
119
+ if not unsorted:
120
+ return []
121
+ roots = [r for r in unsorted.values() if r.down_revision is None]
122
+ if len(roots) != 1:
123
+ raise RevisionGraphError("MVP requires exactly one root revision (linear history)")
124
+ children: dict[str, list[Revision]] = {}
125
+ for r in unsorted.values():
126
+ if r.down_revision is not None:
127
+ if r.down_revision not in unsorted:
128
+ raise RevisionGraphError(f"Missing parent of revision {r.revision}: {r.down_revision}")
129
+ children.setdefault(r.down_revision, []).append(r)
130
+ if any(len(kids) > 1 for kids in children.values()):
131
+ raise RevisionGraphError("Branching detected. MVP only supports one linear head; resolve in Git before deploying")
132
+ result: list[Revision] = []
133
+ current: Revision | None = roots[0]
134
+ while current is not None and current.revision not in {r.revision for r in result}:
135
+ result.append(current)
136
+ current = children.get(current.revision, [None])[0]
137
+ if len(result) != len(unsorted):
138
+ raise RevisionGraphError("Disconnected or cyclic migration history")
139
+ # Validate declarative preconditions across all revisions, independently of environments.
140
+ replay_revisions(result)
141
+ names: set[str] = set()
142
+ for r in result:
143
+ for name, change in r.changes.items():
144
+ if change["after"] is None:
145
+ names.discard(name)
146
+ else:
147
+ names.add(name)
148
+ found = violations[r.revision]
149
+ found.extend(f"case-collision {group}" for group in protocol.case_collisions(names)
150
+ if any(member in r.changes for member in group.split("/")))
151
+ for rule in found:
152
+ warnings.warn(_LEGACY.format(rid=r.revision, rule=rule), LegacyRevisionWarning, stacklevel=2)
153
+ return result
154
+
155
+
156
+ def _apply_changes(
157
+ state: dict[str, dict[str, Any]],
158
+ revision: Revision,
159
+ *,
160
+ backward: bool = False,
161
+ ) -> None:
162
+ for name, change in revision.changes.items():
163
+ expected = change["after"] if backward else change["before"]
164
+ replacement = change["before"] if backward else change["after"]
165
+ if not protocol.same(state.get(name), expected):
166
+ direction = "downgrade" if backward else "upgrade"
167
+ raise MigrationConflictError(
168
+ f"{direction} {revision.revision}: unexpected current value for {name!r}; "
169
+ "possible drift or invalid revision dependency"
170
+ )
171
+ if replacement is None:
172
+ state.pop(name, None)
173
+ else:
174
+ state[name] = replacement
175
+
176
+
177
+ def replay_revisions(revisions: list[Revision]) -> dict[str, dict[str, Any]]:
178
+ state: dict[str, dict[str, Any]] = {}
179
+ for r in revisions:
180
+ _apply_changes(state, r)
181
+ return state