usedesign 1.5.0 → 1.5.1

package/README.md

@@ -1,25 +1,25 @@
 # usedesign — TypeScript
 
-The reference implementation: validates Operation Cards and runs the five checks against a
-repository.
+The reference implementation: validates Operation Cards and form contracts, and runs the five
+checks against a repository.
 
 ```bash
 npx usedesign validate examples/library/
 npx usedesign check usedesign.config.yaml
 ```
 
-Exit status is `1` when anything reported an error, `0` otherwise, `2` on misuse. That is the
-whole CI contract.
+Exit status is `1` when anything reported an error, `0` otherwise, `2` on misuse or on input that
+cannot be read. That is the whole CI contract.
 
 ## Status
 
-**Complete against the corpus, published to npm as `usedesign`.** Everything below runs from a
+**Complete against both corpora, published to npm as `usedesign`.** Everything below runs from a
 clone as well as through `npx usedesign`.
 
 | | |
 |---|---|
-| Cards corpus | **84 / 84** |
-| Repository corpus | **55 / 55** |
+| Cards corpus | every case passes (`tests/conformance/cards/`) |
+| Repository corpus | every case passes (`tests/conformance/checks/`) |
 | Runtime | Node ≥ 20, no native modules |
 | Dependencies | `ajv`, `ajv-formats`, `yaml`, `fast-xml-parser` |
 
