@am_shork/attest 0.10.0 → 0.11.0

package/README.md

@@ -131,12 +131,19 @@ attest init --target cursor    # .cursor/rules/attest.mdc
 attest init --target copilot   # .github/instructions/attest.instructions.md
 ```
 
-"Red before you implement" is enforced rather than advised: `archive` records how
-each of a change's scenarios ended on its first run, into
-`changes/<name>/first-run.json`, and blocks with `never-red` on any requirement
-the delta adds whose scenarios were never seen to fail. Commit `first-run.json`
-with the change — it is the evidence, and CI has to reach the same verdict as
-you do.
+"Every scenario has been seen to fail" is enforced rather than advised:
+`archive` records how each of a change's scenarios ended in every run it
+observes, into `changes/<name>/first-run.json`, and blocks with `never-red` on
+any requirement the delta adds whose scenarios were never seen to fail. Commit
+`first-run.json` with the change — it is the evidence, and CI has to reach the
+same verdict as you do.
+
+**It does not require you to write the test first.** A recorded failure is
+permanent and a recorded pass is not, so a failure observed after the
+implementation exists satisfies the gate exactly like one observed before it:
+if you wrote the intent, the scenario and the code together, remove the
+implementation, run `archive`, and put it back. What is enforced is that the
+assertion can fail — not the order you worked in.
 
 An agent loads the document on its own — its description is already in the
 agent's context, or its path matches what you have open — so nothing has to be
@@ -152,7 +159,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.10.0/docs/en/troubleshooting.md#registry-not-static
+    → https://gitlab.com/Pseudorca/attest/-/blob/v0.11.0/docs/en/troubleshooting.md#registry-not-static
 ```
 
 The anchor **is** the code, so the link cannot point somewhere the section

package/dist/core/gate.d.ts

