throughline 4.2.0__tar.gz → 4.4.0__tar.gz

{throughline-4.2.0/src/throughline.egg-info → throughline-4.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: throughline
-Version: 4.2.0
+Version: 4.4.0
 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
@@ -36,10 +36,10 @@ version control; a `check` command validates the whole graph and gates CI.
 
 **Dogfooded:** throughline's own spec is itself a throughline project —
 <!-- tl:count type == 'system_requirement' -->
-240
+248
 <!-- tl:end --> system requirements,
 <!-- tl:count type == 'user_requirement' -->
-37
+39
 <!-- tl:end --> user requirements, and
 <!-- tl:count type == 'nfr' -->
 21
@@ -164,7 +164,7 @@ detect items that "violate" a non-goal — that judgement stays with a human.
 ```
 tl init [--name NAME]                         # scaffold a project
 tl register new <PREFIX> <dir> [--parent P]   # add a register
-tl new <PREFIX> [--uid U] [--type T] [--ground UID]  # allocate + create (grounded at birth)
+tl new <PREFIX> [--uid U] [--type T] [--ground UID] [--key UUID4]  # allocate + create (grounded at birth); a held key creates nothing
 tl link <SRC> <DST> --type <kind> [--stamp]   # add a typed link
 tl delete <UID> --reason "…"                  # propose a deletion: a tombstone a human ratifies (never erased)
 tl restore <UID>                              # decline a proposed deletion
@@ -206,6 +206,7 @@ Upward and downward coverage are independent and both matter:
 | `uid-filename` | an item's file is not named `<UID>.yml` (git could not see it collide) |
 | `tombstone-deleted` | a retired UID's tombstone was erased (bad merge / stray `git rm`) |
 | `schema` | missing required attr or out-of-enum value |
+| `attribute-kind` | an attribute's value is not of its declared kind (`int`, `float`, `bool`, `date` as YYYY-MM-DD, `string`, `text`) |
 | `suspect-link` | target changed since the link was last confirmed |
 | `unreviewed` | item content changed since last review |
 | `unratified` | AI-origin item still `proposed` |
@@ -241,6 +242,18 @@ reports every finding in `namespace:UID` vocabulary. `query`, `dump`, `docs`,
 answer over the union too; everything else reads your graph alone, and a project
 that declares no sources is untouched by any of this.
 
+A graph whose own items follow a shared model — every deck in a series, every plan
+written to one standard — can take its schema from a source instead of copying it.
+Mark that one source `schema = true`; the project is then checked by the source's
+item types, attributes, link types, statuses, transitions, roles, grounding and coverage rules,
+plus whatever it adds itself. It may add an attribute, a type, a status or a link
+type, but never redefine one the source declares: a widened enum or a changed
+attribute is refused when the configuration is read, naming both values.
+`tl migrate` removes a copy the source makes redundant, `tl context`,
+`tl schema show` and `tl dump` mark what was inherited, and `tl schema` refuses
+to change it. Every operation then reads that one source; the rest wait for the
+union.
+
 Sources are read-only, fetched once into a per-user cache and reached again only
 when a tag or branch has moved; `TL_OFFLINE=1` composes from the cache alone. A
 program embedding the Tool reaches a source through the `Resolver` it supplies, so

{throughline-4.2.0 → throughline-4.4.0}/README.md

@@ -8,10 +8,10 @@ version control; a `check` command validates the whole graph and gates CI.
 
 **Dogfooded:** throughline's own spec is itself a throughline project —
 <!-- tl:count type == 'system_requirement' -->
-240
+248
 <!-- tl:end --> system requirements,
 <!-- tl:count type == 'user_requirement' -->
-37
+39
 <!-- tl:end --> user requirements, and
 <!-- tl:count type == 'nfr' -->
 21
@@ -136,7 +136,7 @@ detect items that "violate" a non-goal — that judgement stays with a human.
 ```
 tl init [--name NAME]                         # scaffold a project
 tl register new <PREFIX> <dir> [--parent P]   # add a register
-tl new <PREFIX> [--uid U] [--type T] [--ground UID]  # allocate + create (grounded at birth)
+tl new <PREFIX> [--uid U] [--type T] [--ground UID] [--key UUID4]  # allocate + create (grounded at birth); a held key creates nothing
 tl link <SRC> <DST> --type <kind> [--stamp]   # add a typed link
 tl delete <UID> --reason "…"                  # propose a deletion: a tombstone a human ratifies (never erased)
 tl restore <UID>                              # decline a proposed deletion
@@ -178,6 +178,7 @@ Upward and downward coverage are independent and both matter:
 | `uid-filename` | an item's file is not named `<UID>.yml` (git could not see it collide) |
 | `tombstone-deleted` | a retired UID's tombstone was erased (bad merge / stray `git rm`) |
 | `schema` | missing required attr or out-of-enum value |
+| `attribute-kind` | an attribute's value is not of its declared kind (`int`, `float`, `bool`, `date` as YYYY-MM-DD, `string`, `text`) |
 | `suspect-link` | target changed since the link was last confirmed |
 | `unreviewed` | item content changed since last review |
 | `unratified` | AI-origin item still `proposed` |
@@ -213,6 +214,18 @@ reports every finding in `namespace:UID` vocabulary. `query`, `dump`, `docs`,
 answer over the union too; everything else reads your graph alone, and a project
 that declares no sources is untouched by any of this.
 
+A graph whose own items follow a shared model — every deck in a series, every plan
+written to one standard — can take its schema from a source instead of copying it.
+Mark that one source `schema = true`; the project is then checked by the source's
+item types, attributes, link types, statuses, transitions, roles, grounding and coverage rules,
+plus whatever it adds itself. It may add an attribute, a type, a status or a link
+type, but never redefine one the source declares: a widened enum or a changed
+attribute is refused when the configuration is read, naming both values.
+`tl migrate` removes a copy the source makes redundant, `tl context`,
+`tl schema show` and `tl dump` mark what was inherited, and `tl schema` refuses
+to change it. Every operation then reads that one source; the rest wait for the
+union.
+
 Sources are read-only, fetched once into a per-user cache and reached again only
 when a tag or branch has moved; `TL_OFFLINE=1` composes from the cache alone. A
 program embedding the Tool reaches a source through the `Resolver` it supplies, so

{throughline-4.2.0 → throughline-4.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "throughline"
-version = "4.2.0"
+version = "4.4.0"
 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-4.2.0 → throughline-4.4.0}/src/throughline/apply.py

@@ -27,6 +27,14 @@ file the set had touched. Everything the set creates or changes is recorded
 with a machine origin, so it enters the lifecycle as proposed and a person still
 decides (SR-0092).
 
+A set may be applied more than once and changes the graph once (SR-0280, SR-0281).
+A ``new`` operation may carry a ``key``, a UUID version 4 recorded on the item it
+creates; where a live item already carries that key the operation creates nothing,
+and its label names that item. Any other operation whose result the graph already
+holds — a link already there, an unlink of one that is not, an amend whose fields
+already read so, a delete of a tombstone — is skipped and reported as already
+applied, whatever revision it quotes, since nothing would be written.
+
 These are the functions `tl apply` is made of; the command line is one caller
 (SR-0224, SR-0225). A program embedding the Tool reaches them by name.
 """
@@ -40,7 +48,8 @@ from typing import Callable
 
 from .fingerprint import fingerprint, revision
 from .grounding import GroundingError, set_status
-from .items import amend_item, delete_item, item_type_for, new_item, parse_attrs
+from .items import (amend_item, check_key, delete_item, item_type_for, keyed_item,
+                    new_item, parse_attrs)
 from .links import GroundingView, LinkError, add_link, remove_link
 from .model import Item, Link
 from .schema import SchemaError
@@ -74,7 +83,7 @@ _DIGEST_RE = re.compile(r"^sha256:[0-9a-f]{64}$")
 _KEYS: dict[str, tuple[set[str], set[str]]] = {
     "new": ({"register"},
             {"op", "register", "type", "title", "text", "rationale", "attrs",
-             "links", "label"}),
+             "links", "label", "key"}),
     "amend": ({"uid"},
               {"op", "uid", "title", "text", "rationale", "attrs",
                "unset"}),
@@ -117,7 +126,10 @@ The five operations:
  "links": [{{"target": "UR-0003", "type": "implements"}}], "label": "sr1"}}
   creates an item in the register with that prefix. "type" may be left out
   where the register declares one. "links" ground the item: a non-root item
-  must reach a root through them. "label" is optional.
+  must reach a root through them. "label" is optional. "key" is optional and
+  recommended: a fresh UUID version 4 (e.g. "3f0c1b7e-8a52-4c4e-9d61-2b7f5a9c0e14")
+  recorded on the item. Where an item already carries it, nothing is created
+  and the label names that item, so the set can be applied again safely.
 
 {{"op": "amend", "uid": "SR-0012", "revision": "sha256:...", "title": "...",
  "text": "...", "rationale": "...", "attrs": {{"priority": "must"}},
@@ -138,6 +150,10 @@ The five operations:
  "reason": "..."}}
   tombstones the item: its file stays and its UID is never reused.
 
+Applying a set twice changes the graph once: an operation whose result the
+graph already holds (a link already there, an amend whose fields already read
+so, a delete of a deleted item) is skipped and reported as already applied.
+
 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
@@ -229,6 +245,7 @@ def parse_change_set(text: str) -> list[dict]:
     problems: list[str] = []
     ops: list[dict] = []
     labels: set[str] = set()
+    keys: set[str] = set()
     for i, op in enumerate(data, start=1):
         where = f"#{i}"
         if not isinstance(op, dict):
@@ -255,7 +272,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", quoted):
+                    "rationale", "label", "reason", "key", 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):
@@ -289,6 +306,14 @@ def parse_change_set(text: str) -> list[dict]:
             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" and isinstance(op.get("key"), str):
+            try:
+                check_key(op["key"])
+            except ValueError as e:
+                problems.append(f"{name}: {e}")
+            if op["key"] in keys:
+                problems.append(f"{name}: key {op['key']} is already used in this set")
+            keys.add(op["key"])
         if kind == "new":
             label = op.get("label")
             if isinstance(label, str):
@@ -361,25 +386,83 @@ def apply_change_set(project, operations: list[dict], *,
     ai = _ai_origin(schema)
     problems: list[str] = []
     labels: dict[str, str] = {}
-
-    def existing(name: str, op: dict) -> Item | None:
+    # The operations whose result the graph already holds (SR-0280, SR-0281), by
+    # position: each is skipped rather than carried out.
+    held: set[int] = set()
+    # Held operations whose quoted version is no longer the item's: the mark of a
+    # set that has run before, as (position, name, uid, key, quoted, now).
+    stale: list[tuple[int, str, str, str, str, str]] = []
+
+    def version(op: dict, item: Item) -> tuple[str, str]:
+        key = "revision" if "revision" in op else "fingerprint"
+        return key, (revision(item) if key == "revision" else fingerprint(item, schema))
+
+    def resolved(ref: str) -> str | None:
+        """A reference as it stands before anything is written: a UID, or the
+        existing item a label names, or ``None`` for an item still to be made."""
+        if not _is_label(ref):
+            return ref
+        return labels.get(ref[1:]) or None
+
+    def existing(name: str, op: dict, i: int) -> Item | None:
         uid = op["uid"]
         if _is_label(uid):
+            # A label naming an item the set found under its key is that item; an
+            # operation on it is judged as on any item created in the set, with
+            # no revision, but may already be held.
+            known = resolved(uid)
+            item = project.get(known) if known else None
+            if item is not None and holds(op, item):
+                held.add(i)
             return None
         item = project.get(uid)
         if item is None:
             problems.append(f"{name}: {uid} does not exist")
+        elif op["op"] == "delete" and item.is_deleted:
+            held.add(i)
         elif item.is_deleted:
             problems.append(f"{name}: {uid} is deleted — a tombstone is permanent")
+        elif holds(op, item):
+            held.add(i)
+            key, now = version(op, item)
+            if op.get(key) != now:
+                stale.append((i, name, uid, key, op.get(key), now))
         else:
-            key = "revision" if "revision" in op else "fingerprint"
-            now = revision(item) if key == "revision" else fingerprint(item, schema)
+            key, now = version(op, item)
             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 holds(op: dict, item: Item) -> bool:
+        """Whether ``item`` already shows what ``op`` would make it (SR-0281)."""
+        kind = op["op"]
+        if kind == "delete":
+            return item.is_deleted
+        if kind in ("link", "unlink"):
+            target = resolved(op["target"])
+            if target is None:
+                return False
+            there = any(l.target == target and (op.get("type") is None
+                                                or l.type == op["type"])
+                        for l in item.links)
+            return there if kind == "link" else not there
+        if kind == "amend":
+            for field_name in ("title", "text", "rationale"):
+                if field_name in op and getattr(item, field_name) != op[field_name]:
+                    return False
+            try:
+                pairs = [f"{k}={v}" for k, v in (op.get("attrs") or {}).items()]
+                wanted = parse_attrs(schema, item.type, pairs, command="apply",
+                                     declared_only=True)
+            except (SchemaError, ValueError):
+                return False
+            if any(item.attrs.get(k) != v for k, v in wanted.items()):
+                return False
+            return not any(k in item.attrs for k in op.get("unset", ()))
+        return False
+
     def target_known(name: str, ref: str) -> None:
         if _is_label(ref) or find(ref) is not None:
             return
@@ -398,15 +481,32 @@ def apply_change_set(project, operations: list[dict], *,
                 if schema.link_types and l["type"] not in schema.link_types:
                     problems.append(f"{name}: '{l['type']}' is not a link type this "
                                     f"project declares ({', '.join(sorted(schema.link_types))})")
+            found = keyed_item(project, op["key"]) if "key" in op else None
+            if found is not None:
+                held.add(i)
             if "label" in op:
-                labels[op["label"]] = ""
+                labels[op["label"]] = found.uid if found is not None else ""
             continue
-        existing(name, op)
+        existing(name, op, i)
         if kind in ("link", "unlink"):
             target_known(name, op["target"])
         if kind == "link" and schema.link_types and op["type"] not in schema.link_types:
             problems.append(f"{name}: '{op['type']}' is not a link type this project "
                             f"declares ({', '.join(sorted(schema.link_types))})")
+    # A set that has run before can be applied again only where every item it
+    # creates carries a key (SR-0280): an unkeyed new operation cannot tell that
+    # it already ran, and would make its item a second time.
+    unkeyed = [f"#{i}" for i, op in enumerate(operations, start=1)
+               if op["op"] == "new" and "key" not in op]
+    if stale and unkeyed:
+        for _i, name, uid, key, quoted, now in stale:
+            problems.append(
+                f"{name}: {uid} changed since the export — the set quotes {key} "
+                f"{quoted} but the item now carries {now}. It already shows what "
+                f"this operation asks, so the set looks applied, and its new "
+                f"operation(s) {', '.join(unkeyed)} carry no key: applying it again "
+                "would create them twice. Nothing was changed. A set whose new "
+                "operations carry keys can be applied again safely (SR-0280)")
     if problems:
         raise ChangeSetError(problems)
 
@@ -445,6 +545,31 @@ def apply_change_set(project, operations: list[dict], *,
     try:
         for i, op in enumerate(operations, start=1):
             kind = op["op"]
+            if i in held:
+                # Held when judged, and skipped if held still. Where an earlier
+                # operation in this set undid it, it is carried out as asked if the
+                # version it quoted was current, and otherwise refused: a set
+                # applied twice cannot tell that apart from a conflict.
+                if kind == "new":
+                    found = keyed_item(project, op["key"])
+                    if found is None:
+                        raise ValueError(f"key {op['key']} no longer names an item")
+                    if "label" in op:
+                        labels[op["label"]] = found.uid
+                    result.operations.append(OperationResult(
+                        i, kind, found.uid, "already applied", f"key {op['key']}"))
+                    continue
+                item = project.get(resolve(op["uid"]))
+                if item is not None and holds(op, item):
+                    result.operations.append(OperationResult(
+                        i, kind, item.uid, "already applied", ""))
+                    continue
+                if i in {pos for pos, *_ in stale}:
+                    raise ValueError("an earlier operation in this set undid what "
+                                     "this one found already done, and the "
+                                     "revision it quotes is not the item's")
+                # An earlier operation in the set undid it, and the version it
+                # quoted was current: it is carried out as asked.
             if kind == "new":
                 prefix = op["register"]
                 item_type = item_type_for(project, prefix, op.get("type"))
@@ -452,7 +577,7 @@ def apply_change_set(project, operations: list[dict], *,
                 attrs = parse_attrs(schema, item_type, pairs, command="apply")
                 item = new_item(project, prefix, item_type=item_type,
                                 title=op.get("title", ""), text=op.get("text", ""),
-                                origin=ai, attrs=attrs)
+                                origin=ai, attrs=attrs, key=op.get("key"))
                 if op.get("rationale"):
                     item.rationale = op["rationale"]
                 for l in op.get("links", []):

{throughline-4.2.0 → throughline-4.4.0}/src/throughline/brief.py

@@ -14,6 +14,7 @@ from __future__ import annotations
 import argparse
 from pathlib import Path
 
+from .inherit import coverage_path
 from .graph import Index
 from .signatures import retired
 from .parser import build_parser
@@ -106,7 +107,27 @@ def _ctx_working(schema) -> str:
     )
 
 
-def _ctx_types(schema) -> str:
+def _from(inheritance, *path: str) -> str:
+    """The mark on a declaration the schema source makes (SR-0279)."""
+    if inheritance is None or not inheritance.owns(*path):
+        return ""
+    return f" (from `{inheritance.namespace}`)"
+
+
+def _ctx_schema_source(inheritance) -> str:
+    """Where this project's schema comes from (SR-0279), so an agent changes a rule
+    where it is declared rather than in a file that only inherits it."""
+    ns = inheritance.namespace
+    return (
+        "## Schema source\n\n"
+        f"This project takes its schema from the source `{ns}` (SR-0275) and declares "
+        "only what it adds. Below, every declaration marked _(from "
+        f"`{ns}`)_ is the source's: it cannot be redefined here (SR-0276), and "
+        "`tl schema` refuses to change it (SR-0279). Change it in the source's own "
+        "graph and move this project's pin to take it.")
+
+
+def _ctx_types(schema, inheritance=None) -> str:
     out = ["## Item types and their attributes\n"]
     if not schema.types:
         out.append("_This project declares no per-type attribute schema; item "
@@ -120,6 +141,8 @@ def _ctx_types(schema) -> str:
             tags.append("delivery-root")
         if not schema.is_normative(tname):
             tags.append("non-normative")
+        if _from(inheritance, "type", tname):
+            tags.append(f"from `{inheritance.namespace}`")
         tag = f" _({', '.join(tags)})_" if tags else ""
         out.append(f"### `{tname}`{tag}\n")
         specs = schema.attrs_for(tname)
@@ -132,19 +155,30 @@ def _ctx_types(schema) -> str:
             s = specs[aname]
             vals = ", ".join(f"`{v}`" for v in s.values) if s.values else "—"
             out.append(
-                f"| `{aname}` | {s.kind or 'free'} | "
+                f"| `{aname}`{_from(inheritance, 'attr', tname, aname)} | "
+                f"{s.kind or 'free'} | "
                 f"{'yes' if s.required else 'no'} | "
                 f"{'yes' if s.normative else 'no'} | {vals} |")
         out.append("")
     return "\n".join(out).rstrip()
 
 
-def _ctx_links(schema) -> str:
+def _inherited_of(inheritance, kind: str, names) -> str:
+    """The members of ``names`` the schema source declares, as a brief line."""
+    if inheritance is None:
+        return ""
+    theirs = [n for n in names if inheritance.owns(kind, n)]
+    return (f"  Of these, {_fmt_set(theirs)} come from the schema source "
+            f"`{inheritance.namespace}`." if theirs else "")
+
+
+def _ctx_links(schema, inheritance=None) -> str:
     out = ["## Links\n"]
     if schema.link_types is None:
         out.append("- **Link vocabulary:** unconstrained (any link type is legal).")
     else:
-        out.append(f"- **Link vocabulary:** {_fmt_set(schema.link_types)}.")
+        out.append(f"- **Link vocabulary:** {_fmt_set(schema.link_types)}."
+                   + _inherited_of(inheritance, "link", schema.link_types))
     out.append(f"- **Grounding links** (these carry justification): "
                f"{_fmt_set(schema.ground_link_types)}.")
     if schema.link_rules:
@@ -164,18 +198,20 @@ def _ctx_links(schema) -> str:
     return "\n".join(out)
 
 
-def _ctx_status(schema) -> str:
+def _ctx_status(schema, inheritance=None) -> str:
     out = ["## Status and lifecycle\n"]
     if schema.statuses is None:
         out.append("- **Statuses:** unconstrained (any status string is legal).")
     else:
-        out.append(f"- **Statuses:** {_fmt_set(schema.statuses)}.")
+        out.append(f"- **Statuses:** {_fmt_set(schema.statuses)}."
+                   + _inherited_of(inheritance, "status", schema.statuses))
     if schema.transitions:
         out.append("- **Allowed transitions** (a status may only move along "
                    "these edges; staying put is always allowed):\n")
         for frm in sorted(schema.transitions):
             tos = schema.transitions[frm]
-            out.append(f"  - `{frm}` → {_fmt_set(tos)}")
+            out.append(f"  - `{frm}` → {_fmt_set(tos)}"
+                       + _from(inheritance, "transition", frm))
         out.append("\n  Render this as a diagram with "
                    "`tl diagram transitions`.")
     else:
@@ -247,7 +283,7 @@ def _describe_requirement(req) -> str:
     return " and ".join(parts)
 
 
-def _ctx_coverage(schema) -> str:
+def _ctx_coverage(schema, inheritance=None) -> str:
     out = ["## Coverage rules\n"]
     if not schema.coverage:
         out.append("_No `[[rules.coverage]]` declared._")
@@ -255,12 +291,19 @@ def _ctx_coverage(schema) -> str:
     out.append("Each rule requires the matching items to have the stated link "
                "(unmet → a `coverage` finding). They are numbered as "
                "`tl schema rule remove` counts them:\n")
-    for pos, rule in enumerate(schema.coverage, start=1):
+    pos = 0
+    for rule in schema.coverage:
         filt = rule.get("filter", "*")
         needs = rule.get("needs", "?")
         sev = rule.get("severity", WARNING)
-        out.append(f"{pos}. items where `{filt}` **need** `{needs}` "
-                   f"(severity: {sev})")
+        line = f"items where `{filt}` **need** `{needs}` (severity: {sev})"
+        # An inherited rule is the schema source's (SR-0275, SR-0279): it is not
+        # this project's to remove, so it takes no number here.
+        if inheritance is not None and inheritance.owns(*coverage_path(rule)):
+            out.append(f"- {line} (from `{inheritance.namespace}`)")
+            continue
+        pos += 1
+        out.append(f"{pos}. {line}")
     return "\n".join(out)
 
 
@@ -471,15 +514,17 @@ def context_markdown(project) -> str:
         "configuration changes, regenerate it with `tl context`. "
         "If a capability isn't described here, it isn't in the tool."
     )
+    inheritance = project.inheritance
     sections = [
         header,
         _ctx_idd(schema),
         _ctx_working(schema),
-        _ctx_types(schema),
-        _ctx_links(schema),
-        _ctx_status(schema),
+        *([_ctx_schema_source(inheritance)] if inheritance is not None else []),
+        _ctx_types(schema, inheritance),
+        _ctx_links(schema, inheritance),
+        _ctx_status(schema, inheritance),
         _ctx_grounding(schema),
-        _ctx_coverage(schema),
+        _ctx_coverage(schema, inheritance),
         _CTX_FORMAT,
         _ctx_commands(),
         _ctx_snapshot(project),

{throughline-4.2.0 → throughline-4.4.0}/src/throughline/cli.py

@@ -83,10 +83,12 @@ from .items import (
     Amendment,
     amend_item,
     birth_item,
+    check_key,
     coerce_attr,
     delete_item,
     restore_item,
     item_type_for,
+    keyed_item,
     new_item,
     newly_suspect,
     parse_attrs,
@@ -286,6 +288,7 @@ def cmd_migrate(args) -> int:
                  or result.cached or result.normative or result.contents
                  or result.unprovable or result.registers or result.lifted
                  or result.tombstones or result.unattributed or result.withdrawn
+                 or result.inherited
                  else " — nothing to migrate"))
     else:
         # Already at this major, but missing configuration the major requires —
@@ -388,6 +391,13 @@ def cmd_migrate(args) -> int:
               "declared source that carries it:")
         for ns in result.withdrawn:
             print(f"  {ns}")
+    # The copy of the schema source's declarations removed (SR-0277), each named
+    # so the keeper can read the diff against this list.
+    if result.inherited:
+        print(f"removed {len(result.inherited)} declaration(s) the schema source "
+              "already makes identically:")
+        for what in result.inherited:
+            print(f"  {what}")
     if result.registers:
         print(f"declared the item type of {len(result.registers)} register(s), "
               "which `tl new` now gives items born there (SR-0241):")
@@ -453,6 +463,24 @@ def cmd_schema(args) -> int:
     return OK
 
 
+def cmd_schema_show(args) -> int:
+    """List the project's schema as formed, each declaration marked with the schema
+    source it came from (SR-0279)."""
+    try:
+        project = schema_ops.load(Path(args.path))
+    except schema_ops.SchemaOpError as e:
+        return _err(str(e))
+    rows = schema_ops.show(project)
+    if args.format == "json":
+        print(json.dumps(rows, indent=2, ensure_ascii=False))
+        return OK
+    for row in rows:
+        value = "" if row["value"] is True else f" = {json.dumps(row['value'])}"
+        origin = f"  (from {row['from']})" if row["from"] else ""
+        print(f"{row['declaration']}{value}{origin}")
+    return OK
+
+
 def cmd_schema_attr_remove(args) -> int:
     """Withdraw an attribute from an item type, naming the items that still carry
     it, and with --unset remove it from them as well (SR-0207).
@@ -466,7 +494,7 @@ def cmd_schema_attr_remove(args) -> int:
         project = schema_ops.load(root)
         declared = project.schema.attr(args.itype, args.name) is not None
         carriers = schema_ops.attr_carriers(project, args.itype, args.name)
-        type_declared = args.itype in (project.config.get("types") or {})
+        type_declared = args.itype in (project.formed_config.get("types") or {})
         if declared:
             change = schema_ops.attr_remove(project, args.itype, args.name)
         elif args.unset and carriers and type_declared:
@@ -689,11 +717,23 @@ def cmd_new(args) -> int:
     # honoured, including for a root type (SR-0091).
     default_type = args.ground_type or "derives_from"
     named = list(args.ground or ())
+    # The same creation asked for again (SR-0280): the item made under this key
+    # is named, and nothing is created or written.
+    key = getattr(args, "key", None)
+    if key is not None:
+        try:
+            check_key(key)
+        except ValueError as e:
+            return _err(str(e))
+        held = keyed_item(project, key)
+        if held is not None:
+            print(f"exists {held.uid} -> {held._path} (key {key}) — nothing created")
+            return OK
     try:
         item = new_item(project, args.prefix, item_type=item_type, uid=args.uid,
                         title=args.title or "", text=args.text or "",
                         status=args.status, origin=args.origin, attrs=attrs,
-                        ground=named, ground_type=default_type)
+                        ground=named, ground_type=default_type, key=key)
     except (ProjectError, GroundingError, SchemaError, UidError) as e:
         return _err(str(e))
     grounds = [(target, default_type) for target in named]