@@ -29,30 +29,31 @@ npm test                      # both corpora
 node dist/cli.js check ../../tests/fixtures/library-service/usedesign.config.yaml
 ```
 
-The last command is expected to report **six errors** — the fixture is deliberately rotten, and
-a clean run there would mean the checks had stopped working.
+The last command is expected to exit `1`: the fixture is deliberately rotten — two wild
+endpoints, three unproven steps, one missing evidence path — and it has no storage inventory,
+which check 4 reports as not run. A clean run there would mean the checks had stopped working.
 
 ## Commands
 
 | Command | What it does |
 |---|---|
-| `validate <path…>` | Cards against the JSON Schema **and** the cross-card rules. `--no-schema` keeps only the latter |
-| `check <config>` | The three invariants: no wild endpoints, no unproven steps, no maturity beyond its evidence |
+| `validate <path…>` | Cards and form contracts against the JSON Schema **and** the cross-card rules. `--no-schema` keeps only the latter |
+| `check <config>` | Checks 1–5: no wild endpoints, no unproven steps, no maturity beyond its evidence, no imagined storage, the form matches its contract. A config's `checks:` names the ones that apply to the repository |
+| `scaffold <openapi.json> --out <dir>` | A draft card per route the cards do not declare yet, read from the application's own OpenAPI. Every draft fails validation on purpose |
+| `preview <config> --out <file.html>` | Form contracts as a three-rail wireframe page |
+| `gen openapi <config> --out <file.json>` | An OpenAPI contract derived from the cards — the opposite direction to `scaffold` |
 | `conformance` | Both corpora. `--cards` / `--checks` to run one |
 
 ## What validation is, in two halves
 
 `validate` runs the published schema and the cross-reference rules, and the split is not
-cosmetic. Measured on the 10 invalid corpus cases:
+cosmetic. The schema catches what a field looks like — a missing required field, an enum out of
+range, a malformed step id, an interface with no transport. It cannot see a test covering a step
+that does not exist, a screen covering a step that does not exist, or one step id used twice.
 
-- **7** are caught by the schema — a missing required field, an enum out of range, a malformed
-  step id, an interface with no transport;
-- **3** are invisible to it — a test covering a step that does not exist, a UI screen covering a
-  step that does not exist, and the same step id used twice.
-
-All three of the invisible ones are the same shape: *a name that points at nothing*. A schema can
-say what a field looks like; only a checker holding the whole card can say whether the thing it
-names is there.
+Those invisible ones are the same shape: *a name that points at nothing*. A schema can say what a
+field looks like; only a checker holding the whole card — and every other card of the run — can
+say whether the thing it names is there.
 
 That second group is the reason this tool exists rather than a bare `ajv` invocation. A schema
 validates *form*; the rules validate *meaning*, and meaning is where cards rot.
@@ -66,19 +67,27 @@ The schema itself is never vendored: the compiled package carries a copy of the
   return after the closing fence; scalars came back with `\r` attached, ids stopped matching
   their pattern, and one card would not parse at all. Every symptom looked like a format problem
   and none of them was. `frontMatter` normalises before parsing.
-- **The three checks are ported line for line from the Python prototype**, including the noise
+- **A field is read only in its type.** A list is read as a list, a map as a map, a name as text;
+  a value of another type is absent to the rules and to the checks, and the schema names it. A
+  rule that trusts the shape of its input stops with a stack trace on the first card that lies.
+- **The Python implementation prints what this one prints, line for line**, including the noise
   suppressions — a dead exclusion is not reported when there are no routes, and a step whose only
   test failed is reported once, not twice. Two implementations that disagree about what to stay
-  quiet about are two dialects.
+  quiet about are two dialects; CI compares them on the corpora and on the fixtures.
 
 ## Layout
 
 | File | What is in it |
 |---|---|
-| `src/core.ts` | Findings, front matter, config, globbing — no rules |
-| `src/validate.ts` | The schema and the cross-card rules |
-| `src/checks.ts` | The three checks |
+| `src/core.ts` | Findings, front matter, config, file collection, typed reads — no rules |
+| `src/validate.ts` | The schema and the cross-card rules for cards and form contracts |
+| `src/checks.ts` | The five checks |
 | `src/conformance.ts` | The corpus runners |
+| `src/scaffold.ts` | Draft cards from an OpenAPI document |
+| `src/gen.ts` | `gen openapi`: an OpenAPI document from the cards |
+| `src/preview.ts` | The wireframe page of form contracts |
+| `src/formInventory.ts` | Helper for producing the form inventory check 5 reads |
+| `src/index.ts` | Library entry point: findings, front matter, config, card collection, card validation, checks 1–3 and the `CHECKS` map of all five, the corpus runners, the form-inventory helpers |
 | `src/cli.ts` | Argument handling and output |
 
 Rules never live in a helper: a rule that hides inside a utility is a rule nobody reviews.

package/dist/checks.d.ts

@@ -22,7 +22,10 @@ type Index = Map<string, TestCase[]>;
 /** Resolve a card's test id to report entries. Full-id matching only — never a substring. */
 export declare function findCases(testId: string, byFull: Index, byName: Index): TestCase[];
 export declare function checkCoverage(config: Config, base: string): CheckResult;
-/** `implemented` is one path or several — one example joins two with ' + '. */
+/**
+ * `implemented` is one path or several — one example joins two with ' + '. A value that is not a
+ * string is absent (1.5.1): `true` was the path `true` here and `True` in the Python prototype.
+ */
 export declare function evidencePaths(value: unknown): string[];
 export declare function checkMaturity(config: Config, base: string, today?: Date): CheckResult;
 export declare function checkStorage(config: Config, base: string): CheckResult;

package/dist/checks.js

@@ -1,16 +1,18 @@
 /**
- * The three checks. Each one has the same shape: the repository states a fact in a format it
+ * The five checks. Each one has the same shape: the repository states a fact in a format it
  * already produces, and usedesign compares that statement with the cards. Nothing here parses a
  * framework, reads source code, or guesses.
  *
- *   1. no wild endpoints      design/route-conformance.md
- *   2. no unproven steps      design/step-coverage.md
- *   3. no inflated maturity   design/maturity-evidence.md
+ *   1. no wild endpoints                design/route-conformance.md
+ *   2. no unproven steps                design/step-coverage.md
+ *   3. no inflated maturity             design/maturity-evidence.md
+ *   4. no imagined storage              SPEC §7.4
+ *   5. the form matches its contract    SPEC §7.5
  */
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { XMLParser } from "fast-xml-parser";
-import { Finding, expandGlobs, loadCardFiles, readDocument } from "./core.js";
+import { Finding, expandGlobs, globMatches, isMap, loadCardFiles, map, maps, readDocument, refuseTwins, text, texts, } from "./core.js";
 const METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
 /**
  * Parameter syntaxes seen in the wild: {name} · :name · <name> · <converter:name>
@@ -42,11 +44,12 @@ function loadDeclared(config, base) {
     const maturityById = new Map();
     const { cards, findings } = loadCardFiles(config, base);
     for (const [cardId, fm] of cards) {
-        maturityById.set(cardId, String(fm["maturity"] ?? ""));
-        for (const [name, iface] of Object.entries(fm["interfaces"] ?? {})) {
-            if (!iface || typeof iface !== "object" || iface.transport !== "http_rest")
+        maturityById.set(cardId, text(fm["maturity"]) ?? "");
+        for (const [name, iface] of Object.entries(map(fm["interfaces"]))) {
+            if (!isMap(iface) || iface["transport"] !== "http_rest")
                 continue;
-            const { method, path } = iface;
+            const method = text(iface["method"]);
+            const path = text(iface["path"]);
             if (!method || !path) {
                 findings.push(new Finding("incomplete_rest_interface", `${cardId}: interface \`${name}\` declares http_rest without method or path`));
                 continue;