@@ -102,17 +102,27 @@ export declare function specLoadFailedIssues(run: RunResult, already?: ReadonlyS
  */
 export declare function notRunIssues(plan: AttestPlan, run: RunResult, specific?: readonly Issue[]): Issue[];
 /**
- * Never-red: a scenario attesting a requirement this change ADDs, whose first
- * observed run did not fail (design §6, mechanism 2).
+ * Never-red: a scenario attesting a requirement this change ADDs, which no run
+ * the gate observed has seen fail (design §6, mechanism 2).
  *
  * This is the half of the gate that certifies the tests ever *discriminated*.
  * Green at archive time says only that they pass now — a scenario that asserted
  * nothing has been green since the commit that added it and clears every other
  * check identically. The two states are reported apart because the fixes differ:
- * a first run that passed means the scenario does not test what it claims, while
- * no observation at all means the workflow's stage-1 step was skipped, and the
- * remedy for the second is to run the gate before implementing rather than to
- * rewrite anything.
+ * a scenario observed passing and never failing does not test what it claims,
+ * while no observation at all means no run has been taken yet, and the remedy
+ * for the second is to take one rather than to rewrite anything.
+ *
+ * **The obligation is discrimination, and it says nothing about ordering.** The
+ * record is monotonic toward failure but a pass is provisional (`red-record.ts`),
+ * so a failure observed *after* the implementation exists replaces a recorded
+ * pass and satisfies this exactly like one observed before it. Running the gate
+ * first is the cheapest route to the evidence and not the only one: removing the
+ * implementation, running the gate, and restoring it produces the same fact by
+ * the same command. Nothing here could enforce an order anyway — a stage-1 red
+ * can come from a typo in the spec rather than from the requirement being
+ * unimplemented, so an earlier observation was never stronger evidence, only
+ * earlier.
  *
  * Scoped to ADDED ids only. A requirement written straight into the base
  * registry — which is how existing behaviour gets described, in a brownfield

package/dist/core/gate.js

@@ -132,17 +132,27 @@ export function notRunIssues(plan, run, specific = []) {
     ];
 }
 /**
- * Never-red: a scenario attesting a requirement this change ADDs, whose first
- * observed run did not fail (design §6, mechanism 2).
+ * Never-red: a scenario attesting a requirement this change ADDs, which no run
+ * the gate observed has seen fail (design §6, mechanism 2).
  *
  * This is the half of the gate that certifies the tests ever *discriminated*.
  * Green at archive time says only that they pass now — a scenario that asserted
  * nothing has been green since the commit that added it and clears every other
  * check identically. The two states are reported apart because the fixes differ:
- * a first run that passed means the scenario does not test what it claims, while
- * no observation at all means the workflow's stage-1 step was skipped, and the
- * remedy for the second is to run the gate before implementing rather than to
- * rewrite anything.
+ * a scenario observed passing and never failing does not test what it claims,
+ * while no observation at all means no run has been taken yet, and the remedy
+ * for the second is to take one rather than to rewrite anything.
+ *
+ * **The obligation is discrimination, and it says nothing about ordering.** The
+ * record is monotonic toward failure but a pass is provisional (`red-record.ts`),
+ * so a failure observed *after* the implementation exists replaces a recorded
+ * pass and satisfies this exactly like one observed before it. Running the gate
+ * first is the cheapest route to the evidence and not the only one: removing the
+ * implementation, running the gate, and restoring it produces the same fact by
+ * the same command. Nothing here could enforce an order anyway — a stage-1 red
+ * can come from a typo in the spec rather than from the requirement being
+ * unimplemented, so an earlier observation was never stronger evidence, only
+ * earlier.
  *
  * Scoped to ADDED ids only. A requirement written straight into the base
  * registry — which is how existing behaviour gets described, in a brownfield
@@ -165,8 +175,8 @@ export function neverRedIssues(plan, addedIds, firstRun) {
             file: s.file,
             line: s.line,
             message: outcome === 'pass'
-                ? `scenario "${s.name}" passed on its first run, so it never showed that ${s.reqId} was unimplemented; give it an assertion that fails without the change and run the gate again — a later failing run replaces this record.`
-                : `scenario "${s.name}" has no recorded first run for ${s.reqId}; run \`attest archive\` before implementing, so ${RED_RECORD_FILE} records it failing.`,
+                ? `scenario "${s.name}" was observed passing and never failing, so it has not shown that it can fail without ${s.reqId} being implemented; give it an assertion that discriminates and run the gate again — a later failing run replaces this record.`
+                : `scenario "${s.name}" has no observed run recorded for ${s.reqId}; run \`attest archive\` with the implementation absent — before writing it, or with it removed — so ${RED_RECORD_FILE} records the scenario failing.`,
         });
     }
     return issues;

package/dist/core/red-record.d.ts

@@ -18,11 +18,11 @@ export declare function redRecordPath(root: string, changeName: string): string;
 /** The file name, exported so a diagnostic can name it without rebuilding it. */
 export declare const RED_RECORD_FILE = "first-run.json";
 /**
- * reqId -> spec file -> scenario name -> the outcome of its first observed run.
+ * reqId -> spec file -> scenario name -> the strongest outcome observed for it.
  *
- * Deliberately not a list of "red scenarios": a scenario whose first run passed
- * is the case mechanism 2 exists to catch, so it has to be recorded as a fact
- * rather than as an absence. An absence then means only one thing — never
+ * Deliberately not a list of "red scenarios": a scenario only ever observed
+ * passing is the case mechanism 2 exists to catch, so it has to be recorded as a
+ * fact rather than as an absence. An absence then means only one thing — never
  * observed at all — and the gate can report the two separately.
  *
  * **The file level is what identifies a scenario, and it was missing.** A

package/dist/core/red-record.js

@@ -1,5 +1,13 @@
-// Mechanism 2's record: what each of a change's scenarios did the *first* time
-// it ran (design §6).
+// Mechanism 2's record: the strongest outcome the gate has ever observed for
+// each of a change's scenarios (design §6).
+//
+// Not "the first run", which is what the file is named after and what this was
+// once described as. The record is revised — see the asymmetry below — and the
+// difference is the whole reason the *order* of the observations is free: an
+// author who has already written the implementation earns the evidence by
+// removing it, running the gate, and restoring it. The file keeps its name
+// because archived records already carry it (`inspect.ts`) and a rename would
+// spend that to fix a word.
 //
 // §8's gate requires green at archive time. That certifies "these tests pass",
 // not "these tests ever discriminated" — a scenario that asserted nothing has
@@ -36,7 +44,8 @@
 // change red. Once a scenario has been seen to fail, nothing can take it back.
 //
 // Provisional pass: plain first-write-wins was the first design here, and it
-// makes the defect this mechanism exists to catch *unrecoverable*. A scenario
+// makes the defect this mechanism exists to catch *unrecoverable*, and it is
+// also what would have made the ordering real. A scenario
 // that passed on its first run is one that asserts nothing; the fix is to give
 // it a real assertion and watch it fail — but under first-write-wins that
 // observation could never be recorded, so the only way out was deleting the

package/dist/core/registry.d.ts

@@ -115,8 +115,34 @@ type ProposedRequirements<T extends RegistryDelta> = T extends {
  * helper over a whole registry; the ids a single change adds are few and known
  * at the call site, so the stricter shape costs nothing and rejects a mistyped
  * id outright instead of leaving it to `check`.
+ *
+ * **`added` is withheld from the type although the value still carries it**, and
+ * that is the one place this shape deliberately understates its own object. Both
+ * `reqs['AUTH-7'].params.x` and `d.added['AUTH-7'].params.x` are correct during
+ * stage 1; only the first survives `--apply`, which repoints the specifier at
+ * the merged registry, and a registry has no `added`. Nothing else catches that:
+ * the gate runs before the rename, `check` executes nothing, and the compiler
+ * sees whichever half is on disk — so the difference appears one command later,
+ * as a `spec-load-failed` naming the file and not the cause.
+ *
+ * The optional `never` rather than a bare `Omit` is load-bearing.
+ * `RegistryDelta`'s four fields are all optional, so an added-only delta with
+ * `added` removed has *no* property in common with it and TypeScript's weak-type
+ * check refuses `applyDelta(base, delta({ added: … }))` outright — nine call
+ * sites in this tree, none of them wrong. An optional property restores the
+ * overlap while still refusing the read, and the refusal survives the escape
+ * hatches that would make it advisory: `d.added!` and `d.added?.[…]` both land
+ * on `never`, and only an explicit `as any` compiles.
+ *
+ * `modified`, `removed` and `renamed` are left alone on purpose. They vanish at
+ * the merge too, but none of them has a by-id equivalent — there is no correct
+ * spelling to redirect an author to, so a spec reading one is reading delta-only
+ * data rather than misspelling a right thing, which is a different defect and
+ * has never been reported.
  */
-export type DefinedDelta<T extends RegistryDelta> = T & ProposedRequirements<T>;
+export type DefinedDelta<T extends RegistryDelta> = Omit<T, 'added'> & {
+    added?: never;
+} & ProposedRequirements<T>;
 /**
  * Declare a registry delta for a change (design §7). Ordered idempotent
  * application (RENAMED -> REMOVED -> MODIFIED -> ADDED) lives in applyDelta.
@@ -130,6 +156,10 @@ export type DefinedDelta<T extends RegistryDelta> = T & ProposedRequirements<T>;
  * exists to reward — and then billed them the rewrite at merge for having
  * complied. Now merging a spec changes its import and nothing else.
  *
+ * That rejected expression is now rejected by the compiler rather than by
+ * this comment — {@link DefinedDelta} withholds `added`, because it was the
+ * one wrong spelling that stage 1 could not tell from the right one.
+ *
  * Still no validation, deliberately. A delta carrying an id the registry would
  * refuse is an `add-invalid` / `rename-target-invalid` ERROR from the gate
  * (ATX-41), which is where a reviewer sees it; throwing here would move that

package/dist/core/registry.js

@@ -48,6 +48,10 @@ export function defineRequirements(input) {
  * exists to reward — and then billed them the rewrite at merge for having
  * complied. Now merging a spec changes its import and nothing else.
  *
+ * That rejected expression is now rejected by the compiler rather than by
+ * this comment — {@link DefinedDelta} withholds `added`, because it was the
+ * one wrong spelling that stage 1 could not tell from the right one.
+ *
  * Still no validation, deliberately. A delta carrying an id the registry would
  * refuse is an `add-invalid` / `rename-target-invalid` ERROR from the gate
  * (ATX-41), which is where a reviewer sees it; throwing here would move that

package/dist/core/skill.js

@@ -289,40 +289,59 @@ one stage where the assertion is being authored against a value nobody has
 implemented yet. MODIFIED ids are deliberately not readable this way — the end
 state is the base entry with the patch applied, and the base is not in that file.
 
-**The scenarios must be red.** Every added requirement needs at least one
-scenario in a \`*.proposed.spec.ts\`, and at this stage they must fail —
-they describe behaviour that does not exist yet. Prove it:
+Reading a proposed requirement through \`added\` — \`d.added['AUTH-7'].params.x\` —
+is refused by the compiler rather than by this paragraph. It is correct today and
+wrong one command later, because \`--apply\` repoints the import at the registry
+and a registry has no \`added\`; the by-id form above is the one that survives.
+
+**Each added scenario must be observed failing, once.** Every added requirement
+needs at least one scenario in a \`*.proposed.spec.ts\`, and the gate has to see
+each of them fail at least once before it will archive the change. Take the
+observation:
 
 \`\`\`
 attest archive <name> --json     # expect a failing verdict carrying tests-red
 \`\`\`
 
-If it passes at this stage, the scenarios assert nothing real — and this is no
-longer advice. That run writes \`changes/<name>/first-run.json\`, recording how
-each of the change's scenarios ended the first time it was seen, and the archive
-gate later refuses any added requirement whose scenarios have no recorded
-failing run (\`never-red\`). A scenario that was green from the start no longer
-clears the gate.
-
-Two consequences worth knowing before you start:
-
-- **Run this before you implement anything.** The record is written by the
-  command, not by you; skipping the step means the first observation is of
-  already-working code, which is a \`never-red\` block.
-- **A recorded failure is permanent, a recorded pass is not.** The green run at
-  the end cannot erase the red — that is the point — but a scenario recorded as
-  passing can still be fixed: give it an assertion that fails without the change
-  and run the gate again, and the real failure replaces it.
+That run writes \`changes/<name>/first-run.json\`, recording how each of the
+change's scenarios ended, and the archive gate later refuses any added
+requirement whose scenarios have no recorded failing run (\`never-red\`). A
+scenario that has only ever been seen green does not clear the gate — if it
+passes while the behaviour it describes is absent, it asserts nothing real.
+
+**The obligation is that the scenario can fail. It is not an obligation to write
+it first.** The run above is the cheapest way to take the observation, because at
+this point in stage 1 nothing is implemented and the scenarios are red by
+construction. It is not the only way, and the record is what makes the other one
+work: a recorded failure is permanent, a recorded pass is provisional, so a
+failure seen later replaces a pass seen earlier. Two routes, one fact:
+
+- **Nothing implemented yet** — run the command above and the record is taken.
+  This is the shape stage 1 is written around.
+- **The implementation already exists** — you wrote the intent, the scenario and
+  the code in one pass, which is a perfectly good way to work. Remove the
+  implementation, run the command above, then restore it. The record that comes
+  back is the same evidence obtained by the same command, and the restored code
+  makes it green again without erasing it.
+
+Do not reorder work you have already done to satisfy this; take the observation
+the second way. What no route excuses is a scenario that stays green with its
+subject removed — that is the defect \`never-red\` exists to name, and it is
+visible only if you actually take the observation.
+
+A recorded pass is not a dead end either: give the scenario an assertion that
+discriminates and run the gate again, and the real failure replaces it.
 
 Commit \`first-run.json\` with the change. It is evidence a reviewer reads, and
 the gate has to reach the same verdict on a CI checkout as on your machine.
 
 **Never write or edit that file yourself.** The gate trusts it and cannot check
-it: everything else Attest writes can be regenerated and compared, but a first
-run cannot be recomputed once the change is green — which is the whole reason
-the record exists. Producing it any way other than by running the gate destroys
-the only thing it is for. If it says something you did not expect, run the gate
-again; a real failing run replaces a recorded pass.
+it: everything else Attest writes can be regenerated from the tree as it is and
+compared, and this cannot — a green tree says nothing about whether a scenario
+could ever have failed, which is the whole reason the record exists. Producing
+it any way other than by running the gate destroys the only thing it is for. If
+it says something you did not expect, take the observation again — remove the
+behaviour and run the gate; a real failing run replaces a recorded pass.
 
 To see where the change stands at any point, without paying for a run:
 
@@ -347,8 +366,9 @@ still not a verdict — \`attest archive\` is the only thing that decides.
 - **What pins each expectation** — a fixture, a literal, an independently
   derived value; never the param the code under test consumed?
 - **Does each statement carry one obligation**, or several under one SHALL?
-- **Was any of this ever red**, or does part of it already work? \`never-red\`
-  asks for a recorded failing run only on the ids you ADD.
+- **Was each scenario ever observed failing** — with its subject absent, whether
+  because it was not written yet or because you removed it? \`never-red\` asks
+  for that on the ids you ADD, and asks nothing about when you took it.
 
 Then present the proposal, the ids, and the red output, and **stop**. Wait for
 agreement before implementing.
@@ -442,8 +462,9 @@ failure this framework exists to make visible:
    identical content is a no-op.
 4. **Do not write or edit \`first-run.json\`.** It is the one file here the gate
    trusts without being able to check it, so a hand-written \`"fail"\` clears
-   \`never-red\` while proving nothing at all. Run the gate before implementing;
-   that is what produces the record honestly.
+   \`never-red\` while proving nothing at all. Run the gate against a tree where
+   the behaviour is absent — that is what produces the record honestly, and it
+   is the one step here nothing else can stand in for.
 
 ### When the gate passes
 

package/dist/core/splice.d.ts

@@ -107,6 +107,26 @@ export declare function spliceModifications(file: string, source: string, change
  * property of its module resolution, uniform across the project, and already
  * answered by the specifier sitting in front of us — the third spelling
  * included, where the answer is "none".
+ *
+ * **A source that does not compile is returned untouched** — ATX-69, over the
+ * one writer that reaches the compiler directly. `ts.createSourceFile` recovers:
+ * handed a file that does not compile it returns a tree built from what the
+ * parser guessed, and every offset below comes out of that tree and is written
+ * back over the bytes of a `*.spec.ts` the user cannot regenerate. The two other
+ * writers in this file ask the same question through the reader that hands them
+ * their offsets; this one has to ask it itself.
+ *
+ * It is unreachable through the command today — the gate refuses a spec it
+ * could not parse before a merge starts (`pipeline.ts`) — and that is exactly
+ * why it is checked here: a defence that holds only because something upstream
+ * holds is not a defence, which is the standard `keySource` above is written to.
+ *
+ * The refusal is the source unchanged rather than a throw or an issue, because
+ * there is no failure channel to use and this function's whole discipline is
+ * that it touches one string literal or nothing. `applyMerge` writes only when
+ * the text moved, so an unparseable spec is renamed with the import it already
+ * had — which is the state a re-run finds and reports, rather than a file
+ * rewritten at offsets nobody can trust.
  */
 export declare function repointImport(file: string, source: string, from: string, to: string): string;
 //# sourceMappingURL=splice.d.ts.map

package/dist/core/splice.js

@@ -34,6 +34,7 @@
 // reach this file because the gate validated the delta before `--apply` ran.
 import ts from 'typescript';
 import { dirname, relative, resolve } from 'node:path';
+import { parseSource } from './compiler.js';
 import { registryEntryLayouts, registryInsertionPoint } from './static-registry.js';
 import { toPosixPath } from './paths.js';
 import { byCodeUnit, sortDeep } from './order.js';
@@ -470,9 +471,32 @@ function sameValue(a, b) {
  * property of its module resolution, uniform across the project, and already
  * answered by the specifier sitting in front of us — the third spelling
  * included, where the answer is "none".
+ *
+ * **A source that does not compile is returned untouched** — ATX-69, over the
+ * one writer that reaches the compiler directly. `ts.createSourceFile` recovers:
+ * handed a file that does not compile it returns a tree built from what the
+ * parser guessed, and every offset below comes out of that tree and is written
+ * back over the bytes of a `*.spec.ts` the user cannot regenerate. The two other
+ * writers in this file ask the same question through the reader that hands them
+ * their offsets; this one has to ask it itself.
+ *
+ * It is unreachable through the command today — the gate refuses a spec it
+ * could not parse before a merge starts (`pipeline.ts`) — and that is exactly
+ * why it is checked here: a defence that holds only because something upstream
+ * holds is not a defence, which is the standard `keySource` above is written to.
+ *
+ * The refusal is the source unchanged rather than a throw or an issue, because
+ * there is no failure channel to use and this function's whole discipline is
+ * that it touches one string literal or nothing. `applyMerge` writes only when
+ * the text moved, so an unparseable spec is renamed with the import it already
+ * had — which is the state a re-run finds and reports, rather than a file
+ * rewritten at offsets nobody can trust.
  */
 export function repointImport(file, source, from, to) {
-    const sf = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, /* setParentNodes */ true);
+    const parsed = parseSource(file, source);
+    if ('error' in parsed)
+        return source;
+    const sf = parsed.sf;
     const dir = dirname(file);
     const edits = [];
     for (const statement of sf.statements) {

package/dist/core/static-registry.js

@@ -217,7 +217,7 @@ export function readDeltaSource(file, source) {
  */
 export function declaredIdsFromSource(file, source) {
     const sf = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, /* setParentNodes */ true);
-    const names = localNames(sf, DEFINE);
+    const names = authoringNames(sf, DEFINE);
     const ids = new Set();
     // Any `defineRequirements({ … })` in the file, not only the exported one: the
     // failure being diagnosed is often that the call is not where it should be —
@@ -309,41 +309,105 @@ function constInitializer(sf, name) {
 function authoringCall(expr, sf, fn) {
     if (!ts.isCallExpression(expr) || expr.arguments.length !== 1)
         return undefined;
-    if (!callsAuthoringFn(expr, localNames(sf, fn), fn))
+    if (!callsAuthoringFn(expr, authoringNames(sf, fn), fn))
         return undefined;
     return unwrap(expr.arguments[0]);
 }
 /**
- * Whether a call is a call of `fn`, by the local names the imports bound to it.
+ * Whether a call is a call of `fn`, by what the file binds the callee to.
  *
  * One predicate for both readers of this question — the extraction above and the
  * id recovery below — because they must not be able to disagree about what
  * counts as the authoring call. An alias rule taught to one and not the other
  * would make recovery silently miss exactly the files the reader refuses.
+ *
+ * **A name this file binds to something other than an import is not `fn`.**
+ * Matching by spelling alone lets a file hand the two readers different
+ * registries while contradicting itself in plain sight — `const
+ * defineRequirements = (r) => ({ ...r, 'ADMIN-1': … })` in front of the export
+ * leaves this reader with the literal argument and the evaluator with whatever
+ * that function returns. A wrong answer rather than a refusal, of the shape the
+ * `let` guard above is kept for, on the commands a reviewer runs *because* they
+ * execute nothing (design §5.2, ATX-16).
+ *
+ * So the rule is about the binding: an import binding is trusted, a name this
+ * file never binds is trusted (it comes from a global or a harness, which is
+ * what the bare name is for), and a `const`/`let`/`var`/`function`/`class` in
+ * this file is not — whether the callee is that name or a property reached
+ * through it. Refusing is all that is needed: the file becomes
+ * `registry-not-static` with `--eval` named as the way back, which is ATX-17
+ * unchanged.
+ *
+ * **What this still cannot see is the module graph**, and it is not written to:
+ * `import { defineRequirements } from './wrapper.js'` binds the name by an
+ * import, so it is accepted, and what that module exports is not a question the
+ * source text of *this* file answers. Resolving it would mean reading — and
+ * then trusting — another file, which is the evaluator's job and the reason
+ * `--eval` exists. The line drawn here is what the file contradicts about itself.
  */
 function callsAuthoringFn(call, names, fn) {
     const callee = call.expression;
-    return ((ts.isIdentifier(callee) && names.has(callee.text)) ||
-        (ts.isPropertyAccessExpression(callee) && callee.name.text === fn));
+    if (ts.isIdentifier(callee))
+        return names.called.has(callee.text);
+    if (!ts.isPropertyAccessExpression(callee) || callee.name.text !== fn)
+        return false;
+    // `attest.defineRequirements(…)`. The object is held to the same rule as the
+    // bare name, which is what keeps the two forms from having two answers: a
+    // namespace import is trusted, a name this file never binds is trusted, and
+    // anything this file built is not. A deeper access — `a.b.defineRequirements`
+    // — is not an identifier and so is not one of those, which no namespace
+    // import can produce anyway.
+    const object = callee.expression;
+    return ts.isIdentifier(object) && !names.declared.has(object.text);
 }
-/** Local names bound to the imported `fn`, including aliases. */
-function localNames(sf, fn) {
-    const names = new Set();
+/** How the file binds the names a callee could be written with. */
+function authoringNames(sf, fn) {
+    const called = new Set();
+    const declared = new Set();
     for (const statement of sf.statements) {
-        if (!ts.isImportDeclaration(statement))
-            continue;
-        const bindings = statement.importClause?.namedBindings;
-        if (!bindings || !ts.isNamedImports(bindings))
+        if (ts.isImportDeclaration(statement)) {
+            const bindings = statement.importClause?.namedBindings;
+            if (bindings && ts.isNamedImports(bindings)) {
+                for (const el of bindings.elements) {
+                    if ((el.propertyName ?? el.name).text === fn)
+                        called.add(el.name.text);
+                }
+            }
             continue;
-        for (const el of bindings.elements) {
-            if ((el.propertyName ?? el.name).text === fn)
-                names.add(el.name.text);
         }
+        for (const name of declaredNames(statement))
+            declared.add(name);
     }
     // A file that never imported it can still be read: the import may come from a
     // global or a test harness, and the callee name is the only signal we need.
-    names.add(fn);
-    return names;
+    // Withdrawn exactly when the file itself says the name is something else.
+    if (!declared.has(fn))
+        called.add(fn);
+    return { called, declared };
+}
+/** The module-scope names one statement binds, if it is not an import. */
+function* declaredNames(statement) {
+    if (ts.isVariableStatement(statement)) {
+        for (const decl of statement.declarationList.declarations)
+            yield* bindingNames(decl.name);
+        return;
+    }
+    if ((ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement)) && statement.name) {
+        yield statement.name.text;
+    }
+}
+/** Every name a binding introduces, destructuring included. */
+function* bindingNames(name) {
+    if (ts.isIdentifier(name)) {
+        yield name.text;
+        return;
+    }
+    // `const { defineRequirements } = evil;` binds the name as surely as an
+    // assignment does, and reads less like a shadow rather than more.
+    for (const element of name.elements) {
+        if (ts.isBindingElement(element))
+            yield* bindingNames(element.name);
+    }
 }
 /** Strip the type-level wrappers that do not change the value (`as const`, `satisfies`, parens). */
 function unwrap(node) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@am_shork/attest",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "TDD-native spec framework: tests are the source of truth for verification, ID-bound requirements the source of truth for intent.",
   "type": "module",
   "packageManager": "pnpm@10.28.0",
@@ -56,6 +56,7 @@
     "attest": "node bin/attest.js",
     "check:self": "node bin/attest.js check self",
     "verify:self": "node bin/attest.js verify self",
+    "debug:self": "vitest run --config vitest.self.config.ts",
     "cover:self": "node bin/attest.js cover self",
     "render:self": "node bin/attest.js render self --out self/requirements/SPEC.md",
     "render:self:check": "node bin/attest.js render self --out self/requirements/SPEC.md --check"