@am_shork/attest 0.4.3 → 0.5.0

package/dist/core/runner.js

@@ -4,6 +4,8 @@
 // never crosses the process boundary; the serialized task tree does.
 import { startVitest } from 'vitest/node';
 import { configDefaults } from 'vitest/config';
+import { relativePath } from './paths.js';
+import { byCodeUnit } from './order.js';
 /** requirement() names each describe block `[reqId]`; recover the id from that. */
 const REQ_SUITE = /^\[(.+)\]$/;
 /**
@@ -17,8 +19,21 @@ const REQ_SUITE = /^\[(.+)\]$/;
  * command goes through — the boundary the gate exists to hold.
  */
 export const BASE_EXCLUDE = configDefaults.exclude;
-/** Proposed / archived changes are excluded from a normal run (design §7, §8). */
-const DEFAULT_EXCLUDE = [...BASE_EXCLUDE, '**/changes/**', '**/archive/**'];
+/**
+ * Proposed / archived changes are excluded from a normal run (design §7, §8).
+ *
+ * The `.proposed.spec.ts` glob is the one carrying the weight now: a proposal's
+ * specs sit at their merged location, next to the code they attest, so nothing
+ * about *where* they are keeps them out of a run. They are red by construction
+ * until their change is implemented, and a default run that swept them up would
+ * report a project as broken for the whole life of every change in flight.
+ */
+const DEFAULT_EXCLUDE = [
+    ...BASE_EXCLUDE,
+    '**/*.proposed.spec.ts',
+    '**/changes/**',
+    '**/archive/**',
+];
 /**
  * Build the child-run options. Attest owns the run *scope* — include/exclude/
  * root/watch always come from here, so the caller can neither widen the spec
@@ -88,20 +103,42 @@ export async function runAndCollect(options = {}) {
         // that notices if the task tree ever stops having a `type`, a `name` or a
         // `result.state`. An `as unknown as` here bought nothing and blinded it to
         // exactly the change that would silently empty the runtime coverage.
-        for (const file of vitest.state.getFiles())
+        const unloadedFiles = [];
+        for (const file of vitest.state.getFiles()) {
             walk(file);
+            // Relative and POSIX for the reason everything derived from the root is
+            // (`paths.ts`): this becomes an `Issue.file`, which a `--json` consumer
+            // diffs across two CI runs that may not share an operating system.
+            if (failedToLoad(file)) {
+                unloadedFiles.push(relativePath(options.root ?? process.cwd(), file.filepath));
+            }
+        }
+        unloadedFiles.sort(byCodeUnit);
         // No optional call and no `?? 0` default: `getCountOfFailedTests` is a
         // required method on Vitest's state, so the guard was dead at the type
         // level — and had it ever become live it defaulted the wrong way, reading a
         // missing API as zero failures and turning a red suite green. This is the
         // one boolean in the engine that must never fail open.
         const passed = vitest.state.getCountOfFailedTests() === 0;
-        return { passed, runtimeCoverage, outcomes };
+        return { passed, runtimeCoverage, outcomes, unloadedFiles };
     }
     finally {
         await vitest.close();
     }
 }
+/**
+ * Did this file fail before any of its tests could exist?
+ *
+ * Errors recorded on the *file* rather than on a test are collection errors —
+ * the module threw while being imported. Measured rather than assumed: a spec
+ * whose assertion fails carries `errors: 0` at the file level and one failing
+ * test task, while a spec whose import throws carries `errors: 1` and no tasks
+ * at all. Both leave `result.state` at `fail`, which is why the state alone
+ * cannot tell them apart.
+ */
+function failedToLoad(file) {
+    return (file.result?.errors?.length ?? 0) > 0;
+}
 /** The outcome of a task that ran, or `undefined` when it did not run at all. */
 function executedOutcome(task) {
     const state = task.result?.state;

package/dist/core/schema.js

@@ -14,10 +14,18 @@ export const RequirementSchema = z.object({
     // blacklists, id sets) are the most drift-prone constants, so keeping them out
     // of params left the highest-risk values unguarded; an array still has exactly
     // one owner (the spec) read by exactly one place (the scenario).
+    // The union carries its own message because a union's default one is the
+    // word "Invalid input", which names neither what was given nor what is
+    // accepted. A nested object is the value that reaches it — a table of
+    // kind -> weight is the natural thing to try — and the constraint that
+    // refuses it is stated nowhere the author is looking, so the message is
+    // where they find it.
     params: z
         .record(z.string(), (() => {
         const scalar = z.union([z.number(), z.string(), z.boolean()]);
-        return z.union([scalar, z.array(scalar)]);
+        return z.union([scalar, z.array(scalar)], {
+            errorMap: () => ({ message: 'expected a string, number, boolean, or an array of those' }),
+        });
     })())
         .default({}),
     outOfScope: z.array(z.string()).default([]),

package/dist/core/skill.js

@@ -74,12 +74,22 @@ promises is a two-stage workflow, and the stages are separate on purpose.
   a limit, a list of names — is written **once**, in the requirement's \`params\`,
   and the scenario reads it from there. The number then cannot drift between the
   spec and the assertion, because there is only one of it.
+- **What earns a param: promises, not 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 (a search depth, a cache
+  size) stays an ordinary constant: nothing is owed if it changes, and a registry
+  that accumulates every knob in the project is one of the ways intent bloats.
 - **What that does not buy.** \`attest check\` executes nothing, so editing a
   param value leaves it at \`✓ No issues\` — nothing became unbound or uncovered.
   The single source makes a value impossible to *diverge*; it does not announce
   that it *moved*. Only \`verify\` goes red, and only when a scenario asserts on
-  the value it read from params. That is the reason to read params **inside** the
-  assertion rather than beside it.
+  the value it read from params.
+- **Reading the param is necessary, not sufficient.** An assertion that
+  recomputes its expectation from the same param the code under test just read
+  has no independent term: both sides move together, and the scenario 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.
 
 ## Rules the engine enforces
 
@@ -128,10 +138,31 @@ Then write the change folder. \`<name>\` is one directory name inside
 \`\`\`
 changes/<name>/
 ├── proposal.md              # why, and what is out of scope. Prose, for humans.
-├── requirements.delta.ts    # the intent change
-└── specs/*.spec.ts          # the scenarios that must pass for it to be done
+└── requirements.delta.ts    # the intent change
 \`\`\`
 
+**The change's scenarios do not live in that folder.** Each goes where it will
+live once the change is merged — beside the code it attests, in the same
+directory as the specs already there — under the name \`*.proposed.spec.ts\`:
+
+\`\`\`
+lib/game/specs/
+├── board.spec.ts            # already merged
+└── fog.proposed.spec.ts     # this change's, and ../fog already resolves
+\`\`\`
+
+That name is the whole mechanism. It keeps the file out of \`attest verify\` and
+out of a plain \`vitest run\` while the change is in flight — the scenarios are
+red by construction — and \`attest archive <name>\` pulls it in by the requirement
+ids it covers: a change claims the proposed specs that declare a scenario for an
+id it ADDs, renames to, or MODIFIEs. Nothing lists paths anywhere, so nothing can
+fall out of step. A proposed spec no change claims is a \`proposed-spec-unclaimed\`
+ERROR from \`attest check\`, because it would otherwise run nowhere at all.
+
+Writing it at its merged location is what makes merging it a rename. Its relative
+imports resolve now exactly as they will afterwards, so \`../fog\` never becomes
+\`../../../lib/game/fog\` and back again.
+
 \`\`\`ts
 // changes/add-2fa/requirements.delta.ts
 import { delta } from '@am_shork/attest/define';
@@ -156,8 +187,22 @@ The delta applies \`RENAMED → REMOVED → MODIFIED → ADDED\`, idempotently:
 ADDED id that already exists with identical content is a no-op, with different
 content it is a conflict.
 
+**A delta also reads as the registry of what it adds**, so a scenario written now
+reads a proposed param exactly as it will after the merge:
+
+\`\`\`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
+\`\`\`
+
+Never hand-write an accessor for a proposed param, and never copy the literal
+into the assertion: both are a second place the value lives, opened during the
+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 under \`changes/<name>/specs/\`, and at this stage they must fail —
+scenario in a \`*.proposed.spec.ts\`, and at this stage they must fail —
 they describe behaviour that does not exist yet. Prove it:
 
 \`\`\`
@@ -227,6 +272,8 @@ once. Branch on \`issues[].code\`, never on \`message\`:
 | \`never-red\` | an added requirement's scenario has no recorded failing run |
 | \`uncovered-requirement\` | a requirement in the applied registry has no scenario |
 | \`declared-not-run\` | a scenario was declared but never executed (\`skip\` / \`only\`?) |
+| \`proposed-spec-unclaimed\` | a \`*.proposed.spec.ts\` no change's delta claims |
+| \`added-id-unmerged\` | a spec failed to load, and this change adds an id the registry on disk lacks |
 | \`unbound-param\` | a \`{placeholder}\` has no matching \`params\` key |
 | \`registry-not-static\` | a registry file is not a literal the engine can read |
 | \`add-conflict\` | the delta adds an id that already exists with different content |
@@ -247,6 +294,12 @@ failure this framework exists to make visible:
    is the drift the single source exists to prevent, and the param is typed at
    the value written in the registry, so a stale expectation stops compiling
    rather than silently passing.
+   *One thing to know before implementation code reads a param this change
+   ADDs:* the suite imports your \`*.reqs.ts\` from disk, while the gate applies
+   the delta in memory — so that read throws at import and the gate answers
+   \`added-id-unmerged\`. Merge the added requirement into the registry and run
+   again; the \`added:\` entry stays, because applying it a second time with
+   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;
@@ -256,8 +309,10 @@ failure this framework exists to make visible:
 
 Then, and not before:
 
-1. Merge \`requirements.delta.ts\` into the main registry, and the change's specs
-   into the main suite.
+1. Merge \`requirements.delta.ts\` into the main registry, and rename each of the
+   change's \`*.proposed.spec.ts\` to \`*.spec.ts\` **in place**. Nothing moves and
+   no import changes; if you find yourself editing a specifier, the spec was not
+   written at its merged location and stage 1 was the place to fix that.
 2. Move \`changes/<name>/\` to \`archive/<date>-<name>/\`.
 3. If the project commits a rendering, regenerate it: \`attest render --out
    <file>\`. A committed document that no longer matches the registry is a

package/dist/core/static-registry.js

@@ -20,7 +20,7 @@
 // value is fixed by the source text — a second walker would be a second answer
 // to "is this a literal", and those two answers must not be able to disagree.
 import ts from 'typescript';
-import { RegistryValidationError } from './registry.js';
+import { RegistryValidationError, withProposedRequirements } from './registry.js';
 import { RegistrySchema } from './schema.js';
 /** The authoring function a registry file must default-export the result of. */
 const DEFINE = 'defineRequirements';
@@ -142,7 +142,11 @@ export function readDeltaSource(file, source) {
     // function deliberately does not make (see the note above on why a delta is
     // not schema-validated here), which is the worst thing an assertion can do —
     // look like verification.
-    return { ok: true, delta: value };
+    // Augmented exactly as `delta()` augments the evaluated one, through the same
+    // function: a delta reads as the registry of what it adds (design §7), and the
+    // two readers must not disagree about that — the differential suite is the
+    // thing that would notice, and it should have nothing to notice.
+    return { ok: true, delta: withProposedRequirements(value) };
 }
 /**
  * The expression a file default-exports, following one level of local binding.

package/dist/core/types.d.ts

@@ -40,6 +40,16 @@ export interface RunResult {
      * it, which is what §6's mechanism 2 records.
      */
     outcomes: Map<string, Map<string, Outcome>>;
+    /**
+     * Spec files that failed to *load*, as project-relative POSIX paths.
+     *
+     * A file whose module threw at import has no tasks at all, so every other
+     * signal it produces is an absence: no coverage, no outcomes, and scenarios
+     * the static plan declared but the runtime never saw. Those absences are
+     * indistinguishable from a `skip` unless the load failure is carried
+     * separately, which is what this is.
+     */
+    unloadedFiles: string[];
 }
 /** Severity levels for graded reporting (design §5.3). */
 export type Level = 'ERROR' | 'WARNING' | 'INFO';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@am_shork/attest",
-  "version": "0.4.3",
+  "version": "0.5.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",
   "engines": {