kinemata 0.2.0__tar.gz → 0.3.0.dev1__tar.gz

{kinemata-0.2.0 → kinemata-0.3.0.dev1}/CHANGELOG.md

@@ -9,6 +9,31 @@ a project outside this repository runs against kinemata and upgrades between pub
 Commits are in `git log`; the reasoning behind a design decision stays in the document that
 carries the decision. A changelog repeating either becomes a second carrier and goes stale.
 
+## Unreleased
+
+**New**
+
+- `[[parity]] translate_identifier`: a second declared translation, for the identifiers, in a run
+  that also compares values. `translate` lands on whichever side the parity compares — the values
+  when a `field` is named — so a declaration whose keys are spelled one way and whose values
+  another had no form for the first, and membership runs in every parity, so both spellings came
+  back as findings. The only way to make such a run green was to have the *oracle* re-key its own
+  output, which puts the hop where no reader of the config can see it: the thing `translate` exists
+  to prevent. Refused alongside a bare `translate` when no `field` is named, where there is one
+  side and two keys naming it would be a declaration saying the same thing twice.
+
+**Fixed**
+
+- `parity` now prints `set-valued: N` for declared cells that held a list, on every run, clean or
+  failing. A list is compared as a set on purpose — a reorder is not a finding, and that rule is
+  unchanged — but nothing said so, so a declaration pinning an enum's `choices` against the code's
+  own tuple reported `agreeing on choices` while an oracle listing the same three values in reverse
+  agreed with it. Measured against a real adopter manifest, not constructed. This was the last
+  suppression in the tool that reported nothing; the others each gained a line earlier, `negated:`
+  most recently. The count is deliberately not a list of sites: a list cell is a suppression the
+  project declared by writing a list and can see in its own file, where a negation is one the tool
+  inferred from prose nobody wrote for it.
+
 ## 0.2.0
 
 **Fixed**

