theurian 0.1.0.dev5__tar.gz → 0.1.0.dev7__tar.gz

{theurian-0.1.0.dev5 → theurian-0.1.0.dev7}/CHANGELOG.md

@@ -12,6 +12,99 @@ Pre-1.0, a MINOR bump may change the protocol. Post-1.0, only a MAJOR may.
 
 ## [Unreleased]
 
+## [0.1.0.dev7] - 2026-08-19
+
+### Added
+
+- **`theurian propose` can now set `--scope-path` and `--label`**
+  ([#249](https://github.com/theurian/theurian/issues/249)). Each is repeatable
+  and keeps the order it was given: `--scope-path` writes `metadata.scope.paths`
+  (the globs Milestone 8's drift detection will read), and `--label` writes
+  `metadata.labels`. A `--label` given alongside `--authored-here` is
+  de-duplicated against the implied `authored-in-theurian` label — the schema
+  declares `labels` `uniqueItems`, so a duplicate would otherwise turn a legal
+  invocation into a refusal. An enhancement rather than a fix: before this, these
+  fields were simply unreachable from the propose flow, and their absence
+  published nothing false.
+
+### Fixed
+
+- **A maintainer-reviewed, public ADR accepted through `propose` → `accept`
+  published `trustLevel: unverified` and `sensitivity: internal` on every result**
+  ([#249](https://github.com/theurian/theurian/issues/249)). `theurian propose`
+  could express no `trustLevel` or `sensitivity`, so a corpus built by the shipped
+  flow could only ever carry the schema defaults; the loader completed the omitted
+  fields silently, and both reach every `knowledge.search` and `knowledge.get`
+  result. Measured on the first dogfooding slice: three publicly readable ADRs a
+  maintainer had merged were published as `unverified`/`internal` beside
+  `status: approved`, and hand-editing the generated YAML was the only remedy.
+  `propose` now takes `--trust-level {unverified|inferred|reviewed|authoritative}`
+  and `--sensitivity {public|internal|confidential|restricted}`, on both the
+  create and update flows, so a false value is correctable rather than permanent.
+  When either is omitted the default is not stamped into the migration — that
+  would assert a judgement the caller never made — but is named in the draft's
+  `--json` next steps, so an omission is a surfaced choice rather than a silent
+  false positive.
+
+## [0.1.0.dev6] - 2026-08-19
+
+### Fixed
+
+- **A rejected item's relation note reached an approved item's `knowledge.get`
+  through an alias-id collision**
+  ([GHSA-vx8x-rjfj-9x54](https://github.com/theurian/theurian/security/advisories/GHSA-vx8x-rjfj-9x54)).
+  Critical; affected 0.1.0.dev0–0.1.0.dev5. An `addAlias` whose key
+  equalled the id of a live `rejected` item, while the alias pointed at an
+  approved item, defeated the relation-visibility gate: `get_item` resolves an
+  alias before it looks up a status, so a lookup for the retired id resolved to
+  the approved target and cleared the gate as that item. An incoming edge the
+  rejected item authored — for example `contradicts` — and its `note`, where the
+  secret that caused the rejection lives, was published on the *approved* item's
+  response. The withheld id itself never appeared; the note did. Requesting the
+  withheld id directly was still correctly refused, and the ranked
+  `knowledge.search` path was never affected — it is held by the revision-identity
+  check that T-18 underwrites.
+
+  The read side is fixed independently of the write-side refusal below, because a
+  migration guard cannot reach a database an affected version already built:
+  `_relation_is_visible` now reads each relation endpoint's status through a new
+  non-resolving `get_item_exact`, the row the id literally names. Reachability
+  still resolves an alias — `knowledge.get(old)` reaches `new` after a rename —
+  but authority, a visibility decision on a referenced id, reads the
+  literally-named row. See
+  [T-21 in the threat model](../../docs/security/threat-model.md).
+
+### Changed
+
+- **BREAKING — an alias key may not collide with a non-deprecated item id across a
+  migration set**
+  ([GHSA-vx8x-rjfj-9x54](https://github.com/theurian/theurian/security/advisories/GHSA-vx8x-rjfj-9x54)).
+
+  **Old shape:** a set whose `addAlias` key equalled a live item's id applied
+  silently. With that item `rejected` and the alias pointing at an approved item,
+  the approved item's `knowledge.get` then published the rejected item's edge and
+  note (the Fixed entry above).
+
+  **New shape:** `migrate validate` and `migrate apply` both refuse the whole set
+  with `AliasItemCollisionError` at exit 4, naming the alias, the item it points
+  at, and the item's final status, and quoting no note. `apply` refuses before it
+  creates a database file, so a refused set costs no state — the property issue
+  #63's refusal already has. Both collision directions are refused — an `addAlias`
+  authored over an existing item, and a `createItem` that takes an id an alias
+  already keys — and a collision that straddles an already-applied migration is
+  caught too, because `apply` reloads every migration file into the set the guard
+  sees. The one exempt shape is the rename `deprecateItem(old)` then
+  `addAlias(old -> new)`, which leaves `old` `deprecated`; every other final
+  status is refused, `superseded` included. `migrate status` does not refuse — its
+  contract is observation — but names every colliding migration under
+  `refusedIds`, matching how it treats the tenant/ACL and duplicate-body rules.
+
+  Breaking because a migration set that applied on `0.1.0.dev5` and earlier now
+  refuses. No stable release exists — the published versions are `0.1.0.devN` —
+  and no compatibility promise covers it, but the break is named here rather than
+  filed as a fix. Documented in
+  [`docs/protocol/migrations.md`](../../docs/protocol/migrations.md).
+
 ## [0.1.0.dev5] - 2026-08-19
 
 ### Added
@@ -65,7 +158,8 @@ Pre-1.0, a MINOR bump may change the protocol. Post-1.0, only a MAJOR may.
 ### Changed
 
 - **BREAKING — one body file may back only one revision across a migration set**
-  ([#210](https://github.com/theurian/theurian/issues/210)).
+  ([#210](https://github.com/theurian/theurian/issues/210);
+  [GHSA-w5cm-cqf9-vm7r](https://github.com/theurian/theurian/security/advisories/GHSA-w5cm-cqf9-vm7r)).
 
   **Old shape:** a set in which two *different* revisions named one `contentFile`
   applied. Measured: two hand-written migrations sharing one path, with a correct
@@ -978,8 +1072,7 @@ Pre-1.0, a MINOR bump may change the protocol. Post-1.0, only a MAJOR may.
   matching hash is out of scope for this control and left to the schema gate, the
   #30 read-back guards, and the corruption checks.
 
-  <!-- Advisory (GHSA) reference for T-19 to be filled at release, when the
-  advisory ships; embargoed until then. -->
+  Published as [GHSA-266v-fcj2-qggx](https://github.com/theurian/theurian/security/advisories/GHSA-266v-fcj2-qggx).
 
 - **`knowledge.search` gains one `fallbackReason`, `index-unbuilt`**, emitted when
   the published index was not built by this installation and the ranked path

{theurian-0.1.0.dev5 → theurian-0.1.0.dev7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: theurian
-Version: 0.1.0.dev5
+Version: 0.1.0.dev7
 Summary: Git-native engineering knowledge platform: versioned, traceable context for AI agents.
 Project-URL: Homepage, https://github.com/theurian/theurian
 Project-URL: Documentation, https://github.com/theurian/theurian/tree/main/docs

{theurian-0.1.0.dev5 → theurian-0.1.0.dev7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "theurian"
-version = "0.1.0.dev5"
+version = "0.1.0.dev7"
 description = "Git-native engineering knowledge platform: versioned, traceable context for AI agents."
 readme = "README.md"
 requires-python = ">=3.13"

{theurian-0.1.0.dev5 → theurian-0.1.0.dev7}/src/theurian/__init__.py

@@ -8,7 +8,7 @@ plugin must never import them (ADR-0001, CP-2).
 
 from theurian.domain.compatibility import CURRENT_PROTOCOL_VERSION
 
-__version__ = "0.1.0.dev5"
+__version__ = "0.1.0.dev7"
 __protocol_version__ = CURRENT_PROTOCOL_VERSION
 
 __all__ = ["__protocol_version__", "__version__"]

theurian-0.1.0.dev7/src/theurian/application/migration_alias_guards.py

@@ -0,0 +1,183 @@
+"""Alias/item-id collision guard over a migration set (SEC-13, T-21).
+
+A static, whole-set check that no ``addAlias`` key equals the id of an item whose
+final status is anything but ``deprecated``. Pure function of a ``MigrationSet``:
+it touches no store, opens no transaction, and reads nothing from disk.
+``MigrationEngine.apply`` calls :func:`refuse_alias_item_id_collision`; ``migrate
+validate``/``apply`` call it through the CLI before any state is written, and
+``migrate status`` reports it through :func:`alias_item_collision_violations`.
+
+The collision is the T-21 disclosure's write-side cause.
+``SqliteCanonicalStore`` resolves an alias before it looks up a status, so an
+``addAlias`` key equal to a ``rejected`` item's id resolves to the approved item
+the alias points at and clears a relation-visibility gate as that item --
+publishing the rejected item's edge and its ``note`` (where the secret that
+caused the rejection lives) on the approved item's response. The read side is
+fixed independently (``_relation_is_visible`` reads the literally-named row via
+``get_item_exact``); this refuses the collision from ever being authored.
+
+Whole-set rather than pending-only, for the reason
+:func:`~theurian.application.migration_engine.refuse_unenforceable_scope` is:
+``migrate validate`` holds no store and so has no notion of pending, and the two
+commands must decide a statically decidable rule on identical input or reopen
+issue #36's class. It also covers the cross-set collision without a store read,
+because ``migrate apply`` reloads every migration file -- an item created by an
+earlier applied migration is in the set the guard sees.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from dataclasses import dataclass
+
+from theurian.domain.enums import KnowledgeStatus
+from theurian.domain.errors import AliasItemCollisionError
+from theurian.domain.identifiers import ItemId, MigrationId
+from theurian.domain.migration import (
+    AddAlias,
+    CreateItem,
+    DeprecateItem,
+    MigrationSet,
+    RemoveAlias,
+    RestoreItem,
+    UpsertRevision,
+)
+
+
+def _final_item_statuses(migration_set: MigrationSet) -> dict[ItemId, KnowledgeStatus]:
+    """Each item id's status after the whole set, computed in application order.
+
+    "Final" is well defined only in application (topological) order, so this
+    normalises to it with ``MigrationSet.ordered`` rather than trusting the
+    caller's iteration order: a raw ``MigrationSet(tuple(...))`` whose
+    ``deprecateItem`` merely lands last would otherwise read as ``deprecated`` and
+    defeat the T-21 exemption. ``ordered`` is idempotent for an already-ordered
+    set, so the ordered-loader caller pays only a re-sort, and re-validates a
+    cycle/missing-dep an applyable set has already passed.
+
+    Only the four operations that move an item's status are consulted, and the
+    same way ``MigrationEngine`` moves it: ``createItem`` sets ``draft`` for a
+    *new* id (a re-create of an existing one is a no-op, so ``setdefault``),
+    ``upsertRevision`` sets the revision's declared status, ``deprecateItem`` sets
+    ``deprecated``, ``restoreItem`` sets ``approved``. ``changeSensitivity`` and
+    ``changeOwner`` preserve status (the engine's ``_replace_item`` does), so they
+    are not consulted.
+    """
+    statuses: dict[ItemId, KnowledgeStatus] = {}
+    for migration in MigrationSet.ordered(migration_set.migrations):
+        for operation in migration.operations:
+            match operation:
+                case CreateItem():
+                    statuses.setdefault(operation.item_id, KnowledgeStatus.DRAFT)
+                case UpsertRevision():
+                    statuses[operation.item_id] = operation.metadata.status
+                case DeprecateItem():
+                    statuses[operation.item_id] = KnowledgeStatus.DEPRECATED
+                case RestoreItem():
+                    statuses[operation.item_id] = KnowledgeStatus.APPROVED
+    return statuses
+
+
+@dataclass(frozen=True, slots=True)
+class _AliasTarget:
+    """Where a live alias key points, and the migration that set it."""
+
+    item_id: ItemId
+    migration_id: MigrationId
+
+
+def _final_alias_targets(migration_set: MigrationSet) -> dict[ItemId, _AliasTarget]:
+    """Each alias key still live after the whole set, and where it was set.
+
+    Normalised to application order via ``MigrationSet.ordered`` for the same
+    reason :func:`_final_item_statuses` is: whether a key added then removed on
+    two migrations is still live, and which migration id a refusal names, are
+    last-write-wins over application order, not over the caller's tuple order.
+
+    ``addAlias`` records a key; ``removeAlias`` takes one back, so a key added and
+    later removed is not a live collision and is dropped. The migration id kept is
+    the ``addAlias``'s own, so a refusal names the operation an author edits.
+    """
+    targets: dict[ItemId, _AliasTarget] = {}
+    for migration in MigrationSet.ordered(migration_set.migrations):
+        for operation in migration.operations:
+            match operation:
+                case AddAlias():
+                    targets[operation.alias] = _AliasTarget(
+                        operation.item_id, migration.migration_id
+                    )
+                case RemoveAlias():
+                    targets.pop(operation.alias, None)
+    return targets
+
+
+@dataclass(frozen=True, slots=True)
+class _AliasCollision:
+    """One alias key that also names a live, non-deprecated item."""
+
+    alias: ItemId
+    target: ItemId
+    status: KnowledgeStatus
+    migration_id: MigrationId
+
+
+def _alias_item_collisions(migration_set: MigrationSet) -> Iterator[_AliasCollision]:
+    """Every live alias key that also names an item whose final status is not deprecated.
+
+    Both collision directions are one predicate: the shape is always "an alias key
+    equals an item id", whether the ``addAlias`` was authored over an existing
+    item or a ``createItem`` later took an id an alias already keyed. Yielded in
+    sorted alias-key order, so the throwing guard refuses a deterministic first
+    one when a set carries several.
+    """
+    statuses = _final_item_statuses(migration_set)
+    targets = _final_alias_targets(migration_set)
+    for alias in sorted(targets, key=lambda a: a.value):
+        status = statuses.get(alias)
+        if status is not None and status is not KnowledgeStatus.DEPRECATED:
+            target = targets[alias]
+            yield _AliasCollision(
+                alias=alias,
+                target=target.item_id,
+                status=status,
+                migration_id=target.migration_id,
+            )
+
+
+def refuse_alias_item_id_collision(migration_set: MigrationSet) -> None:
+    """Refuse a set whose alias key collides with a live, non-deprecated item id (T-21).
+
+    Raises:
+        AliasItemCollisionError: On the first colliding alias key in sorted order.
+    """
+    for collision in _alias_item_collisions(migration_set):
+        raise AliasItemCollisionError(
+            alias=collision.alias,
+            alias_target=collision.target,
+            item_status=collision.status.value,
+            migration_id=collision.migration_id,
+        )
+
+
+def alias_item_collision_violations(migration_set: MigrationSet) -> tuple[MigrationId, ...]:
+    """Every migration :func:`refuse_alias_item_id_collision` would refuse, without raising.
+
+    The non-throwing enumerator ``migrate status`` needs, the sibling of
+    ``unenforceable_scope_violations`` and ``duplicate_content_file_violations``.
+    ``status`` reports rather than gates (issue #63's MEDIUM-3), so this
+    statically decidable rule must stay visible there under ``refusedIds`` --
+    otherwise ``status`` would report ``refusedIds: []`` for a set
+    ``validate``/``apply`` exit 4 on, the #210 gap. Reports each colliding
+    ``addAlias``'s migration id, at most once, in sorted alias-key order.
+    """
+    refused: list[MigrationId] = []
+    for collision in _alias_item_collisions(migration_set):
+        if collision.migration_id not in refused:
+            refused.append(collision.migration_id)
+    return tuple(refused)
+
+
+__all__ = [
+    "alias_item_collision_violations",
+    "refuse_alias_item_id_collision",
+]

{theurian-0.1.0.dev5 → theurian-0.1.0.dev7}/src/theurian/application/migration_engine.py

@@ -20,6 +20,7 @@ from dataclasses import dataclass, field
 from datetime import datetime
 from typing import Final, Protocol
 
+from theurian.application.migration_alias_guards import refuse_alias_item_id_collision
 from theurian.application.migration_body_guards import refuse_duplicate_content_files
 from theurian.domain.enums import KnowledgeStatus, RelationType, may_surface
 from theurian.domain.errors import (
@@ -332,15 +333,23 @@ class MigrationEngine:
                 planning but before any write, so it never depends on what
                 has already been written.
             DuplicateContentFileError: If two operations reference one body
-                file (issue #210). Checked last of the three and over the same
-                whole set: the two above name a specific migration as wrong,
-                while this one is a statement about the set, and reporting the
-                narrower fault first is what keeps a reader from being sent to
-                a second migration that is not the one to edit.
+                file (issue #210). Checked over the same whole set: the scope
+                refusal above names a specific migration as wrong, while this
+                one is a statement about the set, and reporting the narrower
+                fault first is what keeps a reader from being sent to a second
+                migration that is not the one to edit.
+            AliasItemCollisionError: If an ``addAlias`` key equals the id of an
+                item whose final status is not ``deprecated`` (SEC-13, T-21).
+                Checked last and whole-set: a store that resolves the alias
+                before a status lookup would let the retired item surface under
+                the approved item the alias points at. The CLI refuses this
+                before ``create_database`` too, so a refused apply leaves no
+                state database behind.
         """
         plan = self.plan(writer, project_id, migration_set)
         refuse_unenforceable_scope(migration_set)
         refuse_duplicate_content_files(migration_set)
+        refuse_alias_item_id_collision(migration_set)
         report = ApplyReport(skipped=list(plan.already_applied))
 
         # The items whose surfaceability or current revision an operation could

{theurian-0.1.0.dev5 → theurian-0.1.0.dev7}/src/theurian/application/proposal_service.py

@@ -46,7 +46,7 @@ from typing import Final
 import yaml
 
 from theurian.application.project_service import ProjectPaths
-from theurian.domain.enums import KnowledgeKind, KnowledgeStatus
+from theurian.domain.enums import KnowledgeKind, KnowledgeStatus, Sensitivity, TrustLevel
 from theurian.domain.errors import PathEscapeError, TheurianError
 from theurian.domain.identifiers import ItemId, MigrationId, ProposalId, RevisionId
 from theurian.domain.knowledge import AUTHORED_IN_THEURIAN, SourceAnchor
@@ -131,6 +131,13 @@ class ProposalRequest:
     evidence: Evidence
     source_anchors: tuple[SourceAnchor, ...] = ()
     labels: tuple[str, ...] = ()
+    scope_paths: tuple[str, ...] = ()
+    #: Absent means "not stated": the field is left out of the migration and the
+    #: loader applies the schema default. A value is never invented here, because
+    #: `unverified`/`internal` written into every draft would assert a judgement
+    #: the caller did not make (#249).
+    trust_level: TrustLevel | None = None
+    sensitivity: Sensitivity | None = None
     namespace: str | None = None
     expected_revision: RevisionId | None = None
 
@@ -840,9 +847,12 @@ def _migration_document(  # noqa: PLR0913 -- the fields a migration has; all key
     ``status: approved`` is right even though nobody has approved it yet: the
     file applies only once a human has merged it, and ``draft`` would land
     knowledge that ``theurian index build`` leaves out. ``trustLevel`` and
-    ``sensitivity`` are deliberately absent -- claiming ``reviewed`` on
-    something an agent drafted asserts a review that has not happened, and a
-    reviewer can add either.
+    ``sensitivity`` are written only when the caller set them (``--trust-level``,
+    ``--sensitivity``): left unset they are absent from the file and the loader
+    applies its defaults, ``unverified`` and ``internal``. Stamping those
+    defaults in unasked-for would assert a judgement the caller never made, so
+    the omission is surfaced in the CLI's next steps instead of written here
+    (#249).
     """
     metadata: dict[str, object] = {
         "title": request.title,
@@ -852,8 +862,14 @@ def _migration_document(  # noqa: PLR0913 -- the fields a migration has; all key
         "status": KnowledgeStatus.APPROVED.value,
         "owner": request.owner,
     }
+    if request.trust_level is not None:
+        metadata["trustLevel"] = request.trust_level.value
+    if request.sensitivity is not None:
+        metadata["sensitivity"] = request.sensitivity.value
     if request.labels:
         metadata["labels"] = list(request.labels)
+    if request.scope_paths:
+        metadata["scope"] = {"paths": list(request.scope_paths)}
     if request.source_anchors:
         metadata["sourceAnchors"] = [_anchor_document(a) for a in request.source_anchors]
 

{theurian-0.1.0.dev5 → theurian-0.1.0.dev7}/src/theurian/cli/commands.py

@@ -21,6 +21,10 @@ from theurian.application.ingestion_service import (
     IngestionService,
     manifest_from,
 )
+from theurian.application.migration_alias_guards import (
+    alias_item_collision_violations,
+    refuse_alias_item_id_collision,
+)
 from theurian.application.migration_body_guards import (
     duplicate_content_file_violations,
     refuse_duplicate_content_files,
@@ -59,6 +63,7 @@ from theurian.cli.context import (
     resolve_context,
 )
 from theurian.domain.errors import (
+    AliasItemCollisionError,
     DuplicateContentFileError,
     MigrationChecksumMismatchError,
     MigrationCycleError,
@@ -198,6 +203,25 @@ DUPLICATE_CONTENT_FILE_REMEDY: Final = (
 )
 
 
+#: Cure for `AliasItemCollisionError` (SEC-13, T-21). An alias key and an item id
+#: must not be the same string, or a lookup for the retired id resolves to the
+#: item the alias points at and surfaces content the retired item withholds. The
+#: one shape this allows is a rename: deprecate the old item first, then alias it.
+#: Names the rebuild path as the second half of one remedy for the same reason
+#: `DUPLICATE_CONTENT_FILE_REMEDY` does -- editing an applied migration trips
+#: FR-K5's checksum guard, so a remedy that stopped at "edit it" would loop the
+#: reader between the two (issue #63's HIGH-1).
+ALIAS_ITEM_COLLISION_REMEDY: Final = (
+    "Remove the addAlias, or give the item a distinct id -- an alias key and an item id must "
+    "not be the same string. If this is a rename, deprecate the old item first "
+    "(deprecateItem), the one shape this allows: the retired id then resolves to its "
+    "successor without exposing withheld content. If the offending migration was already "
+    "applied, editing it also trips the applied-migration checksum guard -- delete "
+    "`.theurian/state/` after the edit and run `theurian migrate apply`, which rebuilds "
+    "canonical state from the corrected migrations (FR-K4)."
+)
+
+
 #: Every canonical-state database this project has ever built. Excludes
 #: `theurian-index-*.sqlite`, which lives in the same directory
 #: (`ProjectPaths.state`) but is a different schema entirely.
@@ -334,20 +358,41 @@ def _refuse_a_body_file_backing_two_revisions(
         )
 
 
+def _refuse_an_alias_colliding_with_an_item(migration_set: MigrationSet, *, as_json: bool) -> None:
+    """Report T-21's whole-set refusal identically at `migrate validate` and `apply`.
+
+    One function rather than a `try`/`except` in each command, so the two cannot
+    drift on a statically decidable rule (issue #36's class) -- and so `apply`
+    refuses before `create_database` runs and leaves no state database behind, the
+    way the scope and body-file guards already do.
+    """
+    try:
+        refuse_alias_item_id_collision(migration_set)
+    except AliasItemCollisionError as exc:
+        _fail(
+            str(exc),
+            remedy=ALIAS_ITEM_COLLISION_REMEDY,
+            as_json=as_json,
+            code=EXIT_STATE_ERROR,
+        )
+
+
 def _refused_migration_ids(migration_set: MigrationSet) -> list[str]:
     """Every migration id `migrate validate`/`apply` would refuse, for `status`.
 
-    Both gating rules feed `refusedIds`: the tenant/ACL scope rule (issue #63)
-    and the one-body-one-revision rule (issue #210). Each has a non-throwing
-    enumerator split from its throwing refusal precisely so `status` can report
-    without gating -- reporting only the scope rule, as this did, told a reader
-    `refusedIds: []` for a set `validate`/`apply` exit 4 on. Deduplicated in
-    first-seen order (a migration can carry both faults), so the field is stable.
+    Three gating rules feed `refusedIds`: the tenant/ACL scope rule (issue #63),
+    the one-body-one-revision rule (issue #210), and the alias/item-id collision
+    rule (SEC-13, T-21). Each has a non-throwing enumerator split from its
+    throwing refusal precisely so `status` can report without gating -- reporting
+    only some of them told a reader `refusedIds: []` for a set `validate`/`apply`
+    exit 4 on. Deduplicated in first-seen order (a migration can carry more than
+    one fault), so the field is stable.
     """
     seen: dict[str, None] = {}
     for migration_id in (
         *unenforceable_scope_violations(migration_set),
         *duplicate_content_file_violations(migration_set),
+        *alias_item_collision_violations(migration_set),
     ):
         seen.setdefault(str(migration_id), None)
     return list(seen)
@@ -1112,6 +1157,7 @@ def migrate_validate(as_json: JsonOption = False) -> None:
         return
 
     _refuse_a_body_file_backing_two_revisions(context.loaded.migration_set, as_json=as_json)
+    _refuse_an_alias_colliding_with_an_item(context.loaded.migration_set, as_json=as_json)
 
     _emit(
         {
@@ -1150,11 +1196,12 @@ def migrate_apply(as_json: JsonOption = False) -> None:
         )
         return
 
-    # `MigrationEngine.apply` refuses this too, but only once a write
+    # `MigrationEngine.apply` refuses these too, but only once a write
     # transaction is open and `create_database` has already run. Refusing here
     # as well is what keeps issue #63's property -- a refused apply leaves no
-    # database file behind -- true for this rule too (issue #210).
+    # database file behind -- true for these rules too (issue #210, T-21).
     _refuse_a_body_file_backing_two_revisions(context.loaded.migration_set, as_json=as_json)
+    _refuse_an_alias_colliding_with_an_item(context.loaded.migration_set, as_json=as_json)
 
     # This installation's record of the state it built, out of the repository
     # tree (ADR-0004, SEC-7). Used twice below: to refuse to *apply into* a