usedesign 1.5.0 → 1.5.2

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 { SaxesParser } from "saxes";
+import { Finding, expandGlobs, globMatches, isMap, loadCardFiles, map, maps, readDocument, refuseTwins, text, texts, whyUnreadable, } 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) {
@@ -188,6 +197,55 @@ export function checkRoutes(config, base) {
 // The repository states the facts, the checker compares — the same shape as check 1, except that
 // here the format already exists (JUnit XML), so nothing new is invented.
 const PARAMETRISED = /[[(].*$/; // checkout[blocked] · checkout(1) → checkout
+/**
+ * The test cases of a report, read as XML 1.0 reads it: a `testcase` element in no namespace, at any
+ * depth, in document order; its `classname` and `name`; and its status from its own children —
+ * `failure` or `error` fails it, `skipped` skips it, in any letter case, and the last of them decides.
+ *
+ * 1.5.1 read the report with a lenient parser: a report cut off while it was written read as far as
+ * it went, so a test cut before its `<failure>` passed; past 1 000 escaped characters (`&quot;`) the
+ * report was refused; `&#233;` stayed six characters. The Python prototype read all three as XML
+ * reads them; both do now (1.5.2). A DOCTYPE is refused in both: JUnit reports carry none, and its
+ * entities are what the expansion attacks are made of.
+ */
+function readReport(text) {
+    class Doctype extends Error {
+    }
+    const parser = new SaxesParser({ xmlns: true });
+    const cases = [];
+    const open = [];
+    parser.on("doctype", () => {
+        throw new Doctype();
+    });
+    parser.on("opentag", (tag) => {
+        const parent = open[open.length - 1];
+        if (parent && tag.uri === "") {
+            const local = tag.local.toLowerCase();
+            if (local === "failure" || local === "error")
+                parent.status = "failed";
+            else if (local === "skipped")
+                parent.status = "skipped";
+        }
+        let own = null;
+        if (tag.uri === "" && tag.local === "testcase") {
+            const classname = tag.attributes["classname"]?.value ?? "";
+            const name = tag.attributes["name"]?.value ?? "";
+            own = { classname, name, status: "passed", full: classname ? `${classname}.${name}` : name };
+            cases.push(own);
+        }
+        open.push(own);
+    });
+    parser.on("closetag", () => {
+        open.pop();
+    });
+    try {
+        parser.write(text).close();
+    }
+    catch (exc) {
+        return exc instanceof Doctype ? "doctype" : "malformed";
+    }
+    return cases;
+}
 function loadReport(config, base) {
     const location = config.test_report;
     if (!location) {
@@ -199,40 +257,20 @@ function loadReport(config, base) {
     const path = join(base, location);
     if (!existsSync(path))
         return { cases: [], findings: [new Finding("report_missing", `${location} does not exist`)] };
-    let tree;
-    try {
-        tree = new XMLParser({ ignoreAttributes: false, attributeNamePrefix: "@_", isArray: (name) => name === "testcase" }).parse(readFileSync(path, "utf8"));
+    // 1.5.1 named a directory here as malformed XML, and the Python prototype stopped with a traceback.
+    const why = whyUnreadable(path);
+    if (why)
+        return { cases: [], findings: [new Finding("report_missing", `${location} cannot be read: ${why}`)] };
+    const cases = readReport(readFileSync(path, "utf8"));
+    if (cases === "doctype") {
+        return { cases: [], findings: [new Finding("report_malformed", `${location}: a DOCTYPE — a JUnit report has none, and check 2 reads none`)] };
     }
-    catch (exc) {
-        return { cases: [], findings: [new Finding("report_malformed", `${location}: ${exc.message}`)] };
+    if (cases === "malformed") {
+        return {
+            cases: [],
+            findings: [new Finding("report_malformed", `${location}: not well-formed XML — a run that stopped while writing its report leaves such a file`)],
+        };
     }
-    const cases = [];
-    const walk = (node) => {
-        if (!node || typeof node !== "object")
-            return;
-        for (const [key, value] of Object.entries(node)) {
-            if (key === "testcase") {
-                for (const item of Array.isArray(value) ? value : [value]) {
-                    let status = "passed";
-                    for (const child of Object.keys(item ?? {})) {
-                        const tag = child.toLowerCase();
-                        if (tag === "failure" || tag === "error")
-                            status = "failed";
-                        else if (tag === "skipped")
-                            status = "skipped";
-                    }
-                    const classname = String(item?.["@_classname"] ?? "");
-                    const name = String(item?.["@_name"] ?? "");
-                    cases.push({ classname, name, status, full: classname ? `${classname}.${name}` : name });
-                }
-            }
-            else if (typeof value === "object") {
-                for (const item of Array.isArray(value) ? value : [value])
-                    walk(item);
-            }
-        }
-    };
-    walk(tree);
     if (cases.length === 0) {
         return { cases, findings: [new Finding("report_empty", `${location}: no test cases — a failed run, not a suite without tests`)] };
     }
@@ -301,9 +339,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 +371,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 +411,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 +433,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 +454,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 +480,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 +520,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 +537,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 +555,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 +578,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 +633,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 +644,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 +653,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 +759,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 +769,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 +827,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 +865,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 +883,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 +906,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 +920,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 +960,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 +972,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 +983,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) {