@am_shork/attest 0.4.3 → 0.5.0

package/CHANGELOG.md

@@ -13,6 +13,209 @@ input, removes/renames a public API or `--json` field, or changes a default
 runtime behavior an existing invocation relies on — diagnostic message text is
 not API.
 
+## [0.5.0] - 2026-08-03
+
+### Changed
+
+- **Design §11 now states what earns a `params` entry, and the README no longer
+  states a rule that produces the defect it warns about.** Two prose changes,
+  one subject, and both came out of the same adoption report.
+  *What earns a param:* **params for promises, plain constants for tuning.** A
+  value belongs in `params` when the requirement promises it — a timeout the user
+  is owed, a budget someone would file a bug about; a value that only tunes
+  behaviour stays an ordinary constant, because nothing is owed to anyone when a
+  tuning knob changes. `mine-capablanca` arrived at this unaided and applied it
+  consistently across 34 requirements (11 carrying params, 19 values), which is
+  the best available evidence that it is the natural rule — and it was written
+  down nowhere. It pushes back on the second of the two ways intent bloats, the
+  one §11's lumping bullet does not cover: a registry that accumulates every knob
+  in the project. Folded into the same paragraph, because it is the same rule
+  stated over the *type* rather than the value: what a param may therefore be — a
+  scalar, or an array of scalars. Stating those apart is what let one adopter
+  derive the first unaided and meet the second as `Invalid input`.
+  *And the rule that was half-wrong:* "Read the param inside the assertion, not
+  beside it" appeared in the README, the `init` skill and the `possible-drift`
+  section, and it is **necessary but not sufficient** — an assertion that
+  recomputes its expectation from the same param the code under test just read
+  has no independent term, so both sides move together and no edit can make it
+  fail. Measured, not theorised: a mine-density band moved by 3.3× with the whole
+  suite green, `check` silent, and the drift heuristic correctly quiet, because a
+  covering scenario did read the param. Every site now says what the evidence
+  supports — *the expectation must not be a function of the param the code under
+  test consumed* — and `possible-drift` carries a worked ✗/✓ pair. §11 records
+  the sharper statement of the hole: a tautological assertion is a scenario that
+  cannot fail, which the red-before-implement gate exists to catch, and it does
+  catch them in a change — but **changing an existing param's value goes through
+  no gate at all**.
+  No behaviour changed and no gate moved; the detector for the tautological form
+  stays under `Under consideration`, with all three of its blockers intact.
+  Documenting a trap is not the same as deciding not to detect it.
+
+- **A change's spec files now live at the location they will be merged to,
+  marked `*.proposed.spec.ts`.** `changes/<name>/` keeps `proposal.md`,
+  `requirements.delta.ts` and `first-run.json`; the scenarios sit beside the code
+  they attest, and merging one is a rename in place. Reported by
+  `mine-capablanca`: every one of eight merges rewrote the relative imports of
+  the change's specs, and the imports were the only thing that moved.
+  **"Depth" was the wrong word for it, and finding that out changed the
+  design.** The entry that queued this said the specs sat at a *different depth*
+  from where they land. They do not — `changes/<name>/specs/` and
+  `lib/game/specs/` are both three levels down. What differs is the **path**, so
+  no layout that keeps a spec under `changes/` can make one relative specifier
+  resolve in both places; mirroring the destination inside the change folder
+  fails for the same reason, one level further out. The only fix that costs no
+  mechanism is to write the file where it will live, which is what shipped.
+  *Two jobs the folder used to do at once, now done separately.* Keeping a
+  proposal's specs out of the base suite is by **name**, because it has to hold
+  for commands that never heard of a change: those scenarios are red by
+  construction, and a `verify` that swept them up would call every project with
+  a change in flight broken. Deciding which change a spec belongs to is by
+  **id** — a change claims the proposed specs declaring a scenario for an id it
+  ADDs, renames to, or MODIFIEs — because a file name carries no change, and the
+  delta already enumerates what the change is about. That keeps the property the
+  folder had and a `specs: []` list in the delta would have lost: nothing names a
+  path, so nothing can fall out of step with the files. REMOVED ids claim
+  nothing; a file is claimed whole or not at all, because the run scope is a set
+  of files.
+  *What it cost, stated rather than netted off.* A change is no longer one
+  folder a reviewer can read end to end — the delta still enumerates every id and
+  `attest status <name>` still answers what a change contains, but the specs are
+  now found by their marker rather than by looking in one place. And separating
+  the two jobs opened a gap the folder did not have, which is the `Added` entry
+  below. Held by `ATX-45` (excluded by name) and `ATX-46` (claimed by id), split
+  because they fail independently.
+  *Migration, for anyone with an open change directory:* move each spec from
+  `changes/<name>/specs/` to where it will merge, rename it to
+  `*.proposed.spec.ts`, and fix its imports once. That is the rewrite the merge
+  was going to charge anyway, done earlier and once. `first-run.json` is
+  unaffected — it is keyed by requirement id and scenario name, neither of which
+  moves.
+  Gone with the folder: `changeExcludeGlobs`, the sibling-exclusion globs that
+  kept one proposal's specs out of another's gate run. A directory glob could not
+  have told two proposals apart once the specs left `changes/`, and keeping one
+  beside the claim check would be a second scoping rule able to disagree with it.
+
+### Added
+
+- **A change delta now reads as the registry of what it adds.** `delta(…)`
+  returns the delta *and* a record keyed by the ids it ADDs, each carrying the
+  params its author wrote — so a stage-1 scenario reads a proposed param with
+  the expression a merged one uses:
+  ```ts
+  import reqs from '../../changes/add-2fa/requirements.delta.ts';  // ← only this line changes at merge
+  const window = reqs['AUTH-7'].params.totpWindowSec;              // typed at 30, no cast
+  ```
+  Reported by `mine-capablanca`, which hit this on 3 of 8 changes and wrote a
+  throwaway accessor each time, then rewrote every import at merge.
+  **The reason this was a defect and not an ergonomic complaint is which stage
+  it landed on.** Stage 1 is where the scenario must be written and must go red —
+  the entire content of the red-before-implement gate — so the tool pushed the
+  author off `params`, the single source the rest of it exists to reward, at
+  precisely the moment that source is load-bearing, and then billed them the
+  rewrite at merge for having complied. Every hand-written accessor is a second
+  place the value lives, open during the only stage where the assertion is being
+  authored against a value nobody has implemented yet.
+  *Why one value can be both.* A requirement id matches `/^[A-Z]+-\d+$/`, so no
+  id can ever be spelled `added`, `modified`, `removed` or `renamed` — the union
+  is safe by grammar rather than by convention, and neither surface shadows the
+  other. Both readers build it through one function, so the differential suite in
+  `tests/static-registry.spec.ts` still finds them agreeing about what a delta is.
+  *Deliberately not readable this way:* MODIFIED ids and rename targets. A
+  modified requirement's end state is the base entry with the patch applied, the
+  base is not in that file, and a view of the patch alone would answer one key
+  and `undefined` for every other key the requirement has — a shape that reads as
+  the merged requirement and is not one. Still no validation either: a delta
+  carrying an id the registry would refuse stays the gate's verdict (`ATX-41`).
+  Held by `ATX-48`, attested by compiling a fixture — a type has no runtime
+  footprint — with the assertion written as an equality against the merged read,
+  because sameness is the property that makes merging a change of import.
+  *Behaviour change, for whom:* the object `delta()` returns now carries the
+  added ids as own enumerable keys, so `Object.keys(d)` and a deep-equality
+  assertion over a whole delta see them. Nothing in Attest reads a delta that
+  way — `applyDelta` and both registry readers name the four sections — but a
+  consumer that snapshots a delta value will see its snapshot move. Reading
+  `.added`, `.modified`, `.removed` and `.renamed` is unchanged.
+
+- **`added-id-unmerged`: the gate now names why a spec file failed to load,
+  instead of blaming the spec.** Reported by `mine-capablanca`. `archive`
+  applies the delta in memory and gates the result; the suite is a child process
+  that imports `*.reqs.ts` from disk. So implementation code doing what the
+  skill's rule 3 requires — `reqs['FOG-4'].params.modestRisk` for an id the
+  change *adds* — throws at import, every spec transitively importing that module
+  fails to load, and the gate reported `tests-red` plus a `declared-not-run` per
+  scenario, whose message sends the reader to look for a `skip` or an `.only`
+  that is not there. **The change could not be made green by the documented
+  workflow, and the verdict pointed away from the reason.**
+  The gate now carries load failures out of the run alongside the coverage, and
+  when the change adds ids the on-disk registry lacks it reports one ERROR per
+  unloaded file, naming the file and the ids. The `declared-not-run` lines it
+  replaces are dropped — the absence has been explained, and restating it as a
+  guess about a skip costs the reader attention on files that are not at fault.
+  Only in the gate: `verify` keeps reporting them, having no diagnosis to put in
+  their place, and a wrong message still beats silence.
+  **This is the diagnosis and deliberately not the fix.** The way through is to
+  merge the added requirement into the registry before running the gate, which
+  the idempotent ADDED rule makes free — the `added:` entry stays and still
+  documents the intent. The alternative considered was to show the child run the
+  applied registry through an alias or a scratch overlay: it unblocks the
+  workflow and spends the property that the registry the suite ran against is the
+  file on disk, on the one command path that already evaluates project code. That
+  property cannot be given back by a later diagnostic; the convenience can.
+  *The condition is a conjunction and therefore a heuristic* — a module can fail
+  to import for reasons unrelated to any requirement id — so the message states
+  the two facts and the inference between them rather than asserting a cause.
+  Held by `ATX-49` (name the file and the ids) and `ATX-50` (withdraw the lines
+  it replaces), which are two requirements rather than one for the reason
+  `ATX-24` was split out of `ATX-23`: pushing one more issue satisfies the first
+  in full and leaves every misleading line sitting underneath it, so an
+  implementation can pass it and fail the reader exactly as before.
+  *Behaviour change, for whom:* no run goes from green to red — the new ERROR
+  only fires on a run that was already failing, because a file that did not load
+  is a failing run. What does move is what a machine consumer reads: for this
+  case `archive` now emits `added-id-unmerged` where it emitted one
+  `declared-not-run` per scenario. `verify` is untouched, and `declared-not-run`
+  is unchanged everywhere else.
+
+- **`proposed-spec-unclaimed`: a proposed spec no change claims is an ERROR from
+  `attest check`.** This is the cost of the split above, made loud. A file the
+  base suite skips by name and every gate skips by id executes nowhere, and both
+  skips are individually correct, so neither command is positioned to notice.
+  `check` is, because it is the only one that reads the deltas without being
+  about a single change — and reading them is something it already owed, since a
+  change delta is intent and the reporting commands read intent from source
+  (design §5.1). Reported per file, driven off the scanned tree rather than the
+  parsed plan so a proposed spec declaring no scenario at all is caught too. A
+  delta that cannot be read is reported as itself rather than turned into
+  accusations against its specs: not knowing what a change claims is a different
+  finding from knowing it claims nothing. Held by `ATX-47`.
+
+### Fixed
+
+- **`add-invalid` and `modify-invalid` now name the field that failed.** Both
+  quoted the schema's message and dropped the path it came from, so a
+  requirement whose `params` the schema refused reported `Invalid input` and
+  nothing else — no key, no accepted shape. Reported by an adopter who found the
+  failing param by reading `node_modules/@am_shork/attest/dist/core/schema.d.ts`,
+  which is the only place the constraint was written down.
+  *The form is not new, and that is the sharpest part of it.* `troubleshooting.md`
+  has quoted `Added requirement "AUTH-7" is invalid: rationale: Required` since
+  the section was written, and `RegistryValidationError` has spelled paths
+  `a.b.c` since the registry shipped — so the documented sample was one this
+  code could not produce, and the two sites that format the same zod failure
+  disagreed. The fix is the path, in the spelling already documented, from the
+  one function both callers go through. Where there is no path — the id itself,
+  under `introducedIdIssue` — nothing is prefixed rather than `(root)`, because
+  the message's own prefix has already named the thing.
+  Also on the way through: the `params` value union now carries its own message
+  instead of a bare `Invalid input`, so the refusal states what is accepted at
+  the moment it fires, and `registry-invalid` gains the same sentence for free.
+  Message text, so not a behaviour change under this file's own Versioning rule
+  — the codes and the accepted values are untouched, and no existing invocation
+  changes its exit code. Held by `ATX-44`, which states the contract over the
+  *path* rather than the sentence: the separator is the one property a scenario
+  can pin without asserting a word of the wording, which is what keeps
+  `Issue.message` prose while making its information content falsifiable.
+
 ## [0.4.3] - 2026-08-01
 
 ### Added
