@am_shork/attest 0.4.2 → 0.5.0

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
 
@@ -67,13 +75,13 @@ export default defineRequirements({
 });
 ```
 
-**2. Attest it with a scenario** (`auth/session.spec.ts`):
+**2. Attest it with scenarios** (`session.spec.ts`):
 
 ```ts
 import { expect } from 'vitest';
 import { requirement, scenario } from '@am_shork/attest';
-import reqs from '../requirements/auth.reqs.js';
-import { createSession, advance, isValid } from './session.js';
+import reqs from './requirements/auth.reqs.js';
+import { createSession, advance, touch, isValid } from './session.js';
 
 requirement('AUTH-3', () => {
   scenario('idle timeout invalidates the session', () => {
@@ -82,9 +90,22 @@ requirement('AUTH-3', () => {
     advance(s, t + 1, 'minutes');
     expect(isValid(s, t)).toBe(false);
   });
+
+  scenario('activity resets the idle timer', () => {
+    const t = reqs['AUTH-3'].params.idleTimeoutMin;
+    const s = createSession();
+    advance(s, t - 1, 'minutes');
+    touch(s);
+    advance(s, t - 1, 'minutes');
+    expect(isValid(s, t)).toBe(true);
+  });
 });
 ```
 
+Both files above are quoted from `fixtures/consumer/`, which the packaging test
+installs from a real tarball and runs — a test asserts the quotes are byte-equal
+to the files, so a sample the engine would now reject cannot survive here.
+
 **3. Run the engine:**
 
 ```bash
@@ -136,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.2/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',

package/dist/core/gate.d.ts

@@ -9,6 +9,15 @@ export interface GateInputs {
     run: RunResult;
     /** Ids this change ADDs — the scenarios that carry a first-red obligation. */
     addedIds?: readonly string[];
+    /**
+     * Of those, the ids the registry **on disk** does not have yet.
+     *
+     * Computed against the base registry rather than the applied one, because
+     * that is the registry the child run imports: the gate applies the delta in
+     * memory, and the suite is a separate process reading `*.reqs.ts` off the
+     * filesystem. The two disagreeing is the whole content of `added-id-unmerged`.
+     */
+    unmergedAddedIds?: readonly string[];
     /** First observed outcome per scenario, already merged with this run. */
     firstRun?: RedRecord;
 }
@@ -21,6 +30,32 @@ export interface GateInputs {
  * this framework is that agreement should be structural, not clerical.
  */
 export declare function declaredNotRunIssues(plan: AttestPlan, run: RunResult): Issue[];
+/**
+ * A spec file that failed to load, while the change adds ids the registry on
+ * disk does not have yet (design §8).
+ *
+ * The gate applies the delta in memory and hands the result to itself; the
+ * suite is a child process that imports `*.reqs.ts` from the filesystem. So
+ * implementation code doing exactly what the workflow requires —
+ * `reqs['FOG-4'].params.modestRisk` for an id the change *adds* — throws at
+ * import, every spec file transitively importing that module fails to load, and
+ * what the gate could see was `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.
+ *
+ * This names the reason instead. It is a diagnosis, not a fix: the run still
+ * fails, and the way forward is still to merge the added requirement into the
+ * registry before running the gate. What it buys is that the reader is told
+ * that, rather than sent to audit their own spec files for a skip.
+ *
+ * The conjunction is the whole test, and it is deliberately a heuristic: a
+ * module can fail to import for reasons that have nothing to do with a
+ * requirement id. Naming an unmerged id when one exists is more useful than
+ * silence, so the message states the two facts and the inference between them
+ * rather than asserting a cause.
+ */
+export declare function unmergedIdIssues(run: RunResult, unmergedAddedIds: readonly string[]): Issue[];
 /**
  * Never-red: a scenario attesting a requirement this change ADDs, whose first
  * observed run did not fail (design §6, mechanism 2).
@@ -48,10 +83,12 @@ export declare function neverRedIssues(plan: AttestPlan, addedIds: readonly stri
  *      the registry+plan here are already the applied result, so one pass
  *      validates the end state.
  *   2. Executable: all tests green.
- *   3. Static coverage vs runtime coverage: every declared scenario actually
+ *   3. A spec file that failed to load while the change adds an id the registry
+ *      on disk lacks — the reason, named before the absences it causes.
+ *   4. Static coverage vs runtime coverage: every declared scenario actually
  *      ran (catches skip/only false coverage).
- *   4. Never-red: every scenario of an ADDED requirement failed on its first
+ *   5. Never-red: every scenario of an ADDED requirement failed on its first
  *      recorded run (design §6, mechanism 2).
  */
-export declare function evaluateGate({ registry, plan, run, addedIds, firstRun }: GateInputs): Issue[];
+export declare function evaluateGate({ registry, plan, run, addedIds, unmergedAddedIds, firstRun, }: GateInputs): Issue[];
 //# sourceMappingURL=gate.d.ts.map

package/dist/core/gate.js

@@ -29,6 +29,43 @@ export function declaredNotRunIssues(plan, run) {
     }
     return issues;
 }
+/**
+ * A spec file that failed to load, while the change adds ids the registry on
+ * disk does not have yet (design §8).
+ *
+ * The gate applies the delta in memory and hands the result to itself; the
+ * suite is a child process that imports `*.reqs.ts` from the filesystem. So
+ * implementation code doing exactly what the workflow requires —
+ * `reqs['FOG-4'].params.modestRisk` for an id the change *adds* — throws at
+ * import, every spec file transitively importing that module fails to load, and
+ * what the gate could see was `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.
+ *
+ * This names the reason instead. It is a diagnosis, not a fix: the run still
+ * fails, and the way forward is still to merge the added requirement into the
+ * registry before running the gate. What it buys is that the reader is told
+ * that, rather than sent to audit their own spec files for a skip.
+ *
+ * The conjunction is the whole test, and it is deliberately a heuristic: a
+ * module can fail to import for reasons that have nothing to do with a
+ * requirement id. Naming an unmerged id when one exists is more useful than
+ * silence, so the message states the two facts and the inference between them
+ * rather than asserting a cause.
+ */
+export function unmergedIdIssues(run, unmergedAddedIds) {
+    if (unmergedAddedIds.length === 0)
+        return [];
+    return run.unloadedFiles.map((file) => ({
+        level: 'ERROR',
+        code: 'added-id-unmerged',
+        file,
+        message: `${file} failed to load, and this change adds ${unmergedAddedIds.join(', ')}, which the registry on disk does not have yet. ` +
+            `The suite runs against the registry files, not the applied registry the gate computed, so code reading a requirement this change adds throws at import. ` +
+            `Merge the added requirement into the registry and run the gate again: applying a delta whose ADDED entry already exists with identical content is a no-op, so the change still documents the intent.`,
+    }));
+}
 /**
  * Never-red: a scenario attesting a requirement this change ADDs, whose first
  * observed run did not fail (design §6, mechanism 2).
@@ -77,12 +114,14 @@ export function neverRedIssues(plan, addedIds, firstRun) {
  *      the registry+plan here are already the applied result, so one pass
  *      validates the end state.
  *   2. Executable: all tests green.
- *   3. Static coverage vs runtime coverage: every declared scenario actually
+ *   3. A spec file that failed to load while the change adds an id the registry
+ *      on disk lacks — the reason, named before the absences it causes.
+ *   4. Static coverage vs runtime coverage: every declared scenario actually
  *      ran (catches skip/only false coverage).
- *   4. Never-red: every scenario of an ADDED requirement failed on its first
+ *   5. Never-red: every scenario of an ADDED requirement failed on its first
  *      recorded run (design §6, mechanism 2).
  */
-export function evaluateGate({ registry, plan, run, addedIds, firstRun }) {
+export function evaluateGate({ registry, plan, run, addedIds, unmergedAddedIds, firstRun, }) {
     const blocking = [];
     // 1) Structure (end-state re-validation).
     blocking.push(...validateStructure(registry, plan).filter((i) => i.level === 'ERROR'));
@@ -94,9 +133,20 @@ export function evaluateGate({ registry, plan, run, addedIds, firstRun }) {
             message: 'Some tests are failing; the change cannot be archived.',
         });
     }
-    // 3) Declared-not-run: static coverage claimed, runtime never executed it.
-    blocking.push(...declaredNotRunIssues(plan, run));
-    // 4) Never-red: the added scenarios have to have discriminated once.
+    // 3) A file that failed to load, named before the absences it produces.
+    const unmerged = unmergedIdIssues(run, unmergedAddedIds ?? []);
+    blocking.push(...unmerged);
+    // 4) Declared-not-run: static coverage claimed, runtime never executed it.
+    //
+    // Scenarios in a file diagnosed just above are left out. Not because they
+    // ran — they could not have — but because "declared but never executed
+    // (skipped, or excluded by an .only?)" is one fact restated as a guess about
+    // a cause the line above has already established. Only when that line was
+    // emitted: with no diagnosis to replace it, a wrong message still beats
+    // silence, which is why `verify` keeps reporting them.
+    const diagnosed = new Set(unmerged.map((i) => i.file));
+    blocking.push(...declaredNotRunIssues(plan, run).filter((i) => !diagnosed.has(i.file)));
+    // 5) Never-red: the added scenarios have to have discriminated once.
     if (addedIds && addedIds.length > 0) {
         blocking.push(...neverRedIssues(plan, addedIds, firstRun ?? {}));
     }

package/dist/core/locate.d.ts

@@ -1,6 +1,24 @@
 import type { Loader } from './loader.js';
 import type { AttestPlan, Issue, Registry } from './types.js';
 export declare const isReqsFile: (name: string) => boolean;
+/**
+ * A spec belonging to a change that has not been agreed yet (design §7).
+ *
+ * The marker is in the **name** rather than the directory because the file
+ * already sits where it will live once the change is merged: a proposal's spec
+ * is written next to the code it attests, so its relative imports resolve
+ * identically before and after the merge, and merging renames it in place
+ * instead of moving it up a tree and rewriting every specifier.
+ */
+export declare const isProposedSpecFile: (name: string) => boolean;
+/**
+ * A spec belonging to the merged suite.
+ *
+ * Proposed specs are excluded here rather than at each call site, so the base
+ * scan, the base run and every reporting command are wrong together or not at
+ * all: a red scenario for behaviour nobody has implemented must not reach any
+ * of them until its gate passes.
+ */
 export declare const isSpecFile: (name: string) => boolean;
 /**
  * Recursively find files under root whose basename matches `match`.
@@ -11,16 +29,21 @@ export declare const isSpecFile: (name: string) => boolean;
  * order never depends on which `readdir` happened to resolve first.
  */
 export declare function findFiles(root: string, match: (name: string) => boolean): Promise<string[]>;
-/** The two file sets every command needs, collected in one pass. */
+/** The file sets every command needs, collected in one pass. */
 export interface ProjectScan {
     reqsFiles: string[];
     specFiles: string[];
+    /** Specs of changes still under review; never part of the base suite. */
+    proposedSpecFiles: string[];
 }
 /**
  * Find the registry and spec files under root in a **single** traversal.
  *
  * Calling findFiles once per pattern meant `check` walked the tree twice and
- * `archive` four times, over a tree that cannot change in between.
+ * `archive` four times, over a tree that cannot change in between. Proposed
+ * specs are collected in the same pass for that reason and kept in their own
+ * list: they are found everywhere the merged ones are, and no caller may reach
+ * them by accident.
  */
 export declare function scanProject(root: string): Promise<ProjectScan>;
 /** One file's worth of registry, or the single issue that stopped it. */
@@ -92,8 +115,6 @@ export declare function loadRegistry(root: string, reader: RegistryReader, files
 export declare function parseSpecs(files: string[], displayRoot: string): Promise<AttestPlan>;
 /** Parse every `*.spec.ts` under root into one merged plan (file paths shown relative to root). */
 export declare function parseAllSpecFiles(root: string): Promise<AttestPlan>;
-/** Parse the spec files belonging to a single proposed change (design §8). */
-export declare function parseChangeSpecs(root: string, changeName: string): Promise<AttestPlan>;
 /** List the names of proposed changes under `root/changes`. */
 export declare function listChangeNames(root: string): Promise<string[]>;
 //# sourceMappingURL=locate.d.ts.map

package/dist/core/locate.js

@@ -20,7 +20,25 @@ const SKIP_DIRS = new Set([
     'archive',
 ]);
 export const isReqsFile = (name) => name.endsWith('.reqs.ts');
-export const isSpecFile = (name) => name.endsWith('.spec.ts');
+/**
+ * A spec belonging to a change that has not been agreed yet (design §7).
+ *
+ * The marker is in the **name** rather than the directory because the file
+ * already sits where it will live once the change is merged: a proposal's spec
+ * is written next to the code it attests, so its relative imports resolve
+ * identically before and after the merge, and merging renames it in place
+ * instead of moving it up a tree and rewriting every specifier.
+ */
+export const isProposedSpecFile = (name) => name.endsWith('.proposed.spec.ts');
+/**
+ * A spec belonging to the merged suite.
+ *
+ * Proposed specs are excluded here rather than at each call site, so the base
+ * scan, the base run and every reporting command are wrong together or not at
+ * all: a red scenario for behaviour nobody has implemented must not reach any
+ * of them until its gate passes.
+ */
+export const isSpecFile = (name) => name.endsWith('.spec.ts') && !isProposedSpecFile(name);
 /**
  * Recursively find files under root whose basename matches `match`.
  *
@@ -53,19 +71,29 @@ export async function findFiles(root, match) {
  * Find the registry and spec files under root in a **single** traversal.
  *
  * Calling findFiles once per pattern meant `check` walked the tree twice and
- * `archive` four times, over a tree that cannot change in between.
+ * `archive` four times, over a tree that cannot change in between. Proposed
+ * specs are collected in the same pass for that reason and kept in their own
+ * list: they are found everywhere the merged ones are, and no caller may reach
+ * them by accident.
  */
 export async function scanProject(root) {
-    const files = await findFiles(root, (n) => isReqsFile(n) || isSpecFile(n));
+    const files = await findFiles(root, (n) => isReqsFile(n) || isSpecFile(n) || isProposedSpecFile(n));
     const reqsFiles = [];
     const specFiles = [];
+    const proposedSpecFiles = [];
     for (const f of files) {
-        if (isReqsFile(basename(f)))
+        const name = basename(f);
+        // Sorted by `isSpecFile` rather than by `isProposedSpecFile`, so what makes
+        // a spec part of the merged suite is decided in exactly one place: the two
+        // predicates would otherwise both have to be right about the same file.
+        if (isReqsFile(name))
             reqsFiles.push(f);
-        else
+        else if (isSpecFile(name))
             specFiles.push(f);
+        else
+            proposedSpecFiles.push(f);
     }
-    return { reqsFiles, specFiles };
+    return { reqsFiles, specFiles, proposedSpecFiles };
 }
 /**
  * Read registries by **executing** the module through the Vite loader.
@@ -251,11 +279,6 @@ export async function parseSpecs(files, displayRoot) {
 export async function parseAllSpecFiles(root) {
     return parseSpecs(await findFiles(root, isSpecFile), root);
 }
-/** Parse the spec files belonging to a single proposed change (design §8). */
-export async function parseChangeSpecs(root, changeName) {
-    const dir = join(root, 'changes', changeName);
-    return parseSpecs(await findFiles(dir, isSpecFile), root);
-}
 /** List the names of proposed changes under `root/changes`. */
 export async function listChangeNames(root) {
     try {

package/dist/core/pipeline.d.ts

@@ -120,15 +120,6 @@ export declare function runInit(root: string, names: readonly string[]): Promise
     files: string[];
     issues: Issue[];
 }>;
-/**
- * The globs that keep *other* proposals out of a change's gate run.
- *
- * Sibling names come from `readdir`, not from the guard above, so they are
- * escaped: a directory called `feat(auth)` pasted in raw is a *pattern*, it
- * matches nothing, and that sibling's specs silently join the run — quietly
- * widening the scope of the one check that decides "done".
- */
-export declare function changeExcludeGlobs(others: string[]): string[];
 export interface StatusResult {
     change: string;
     /** One row per added id, in id order. */