throughline 3.18.2__tar.gz → 3.19.2__tar.gz

{throughline-3.18.2/src/throughline.egg-info → throughline-3.19.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: throughline
-Version: 3.18.2
+Version: 3.19.2
 Summary: A Git-native requirements management tool with a scope-avalanche grounding layer: permanent UIDs, one file per item, typed links, suspect detection, and a CI-gating check.
 Author-email: Henry J Grech-Cini <henry.grechcini@gmail.com>
 License-Expression: Apache-2.0

{throughline-3.18.2 → throughline-3.19.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "throughline"
-version = "3.18.2"
+version = "3.19.2"
 description = "A Git-native requirements management tool with a scope-avalanche grounding layer: permanent UIDs, one file per item, typed links, suspect detection, and a CI-gating check."
 readme = "README.md"
 requires-python = ">=3.11"

{throughline-3.18.2 → throughline-3.19.2}/src/throughline/__init__.py

@@ -30,7 +30,7 @@ from .composition import (
 )
 from .diagrams import diagram_transitions, diagram_types
 from .dump import build_dump
-from .fingerprint import fingerprint
+from .fingerprint import fingerprint, revision
 from .graph import Index
 from .grounding import (
     GroundingError,
@@ -179,7 +179,7 @@ __all__ = [
     "ProjectError", "CONFIG_NAME", "MANIFEST_NAME",
     # identity of an item
     "UID_RE", "parse_uid", "format_uid", "next_uid", "collisions",
-    "Index", "fingerprint",
+    "Index", "fingerprint", "revision",
     # the schema a project declares
     "Schema", "AttrSpec", "LinkRule", "SchemaError",
     # creating and changing an item

{throughline-3.18.2 → throughline-3.19.2}/src/throughline/apply.py

@@ -2,18 +2,23 @@
 # SPDX-License-Identifier: Apache-2.0
 """Carrying out a change set drafted where the Tool cannot run (SR-0252).
 
-An assistant that reads at most a few files, cannot run commands and returns
-only text works from an export of the graph (throughline-transform's assistant
-form, built on `tl dump` and the fingerprint each item carries there, SR-0251)
-and sends its changes back as a *change set*: one JSON document listing the
-Tool's own operations — new, amend, link, unlink, delete — each naming the item
-it touches and, for an item that already exists, quoting the fingerprint it was
-drafted against.
+An assistant or agent that cannot run the Tool — one that reads a capped number
+of files and returns only text, as Microsoft 365 Copilot does in a controlled
+environment — works from an export of the graph, built on `tl dump` and the
+fingerprint and revision each item carries there (SR-0251). The export is the
+business of whatever tool briefs that assistant (rhodium-org/throughline-ms-copilot
+does it for Copilot); the assistant sends its changes back as a *change set*: one JSON
+document listing the Tool's own operations — new, amend, link, unlink, delete —
+each naming the item it touches and, for an item that already exists, quoting
+the revision it was drafted against: the digest of its whole stored record that
+the dump gives beside its fingerprint, so a change to any field since the export
+refuses the set (format 2). A format-1 set quotes the fingerprint instead and is
+still read, with the weaker check that implies.
 
 The set is carried out all or nothing. Every operation is checked against the
 graph as it stands before anything is written: a malformed operation, an
 operation the Tool does not offer an assistant (a decision, or a change to the
-structure), or a fingerprint that is not the item's current one refuses the
+structure), or a revision that is not the item's current one refuses the
 whole set, naming every offending operation. Each operation then runs through
 the same function the matching command runs — :func:`new_item`,
 :func:`amend_item`, :func:`add_link`, :func:`remove_link`, :func:`delete_item`
@@ -33,7 +38,7 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Callable
 
-from .fingerprint import fingerprint
+from .fingerprint import fingerprint, revision
 from .grounding import GroundingError
 from .items import amend_item, delete_item, item_type_for, new_item, parse_attrs
 from .links import GroundingView, LinkError, add_link, remove_link
@@ -42,8 +47,16 @@ from .schema import SchemaError
 from .storage import ProjectError, write_item
 from .uid import UidError
 
-#: The version of the change-set form this release reads and documents.
-CHANGE_SET_FORMAT_VERSION = 1
+#: The version of the change-set form this release documents and writes about.
+#: Format 2 quotes each existing item's ``revision``; format 1 quoted its
+#: ``fingerprint``, which misses a change to the title, rationale, links, status
+#: or a non-normative attribute, and is still read so a set already drafted
+#: against it is not broken.
+CHANGE_SET_FORMAT_VERSION = 2
+
+#: The versions :func:`parse_change_set` reads, and the key each one quotes an
+#: existing item's version under.
+READABLE_FORMATS = {1: "fingerprint", 2: "revision"}
 
 #: The operations an assistant may ask for, in the Tool's own vocabulary.
 OPERATIONS = ("new", "amend", "link", "unlink", "delete")
@@ -54,39 +67,43 @@ _DECISIONS = ("ratify", "withdraw", "clarify", "status", "invalidate", "flag",
               "review", "schema", "migrate", "resolve", "init", "register")
 
 _LABEL_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_-]*$")
-_FINGERPRINT_RE = re.compile(r"^sha256:[0-9a-f]{64}$")
+_DIGEST_RE = re.compile(r"^sha256:[0-9a-f]{64}$")
 
-# The keys each operation may carry, and the ones it must.
+# The keys each operation may carry, and the ones it must. An operation on an
+# existing item may also carry the version key of its format (READABLE_FORMATS).
 _KEYS: dict[str, tuple[set[str], set[str]]] = {
     "new": ({"register"},
             {"op", "register", "type", "title", "text", "rationale", "attrs",
              "links", "label"}),
     "amend": ({"uid"},
-              {"op", "uid", "fingerprint", "title", "text", "rationale", "attrs",
+              {"op", "uid", "title", "text", "rationale", "attrs",
                "unset"}),
     "link": ({"uid", "target", "type"},
-             {"op", "uid", "fingerprint", "target", "type", "stamp"}),
+             {"op", "uid", "target", "type", "stamp"}),
     "unlink": ({"uid", "target"},
-               {"op", "uid", "fingerprint", "target", "type"}),
-    "delete": ({"uid"}, {"op", "uid", "fingerprint", "reason"}),
+               {"op", "uid", "target", "type"}),
+    "delete": ({"uid"}, {"op", "uid", "reason"}),
 }
 
 #: The change-set form, as the text handed to an assistant with the export.
-#: throughline-transform takes it from here (its SR-0018), so what an assistant
-#: is told to write cannot drift from what :func:`parse_change_set` accepts.
+#: A tool that briefs an assistant takes it from here (`tl apply --describe`),
+#: so what the assistant is told to write cannot drift from what
+#: :func:`parse_change_set` accepts.
 CHANGE_SET_FORMAT = f"""\
 # A throughline change set — the form `tl apply` accepts (format {CHANGE_SET_FORMAT_VERSION})
 
 A change set is one JSON document: a list of operations, carried out in order,
 all or nothing. `tl apply` refuses the whole set, naming every offending
 operation, when any operation is malformed, is not one of the five below, or
-quotes a fingerprint that is not the item's current one. Nothing is written
+quotes a revision that is not the item's current one. Nothing is written
 until every operation has been checked, and a refused set changes nothing.
 
-An item that already exists is named by its UID and carries the "fingerprint"
-the export gave for it (the `fingerprint` field of the item in `tl dump`). An
-item created earlier in the same set is named by its label, written "$label",
-and carries no fingerprint.
+An item that already exists is named by its UID and carries the "revision"
+the export gave for it (the `revision` field of the item in `tl dump`). Any
+change to the item since the export — its text, title, rationale, links,
+status or any attribute — refuses the set, so a change is never written over a
+newer one. An item created earlier in the same set is named by its label,
+written "$label", and carries no revision.
 
 Everything the set creates or changes is recorded with origin "ai" and waits
 as proposed: a person decides afterwards. Decisions — ratify, withdraw,
@@ -102,29 +119,29 @@ The five operations:
   where the register declares one. "links" ground the item: a non-root item
   must reach a root through them. "label" is optional.
 
-{{"op": "amend", "uid": "SR-0012", "fingerprint": "sha256:...", "title": "...",
+{{"op": "amend", "uid": "SR-0012", "revision": "sha256:...", "title": "...",
  "text": "...", "rationale": "...", "attrs": {{"priority": "must"}},
  "unset": ["owner"]}}
   changes only the fields given; an empty string clears a field. Only an
   attribute the item's type declares may be set.
 
-{{"op": "link", "uid": "SR-0012", "fingerprint": "sha256:...",
+{{"op": "link", "uid": "SR-0012", "revision": "sha256:...",
  "target": "UR-0003", "type": "implements"}}
   adds a typed link from the item to the target.
 
-{{"op": "unlink", "uid": "SR-0012", "fingerprint": "sha256:...",
+{{"op": "unlink", "uid": "SR-0012", "revision": "sha256:...",
  "target": "UR-0003", "type": "implements"}}
   removes that link; "type" may be left out when one link joins them. Refused
   where it would leave an item ungrounded.
 
-{{"op": "delete", "uid": "SR-0012", "fingerprint": "sha256:...",
+{{"op": "delete", "uid": "SR-0012", "revision": "sha256:...",
  "reason": "..."}}
   tombstones the item: its file stays and its UID is never reused.
 
 Rules: no other keys; a "uid", "target" or "label" is written exactly; every
 value is a string except "attrs" (strings, numbers or booleans), "stamp"
 (boolean), and "unset" and "links" (lists). The list may also be sent as
-{{"change_set_format": {CHANGE_SET_FORMAT_VERSION}, "operations": [...]}}. Never send rewritten
+{{"change_set_format": {CHANGE_SET_FORMAT_VERSION}, "operations": [...]}}, which is the safer form. Never send rewritten
 item files: send this change set, and nothing else.
 """
 
@@ -172,24 +189,43 @@ def _scalar(value: object) -> bool:
         or isinstance(value, bool)
 
 
+def _inferred_format(data: list) -> int:
+    """The format of a set that does not say: 1 only where its operations quote a
+    fingerprint and none quotes a revision, so a format-1 set drafted before
+    format 2 still reads as it was written. A set mixing the two is read as the
+    current format, whose rules then name each fingerprint as an unknown key."""
+    ops = [op for op in data if isinstance(op, dict)]
+    if any("fingerprint" in op for op in ops) and not any("revision" in op for op in ops):
+        return 1
+    return CHANGE_SET_FORMAT_VERSION
+
+
 def parse_change_set(text: str) -> list[dict]:
     """Read a change set from its JSON text, refusing it whole when any operation
-    is malformed or is not one an assistant may take (SR-0252). The operations
+    is malformed or is not one an assistant may take (SR-0252). A set that names
+    its ``change_set_format`` is read in that format; one that does not is read
+    as the current format unless it quotes only fingerprints. The operations
     come back as given, checked for shape; whether each can be carried out is
     :func:`apply_change_set`'s to say."""
     try:
         data = json.loads(text)
     except json.JSONDecodeError as e:
         raise ChangeSetError([f"the change set is not JSON: {e}"]) from None
+    version = None
     if isinstance(data, dict) and "operations" in data:
-        version = data.get("change_set_format", CHANGE_SET_FORMAT_VERSION)
-        if version != CHANGE_SET_FORMAT_VERSION:
+        version = data.get("change_set_format")
+        if version is not None and (isinstance(version, bool)
+                                    or version not in READABLE_FORMATS):
             raise ChangeSetError([f"change_set_format {version!r} is not one this "
-                                  f"release reads ({CHANGE_SET_FORMAT_VERSION})"])
+                                  "release reads ("
+                                  + ", ".join(map(str, READABLE_FORMATS)) + ")"])
         data = data["operations"]
     if not isinstance(data, list):
         raise ChangeSetError(["the change set must be a JSON list of operations "
                               "(or an object whose \"operations\" is that list)"])
+    if version is None:
+        version = _inferred_format(data)
+    quoted = READABLE_FORMATS[version]
     problems: list[str] = []
     ops: list[dict] = []
     labels: set[str] = set()
@@ -209,6 +245,8 @@ def parse_change_set(text: str) -> list[dict]:
                                 f"{', '.join(OPERATIONS)}, got {kind!r}")
             continue
         required, allowed = _KEYS[kind]
+        if kind != "new":
+            allowed = allowed | {quoted}
         name = f"{where} {kind}"
         extra = sorted(set(op) - allowed)
         if extra:
@@ -217,7 +255,7 @@ def parse_change_set(text: str) -> list[dict]:
         if missing:
             problems.append(f"{name}: missing {', '.join(missing)}")
         for key in ("uid", "target", "register", "type", "title", "text",
-                    "rationale", "label", "reason", "fingerprint"):
+                    "rationale", "label", "reason", quoted):
             if key in op and not isinstance(op[key], str):
                 problems.append(f"{name}: \"{key}\" must be a string")
         if "stamp" in op and not isinstance(op["stamp"], bool):
@@ -245,12 +283,11 @@ def parse_change_set(text: str) -> list[dict]:
                 if uid[1:] not in labels:
                     problems.append(f"{name}: {uid} names no item created earlier "
                                     "in this set")
-            elif "fingerprint" not in op:
+            elif quoted not in op:
                 problems.append(f"{name} {uid}: an operation on an existing item "
-                                "carries the \"fingerprint\" it was based on")
-            elif isinstance(op["fingerprint"], str) \
-                    and not _FINGERPRINT_RE.match(op["fingerprint"]):
-                problems.append(f"{name} {uid}: \"fingerprint\" must be the sha256:… "
+                                f"carries the \"{quoted}\" it was based on")
+            elif isinstance(op[quoted], str) and not _DIGEST_RE.match(op[quoted]):
+                problems.append(f"{name} {uid}: \"{quoted}\" must be the sha256:… "
                                 "value the export gave")
         if kind == "new":
             label = op.get("label")
@@ -309,10 +346,10 @@ def apply_change_set(project, operations: list[dict], *,
     ``project``, all or nothing (SR-0252).
 
     Every operation is first checked against the graph as it stands: the item it
-    names exists and is not deleted, the fingerprint it quotes is the item's
-    current one, and what it links to can be found. A problem anywhere refuses
-    the whole set before a file is written. Then each operation runs through the
-    function the matching command runs, and a refusal from any of them restores
+    names exists and is not deleted, the revision it quotes (or, in a format-1
+    set, the fingerprint) is the item's current one, and what it links to can be
+    found. A problem anywhere refuses the whole set before a file is written.
+    Then each operation runs through the function the matching command runs, and a refusal from any of them restores
     every file and refuses the set the same way. ``view`` and ``find`` let a
     program that grounds over a wider graph than the one it writes — a union with
     its sources — judge links and find targets there (SR-0212); left out, they are
@@ -334,10 +371,13 @@ def apply_change_set(project, operations: list[dict], *,
             problems.append(f"{name}: {uid} does not exist")
         elif item.is_deleted:
             problems.append(f"{name}: {uid} is deleted — a tombstone is permanent")
-        elif op.get("fingerprint") != fingerprint(item, schema):
-            problems.append(f"{name}: {uid} changed since the export — the set "
-                            f"quotes {op.get('fingerprint')} but the item now "
-                            f"carries {fingerprint(item, schema)}")
+        else:
+            key = "revision" if "revision" in op else "fingerprint"
+            now = revision(item) if key == "revision" else fingerprint(item, schema)
+            if op.get(key) != now:
+                problems.append(f"{name}: {uid} changed since the export — the set "
+                                f"quotes {key} {op.get(key)} but the item now "
+                                f"carries {now}")
         return item
 
     def target_known(name: str, ref: str) -> None:

{throughline-3.18.2 → throughline-3.19.2}/src/throughline/dump.py

@@ -14,10 +14,16 @@ content as it stands (SR-0251), under this documented key, so a reader working
 from the dump can quote back which version of an item it read — what a change
 set hands to ``tl apply`` (SR-0252). It is computed here by the one fingerprint
 rule and nowhere else, so a tool built on the dump never hashes an item itself.
+
+Each item also carries ``revision``: a digest of its whole stored record, so it
+moves on any change at all — a title, a rationale, a link, a status — where the
+fingerprint, which ratification is taken over, moves only on normative content.
+A change set quotes the revision (SR-0252), so an operation drafted against an
+item that has since changed in any way is refused rather than written over it.
 """
 from __future__ import annotations
 
-from .fingerprint import fingerprint
+from .fingerprint import fingerprint, revision
 from .model import Project
 from .storage import FORMAT_VERSION
 
@@ -43,6 +49,7 @@ def build_dump(project: Project, tool_version: str) -> dict:
     def entry(it) -> dict:
         d = it.to_dict()
         d["fingerprint"] = fingerprint(it, schema)
+        d["revision"] = revision(it)
         return d
 
     return {

{throughline-3.18.2 → throughline-3.19.2}/src/throughline/fingerprint.py

@@ -24,6 +24,7 @@ from __future__ import annotations
 
 import copy
 import hashlib
+import json
 import unicodedata
 
 from .schema import Schema
@@ -119,3 +120,16 @@ def content_fingerprint(uid: str, content: object) -> str | None:
         return None
     return _digest(uid, content["type"], content["text"], content["normative"],
                    content["derived"], list(attrs.items()))
+
+
+def revision(item) -> str:
+    """The revision of an item's whole stored record (SR-0251): SHA-256 over the
+    record the item's file holds — every field an operation reads or writes,
+    title, rationale, status, links and every attribute included — in canonical
+    JSON. Unlike :func:`fingerprint`, which a ratification is taken over and so
+    reads only normative content, any change to the item moves its revision, so a
+    change set quoting it is refused when anything about the item has moved since
+    the export it was drafted from (SR-0252)."""
+    record = json.dumps(item.to_dict(), sort_keys=True, ensure_ascii=False,
+                        separators=(",", ":"), default=str)
+    return "sha256:" + hashlib.sha256(record.encode("utf-8")).hexdigest()

{throughline-3.18.2 → throughline-3.19.2/src/throughline.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: throughline
-Version: 3.18.2
+Version: 3.19.2
 Summary: A Git-native requirements management tool with a scope-avalanche grounding layer: permanent UIDs, one file per item, typed links, suspect detection, and a CI-gating check.
 Author-email: Henry J Grech-Cini <henry.grechcini@gmail.com>
 License-Expression: Apache-2.0

{throughline-3.18.2 → throughline-3.19.2}/tests/test_apply.py

@@ -1,13 +1,13 @@
 # Copyright (c) 2026 Henry J Grech-Cini
 # SPDX-License-Identifier: Apache-2.0
-"""`tl dump` states each item's fingerprint (SR-0251) and `tl apply` carries out a
-change set of the Tool's own operations, all or nothing (SR-0252).
+"""`tl dump` states each item's fingerprint and revision (SR-0251) and `tl apply`
+carries out a change set of the Tool's own operations, all or nothing (SR-0252).
 
 An assistant that reads a few files, cannot run commands and returns only text
-works from an export and sends back a change set quoting the fingerprint each
-item carried. These tests hold the two halves to their requirements: the dump
+works from an export and sends back a change set quoting the revision each item
+carried. These tests hold the two halves to their requirements: the dump
 carries the fingerprint the Tool computes, and apply refuses a set whole — on a
-stale fingerprint, a malformed operation, an operation an assistant may not take,
+stale revision, a malformed operation, an operation an assistant may not take,
 or a refusal from the operation itself — changing nothing, and otherwise carries
 out every operation through the matching command's own function, recording what
 it creates or changes with origin ai.
@@ -21,7 +21,7 @@ from throughline import apply_change_set, build_dump, parse_change_set
 from throughline.apply import ChangeSetError
 from throughline.cli import main as _cli
 from throughline.dump import DUMP_SCHEMA_VERSION
-from throughline.fingerprint import fingerprint
+from throughline.fingerprint import fingerprint, revision
 from throughline.storage import load_project
 
 
@@ -50,6 +50,12 @@ def _fp(root: Path, uid: str) -> str:
     return next(i["fingerprint"] for i in dump["items"] if i["uid"] == uid)
 
 
+def _rev(root: Path, uid: str) -> str:
+    """The revision the export gives, read from the dump as an assistant would."""
+    dump = build_dump(load_project(root), "9.9.9")
+    return next(i["revision"] for i in dump["items"] if i["uid"] == uid)
+
+
 def _tree(root: Path) -> dict[str, bytes]:
     return {p.relative_to(root).as_posix(): p.read_bytes()
             for p in root.rglob("*") if p.is_file()}
@@ -66,7 +72,7 @@ def _sound(root: Path) -> list[dict]:
         {"op": "new", "register": "FR", "type": "requirement", "title": "a second",
          "text": "The Tool shall do a second thing.", "rationale": "because",
          "links": [{"target": "INT-0001", "type": "derives_from"}], "label": "fr2"},
-        {"op": "amend", "uid": "FR-0001", "fingerprint": _fp(root, "FR-0001"),
+        {"op": "amend", "uid": "FR-0001", "revision": _rev(root, "FR-0001"),
          "text": "rewritten by an assistant"},
         {"op": "link", "uid": "$fr2", "target": "FR-0001", "type": "derives_from"},
         {"op": "unlink", "uid": "$fr2", "target": "FR-0001", "type": "derives_from"},
@@ -88,12 +94,25 @@ def test_the_dump_states_each_items_fingerprint_under_its_documented_key(tmp_pat
                                                    project.schema)
 
 
+def test_the_dump_states_each_items_revision_beside_its_fingerprint(tmp_path):
+    root = _scaffold(tmp_path)
+    project = load_project(root)
+    for entry in build_dump(project, "9.9.9")["items"]:
+        assert entry["revision"] == revision(project.get(entry["uid"]))
+    before = _rev(root, "FR-0001"), _fp(root, "FR-0001")
+    assert _cli(["-C", str(root), "amend", "FR-0001", "--title", "moved"]) == 0
+    # a title is not normative: the fingerprint stands and the revision moves
+    assert _fp(root, "FR-0001") == before[1]
+    assert _rev(root, "FR-0001") != before[0]
+
+
 def test_the_command_line_dump_carries_it_too(tmp_path, capsys):
     root = _scaffold(tmp_path)
     capsys.readouterr()                      # the scaffold's own output
     assert _cli(["-C", str(root), "dump"]) == 0
     dump = json.loads(capsys.readouterr().out)
     assert all(i["fingerprint"].startswith("sha256:") for i in dump["items"])
+    assert all(i["revision"].startswith("sha256:") for i in dump["items"])
 
 
 # --------------------------------------------------------------------------- #
@@ -105,7 +124,9 @@ def test_describe_prints_the_form_an_assistant_is_given(tmp_path, capsys):
     out = capsys.readouterr().out
     for op in ("new", "amend", "link", "unlink", "delete"):
         assert f'"op": "{op}"' in out
-    assert "fingerprint" in out and "all or nothing" in out
+    assert '"revision": "sha256:...' in out and "all or nothing" in out
+    # what an assistant is told to write is format 2 only: no fingerprint key
+    assert '"fingerprint"' not in out
 
 
 def test_a_sound_set_is_carried_out_in_order_and_everything_is_proposed_origin_ai(
@@ -129,13 +150,13 @@ def test_a_sound_set_is_carried_out_in_order_and_everything_is_proposed_origin_a
     assert first.title == "original title"
 
 
-def test_a_stale_fingerprint_refuses_the_whole_set_and_names_the_operation(
+def test_a_stale_revision_refuses_the_whole_set_and_names_the_operation(
         tmp_path, capsys):
     root = _scaffold(tmp_path)
     before = _tree(root)
     stale = "sha256:" + "0" * 64
     ops = _sound(root)
-    ops[1]["fingerprint"] = stale
+    ops[1]["revision"] = stale
     path = _set(root, ops)
     assert _cli(["-C", str(root), "apply", str(path)]) == 1
     out = capsys.readouterr().out
@@ -146,10 +167,10 @@ def test_a_stale_fingerprint_refuses_the_whole_set_and_names_the_operation(
 def test_a_malformed_set_names_every_offending_operation(tmp_path, capsys):
     root = _scaffold(tmp_path)
     before = _tree(root)
-    fp = _fp(root, "FR-0001")
+    rev = _rev(root, "FR-0001")
     path = _set(root, [
-        {"op": "amend", "fingerprint": fp, "text": "no uid"},
-        {"op": "link", "uid": "FR-0001", "fingerprint": fp, "target": "INT-0001",
+        {"op": "amend", "revision": rev, "text": "no uid"},
+        {"op": "link", "uid": "FR-0001", "revision": rev, "target": "INT-0001",
          "type": "derives_from", "colour": "red"},
         {"op": "ratify", "uid": "FR-0001"},
         {"op": "delete", "uid": "FR-0001"},
@@ -182,10 +203,10 @@ def test_a_refusal_from_an_operation_restores_every_file(tmp_path, capsys):
     refused and #1 is undone."""
     root = _scaffold(tmp_path)
     before = _tree(root)
-    fp = _fp(root, "FR-0001")
+    rev = _rev(root, "FR-0001")
     path = _set(root, [
-        {"op": "amend", "uid": "FR-0001", "fingerprint": fp, "text": "changed"},
-        {"op": "unlink", "uid": "FR-0001", "fingerprint": fp, "target": "INT-0001"},
+        {"op": "amend", "uid": "FR-0001", "revision": rev, "text": "changed"},
+        {"op": "unlink", "uid": "FR-0001", "revision": rev, "target": "INT-0001"},
     ])
     assert _cli(["-C", str(root), "apply", str(path)]) == 1
     out = capsys.readouterr().out
@@ -215,7 +236,7 @@ def test_json_output_reports_each_operation_and_the_files(tmp_path, capsys):
     assert report["created"] == ["FR-0002"] and report["changed"] == ["FR-0001"]
     assert sorted(report["files"]) == ["features/FR-0001.yml", "features/FR-0002.yml"]
     # a refusal is reported the same way
-    path = _set(root, [{"op": "delete", "uid": "FR-0009", "fingerprint": "sha256:" + "a" * 64}])
+    path = _set(root, [{"op": "delete", "uid": "FR-0009", "revision": "sha256:" + "a" * 64}])
     assert _cli(["-C", str(root), "apply", str(path), "--format", "json"]) == 1
     refusal = json.loads(capsys.readouterr().out)
     assert refusal["applied"] is False and "FR-0009 does not exist" in refusal["problems"][0]
@@ -223,21 +244,21 @@ def test_json_output_reports_each_operation_and_the_files(tmp_path, capsys):
 
 def test_a_delete_tombstones_and_an_operation_on_a_tombstone_is_refused(tmp_path):
     root = _scaffold(tmp_path)
-    fp = _fp(root, "FR-0001")
-    path = _set(root, [{"op": "delete", "uid": "FR-0001", "fingerprint": fp,
+    rev = _rev(root, "FR-0001")
+    path = _set(root, [{"op": "delete", "uid": "FR-0001", "revision": rev,
                         "reason": "withdrawn by the assistant"}])
     assert _cli(["-C", str(root), "apply", str(path)]) == 0
     gone = _item(root, "FR-0001")
     assert gone.is_deleted and gone.deleted["reason"] == "withdrawn by the assistant"
     assert gone.attrs["origin"] == "ai"
-    path = _set(root, [{"op": "amend", "uid": "FR-0001", "fingerprint": fp,
+    path = _set(root, [{"op": "amend", "uid": "FR-0001", "revision": rev,
                         "text": "back from the dead"}])
     assert _cli(["-C", str(root), "apply", str(path)]) == 1
 
 
 def test_the_wrapped_form_is_accepted_and_the_library_needs_no_command_line(tmp_path):
     root = _scaffold(tmp_path)
-    text = json.dumps({"change_set_format": 1, "operations": _sound(root)})
+    text = json.dumps({"change_set_format": 2, "operations": _sound(root)})
     operations = parse_change_set(text)
     project = load_project(root)
     result = apply_change_set(project, operations)
@@ -251,3 +272,74 @@ def test_the_wrapped_form_is_accepted_and_the_library_needs_no_command_line(tmp_
         assert any("FR-0001 changed since the export" in p for p in e.problems)
     else:
         raise AssertionError("a stale set was applied")
+
+
+# --------------------------------------------------------------------------- #
+# SR-0252 — a change to any field since the export refuses the set
+# --------------------------------------------------------------------------- #
+
+import pytest  # noqa: E402
+
+_EDITS = {
+    "title": ["amend", "FR-0001", "--title", "moved by someone else"],
+    "rationale": ["amend", "FR-0001", "--rationale", "a newer reason"],
+    "attribute": ["amend", "FR-0001", "--attr", "owner=someone"],
+    "link": ["link", "FR-0001", "FR-0002", "--type", "relates"],
+    "status": ["status", "FR-0001", "deferred"],
+}
+
+
+@pytest.mark.parametrize("edit", sorted(_EDITS))
+def test_an_edit_after_the_export_that_moves_no_fingerprint_still_refuses_the_set(
+        tmp_path, capsys, edit):
+    root = _scaffold(tmp_path)
+    assert _cli(["-C", str(root), "new", "FR", "--type", "requirement",
+                 "--title", "other", "--text", "other", "--ground", "INT-0001"]) == 0
+    if edit == "attribute":
+        assert _cli(["-C", str(root), "schema", "attr", "add", "requirement",
+                     "owner", "--kind", "string", "--because", "a test"]) == 0
+    exported = _rev(root, "FR-0001"), _fp(root, "FR-0001")
+    assert _cli(["-C", str(root), *_EDITS[edit]]) == 0
+    assert _fp(root, "FR-0001") == exported[1], "the edit is not normative"
+    before = _tree(root)
+    path = _set(root, [{"op": "amend", "uid": "FR-0001", "revision": exported[0],
+                        "title": "the assistant's title"}])
+    capsys.readouterr()
+    assert _cli(["-C", str(root), "apply", str(path)]) == 1
+    out = capsys.readouterr().out
+    assert "#1 amend: FR-0001 changed since the export" in out
+    assert _tree(root) == before
+
+
+def test_a_format_1_set_quoting_fingerprints_is_still_read(tmp_path):
+    root = _scaffold(tmp_path)
+    fp = _fp(root, "FR-0001")
+    for text in (json.dumps([{"op": "amend", "uid": "FR-0001", "fingerprint": fp,
+                              "title": "bare list"}]),
+                 json.dumps({"change_set_format": 1, "operations": [
+                     {"op": "amend", "uid": "FR-0001", "fingerprint": fp,
+                      "title": "wrapped"}]})):
+        result = apply_change_set(load_project(root), parse_change_set(text))
+        assert result.changed == ["FR-0001"]
+    assert _item(root, "FR-0001").title == "wrapped"
+
+
+def test_format_2_takes_only_the_revision_and_format_1_only_the_fingerprint(tmp_path):
+    root = _scaffold(tmp_path)
+    fp, rev = _fp(root, "FR-0001"), _rev(root, "FR-0001")
+    cases = [
+        ({"change_set_format": 2, "operations": [
+            {"op": "amend", "uid": "FR-0001", "fingerprint": fp, "title": "x"}]},
+         "unknown key(s) fingerprint"),
+        ({"change_set_format": 1, "operations": [
+            {"op": "amend", "uid": "FR-0001", "revision": rev, "title": "x"}]},
+         "unknown key(s) revision"),
+        ([{"op": "amend", "uid": "FR-0001", "revision": rev, "title": "x"},
+          {"op": "amend", "uid": "FR-0001", "fingerprint": fp, "title": "y"}],
+         "#2 amend: unknown key(s) fingerprint"),
+        ({"change_set_format": 3, "operations": []}, "is not one this release reads"),
+    ]
+    for data, expected in cases:
+        with pytest.raises(ChangeSetError) as e:
+            parse_change_set(json.dumps(data))
+        assert any(expected in p for p in e.value.problems), (expected, e.value.problems)