@@ -2046,10 +2249,17 @@ feedback reports are triaged into issues or `Unreleased` and deliberately not
 kept in this tree; that rule stands, and holds for anything with a reporter, a
 repro, or a state to track. What is kept here is the narrower thing this file
 already keeps one section of: a **decision with an argument attached**, where
-losing the argument would cost more than losing the task. The last below came out
-of reading another repository against this one — `msw`. The first came out of
-building something queued here, which is the other way an entry arrives: a gate
-that finds a defect on its first run files the defect.
+losing the argument would cost more than losing the task. The first below came out
+of building something queued here, which is one way an entry arrives: a gate that
+finds a defect on its first run files the defect. The second came out of reading
+another repository against this one — `msw`. The last came out of an adoption
+report (`mine-capablanca`, 0.4.2, 34 requirements / 56 scenarios / greenfield),
+which is the third way: not a defect, but a shape the tool made an adopter work
+around eight times without ever erroring. Two further entries from that report
+left this section by shipping in `[0.5.0]` — a change's specs moving to their
+merged location, and the delta reading as the registry of what it adds — and
+their arguments are recorded there, including the part of the first one that
+turned out to be wrong.
 
 - **A diagnosable refusal when the resolved compiler has no AST API.**
   Discovered by building the `typescript` matrix (see `[0.4.2]`), which is