{kinemata-0.2.0 → kinemata-0.3.0.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemata
-Version: 0.2.0
+Version: 0.3.0.dev1
 Summary: One declared place per fact; find the code that re-derives it.
 Author-email: Jei Blanchard <jjb@eng.ufl.edu>
 License-Expression: GPL-3.0-only
@@ -309,9 +309,10 @@ that has since been renamed: the claim survives, its provenance does not.
 size of the exemption list **on every run, including clean ones**. `review` is
 deliberately unaffected — the ratchet governs the gate, not the advice.
 
-**One list, three gates.** `claims` and `undeclared` read the same baseline, so a
-documentation tree or a closed registry that is already failing can be adopted
-the same way. A second exemption list was the alternative and is the failure
+**One list, several gates**, and the number is deliberately not given here — it
+said *three* and was overtaken twice. Every gate that ratchets reads the same
+baseline, so a documentation tree or a closed registry that is already failing
+can be adopted the same way; `kinemata baseline` prints the scopes. A second exemption list was the alternative and is the failure
 mode: two lists eventually disagree about what a project accepted, and the one
 nobody reads is the one still exempting something real. Records carry the check
 that produced them, so no gate reports another's as fixed — it names them
@@ -516,7 +517,7 @@ removal, visible in a diff.
 by hand can at least declare that the instruction to run them still exists. That
 is a reminder about a reminder, and worth what it sounds like.
 
-The companion guard is a number with an oracle. This suite is **1101 tests**, and
+The companion guard is a number with an oracle. This suite is **1107 tests**, and
 `kinemata claims` settles that figure against `pytest --collect-only`, so a
 suite that silently shrinks fails the gate rather than passing faster.
 

{kinemata-0.2.0 → kinemata-0.3.0.dev1}/README.md

@@ -285,9 +285,10 @@ that has since been renamed: the claim survives, its provenance does not.
 size of the exemption list **on every run, including clean ones**. `review` is
 deliberately unaffected — the ratchet governs the gate, not the advice.
 
-**One list, three gates.** `claims` and `undeclared` read the same baseline, so a
-documentation tree or a closed registry that is already failing can be adopted
-the same way. A second exemption list was the alternative and is the failure
+**One list, several gates**, and the number is deliberately not given here — it
+said *three* and was overtaken twice. Every gate that ratchets reads the same
+baseline, so a documentation tree or a closed registry that is already failing
+can be adopted the same way; `kinemata baseline` prints the scopes. A second exemption list was the alternative and is the failure
 mode: two lists eventually disagree about what a project accepted, and the one
 nobody reads is the one still exempting something real. Records carry the check
 that produced them, so no gate reports another's as fixed — it names them
@@ -492,7 +493,7 @@ removal, visible in a diff.
 by hand can at least declare that the instruction to run them still exists. That
 is a reminder about a reminder, and worth what it sounds like.
 
-The companion guard is a number with an oracle. This suite is **1101 tests**, and
+The companion guard is a number with an oracle. This suite is **1107 tests**, and
 `kinemata claims` settles that figure against `pytest --collect-only`, so a
 suite that silently shrinks fails the gate rather than passing faster.
 

{kinemata-0.2.0 → kinemata-0.3.0.dev1}/docs/design.md

@@ -380,8 +380,10 @@ bibliography: a reference key is recognizable because the stamp's delimiters wer
 so, which is why that one registry can answer, and until a bibliography was declared `kinemata
 undeclared` run here refused rather than reporting a false clean.
 
-⚑ **Closability is a boundary for two of the three kinds, settled 2026-09-13** rather than left as
-an open gap. `code-patterns` and `substitutions` are **negative** registries — they declare what
+⚑ **Closability is a boundary for `code-patterns` and `substitutions`, and a deliberate gap for
+`python-constants`, settled 2026-09-13** rather than left as an open gap. ⚑ **Named rather than
+counted**: this read *"two of the three kinds"* until 2026-09-19, when a fourth kind existed and
+the phrase had quietly become a claim about the whole adapter set rather than about these three. `code-patterns` and `substitutions` are **negative** registries — they declare what
 must *not* appear, and the complement of "not a forbidden spelling" is every other string in the
 language, so there is no membership list to enumerate and no closed-world question to ask. They
 will never be closable, and that is a property of the data model. `python-constants` is a genuine

{kinemata-0.2.0 → kinemata-0.3.0.dev1}/docs/introduction.md

@@ -253,13 +253,28 @@ extract = '(?m)^(\S+)=(.*)$'
 field = ["default", "primary"]
 authority = "declared"
 
-# At most one translation, on the declared side, so a reader of the config can
-# see that a comparison is not literal. `map` or `pattern`/`replacement`,
-# never both.
+# A translation, on the declared side, so a reader of the config can see that a
+# comparison is not literal. `map` or `pattern`/`replacement`, never both.
+# `translate` lands on whichever side this parity compares: the values when a
+# `field` is named, the identifiers when one is not.
 [parity.translate]
 pattern = '/$'              # the manifest writes a directory prefix with a
 replacement = ''            # trailing separator; the code carries none
 
+# The second hop, for a declaration whose KEYS are spelled one way and whose
+# VALUES are spelled another. Membership runs in every parity, so without this
+# a value run compared identifiers raw and reported both spellings as findings
+# -- and the only way to green it was to have the ORACLE re-key its own output,
+# which puts the hop where no reader of the config can see it. That escape is
+# the reason this key exists rather than a convenience.
+#
+# Refused alongside a bare `translate` when no `field` is named: there is one
+# side to translate then, and two keys naming it is a declaration saying the
+# same thing twice.
+[parity.translate_identifier]
+pattern = '^agent\.<agent>\.'   # the manifest declares one templated row
+replacement = 'agent.claude.'   # the code emits it per agent
+
 # `relation` says what the two sets are claimed to be. Without it a parity
 # means `equal`, which is what it has always meant. The others are weaker or
 # inverted claims, spelled as what IS claimed rather than as a direction
@@ -294,6 +309,21 @@ replacement = ''            # trailing separator; the code carries none
 # below can be `disjoint`); a list of what is broken is not. Measured both ways
 # on a scratch tree rather than reasoned about, after an adopter asked whether
 # artifact freshness was a shape this tool wanted.
+#
+# **AND THE DECLARED SIDE MUST NOT BE DERIVED FROM THE PRODUCED ONE.** A
+# registry enumerated from the same place the oracle reads compares that place
+# with itself: whatever leaves, leaves both sides at once, and the run reports
+# agreement. The adopter who took the freshness shape hit this and reported it
+# with a control -- a registry read off the artifact directory cannot see an
+# artifact DELETED, because the row and the file vanish together, while a
+# hand-maintained declaration reds immediately. **A declaration is a statement
+# of what ought to be there**, which is exactly what it cannot be if the tree
+# writes it.
+#
+# This is `docs/design.md`'s rule about `declared()` arriving from the other
+# side: the declaration and the thing it judges must not share a source. There
+# it is an adapter calling the project's own classifier; here it is a registry
+# generated from the directory being checked. Same defect, and both pass.
 [[parity]]
 registry = "denials"
 relation = "declared_contains"
@@ -1255,12 +1285,21 @@ limit is closed, in the same commit that closes it.**
   ⚑ **A fourth cause is not a spelling divergence at all** and is worth separating, because no
   translation form whatever would reach it: a **parametric row with no code-side member**. That one
   is the registry's addressing, not the comparison's notation.
-  ⚑ **And the sharpest consequence is structural rather than a matter of degree.** The translation
-  has one target, chosen by whether `field` is declared — so a comparison that names a `field`
-  translates the **values** and compares the **identifiers raw**. Membership runs either way and is
-  not made optional by a value declaration, which is deliberate; but it means a declaration whose
-  identifiers need a spelling map and whose values need comparing has **no form for the first
-  one at all**.
+  ⚑ **~~And the sharpest consequence is structural rather than a matter of degree.~~ Closed
+  2026-09-19 by `translate_identifier`.** The translation had one target, chosen by whether `field`
+  was declared — so a comparison naming a `field` translated the **values** and compared the
+  **identifiers raw**, and membership runs either way. A declaration whose identifiers need a
+  spelling map *and* whose values need comparing had no form for the first, and the only way to
+  green one was to have the oracle re-key its own output.
+  ⚑ **That workaround is why it was built, and the general form of the argument is worth more than
+  the key.** A capability whose absence is routed around **silently** is not absent — it is
+  undeclared, and the routing lands in the one place this entry already says a reader cannot see.
+  Measured on an adopter's real manifest row rather than argued: the re-keyed oracle turns the run
+  green, and nothing in the config says a hop happened.
+  ⚑ **It moved no reach figure**, which is stated because the temptation is to claim one: the row
+  it was measured against is still unreached, on an assertion about a *templated* declaration row
+  standing for several produced identifiers, which is the fourth cause named above and is the
+  registry's addressing rather than the comparison's notation.
   ⚑ **“No real row has needed two” was already false when it was published**, by a measurement in
   this project's own records rather than by the one above: of an adopting project's five translated
   rows, one needs two — a reference hop *and* a segment substitution — and the characterization
@@ -1571,6 +1610,26 @@ down, and the two shapes at the end are the findings that matter most.
   that is neither equality nor membership**: an **ordering** (a list is compared as a set, on
   purpose), an **inequality**, and a second declared **translation**. Three conformance rows in the
   measured population, one each.
+  ⚑ **All three were run against that project's real files on 2026-09-19 rather than reasoned
+  about, and two were reachable only in a form worse than the gap.** An oracle can re-key its
+  output to the declaration's spelling, which carried the second translation — and spent the
+  visibility `translate` exists for. An oracle can print a **verdict** per row against a declared
+  constant, which carries the inequality — and then the comparison is the oracle's and nothing
+  checks it. **Neither counts as reach**, on the rule that an oracle answers what the code
+  *produces* while a declaration answers what it *must be*: once the oracle answers whether it is
+  **right**, the declaration is a rubber stamp.
+  ⚑ **The translation half was then closed properly**, the same day, by `translate_identifier` —
+  the entry above carries it. **Finding the silent workaround is what justified building it**, not
+  the row: a capability an adopter can route around without saying so is undeclared rather than
+  absent. The inequality stands, and so does the ordering.
+  ⚑ **The ordering half is disclosed rather than silent** — `set-valued: N` on every run, clean or
+  failing, whose declared cell held a list. The set rule is deliberate and stays; what was wrong is
+  that a declaration pinning an enum's `choices` printed *agreeing on choices* while the oracle
+  listed the same three values in **reverse**, so the run read exactly like one that had checked
+  the order. **The count does not say the comparison was wrong. It says which question was
+  answered.** This was the last suppression here that reported nothing, after `negated:`.
+  **What the claim itself would take:** an opt-in ordered comparison — a form question rather than
+  a missing capability, since the rendering already knows the cell was a list.
   ⚑ **The other half — a declared entry's *field* against what the code prints for it — landed the
   same day**, with the translation and the authority marker the same project's worked rows asked
   for. **The entry stays open and `accepted`**, and what is left is of two different kinds. One is
@@ -1720,6 +1779,23 @@ down, and the two shapes at the end are the findings that matter most.
   ⚑ **One residual is the rule language rather than the adapter, and it has its own entry below.**
   Recorded separately rather than quietly reclassified, because the adapter reaches exactly what the
   measurement said it would.
+- **accepted** · **There is no expression language in the config, in any mechanism.** A `[[shape]]`
+  guard and claim, a `[[probe]]` outcome and a `[[parity]]` comparison are each a table of fixed
+  operators, so a project wanting a relation none of them spells — an ordering between two values,
+  an arithmetic bound, a condition joining two fields — reaches the one escape there is: a
+  **predicate the project names**, which costs it a module to import and a function to maintain.
+  **What it would take:** a syntax, a parser, and a defined semantic for every type a declaration
+  can hold. The core takes no runtime dependency, so nothing could be borrowed and it would be
+  written here — a second, worse copy of a solved thing, inside the package whose subject is code
+  that re-derives what is already declared. That is the whole of the argument, and it is an
+  argument about **cost**: no part of the design forecloses one.
+  ⚑ **What would revive it: projects reaching for the predicate escape to express *relations
+  between declared values* rather than models of their own data.** The escape exists for the
+  second. A population using it for the first says the operator tables are the wrong **shape**
+  rather than merely short, which is the finding no single unusual claim can establish — so the
+  evidence is a count across projects, not one project's case.
+  ⚑ **Said explicitly because the phrasing here used to be *"refused rather than deferred"***, which
+  reads as a promise never to revisit, and a disposition has no standing to make one.
 - **accepted** · **A rule speaks about the selected set, not about each group within it.** With a
   flattened registry every cell of a matrix is an entry, so a rule can claim something about *all*
   cells. *"Every row's columns are exactly the relations axis"* is a claim about **each first-level

{kinemata-0.2.0 → kinemata-0.3.0.dev1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kinemata"
-version = "0.2.0"
+version = "0.3.0.dev1"
 description = "One declared place per fact; find the code that re-derives it."
 readme = "README.md"                 # without this a built distribution ships no
                                      # long description at all: the PyPI page and

{kinemata-0.2.0 → kinemata-0.3.0.dev1}/src/kinemata/claims.py

@@ -164,6 +164,16 @@ EXAMPLE_STEM = re.compile(r"(^|/)[a-z]\.[a-z]+$")
 #: Prefixes that put a path outside the tree, where this cannot verify it.
 #: ``%`` joined them after a Windows ``%APPDATA%\\httpie\\config.json`` in
 #: httpie's documentation was reported as a dead path in httpie's own tree.
+#:
+#: **This skip is silent and stays silent, re-examined 2026-09-19 against the
+#: negation count and deliberately not given one.** An adopter noticed the
+#: asymmetry -- a ``~/`` spelling would have made their failing header pass --
+#: and declined to use it, on the grounds that going green by hiding from the
+#: checker is not the same as going green. They were right about their header
+#: and the asymmetry is not the same shape: a token starting with one of these
+#: **was never a claim about this tree**, which is a classification, where a
+#: negated token *was* one and prose withdrew it. Counting a claim that never
+#: existed would put a number on every absolute path in every document.
 EXTERNAL_PREFIXES = ("~", "/", "#", "@", "$", "%")
 
 #: A backslash means this is not a path *here*: a Windows path, which cannot be

{kinemata-0.2.0 → kinemata-0.3.0.dev1}/src/kinemata/cli.py

@@ -754,6 +754,30 @@ def cmd_undeclared(args: argparse.Namespace) -> int:
     return 0
 
 
+def _set_valued(result: Parity, args: argparse.Namespace) -> None:
+    """Say when a value comparison was a *set* comparison.
+
+    A list cell is compared as a set on purpose, so this is a disclosure and
+    never a finding -- but it was the one suppression here that printed
+    nothing, which is exactly what made a withdrawn path claim invisible in
+    ``claims`` until 0.2.0.
+
+    **A count and no identifiers**, deliberately, and the distinction is the
+    one that release already drew: a negation is a suppression the tool
+    *inferred* from prose nobody wrote for it, so the sites are the only way to
+    judge it, while a list cell is a suppression the project **declared** by
+    writing a list. Its author can see which rows those are; what they could
+    not see is that order went unchecked.
+    """
+    if not result.set_valued or args.quiet:
+        return
+    count = len(result.set_valued)
+    print(
+        f"  set-valued: {count} declared cell(s) hold a list, compared as "
+        "sets -- order is not part of the claim"
+    )
+
+
 def _parity(
     args: argparse.Namespace, settings: Settings, target: Path
 ) -> list[Parity]:
@@ -852,10 +876,12 @@ def cmd_parity(args: argparse.Namespace) -> int:
                     f"# {result.registry}: {result.declared} declared, "
                     f"{result.produced} produced, {held}{also}."
                 )
+                _set_valued(result, args)
             continue
         print(f"# {result.registry}")
         for item in shown:
             print(f"  {item}")
+        _set_valued(result, args)
         failed += len(shown)
 
     if split.accepted and not args.quiet:

{kinemata-0.2.0 → kinemata-0.3.0.dev1}/src/kinemata/config.py

@@ -782,7 +782,7 @@ COUNT_KEYS = frozenset(
 PARITY_KEYS = frozenset(
     {
         "command", "run", "args", "directory", "registry", "extract", "field",
-        "authority", "translate", "relation",
+        "authority", "translate", "translate_identifier", "relation",
     }
 )
 SHAPE_KEYS = frozenset({"registry", "rule"})
@@ -2010,6 +2010,19 @@ def _build_parities(
                 "this relation is about. Declare one or the other."
             )
 
+        # Without a field there is one side to translate and `translate`
+        # already reaches it, so a second key naming that side is a declaration
+        # saying the same thing twice -- and refusing beats picking a winner,
+        # since either choice makes the other line inert.
+        if spec.get("translate_identifier") is not None and not value_field:
+            raise ConfigError(
+                f"{path}: [[parity]] {index} declares 'translate_identifier' "
+                "and compares no field, so it already translates its "
+                "identifiers through 'translate'. Use one key: "
+                "'translate_identifier' is for a parity that compares values "
+                "as well, where 'translate' is spent on those."
+            )
+
         argv += _argv(spec.get("args"), f"{path}: [[parity]] {index}", "args")
         built.append(
             Oracle(
@@ -2020,6 +2033,10 @@ def _build_parities(
                 field=value_field,
                 authority=authority,
                 translate=_build_translation(spec.get("translate"), path, index),
+                translate_identifier=_build_translation(
+                    spec.get("translate_identifier"), path, index,
+                    "translate_identifier",
+                ),
                 relation=relation,
             )
         )
@@ -2500,18 +2517,21 @@ def _shape_guard(declared: object, where: str) -> Condition | Predicate:
 
 
 def _build_translation(
-    declared: object, path: Path, index: int
+    declared: object, path: Path, index: int, key: str = "translate"
 ) -> Translation | None:
-    """The one translation a ``[[parity]]`` may declare, or a refusal.
+    """One translation a ``[[parity]]`` declares, or a refusal.
 
     Compiled here rather than at the comparison, unlike ``extract``: an
     unusable ``extract`` makes a run fail loudly as blocked, while an unusable
     translation would make every comparison in it wrong. A project's mistake
     belongs where a project's mistakes are refused.
+
+    ``key`` names the one being built, so a refusal about
+    ``translate_identifier`` does not point at the other key's spelling.
     """
     if declared is None:
         return None
-    where = f"{path}: [[parity]] {index}'s translate"
+    where = f"{path}: [[parity]] {index}'s {key}"
     if not isinstance(declared, dict):
         raise ConfigError(f"{where} must be a table, not a {type(declared).__name__}")
     table, pattern = declared.get("map"), declared.get("pattern")

{kinemata-0.2.0 → kinemata-0.3.0.dev1}/src/kinemata/parity.py

@@ -151,6 +151,12 @@ class Translation:
     ``docs/introduction.md`` [0TN7FP9-Pa0004] § Known limits, which carries the
     measurement that withdrew it and what a wider form would take.
 
+    ⚑ **One per SIDE, since 2026-09-19.** A value comparison spends this on the
+    values, so :attr:`Oracle.translate_identifier` is the identifier hop -- see
+    that attribute for why it is a capability rather than a convenience. Still
+    one translation per side: a pipeline of them is what nobody can read off a
+    config.
+
     Two forms, never both, and each is deliberately dull:
 
     ``table``
@@ -227,12 +233,24 @@ class Oracle:
     #: identifiers when :attr:`field` is empty, the values when it is not. One
     #: target, so what a translation touches is a thing a reader can settle from
     #: the config rather than infer.
-    #:
-    #: ⚑ **The cost of that is a declaration comparing values cannot translate
-    #: its identifiers at all**, and membership runs regardless -- see
-    #: ``docs/introduction.md`` [0TN7FP9-Pa0004] § Known limits, where the reach
-    #: of one translation is measured and dispositioned.
     translate: Translation | None = None
+    #: Applied to the declared **identifiers**, in a run that also compares
+    #: values. Without it such a run has no way to spell an identifier hop, and
+    #: membership runs regardless -- so a declaration whose keys are spelled one
+    #: way and whose values are spelled another could be made to pass only by
+    #: having the **oracle** re-key its own output.
+    #:
+    #: ⚑ **That escape is why this exists rather than being a convenience.**
+    #: Measured on an adopter's real manifest: the oracle route turns the run
+    #: green and puts the hop somewhere no reader of the config can see it,
+    #: which is the exact visibility :class:`Translation` was built to buy.
+    #: A capability whose absence is routed around silently is not absent, it
+    #: is undeclared.
+    #:
+    #: Refused alongside a bare :attr:`translate` when :attr:`field` is empty:
+    #: there is one side to translate then, and two keys naming it is a
+    #: declaration saying the same thing twice.
+    translate_identifier: Translation | None = None
     #: What this declaration claims about the two sets, from :data:`RELATIONS`.
     #: ``equal`` is the default and is what every parity meant before the key
     #: existed, so no declaration written without it changes.
@@ -392,6 +410,19 @@ class Parity:
     #: Read by :meth:`scopes` rather than inferred from :attr:`divergent`, which
     #: is empty both when nothing was compared and when everything agreed.
     compared: str = ""
+    #: Entries whose declared cell held a **list**, and whose comparison was
+    #: therefore a set comparison with the declaration's order discarded.
+    #:
+    #: **Reported because it is a suppression that reported nothing.** A
+    #: declaration pinning ``choices`` against the code's own tuple reads
+    #: ``in agreement, agreeing on choices`` while the code's *order* changes
+    #: underneath it -- measured against an adopter's real manifest, where an
+    #: oracle printing the three access tiers reversed still agreed. The
+    #: set rule itself is deliberate and argued in
+    #: ``test_a_list_valued_field_is_compared_as_a_set``; what was missing is
+    #: any way for a reader of the run to learn that the weaker question was
+    #: the one answered. Every other suppression in this package prints a line.
+    set_valued: tuple[str, ...] = ()
 
     @property
     def failed(self) -> bool:
@@ -534,9 +565,32 @@ def _rendered(value: object) -> str | None:
     return str(value) if isinstance(value, _SCALARS) else None
 
 
+@dataclass(frozen=True)
+class _DeclaredSide:
+    """One entry's declared side, rendered for comparison.
+
+    **A named field rather than a tuple**, on the same reasoning
+    :class:`kinemata.targets.Target` records: :attr:`listed` was added to a
+    three-tuple every caller unpacked positionally, and a fourth slot nobody
+    can read at the call site is how a fact gets carried and then ignored.
+    """
+
+    #: The values to compare, or ``None`` when the cell cannot be rendered.
+    values: frozenset[str] | None
+    #: The declaration records nothing here, which is a claim rather than a gap.
+    absent: bool
+    #: Why it could not be rendered, empty when it could.
+    problem: str
+    #: The cell held a **list**, so the comparison that follows is a set
+    #: comparison and its order was discarded. Carried out of here rather than
+    #: re-derived by the caller: the lookup is a path walk, and doing it twice
+    #: to learn one fact about the first walk is this package's own subject.
+    listed: bool
+
+
 def _declared_values(
     entry: Entry, spec: Oracle, translate: Translation
-) -> tuple[frozenset[str] | None, bool, str]:
+) -> _DeclaredSide:
     """One entry's declared side: the values, whether absent, and why not.
 
     A container that is not a flat list is **refused** rather than rendered. It
@@ -551,18 +605,21 @@ def _declared_values(
     # decides membership rather than a value.
     raw = None if found is MISSING else found
     if raw is None:
-        return frozenset(), True, ""
-    items = list(raw) if isinstance(raw, (list, tuple)) else [raw]
+        return _DeclaredSide(frozenset(), True, "", False)
+    listed = isinstance(raw, (list, tuple))
+    items = list(raw) if listed else [raw]
     rendered = [_rendered(item) for item in items]
     if any(item is None for item in rendered):
         kinds = ", ".join(sorted({type(item).__name__ for item in items}))
-        return None, False, (
+        return _DeclaredSide(None, False, (
             f"declares {entry.id} with a {spell_path(spec.field)!r} holding {kinds}, "
             "which "
             "is not a scalar or a list of them and has no spelling an oracle "
             "could be expected to print"
-        )
-    return frozenset(translate.apply(item) for item in rendered), False, ""
+        ), listed)
+    return _DeclaredSide(
+        frozenset(translate.apply(item) for item in rendered), False, "", listed
+    )
 
 
 def compare(
@@ -626,13 +683,15 @@ def compare(
     printed, why = produced(spec, root, timeout)
     entries = list(registry.entries())
     translate = spec.translate or Translation()
-    # The translation has one target, and which one depends on what is being
-    # compared: a membership declaration's own side is its identifiers, a value
-    # declaration's is its values. Applying it to both would be two
-    # translations wearing one name.
-    declared = {
-        entry.id if spec.field else translate.apply(entry.id) for entry in entries
-    }
+    # `translate` keeps its published target -- the identifiers of a membership
+    # declaration, the values of a value one -- and `translate_identifier` is
+    # the second hop, which only a value run can need: without a field there is
+    # one side and `translate` already reaches it. The config refuses the pair
+    # in that case rather than silently preferring one.
+    identify = spec.translate_identifier or (
+        Translation() if spec.field else translate
+    )
+    declared = {identify.apply(entry.id) for entry in entries}
     if printed is None:
         return Parity(
             registry=spec.registry,
@@ -677,10 +736,19 @@ def compare(
 
     values = printed.values or {}
     divergent: list[Divergence] = []
+    set_valued: list[str] = []
     for entry in entries:
-        if entry.id not in values:
+        # Paired on the identifier as *translated*, which is the vocabulary
+        # both sides were compared in above. A finding names that spelling for
+        # the same reason: it is the one the oracle printed, so a reader can
+        # find it in the run they are holding.
+        key = identify.apply(entry.id)
+        if key not in values:
             continue  # membership above has already said so
-        mine, absent, problem = _declared_values(entry, spec, translate)
+        side = _declared_values(entry, spec, translate)
+        mine, absent, problem = side.values, side.absent, side.problem
+        if side.listed:
+            set_valued.append(key)
         if mine is None:
             # **Membership rides along**, and leaving it out was the defect an
             # adopter reported: 18 of their 66 rows hold a dict, so one
@@ -697,12 +765,12 @@ def compare(
                 relation=spec.relation,
                 **membership,
             )
-        theirs = values[entry.id]
+        theirs = values[key]
         if mine != theirs:
             divergent.append(
                 Divergence(
                     registry=spec.registry,
-                    identifier=entry.id,
+                    identifier=key,
                     field=spell_path(spec.field),
                     authority=spec.authority,
                     declared=tuple(sorted(mine)),
@@ -716,6 +784,7 @@ def compare(
         produced=len(printed.ids),
         divergent=tuple(divergent),
         compared=spell_path(spec.field),
+        set_valued=tuple(sorted(set_valued)),
         relation=spec.relation,
         **membership,
     )

{kinemata-0.2.0 → kinemata-0.3.0.dev1}/src/kinemata/shape.py

@@ -21,9 +21,11 @@ rewarded (the edit that omits the flag is shorter).
 adopter's own suite calls these cases throughout, and it does not promise JSON
 Schema by increments. There is no expression syntax here, no coercion and no
 inference: two small tables of dull operators, and one escape to a predicate the
-project names. An expression language was refused rather than deferred -- it
-would re-derive a solved thing, the core takes no runtime dependency so none
-could be borrowed, and the result would be a second worse copy.
+project names. An expression language was declined **on its cost** -- it would
+re-derive a solved thing, the core takes no runtime dependency so none could be
+borrowed, and the result would be a second worse copy. Nothing in this design
+forecloses one: ``docs/introduction.md`` [0TN7FP9-Pa0004] § Known limits carries
+the disposition and what would revive it.
 
 **One form throughout: a rule is a guard and a claim.** A rule with no guard
 judges every entry; a guarded rule judges the group its guard selects. That

{kinemata-0.2.0 → kinemata-0.3.0.dev1}/src/kinemata.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemata
-Version: 0.2.0
+Version: 0.3.0.dev1
 Summary: One declared place per fact; find the code that re-derives it.
 Author-email: Jei Blanchard <jjb@eng.ufl.edu>
 License-Expression: GPL-3.0-only
@@ -309,9 +309,10 @@ that has since been renamed: the claim survives, its provenance does not.
 size of the exemption list **on every run, including clean ones**. `review` is
 deliberately unaffected — the ratchet governs the gate, not the advice.
 
-**One list, three gates.** `claims` and `undeclared` read the same baseline, so a
-documentation tree or a closed registry that is already failing can be adopted
-the same way. A second exemption list was the alternative and is the failure
+**One list, several gates**, and the number is deliberately not given here — it
+said *three* and was overtaken twice. Every gate that ratchets reads the same
+baseline, so a documentation tree or a closed registry that is already failing
+can be adopted the same way; `kinemata baseline` prints the scopes. A second exemption list was the alternative and is the failure
 mode: two lists eventually disagree about what a project accepted, and the one
 nobody reads is the one still exempting something real. Records carry the check
 that produced them, so no gate reports another's as fixed — it names them
@@ -516,7 +517,7 @@ removal, visible in a diff.
 by hand can at least declare that the instruction to run them still exists. That
 is a reminder about a reminder, and worth what it sounds like.
 
-The companion guard is a number with an oracle. This suite is **1101 tests**, and
+The companion guard is a number with an oracle. This suite is **1107 tests**, and
 `kinemata claims` settles that figure against `pytest --collect-only`, so a
 suite that silently shrinks fails the gate rather than passing faster.
 

{kinemata-0.2.0 → kinemata-0.3.0.dev1}/tests/test_parity.py

@@ -360,6 +360,133 @@ def test_a_list_valued_field_is_compared_as_a_set(tmp_path):
     assert not result.failed
 
 
+def test_a_value_parity_can_translate_its_identifiers_as_well(tmp_path):
+    """The second hop, and the reason it is a capability rather than a nicety.
+
+    A declaration whose keys are spelled one way and whose values are spelled
+    another needs a hop on each side of the seam. With one translation, the
+    side it lands on is decided by ``field`` -- so a value run left identifiers
+    untranslated and reported both as membership findings, and the only way to
+    green it was to have the *oracle* re-key its own output, putting the hop
+    where no reader of the config can see it. Measured on an adopter's real
+    manifest before this existed.
+    """
+    result = compare(
+        Registry("keyspace.old", extra={"keyspace.old": {"default": "THEME"}}),
+        value_oracle(
+            command=("{python}", "-c", "print('keyspace.new=theme')"),
+            translate=Translation(pattern="^THEME$", replacement="theme"),
+            translate_identifier=Translation(pattern=r"\.old$", replacement=".new"),
+        ),
+        tmp_path,
+    )
+    assert not result.failed
+    assert result.undeclared == () and result.unproduced == ()
+
+
+def test_a_divergence_names_the_identifier_as_translated(tmp_path):
+    """The spelling the oracle printed, which is the run the reader is holding.
+
+    Membership is compared in the translated vocabulary, so a value finding
+    naming the untranslated one would make a single run speak two languages.
+    """
+    result = compare(
+        Registry("keyspace.old", extra={"keyspace.old": {"default": "THEME"}}),
+        value_oracle(
+            command=("{python}", "-c", "print('keyspace.new=other')"),
+            translate_identifier=Translation(pattern=r"\.old$", replacement=".new"),
+        ),
+        tmp_path,
+    )
+    (found,) = result.divergent
+    assert found.identifier == "keyspace.new"
+
+
+def test_translate_identifier_without_a_field_is_refused(tmp_path):
+    """Two keys naming one side is a declaration saying the same thing twice.
+
+    Without a field there is only the identifier side, and `translate` already
+    reaches it -- so this is refused rather than resolved by preferring one,
+    which would leave the other line inert in a config that reads as if both
+    applied.
+    """
+    declare(tmp_path, extra=(
+        'translate_identifier = { pattern = "^a$", replacement = "b" }'
+    ))
+    with pytest.raises(ConfigError) as caught:
+        load(Path(cfg(tmp_path)))
+    assert "already translates its identifiers" in str(caught.value)
+
+
+def test_a_list_valued_field_says_it_was_compared_as_a_set(tmp_path):
+    """The rule above is deliberate; reporting nothing about it was not.
+
+    Measured against an adopter's real manifest, a declaration pinning an enum's
+    ``choices`` against the code's own tuple printed *in agreement, agreeing on
+    choices* while the oracle listed the three tiers in **reverse** -- and
+    nothing in the run said the order half had gone unchecked. Every other
+    suppression in this package prints a line; this was the one that did not,
+    which is the same defect ``claims`` carried until a withdrawn path claim
+    gained ``negated:``.
+    """
+    result = compare(
+        Registry("app.name", extra={"app.name": {"default": ["b", "a"]}}),
+        value_oracle(
+            command=("{python}", "-c",
+                     "print('app.name=a'); print('app.name=b')"),
+        ),
+        tmp_path,
+    )
+    assert not result.failed
+    assert result.set_valued == ("app.name",)
+
+
+def test_a_scalar_field_is_not_called_set_valued(tmp_path):
+    """The disclosure is about lists, not about every value comparison.
+
+    A line on every run is a line nobody reads, and the fact being disclosed --
+    that an order was discarded -- is not true of a scalar.
+    """
+    result = compare(
+        Registry("app.name", extra={"app.name": {"default": "truecolor"}}),
+        value_oracle(),
+        tmp_path,
+    )
+    assert not result.failed
+    assert result.set_valued == ()
+
+
+def test_the_command_discloses_a_set_comparison_on_a_CLEAN_run(tmp_path, capsys):
+    """The clean run is the whole point: a failing one is already being read."""
+    write(tmp_path, "keys.yaml",
+          'keys:\n  app.name:\n    spec: "§1"\n    default:\n      - a\n      - b\n')
+    write(tmp_path, "src/a.py", 'NAME = "app.name"\n')
+    write(tmp_path, "kinemata.toml", """
+        [project]
+        root = "."
+
+        [[registry]]
+        name = "keyspace"
+        kind = "yaml-mapping"
+        source = "keys.yaml"
+        section = "keys"
+        clause_field = "spec"
+        syntax = '\\bapp\\.[a-z_]+'
+
+        [[parity]]
+        registry = "keyspace"
+        command = ["{python}", "-c", "print('app.name=b'); print('app.name=a')"]
+        extract = '(?m)^(\\S+)=(.*)$'
+        field = "default"
+        authority = "declared"
+        """)
+    assert main(["parity", "-c", cfg(tmp_path)]) == 0
+    out = capsys.readouterr().out
+    assert "in agreement, agreeing on default" in out
+    assert "set-valued: 1" in out
+    assert "order is not part of the claim" in out
+
+
 def test_a_set_valued_divergence_names_the_side_each_difference_is_on(tmp_path):
     result = compare(
         Registry("app.name", extra={"app.name": {"default": ["a", "gone"]}}),