@@ -54,12 +57,14 @@ function loadDeclared(config, base) {
             // The key stays the route shape — that is what the inventory can be compared against.
             // Dispatch tells cards apart from each other, not routes from each other.
             const key = normalise(method, path);
-            const d = iface.dispatch;
+            const d = map(iface["dispatch"]);
+            const by = text(d["by"]);
+            const value = text(d["value"]);
             declared.set(key, [...(declared.get(key) ?? []), cardId]);
-            dispatchOf.set(`${key}\u0000${cardId}`, d?.by && d?.value ? `${d.by}=${d.value}` : "");
+            dispatchOf.set(`${key}\u0000${cardId}`, by && value ? `${by}=${value}` : "");
         }
     }
-    for (const [key, owners] of [...declared.entries()].sort()) {
+    for (const [key, owners] of byKey(declared)) {
         if (owners.length < 2)
             continue;
         // Several operations may legitimately share a route, told apart by a request field — a
@@ -72,6 +77,14 @@ function loadDeclared(config, base) {
     }
     return { declared, maturityById, findings };
 }
+/**
+ * Declared routes in the order of their `METHOD shape` (1.5.1). Sorted as pairs, they were ordered
+ * by the text `GET /a,owner` — `GET /a+b` before `GET /a` — and the Python prototype by the pair
+ * itself, so two routes could print in a different order in each.
+ */
+function byKey(declared) {
+    return [...declared.entries()].sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+}
 function loadInventory(config, base) {
     const location = config.inventory;
     if (!location) {
@@ -103,17 +116,13 @@ function loadInventory(config, base) {
     }
     return { routes, findings, producedBy: data.produced_by ?? "" };
 }
-/** Shell-style match for exclusion patterns: `*` and `?` do not cross a `/`. */
-function matchesPattern(shape, pattern) {
-    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]");
-    return new RegExp(`^${escaped}$`).test(shape);
-}
+/** The rule that hides this route, by the glob of a `cards:` segment (1.5.1), or -1. */
 function excludedBy(config, method, shape) {
     const rules = config.exclude ?? [];
     for (const [index, rule] of rules.entries()) {
         if (rule.method && rule.method.toUpperCase() !== method)
             continue;
-        if (matchesPattern(shape, rule.path ?? ""))
+        if (globMatches(shape, rule.path ?? ""))
             return index;
     }
     return -1;
@@ -140,7 +149,7 @@ export function checkRoutes(config, base) {
             findings.push(new Finding("wild_endpoint", `${key} is served but declared by no card${entry.source ? ` (source: ${entry.source})` : ""}`));
         }
     }
-    for (const [key, owners] of [...declared.entries()].sort()) {
+    for (const [key, owners] of byKey(declared)) {
         const method = key.slice(0, key.indexOf(" "));
         const shape = key.slice(key.indexOf(" ") + 1);
         if (routes.length > 0 && !served.has(key) && excludedBy(config, method, shape) === -1) {
@@ -301,9 +310,9 @@ export function checkCoverage(config, base) {
     for (const [cardId, fm] of cards) {
         const byStep = new Map();
         ownProof.set(cardId, byStep);
-        for (const test of (fm["tests"] ?? [])) {
-            const refs = Array.isArray(test?.covers) ? test.covers : [test?.covers];
-            const testId = test?.id ?? "";
+        for (const test of maps(fm["tests"])) {
+            const refs = coversOf(test);
+            const testId = text(test["id"]) ?? "";
             const matched = haveReport ? findCases(testId, byFull, byName) : [];
             if (haveReport) {
                 if (matched.length === 0) {
@@ -333,14 +342,14 @@ export function checkCoverage(config, base) {
     // Pass 2 — verdicts, with a variant's inherited steps credited from the original.
     const byId = new Map(cards);
     for (const [cardId, fm] of cards) {
-        const steps = (fm["steps"] ?? []).map((s) => s?.id);
-        const gaps = new Set((fm["coverage_gaps"] ?? []).map((g) => g?.step));
+        const steps = stepIdsOf(fm);
+        const gaps = gapStepsOf(fm);
         const byStep = ownProof.get(cardId);
         const { credited, explained } = inheritance(cardId, fm, steps, byStep, byId, ownProof, haveReport, findings);
         // Round 26 ⑬: a gap says why the proof is missing — counted apart, so "not written yet" is
         // never read as "cannot be written".
-        for (const entry of (fm["coverage_gaps"] ?? [])) {
-            const kind = String(entry?.kind ?? "unwritten");
+        for (const entry of maps(fm["coverage_gaps"])) {
+            const kind = text(entry["kind"]) || "unwritten";
             if (kind === "unwritten" || kind === "harness" || kind === "unreachable")
                 gapKinds[kind] += 1;
         }
@@ -373,6 +382,19 @@ export function checkCoverage(config, base) {
         },
     };
 }
+/** The steps a test covers: one id or a list of them (1.5.1: an id of another type is absent). */
+function coversOf(test) {
+    const covers = test["covers"];
+    return typeof covers === "string" ? [covers] : texts(covers);
+}
+/** A card's step ids, in order; a step that is not a map, or an id that is not a string, is absent. */
+function stepIdsOf(fm) {
+    return texts(maps(fm["steps"]).map((step) => step["id"]));
+}
+/** The steps a card declares a gap for. */
+function gapStepsOf(fm) {
+    return new Set(texts(maps(fm["coverage_gaps"]).map((gap) => gap["step"])));
+}
 /**
  * Which inherited steps of a variant (§5.2e) the original's own tests prove. `explained` holds the
  * steps whose missing credit a variant finding has already reported, so check 2 does not repeat it
@@ -382,18 +404,18 @@ function inheritance(cardId, fm, steps, byStep, byId, ownProof, haveReport, find
     const credited = new Set();
     const explained = new Set();
     const variant = fm["variant_of"];
-    if (!variant || typeof variant !== "object")
+    if (!isMap(variant))
         return { credited, explained };
-    const inherits = (Array.isArray(variant.inherits) ? variant.inherits : []).filter((s) => typeof s === "string");
-    const originalId = String(variant.card ?? "");
+    const inherits = texts(variant["inherits"]);
+    const originalId = text(variant["card"]) ?? "";
     const original = byId.get(originalId);
     if (!original) {
         findings.push(new Finding("variant_of_unknown", `${cardId}: \`variant_of\` names \`${originalId}\`, which no card in the set declares`));
         inherits.forEach((s) => explained.add(s));
         return { credited, explained };
     }
-    const shared = String(variant.shared ?? "").trim().replace(LINE_SUFFIX, "");
-    const codeShared = evidencePaths(original["maturity_evidence"]?.["implemented"]).includes(shared);
+    const shared = (text(variant["shared"]) ?? "").trim().replace(LINE_SUFFIX, "");
+    const codeShared = evidencePaths(map(original["maturity_evidence"])["implemented"]).includes(shared);
     if (!codeShared) {
         findings.push(new Finding("variant_code_not_shared", `${cardId}: \`${shared}\` is not in the \`implemented\` evidence of \`${originalId}\` — nothing shows the two run the same code`));
     }
@@ -403,8 +425,8 @@ function inheritance(cardId, fm, steps, byStep, byId, ownProof, haveReport, find
     if (!wired) {
         findings.push(new Finding("variant_unwired", `${cardId}: no passing test of its own covers its last step \`${last ?? "(none)"}\` — ${inherits.length} inherited step(s) get no credit`, haveReport ? "error" : "warning"));
     }
-    const originalSteps = new Set((original["steps"] ?? []).map((s) => s?.id));
-    const originalGaps = new Set((original["coverage_gaps"] ?? []).map((g) => g?.step));
+    const originalSteps = new Set(stepIdsOf(original));
+    const originalGaps = gapStepsOf(original);
     const originalProof = ownProof.get(originalId) ?? new Map();
     for (const step of inherits) {
         if (!originalSteps.has(step)) {
@@ -429,12 +451,15 @@ function inheritance(cardId, fm, steps, byStep, byId, ownProof, haveReport, find
 const LEVELS = ["conceived", "designed", "implemented", "tested", "in_production", "deprecated"];
 const LINE_SUFFIX = /:\d+$/;
 const DEFAULT_HORIZON_DAYS = 180;
-/** `implemented` is one path or several — one example joins two with ' + '. */
+/**
+ * `implemented` is one path or several — one example joins two with ' + '. A value that is not a
+ * string is absent (1.5.1): `true` was the path `true` here and `True` in the Python prototype.
+ */
 export function evidencePaths(value) {
-    const values = Array.isArray(value) ? value : [value];
+    const values = typeof value === "string" ? [value] : texts(value);
     const paths = [];
     for (const item of values) {
-        for (const part of String(item).split("+")) {
+        for (const part of item.split("+")) {
             const trimmed = part.trim().replace(LINE_SUFFIX, "");
             if (trimmed)
                 paths.push(trimmed);
@@ -466,11 +491,11 @@ export function checkMaturity(config, base, today = new Date()) {
     findings.push(...cardFindings);
     let checkedPaths = 0;
     for (const [cardId, fm] of cards) {
-        const maturity = fm["maturity"];
+        const maturity = text(fm["maturity"]) ?? "";
         if (!LEVELS.includes(maturity))
             continue;
         const level = LEVELS.indexOf(maturity);
-        const evidence = fm["maturity_evidence"] ?? {};
+        const evidence = map(fm["maturity_evidence"]);
         // Tier 1 — the code the card points at exists.
         if (level >= LEVELS.indexOf("implemented") && evidence["implemented"] && root) {
             for (const path of evidencePaths(evidence["implemented"])) {
@@ -483,14 +508,13 @@ export function checkMaturity(config, base, today = new Date()) {
         // Tier 2 — the claim is derived from the report, not from prose.
         const passing = [];
         const covered = new Set();
-        for (const test of (fm["tests"] ?? [])) {
-            const matched = haveReport ? findCases(test?.id ?? "", byFull, byName) : [];
+        for (const test of maps(fm["tests"])) {
+            const testId = text(test["id"]) ?? "";
+            const matched = haveReport ? findCases(testId, byFull, byName) : [];
             if (matched.length > 0 && matched.every((c) => c.status === "passed")) {
-                passing.push(test?.id);
-                for (const ref of Array.isArray(test?.covers) ? test.covers : [test?.covers]) {
-                    if (typeof ref === "string")
-                        covered.add(ref);
-                }
+                passing.push(testId);
+                for (const ref of coversOf(test))
+                    covered.add(ref);
             }
         }
         if (level >= LEVELS.indexOf("tested") && passing.length === 0) {
@@ -502,16 +526,16 @@ export function checkMaturity(config, base, today = new Date()) {
         // And only when a passing test covers the LAST step — the proof §5.2e rule 4 accepts that an
         // operation goes all the way through. Tests of the door alone (sign-in, permission) pass in
         // front of an operation that answers 501; that card is honestly `designed`.
-        const steps = Array.isArray(fm["steps"]) ? fm["steps"] : [];
-        const stepIds = steps.filter((s) => s && typeof s === "object" && !Array.isArray(s)).map((s) => s.id);
+        const stepIds = stepIdsOf(fm);
         const last = stepIds.length > 0 ? stepIds[stepIds.length - 1] : undefined;
-        if (haveReport && level < LEVELS.indexOf("implemented") && typeof last === "string" && covered.has(last)) {
+        if (haveReport && level < LEVELS.indexOf("implemented") && last !== undefined && covered.has(last)) {
             findings.push(new Finding("maturity_understated", `${cardId}: claims \`${maturity}\` while a passing test of its own covers its last step \`${last}\` (${passing.length} of its tests pass)`, "warning"));
         }
         // Tier 3 — what cannot be verified must expire.
         if (level >= LEVELS.indexOf("in_production")) {
+            // A dated map or a bare string (the schema's two forms); any other value is absent (1.5.1).
             const deployed = evidence["deployed"];
-            if (deployed && typeof deployed === "object" && !Array.isArray(deployed)) {
+            if (isMap(deployed)) {
                 // A day the calendar has (1.4.3): `new Date` carried 2026-02-30 over to 2 March and called it
                 // stale, where the Python prototype said it is not a date. Year 0 is none either.
                 const raw = typeof deployed.since === "string" ? deployed.since : "";
@@ -525,7 +549,7 @@ export function checkMaturity(config, base, today = new Date()) {
                     findings.push(new Finding("evidence_stale", `${cardId}: \`deployed\` was last affirmed ${age} days ago (horizon ${horizon}) — nobody has looked since`, "warning"));
                 }
             }
-            else if (deployed) {
+            else if (typeof deployed === "string" && deployed) {
                 findings.push(new Finding("evidence_undated", `${cardId}: \`deployed: ${deployed}\` carries no date, so it can never go stale`, "warning"));
             }
         }
@@ -580,10 +604,10 @@ export function checkStorage(config, base) {
     const touched = new Set();
     let claims = 0;
     for (const [cardId, fm] of cards) {
-        for (const claim of fm["data"]?.storage ?? []) {
+        for (const claim of maps(map(fm["data"])["storage"])) {
             claims += 1;
-            const pattern = claim?.store ?? "";
-            const matched = stores.filter((store) => matchesPattern(String(store.name), pattern));
+            const pattern = text(claim["store"]) ?? "";
+            const matched = stores.filter((store) => globMatches(String(store.name), pattern));
             if (matched.length === 0) {
                 findings.push(new Finding("unknown_store", `${cardId}: claims store \`${pattern}\`, which the storage does not have`));
                 continue;
@@ -591,7 +615,7 @@ export function checkStorage(config, base) {
             for (const store of matched)
                 touched.add(String(store.name));
             // Every environment must agree, or the card is true in one place and false in another.
-            const claimedKeys = claim?.keyed_by ?? [];
+            const claimedKeys = texts(claim["keyed_by"]);
             if (claimedKeys.length > 0) {
                 for (const store of matched) {
                     const actual = store.keyed_by ?? [];
@@ -600,7 +624,7 @@ export function checkStorage(config, base) {
                     }
                 }
             }
-            const index = claim?.via_index;
+            const index = text(claim["via_index"]);
             if (index) {
                 for (const store of matched) {
                     const names = (store.indexes ?? []).map((i) => String(i.name));
@@ -706,9 +730,8 @@ function judgeCalls(contractId, name, control, shownWhen, dataOf, cardById, find
     // `from` is one state or a SET of states (round 18): the control must be shown only in
     // states that belong to the set, and in at least one of them. `none` / `any` switch the
     // rule off — `any` is the honest word for an operation that does not check its origin.
-    const transition = card["data_transition"];
-    const rawFrom = transition && typeof transition === "object" ? transition.from : undefined;
-    const fromSet = Array.isArray(rawFrom) ? rawFrom.map(String) : rawFrom ? [String(rawFrom)] : [];
+    const rawFrom = map(card["data_transition"])["from"];
+    const fromSet = typeof rawFrom === "string" && rawFrom ? [rawFrom] : texts(rawFrom);
     if (fromSet.length > 0 && !fromSet.includes("none") && !fromSet.includes("any")) {
         const mismatch = shownWhen.filter((state) => !fromSet.includes(dataOf(state)));
         if (mismatch.length > 0 || !shownWhen.some((state) => fromSet.includes(dataOf(state)))) {
@@ -717,6 +740,14 @@ function judgeCalls(contractId, name, control, shownWhen, dataOf, cardById, find
         }
     }
 }
+/** A list of state names, or undefined when the field is not a list (1.5.1: a name that is not a string is absent). */
+function statesOf(value) {
+    return Array.isArray(value) ? texts(value) : undefined;
+}
+/** `at_least`, an integer, or 1. */
+function floorOf(line) {
+    return Number.isInteger(line["at_least"]) ? Number(line["at_least"]) : 1;
+}
 export function checkForm(config, base) {
     const findings = [];
     const patterns = config.forms ?? [];
@@ -767,30 +798,35 @@ export function checkForm(config, base) {
     }
     const cardById = new Map(cards);
     const contracts = [];
+    const read = [];
     for (const path of expandGlobs(base, patterns)) {
         const fm = readDocument(path);
-        if (fm && fm["usedesign_form"] === 1)
-            contracts.push([String(fm["id"] ?? path), fm]);
+        if (isMap(fm) && fm["usedesign_form"] === 1) {
+            contracts.push([text(fm["id"]) ?? path, fm]);
+            read.push([path, fm]);
+        }
     }
+    refuseTwins(read);
     if (contracts.length === 0) {
         findings.push(new Finding("form_contracts_missing", "the `forms` patterns matched no contract"));
     }
     const claimed = new Map();
     let designedAhead = 0;
     for (const [contractId, fm] of contracts) {
-        const screen = String(fm["screen"] ?? "");
+        const screen = text(fm["screen"]) ?? "";
         const states = byScreen.get(screen);
         // A contract may be written before its screen — the format's own recommended order of
         // work — and say so with `maturity: designed` (issue #8, the forms twin of issue #3). Then
         // an absent screen is a warning, not the same error as a screen that vanished. The flag
         // cannot go stale silently: the day the screen renders, the contract still saying
         // `designed` is reported too — the gate itself tells the owner to flip it.
-        const maturity = String(fm["maturity"] ?? "implemented");
+        const maturity = text(fm["maturity"]) || "implemented";
         // Screen state → data state, through the contract's `states:` map; identity when unmapped.
-        const stateMap = fm["states"] && typeof fm["states"] === "object" ? fm["states"] : {};
+        // Looked up among the map's own keys: `toString` is not a state.
+        const stateMap = map(fm["states"]);
         const dataOf = (state) => {
-            const spec = stateMap[state];
-            return spec && typeof spec === "object" && spec.data ? String(spec.data) : state;
+            const spec = Object.prototype.hasOwnProperty.call(stateMap, state) ? stateMap[state] : undefined;
+            return (isMap(spec) && text(spec["data"])) || state;
         };
         if (!states) {
             if (maturity === "designed") {
@@ -800,9 +836,9 @@ export function checkForm(config, base) {
                 // and comparing it with the cards needs no inventory (issue #13). Only where the config
                 // declares `cards:`: a frontend-only repository has none, and stays as quiet as before.
                 if (config.cards) {
-                    for (const control of fm["controls"] ?? []) {
-                        const name = control?.control_pattern ? String(control.control_pattern) : String(control?.control ?? "");
-                        judgeCalls(contractId, name, control, control?.shown_when, dataOf, cardById, findings, "warning");
+                    for (const control of maps(fm["controls"])) {
+                        const name = text(control["control_pattern"]) || text(control["control"]) || "";
+                        judgeCalls(contractId, name, control, statesOf(control["shown_when"]), dataOf, cardById, findings, "warning");
                     }
                 }
             }
@@ -818,17 +854,18 @@ export function checkForm(config, base) {
         const mine = claimed.get(screen) ?? { fields: new Set(), controls: new Set(), fieldFamilies: [], controlFamilies: [] };
         claimed.set(screen, mine);
         const countOf = (regex, set) => [...set].filter((name) => regex.test(name)).length;
-        for (const entry of fm["presents"] ?? []) {
-            const pattern = entry?.field_pattern ? String(entry.field_pattern) : "";
+        for (const entry of maps(fm["presents"])) {
+            const pattern = text(entry["field_pattern"]) ?? "";
+            const when = statesOf(entry["when"]);
             if (pattern) {
                 // A family: one element per item of a list that arrives at runtime. Every rendered
                 // anchor matching the pattern is accounted for; `at_least` keeps the family from
                 // silently becoming empty — a screen rendering NO tabs because the backend returned
                 // nothing is a real failure, and without the floor nothing would notice.
                 const regex = familyRegex(pattern);
-                const atLeast = Number.isInteger(entry?.at_least) ? Number(entry.at_least) : 1;
+                const atLeast = floorOf(entry);
                 mine.fieldFamilies.push(regex);
-                for (const state of entry?.when ?? everyState) {
+                for (const state of when ?? everyState) {
                     const rendered = states.get(state);
                     if (!rendered) {
                         findings.push(new Finding("form_state_missing", `${contractId}: \`${pattern}\` is required in state \`${state}\`, which the inventory never rendered`));
@@ -840,12 +877,12 @@ export function checkForm(config, base) {
                         }
                     }
                 }
-                fieldOutOfState(contractId, pattern, entry?.when, states, (rendered) => countOf(regex, rendered.fields) > 0, findings);
+                fieldOutOfState(contractId, pattern, when, states, (rendered) => countOf(regex, rendered.fields) > 0, findings);
                 continue;
             }
-            const field = String(entry?.field ?? "");
+            const field = text(entry["field"]) ?? "";
             mine.fields.add(field);
-            for (const state of entry?.when ?? everyState) {
+            for (const state of when ?? everyState) {
                 const rendered = states.get(state);
                 if (!rendered) {
                     findings.push(new Finding("form_state_missing", `${contractId}: \`${field}\` is required in state \`${state}\`, which the inventory never rendered`));
@@ -854,18 +891,18 @@ export function checkForm(config, base) {
                     findings.push(new Finding("element_missing", `${contractId}: \`${field}\` must be shown in state \`${state}\` and is not`));
                 }
             }
-            fieldOutOfState(contractId, field, entry?.when, states, (rendered) => rendered.fields.has(field), findings);
+            fieldOutOfState(contractId, field, when, states, (rendered) => rendered.fields.has(field), findings);
         }
-        for (const control of fm["controls"] ?? []) {
-            const pattern = control?.control_pattern ? String(control.control_pattern) : "";
+        for (const control of maps(fm["controls"])) {
+            const pattern = text(control["control_pattern"]) ?? "";
             const regex = pattern ? familyRegex(pattern) : null;
-            const atLeast = Number.isInteger(control?.at_least) ? Number(control.at_least) : 1;
-            const name = pattern || String(control?.control ?? "");
+            const atLeast = floorOf(control);
+            const name = pattern || (text(control["control"]) ?? "");
             if (regex)
                 mine.controlFamilies.push(regex);
             else
                 mine.controls.add(name);
-            const shownWhen = control?.shown_when;
+            const shownWhen = statesOf(control["shown_when"]);
             // For a literal both questions are "is it there"; for a family they differ: enough
             // members for the floor, versus any member at all (which is what leaks out of state).
             const enough = (rendered) => (regex ? countOf(regex, rendered.controls) >= atLeast : rendered.controls.has(name));
@@ -894,8 +931,8 @@ export function checkForm(config, base) {
             }
             judgeCalls(contractId, name, control, shownWhen, dataOf, cardById, findings, "error");
         }
-        for (const entry of fm["removed"] ?? []) {
-            const name = String(entry?.control ?? "");
+        for (const entry of maps(fm["removed"])) {
+            const name = text(entry["control"]) ?? "";
             mine.controls.add(name);
             for (const [state, rendered] of states) {
                 if (rendered.controls.has(name)) {
@@ -906,9 +943,10 @@ export function checkForm(config, base) {
         // A group's anchor is accounted for BY the group line: the owner named the container when
         // grouping by it. Warning about it as undescribed would ask the owner to decide what they
         // already decided — measured 19.08: three of fourteen warnings were exactly this noise.
-        for (const group of fm["groups"] ?? []) {
-            if (group?.group)
-                mine.fields.add(String(group.group));
+        for (const group of maps(fm["groups"])) {
+            const gname = text(group["group"]);
+            if (gname)
+                mine.fields.add(gname);
         }
         // ── group membership ───────────────────────────────────────────────────────────────────
         // The contract seats elements in groups; the inventory's `within` records which containers
@@ -916,16 +954,15 @@ export function checkForm(config, base) {
         // where the member renders and the inventory carries the measurement. The first inventory
         // with containers refuted its own contract: `add-set` was contracted into the footer and
         // measured living only in the set table — the checker's first catch was its author.
-        for (const group of fm["groups"] ?? []) {
-            const gname = String(group?.group ?? "");
+        for (const group of maps(fm["groups"])) {
+            const gname = text(group["group"]) ?? "";
             if (!gname)
                 continue;
             const anchorSeen = [...states.values()].some((r) => r.fields.has(gname) || (r.within !== null && [...r.within.values()].some((chain) => chain.has(gname))));
             if (!anchorSeen) {
                 findings.push(new Finding("group_missing", `${contractId}: group \`${gname}\` is contracted but its anchor never renders`));
             }
-            for (const memberRaw of group?.contains ?? []) {
-                const member = String(memberRaw);
+            for (const member of texts(group["contains"])) {
                 // A family seated in a group: every rendered member of the family must sit there.
                 const regex = member.includes("*") ? familyRegex(member) : null;
                 for (const [state, rendered] of states) {