@@ -2147,6 +2357,158 @@ have to gather again.
   someone hits an `EMFILE` from `attest check`, the diagnosis is already written
   down rather than rediscovered.
 
+- **An assertion that recomputes its expectation from the param the code under
+  test just read is a tautology, and nothing says so.** Reported by
+  `mine-capablanca`, which probed it by mutating the registry and running the
+  full gate on each mutation:
+
+  | mutation | who reads it | `check` | `verify` |
+  |---|---|---|---|
+  | `GEN-1.maxCandidatesPerPiece` 64 → 4 | scenario only | ok | **red** |
+  | `BOARD-1.boardSize` 10 → 12 | app + fixtures | ok | **red** |
+  | `BOARD-2.maxMines` 12 → **40** | app + assertion | ok | **green** |
+  | `BOARD-2.minMines` 9 → **1** | app + assertion | ok | **green** |
+
+  The mine-density band — the one number deciding whether that game is playable —
+  moved by 3.3× with the whole suite green, `check` silent, and `possible-drift`
+  correctly not firing, because a covering scenario *does* read the param.
+  **Read the third and fourth rows against the second, because that is the
+  finding.** The reporter's diagnosis was "app and spec both read it", but row 2
+  is app-and-spec and goes red. What distinguishes the green rows is narrower and
+  more useful: the assertion **derives its expectation from the same param the
+  code under test used**, so both sides move together and the comparison has no
+  independent term. Row 2's expectation lives in fixtures, which do not move when
+  the param does, and the mechanism works. So the failing condition is a property
+  of the assertion, not of who reads the value — which matters, because it means
+  the answer is a rule about how to write the assertion, and *not* the detector
+  the reporter proposed.
+  **What this falsifies is written in this file.** The rejection of a committed
+  params snapshot, below, closes on *"the mechanism that guards a param is a
+  scenario reading it, not a file recording it"* — a sufficiency claim, and rows
+  3 and 4 are counterexamples to it. A scenario reading the param is necessary
+  and not sufficient. That entry stays rejected on its own argument, which was
+  never about detection power, but its fallback clause is now known incomplete
+  and is annotated accordingly. The README's §"killer move" has the same shape:
+  it says noticing a param *moved* is `verify`'s job "only when a scenario asserts
+  on the value it read from `params`" — literally a necessary condition, and read
+  by an adopter as a sufficient one, with the very next line (*"Read the param
+  inside the assertion, not beside it"*) being the instruction that produces the
+  tautology.
+  **The framing that probably resolves it: this is `never-red` wearing different
+  clothes.** A tautological assertion is a scenario that cannot fail, which is
+  the exact defect `archive`'s red-before-implement gate exists to catch — and it
+  did catch two of them in this very repo (`CHECK-2`, `FOG-3`, both confirmed
+  correct by the reporter). The reason it did not catch these is structural:
+  **changing the value of an existing param goes through no gate at all.**
+  `archive` gates a change; a param edit is not a change. That is a cleaner
+  statement of the gap than "params can be tautological".
+  *What blocks the decision — three things, all of them real.* **(1)** Every
+  mutation above is synthetic. Across 8 commits touching `*.reqs.ts` in that
+  repo, **no param value was ever modified** — every `params:` line in every diff
+  is an addition. So the hole is proven as a logical property and its frequency is
+  entirely unmeasured, from one greenfield repo. **(2)** The reporter's proposed
+  mechanism — a WARNING when one param id is read from both a spec and a non-spec
+  file — is the wrong shape twice over: it fires on row 2, which is correct usage
+  and goes red, and it would fire on the arrangement the README actively
+  recommends, which is §9's "usually wrong about staleness" failure mode again.
+  It also needs a static sweep of the whole project for `reqs['X'].params.y`,
+  far past the two registry readers' current surface. **(3)** No mechanism is yet
+  known that separates "the assertion pins this independently" from "the assertion
+  echoes it" without executing the scenario twice under different values — which
+  is mutation testing, a much larger thing to own.
+  **The guidance half has shipped; this entry is now only about the detector.**
+  "Read the param inside the assertion" was insufficient and half-wrong as
+  written, and `[0.5.0]` replaces it everywhere it appeared — README, the
+  `init` skill, `possible-drift`, and design §11 — with what the evidence
+  supports: **the expectation must not be a function of the param the code under
+  test consumed**, pinned in a fixture, a literal, or a second independently
+  derived value. Row 2 is the worked example, and the reporter's own
+  `CHECK-2`/`FOG-3` fixes are the same move. It was held back once because
+  rewording the central claim of the tool is not a line appended; that is what
+  was then done, deliberately and in one pass.
+  **What stays undecided is the mechanism**, and all three blockers above are
+  untouched by the rewording: the frequency is still unmeasured from one
+  greenfield repo, the reporter's proposed detector is still the wrong shape
+  twice over, and nothing short of mutation testing separates an independent pin
+  from an echo. What the guidance does not do is close the hole — a tautological
+  assertion is still green, still silent, and still reachable — so this stays
+  here rather than moving to `Considered and rejected`: documenting a trap is
+  not the same as deciding not to detect it.
+
+- **`attest archive <change> --apply`, finishing the merge the gate approved.**
+  `mine-capablanca`'s single loudest item: eight changes, eight hand-written
+  Python scripts, and the report quotes one — it locates the delta's block by
+  `split('added: {', 1)`, trims two spaces of indent per line, and re-terminates
+  the registry on `assert t.endswith('});')`. After the gate goes green the
+  adopter hand-splices the delta into the registry, moves specs into the suite,
+  rewrites their imports, moves the folder to `archive/` and re-renders `SPEC.md`.
+  **The cost is the smaller half of the argument. The hole is that the gate's
+  verdict does not cover the step that acts on it** — `archive` proves the delta
+  is green, covered and drift-free, and then a human transcribes it by hand with
+  nothing checking the transcription. A delta can be spliced in wrong, partially,
+  or twice, and the next `check` sees only whatever ended up in the file.
+  **The objection that has to be answered is the `AGENTS.md` block under
+  `Considered and rejected`.**
+  The `AGENTS.md` block was rejected because "that is a merge tool, and each of
+  its failure modes is destructive on a file the user cannot regenerate". The
+  argument for why it does not transfer, which needs to be right before this
+  ships: there, Attest would edit prose whose grammar it does not own; here the
+  registry is a **literal** Attest defines, statically parseable, with a
+  differential suite already asserting two readers agree on it — so the result of
+  a splice is checkable by re-reading it, and the delta was validated by the gate
+  that just ran. Idempotence is verifiable rather than assumed. That reasoning
+  covers delta→registry, the folder move and the re-render. It used **not** to
+  cover import rewriting, which is editing arbitrary TypeScript and is squarely
+  the rejected shape.
+  *That blocker is gone, and it was removed rather than solved.* Proposed specs
+  now live at their merged location under `*.proposed.spec.ts` (`[0.5.0]`), so
+  the merge step for a spec is a rename in place — there are no specifiers to
+  rewrite, and `--apply` no longer inherits the one part of the job that could
+  not be made safe. What is left for it is the delta→registry splice, the rename,
+  the folder move to `archive/` and the re-render, all of which the paragraph
+  above argues are checkable by re-reading the result.
+  *What still blocks the decision:* two questions with no answer yet — what
+  `--apply` does when the working tree is dirty (`archive` already has a position
+  on this; whether a file-mutating flag takes the same one is not obvious), and
+  whether a partially applied merge is recoverable or whether the flag must be
+  all-or-nothing against a scratch copy.
+  *The frequency blocker has moved.* This entry used to close on "one report, one
+  repo: the cost evidence is strong and the frequency evidence is a single
+  adopter." It is now two. This project's own maintainer proposed the same command
+  independently, without the entry in front of them, having felt the same step by
+  hand — which is the second data point that clause was waiting for. Not
+  conclusive about frequency in the field, and it does not touch either question
+  above, but it removes the reason to keep waiting for someone else to ask.
+
+  *A narrower shape was proposed with it and is rejected — `attest merge <change>`,
+  moving the change folder to `archive/<date>-<name>/` and nothing else.* Three
+  reasons, and the third is the one that decides it.
+  **(1) It targets the cheap half.** The expensive step in the report is the
+  delta→registry splice — the quoted Python locates the block by
+  `split('added: {', 1)`, trims two spaces per line, and re-terminates on
+  `assert t.endswith('});')`. The folder move is `mv`. A new command that saves a
+  shell invocation and leaves the TypeScript-literal surgery is the wrong half to
+  automate. The date it would stamp is real ergonomics but small: `archive/` is
+  named in three places and all three are exclusions (`locate.ts`'s SKIP_DIRS,
+  and the two exclude globs), so nothing reads the directory and a mis-stamped
+  date has no mechanical consequence at all.
+  **(2) It would make two command names mislead instead of one.** `attest archive`
+  archives nothing today — it is purely the gate. Adding a second verb that does
+  the archiving leaves `archive` still lying and `merge` doing its job; `--apply`
+  goes the other way and makes the existing verb finally mean what it says.
+  **(3) A move that does not re-run the gate can file an unfinished change as
+  done.** That is the one thing this tool must not ship: the whole claim is that
+  "done" has a hard definition, and a command able to mark completion around that
+  definition removes it. The alternative is that `merge` re-runs the gate — at
+  which point it *is* `--apply` and should be spelled that way. There is no third
+  option, which is why this is a rejection of the shape rather than of the idea.
+  *Recorded here rather than under `Considered and rejected`,* because nothing
+  was decided against: the idea is this entry, and only the narrow spelling of it
+  died. Also worth stating because it needed no release to ride — a new command
+  changes no exit code, rejects no previously-valid input, and removes no API, so
+  it is additive under this file's own Versioning rule and was never blocked on a
+  version bump.
+
 ## Considered and rejected
 
 Decisions **not** to build something, kept where they can be found before the
@@ -2393,6 +2755,21 @@ no scenario caught it, and `possible-drift` was **not** already printing —
 because if it was printing, what failed was reading the report, and a second
 gate does not fix that.
 
+*Annotated after `mine-capablanca` (0.4.2): the last two sentences above are
+wrong and the rejection is not.* "A scenario reading it" is necessary and not
+sufficient — where the assertion recomputes its expectation from the same param
+the code under test consumed, the value moved 3.3× with the suite green and
+`possible-drift` correctly silent, so "the only condition under which a moved
+param goes unnoticed" names one condition out of two. The reopen clause is
+therefore satisfied in substance while failing on its own literal terms, since it
+was written expecting the uncovered case and the demonstrated one has a covering
+scenario. **What that changes here is nothing**: this entry was rejected on the
+population a snapshot fires on — every legitimate param edit, fix a commit with
+no decision in it — and that objection is untouched by the new evidence, which
+concerns detection the snapshot was never denied having. The live question moved
+to `Under consideration` above, where it belongs, because the mechanism now in
+question is a rule about assertions rather than a file beside the registry.
+
 ### Grouping `render`'s output by prefix
 
 The *detection* half of this is already rejected above (every automatic
@@ -2417,7 +2794,43 @@ requirement, and human review at propose is still the whole answer. What is
 rejected is grouping as a way to assist it, and this reopens only on a
 contradiction that grouping would have caught.
 
-[Unreleased]: https://gitlab.com/Pseudorca/attest/-/compare/v0.4.3...main
+### Nested objects in `params`, so a lookup table can be registry-owned
+
+Raised by `mine-capablanca` (0.4.2) and explicitly not as a request, which is
+why it is recorded with its own answer rather than left as a complaint about a
+message. A `params` value is a scalar or a list of scalars; a table — piece kind
+to weight, tier to limit — is refused, and the only way to register one is to
+split it across parallel arrays, which reads worse in the rendered spec than it
+buys. *What rejected it: the two properties a param has, and a table has
+neither.* A param is **rendered into `SPEC.md` as a value a human checks at a
+glance**, and it is **read by a scenario as the one place that value lives**. A
+nested object fails the first by construction — there is no reading of a
+five-row table that a reviewer verifies the way they verify `30`. It fails the
+second more quietly: a table has many readers by definition, so "the one place"
+becomes "the one file", which is what an ordinary module already is. The
+schema's own comment records where the line was drawn and why arrays were let
+in — list constants are the most drift-prone values, and an array still has one
+owner read by one scenario. A table does not clear that bar; the reason arrays
+did is exactly the reason it does not.
+*The reporter's own resolution is the argument's strongest form.* The table went
+to a shared module, is not registry-owned, and **nothing was lost** — because a
+piece-value table is tuning, not a promise. That is the rule design §11 now
+states — *params for promises, plain constants for tuning* — derived
+independently by the same adopter before it was written anywhere. Under it this
+candidate is not a limitation of `params` at all: it is a value that was never a
+requirement's to hold, and §11 carries this rejection's own argument in the same
+paragraph, as the rule stated over the type rather than over the value.
+*What ships instead*, in `[0.5.0]`: the refusal now says what is accepted
+instead of `Invalid input`, and `troubleshooting.md` states the constraint and
+where such a value belongs — the reporter's actual ask, which was for the
+decision to be visible rather than discovered by reading the shipped `.d.ts`.
+The permanent half goes to design §11 with the params rule, not here.
+*This reopens on* a report where the value is genuinely promised — a table an
+adopter owes their users, whose rows a reviewer would want in the rendered spec.
+None has been seen; the one that raised it was tuning.
+
+[Unreleased]: https://gitlab.com/Pseudorca/attest/-/compare/v0.5.0...main
+[0.5.0]: https://gitlab.com/Pseudorca/attest/-/tags/v0.5.0
 [0.4.3]: https://gitlab.com/Pseudorca/attest/-/tags/v0.4.3
 [0.4.2]: https://gitlab.com/Pseudorca/attest/-/tags/v0.4.2
 [0.4.1]: https://gitlab.com/Pseudorca/attest/-/tags/v0.4.1

package/README.md

@@ -8,18 +8,26 @@ by a stable ID and continuously detects drift.
 - **Result** — is every test green? (from the test runner)
 - **Drift** — do intent and assertions still agree? (static + runtime cross-check)
 
-The killer move against drift: values that change (timeouts, limits) live **once**
-in a requirement's `params`, and tests read them from there — so a number is
-physically impossible to drift between the spec and the assertion. A param may be
-a scalar or an array of scalars, so list-shaped constants (vendor blacklists, id
-sets) get the same single source as a lone number.
+The killer move against drift: values a requirement **promises** (timeouts,
+limits, budgets) live **once** in its `params`, and tests read them from there —
+so a number is physically impossible to drift between the spec and the assertion.
+Values that merely tune behaviour stay ordinary constants; nothing is owed to
+anyone when a tuning knob changes. A param may be a scalar or an array of
+scalars, so list-shaped constants (vendor blacklists, id sets) get the same
+single source as a lone number.
 
 What that does not buy is a warning when you change the value. `check` runs
 nothing, so editing a param leaves it at `✓ No issues` — nothing became unbound,
 nothing became uncovered. The value cannot *diverge* from the assertion, which is
 the stronger property; noticing that it *moved* is `verify`'s job, and only when
-a scenario asserts on the value it read from `params`. Read the param inside the
-assertion, not beside it.
+a scenario asserts on the value it read from `params`.
+
+Reading the param is necessary and **not sufficient**, which is worth knowing
+before you rely on it: an assertion that recomputes its expectation from the same
+param the code under test just read has no independent term, so both sides move
+together and the test stays green through any edit. Pin the expectation to
+something that does not move with the param — a fixture, a literal in the test,
+or a second independently derived value.
 
 ## Prerequisites
 
@@ -149,7 +157,7 @@ Every diagnostic carries a `code`, and every code has a section in
 ```
 ERROR   registry-not-static (requirements/upload.reqs.ts:5)
     Value is not a literal.
-    → https://gitlab.com/Pseudorca/attest/-/blob/v0.4.3/docs/en/troubleshooting.md#registry-not-static
+    → https://gitlab.com/Pseudorca/attest/-/blob/v0.5.0/docs/en/troubleshooting.md#registry-not-static
 ```
 
 The anchor **is** the code, so the link cannot point somewhere the section

package/dist/core/apply.d.ts

@@ -12,6 +12,21 @@ export interface ApplyResult {
  * than off `delta.added`, so the two can never be scoped differently.
  */
 export declare function addedIds(d: RegistryDelta): string[];
+/**
+ * The ids a delta **claims**: what it adds, renames to, or modifies.
+ *
+ * This is how a proposed spec is attributed to a change (design §7). A spec
+ * sitting at its merged location carries no change name, so the delta names its
+ * specs the only way that cannot drift from them — by the requirements they
+ * declare a scenario for. Wider than `addedIds` on purpose: a delta that
+ * retunes a param or renames an id may need a scenario of its own, and one that
+ * could not be claimed would be a spec the gate never ran.
+ *
+ * REMOVED ids are absent. A scenario for a requirement the change deletes is
+ * not proposed behaviour, and claiming it would put a spec into the gate run
+ * whose requirement the same delta has just taken away.
+ */
+export declare function claimedIds(d: RegistryDelta): string[];
 /**
  * Apply a change delta to a base registry, returning the merged registry plus
  * any apply-level issues (conflicts, missing targets, invalid results). The

package/dist/core/apply.js

@@ -14,6 +14,27 @@ import { byCodeUnit } from './order.js';
 export function addedIds(d) {
     return Object.keys(d.added ?? {});
 }
+/**
+ * The ids a delta **claims**: what it adds, renames to, or modifies.
+ *
+ * This is how a proposed spec is attributed to a change (design §7). A spec
+ * sitting at its merged location carries no change name, so the delta names its
+ * specs the only way that cannot drift from them — by the requirements they
+ * declare a scenario for. Wider than `addedIds` on purpose: a delta that
+ * retunes a param or renames an id may need a scenario of its own, and one that
+ * could not be claimed would be a spec the gate never ran.
+ *
+ * REMOVED ids are absent. A scenario for a requirement the change deletes is
+ * not proposed behaviour, and claiming it would put a spec into the gate run
+ * whose requirement the same delta has just taken away.
+ */
+export function claimedIds(d) {
+    return [
+        ...Object.keys(d.added ?? {}),
+        ...(d.renamed ?? []).map((r) => r.to),
+        ...Object.keys(d.modified ?? {}),
+    ].sort(byCodeUnit);
+}
 /**
  * Apply a change delta to a base registry, returning the merged registry plus
  * any apply-level issues (conflicts, missing targets, invalid results). The
@@ -132,8 +153,29 @@ function introducedIdIssue(id, code, prefix) {
 function err(code, message, reqId) {
     return { level: 'ERROR', code, ...(reqId ? { reqId } : {}), message };
 }
+/**
+ * The first schema failure, as `path: message`.
+ *
+ * The path is the half that was being dropped. A requirement carries a record —
+ * `params` — so "invalid" on its own does not say *which* param, and the value
+ * that most often fails is one the author has to find by reading the schema's
+ * `.d.ts`. `RegistryValidationError` has spelled a path `a.b.c` since the
+ * registry shipped, and `troubleshooting.md` has been quoting `rationale:
+ * Required` for `add-invalid` the whole time — a form this function could not
+ * produce. So this is the spelling matching what is already documented, not a
+ * new one.
+ *
+ * Omitted rather than rendered as `(root)` when the path is empty, because the
+ * one caller that gets an empty path is `introducedIdIssue`, whose prefix has
+ * already named the thing: `Added requirement "auth-7" is invalid: id must look
+ * like AUTH-3` reads correctly and `(root): id must look like AUTH-3` does not.
+ */
 function firstMessage(error) {
-    return error.issues[0]?.message ?? 'unknown error';
+    const first = error.issues[0];
+    if (!first)
+        return 'unknown error';
+    const path = first.path.map(String).join('.');
+    return path ? `${path}: ${first.message}` : first.message;
 }
 /** Content equality via canonical JSON (params key order does not matter). */
 function sameRequirement(a, b) {

package/dist/core/docs.d.ts

@@ -8,7 +8,7 @@
  * and the `##` headings of both language documents, so landing here cannot
  * produce a dead link.
  */
-export declare const ISSUE_CODES: readonly ["add-conflict", "add-invalid", "change-not-found", "declared-not-run", "duplicate-prefix", "duplicate-requirement", "empty-spec", "internal-error", "invalid-change-name", "missing-spec-doc", "modify-invalid", "modify-missing", "never-red", "orphan-test", "possible-drift", "rationale-placeholder", "registry-invalid", "registry-no-default", "registry-not-static", "rename-source-missing", "rename-target-exists", "rename-target-invalid", "stale-spec-doc", "tests-red", "unbound-param", "uncovered-requirement", "unknown-target"];
+export declare const ISSUE_CODES: readonly ["add-conflict", "add-invalid", "added-id-unmerged", "change-not-found", "declared-not-run", "duplicate-prefix", "duplicate-requirement", "empty-spec", "internal-error", "invalid-change-name", "missing-spec-doc", "modify-invalid", "modify-missing", "never-red", "orphan-test", "possible-drift", "proposed-spec-unclaimed", "rationale-placeholder", "registry-invalid", "registry-no-default", "registry-not-static", "rename-source-missing", "rename-target-exists", "rename-target-invalid", "stale-spec-doc", "tests-red", "unbound-param", "uncovered-requirement", "unknown-target"];
 export type IssueCode = (typeof ISSUE_CODES)[number];
 /**
  * The page explaining `code`, or `undefined` when nothing explains it.

package/dist/core/docs.js

@@ -21,6 +21,7 @@ import { packageVersion } from './version.js';
 export const ISSUE_CODES = [
     'add-conflict',
     'add-invalid',
+    'added-id-unmerged',
     'change-not-found',
     'declared-not-run',
     'duplicate-prefix',
@@ -34,6 +35,7 @@ export const ISSUE_CODES = [
     'never-red',
     'orphan-test',
     'possible-drift',
+    'proposed-spec-unclaimed',
     'rationale-placeholder',
     'registry-invalid',
     'registry-no-default',