{throughline-4.2.0 → throughline-4.4.0}/src/throughline/composition.py

@@ -478,7 +478,7 @@ def local_view(view: Project, consumer: Project) -> Project:
     SR-0040). Ownership is read from the consumer's own register set rather than
     inferred from the shape of a displayed name, so narrowing cannot disagree with
     what was loaded."""
-    out = Project(path=view.path, config=view.config)
+    out = view.shell()
     for prefix, reg in view.registers.items():
         if prefix in consumer.registers:
             out.registers[prefix] = reg

{throughline-4.2.0 → throughline-4.4.0}/src/throughline/dump.py

@@ -56,7 +56,7 @@ def build_dump(project: Project, tool_version: str) -> dict:
         d["revision"] = revision(it)
         return d
 
-    return {
+    out = {
         "throughline_dump": {
             "dump_schema_version": DUMP_SCHEMA_VERSION,
             "format_version": FORMAT_VERSION,
@@ -66,3 +66,15 @@ def build_dump(project: Project, tool_version: str) -> dict:
         "registers": registers,
         "items": [entry(it) for it in items],
     }
+    # A project that takes its schema from a source (SR-0275) says so, with the
+    # schema as formed and every declaration it inherited (SR-0279). `config`
+    # stays the project's own file. Absent for every other project, whose dump is
+    # unchanged.
+    inheritance = project.inheritance
+    if inheritance is not None:
+        out["schema_source"] = {
+            "namespace": inheritance.namespace,
+            "formed": project.formed_config,
+            "inherited": sorted(list(p) for p in inheritance.paths),
+        }
+    return out