usedesign 1.4.1 → 1.4.3

package/dist/validate.js

@@ -86,20 +86,37 @@ const CONTROL_KEYS = new Set(["control", "control_pattern", "at_least", "calls",
 const GROUP_KEYS = new Set(["group", "role", "contains", "note"]);
 const GROUP_ROLES = ["header", "footer", "section", "table", "list", "toolbar", "menu"];
 const REMOVED_KEYS = new Set(["control", "was", "verdict"]);
+// ── reading a field in its type (1.4.3) ─────────────────────────────────────────────────────
+//
+// A rule reads a field only in the type the format gives it: a list as a list, a map as a map, an
+// id, a reference or a name as a string, a status as an integer. Any other value is absent to the
+// rules, and the schema layer names its type. Before, a number where a list belongs threw here
+// (`responses: 412`), a string was walked letter by letter as if it were steps, `[]` counted as a
+// value here and as nothing in the Python prototype, which stopped with a traceback on most of
+// these. An enumeration keeps its own rule: a value outside the list, of whatever type, is reported
+// as written. A key is looked up among the map's own keys — `toString` is not an outcome.
+const isMap = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const list = (value) => (Array.isArray(value) ? value : []);
+const map = (value) => (isMap(value) ? value : {});
+const text = (value) => (typeof value === "string" ? value : undefined);
+const status = (value) => (Number.isInteger(value) ? value : undefined);
+/** Absent for a required key: not written, null, or an empty string. */
+const absent = (value) => value === undefined || value === null || value === "";
+const has = (object, key) => Object.prototype.hasOwnProperty.call(object, key);
 /**
  * One line names ONE anchor or ONE family, never both and never neither. A family (issue #10)
  * is a pattern with `*`; a "pattern" without a wildcard is a literal wearing the wrong key,
  * and would silently match nothing the literal key would have matched.
  */
 function anchorOrFamily(line, literalKey, patternKey, where, err) {
-    const literal = line[literalKey];
-    const pattern = line[patternKey];
+    const literal = text(line[literalKey]);
+    const pattern = text(line[patternKey]);
     if (!literal && !pattern)
         err("missing_required_field", `${where}: \`${literalKey}\` (or \`${patternKey}\`) is absent`);
     if (literal && pattern) {
         err("literal_and_pattern", `${where}: both \`${literalKey}\` and \`${patternKey}\` — one line names one anchor or one family, never both`);
     }
-    if (pattern && !String(pattern).includes("*")) {
+    if (pattern && !pattern.includes("*")) {
         err("pattern_without_wildcard", `${where}: \`${pattern}\` has no \`*\` — a family without a wildcard is a literal; write \`${literalKey}:\``);
     }
     const atLeast = line["at_least"];
@@ -109,7 +126,7 @@ function anchorOrFamily(line, literalKey, patternKey, where, err) {
     if (atLeast !== undefined && !pattern) {
         err("malformed_at_least", `${where}: \`at_least\` belongs to a family line (\`${patternKey}\`) — a single anchor is present or it is not`);
     }
-    return literal ? String(literal) : pattern ? String(pattern) : undefined;
+    return literal || pattern || undefined;
 }
 /**
  * Validate one form contract's *meaning*. `knownForms` enables the cross-contract link warning
@@ -129,7 +146,7 @@ export function validateForm(fm, filename = "", knownForms = null, knownCards =
         if (!FORM_KEYS.has(key))
             err("unknown_field", `\`${key}\` is not part of the form contract format`);
     }
-    const formId = fm["id"] ?? "";
+    const formId = text(fm["id"]) ?? "";
     if (formId && !OPERATION_ID.test(formId)) {
         err("malformed_form_id", `\`${formId}\` is not <area>.<object>.<name>`);
     }
@@ -143,16 +160,16 @@ export function validateForm(fm, filename = "", knownForms = null, knownCards =
     // every entry names the data state it lives in.
     const stateMap = fm["states"];
     if (stateMap !== undefined) {
-        if (!stateMap || typeof stateMap !== "object" || Array.isArray(stateMap)) {
+        if (!isMap(stateMap)) {
             err("malformed_states", "`states` must be a map of screen state → { data: <data state> }");
         }
         else {
             for (const [state, spec] of Object.entries(stateMap)) {
-                if (!spec || typeof spec !== "object" || Array.isArray(spec)) {
+                if (!isMap(spec)) {
                     err("missing_required_field", `states.${state}: \`data\` is absent`);
                     continue;
                 }
-                if (!spec["data"])
+                if (!text(spec["data"]))
                     err("missing_required_field", `states.${state}: \`data\` is absent`);
                 for (const key of Object.keys(spec)) {
                     if (!STATE_KEYS.has(key))
@@ -161,12 +178,12 @@ export function validateForm(fm, filename = "", knownForms = null, knownCards =
             }
         }
     }
-    const presents = Array.isArray(fm["presents"]) ? fm["presents"] : [];
+    const presents = list(fm["presents"]);
     const seenFields = new Set();
     for (const [index, element] of presents.entries()) {
-        if (!element || typeof element !== "object")
+        if (!isMap(element))
             continue;
-        if (!element["shows"])
+        if (!text(element["shows"]))
             err("missing_required_field", `presents[${index}]: \`shows\` is absent`);
         for (const key of Object.keys(element)) {
             if (!ELEMENT_KEYS.has(key))
@@ -179,10 +196,10 @@ export function validateForm(fm, filename = "", knownForms = null, knownCards =
             seenFields.add(field);
         }
     }
-    const controls = Array.isArray(fm["controls"]) ? fm["controls"] : [];
+    const controls = list(fm["controls"]);
     const seenControls = new Set();
     for (const [index, control] of controls.entries()) {
-        if (!control || typeof control !== "object")
+        if (!isMap(control))
             continue;
         for (const key of Object.keys(control)) {
             if (!CONTROL_KEYS.has(key))
@@ -194,9 +211,9 @@ export function validateForm(fm, filename = "", knownForms = null, knownCards =
                 err("duplicate_control", `\`${name}\` appears more than once in controls`);
             seenControls.add(name);
         }
-        const opens = control["opens"];
+        const opens = text(control["opens"]);
         if (opens && knownForms !== null && !knownForms.has(opens)) {
-            warn("undescribed_form", `control \`${name}\` opens \`${opens}\`, which no contract in this set describes`);
+            warn("undescribed_form", `control \`${name ?? ""}\` opens \`${opens}\`, which no contract in this set describes`);
         }
         // `calls` names the operation a control runs, or null for local behaviour — and since round 27
         // the chain it runs, in call order: a draft's «save as plan» renames it, then publishes it.
@@ -223,7 +240,7 @@ export function validateForm(fm, filename = "", knownForms = null, knownCards =
             for (const [step, id] of chain.entries()) {
                 if (!knownCards.has(id)) {
                     const where = chain.length > 1 ? ` (step ${step + 1} of ${chain.length})` : "";
-                    warn("form_calls_undescribed", `control \`${name}\` calls \`${id}\`${where}, which no card in this set describes`);
+                    warn("form_calls_undescribed", `control \`${name ?? ""}\` calls \`${id}\`${where}, which no card in this set describes`);
                 }
             }
         }
@@ -236,34 +253,36 @@ export function validateForm(fm, filename = "", knownForms = null, knownCards =
     const members = new Set([...seenFields, ...seenControls]);
     const seenGroups = new Set();
     const claimed = new Map();
-    for (const [index, group] of (Array.isArray(fm["groups"]) ? fm["groups"] : []).entries()) {
-        if (!group || typeof group !== "object")
+    for (const [index, group] of list(fm["groups"]).entries()) {
+        if (!isMap(group))
             continue;
         for (const required of ["group", "role", "contains"]) {
-            if (!group[required])
+            if (absent(group[required]))
                 err("missing_required_field", `groups[${index}]: \`${required}\` is absent`);
         }
         for (const key of Object.keys(group)) {
             if (!GROUP_KEYS.has(key))
                 err("unknown_field", `groups[${index}]: \`${key}\` is not part of a group line`);
         }
-        const name = group["group"];
+        const name = text(group["group"]);
         if (name) {
             if (seenGroups.has(name))
                 err("duplicate_group", `\`${name}\` appears more than once in groups`);
             seenGroups.add(name);
         }
         const role = group["role"];
-        if (role && !GROUP_ROLES.includes(role)) {
+        if (!absent(role) && !GROUP_ROLES.includes(role)) {
             err("invalid_enum_value", `groups[${index}]: role \`${role}\` is not one of ${GROUP_ROLES}`);
         }
-        for (const member of Array.isArray(group["contains"]) ? group["contains"] : []) {
+        for (const member of list(group["contains"])) {
+            if (typeof member !== "string")
+                continue;
             if (!members.has(member)) {
-                err("unknown_group_member", `group \`${name}\` contains \`${member}\`, which no element or control declares`);
+                err("unknown_group_member", `group \`${name ?? ""}\` contains \`${member}\`, which no element or control declares`);
             }
             const already = claimed.get(member);
             if (already && already !== name) {
-                err("element_in_two_groups", `\`${member}\` sits in \`${already}\` and \`${name}\` — an element renders in one place`);
+                err("element_in_two_groups", `\`${member}\` sits in \`${already}\` and \`${name ?? ""}\` — an element renders in one place`);
             }
             if (name)
                 claimed.set(member, name);
@@ -271,16 +290,16 @@ export function validateForm(fm, filename = "", knownForms = null, knownCards =
     }
     // One document both requiring and forbidding a control is not incompleteness — it is the
     // contract disagreeing with itself, and no amount of code can satisfy it.
-    for (const [index, removed] of (Array.isArray(fm["removed"]) ? fm["removed"] : []).entries()) {
-        if (!removed || typeof removed !== "object")
+    for (const [index, removed] of list(fm["removed"]).entries()) {
+        if (!isMap(removed))
             continue;
-        if (!removed["control"])
+        if (!text(removed["control"]))
             err("missing_required_field", `removed[${index}]: \`control\` is absent`);
         for (const key of Object.keys(removed)) {
             if (!REMOVED_KEYS.has(key))
                 err("unknown_field", `removed[${index}]: \`${key}\` is not part of a removed line`);
         }
-        const name = removed["control"];
+        const name = text(removed["control"]);
         if (name && seenControls.has(name)) {
             err("removed_also_required", `\`${name}\` is listed in controls and in removed — the contract both requires and forbids it`);
         }
@@ -403,7 +422,7 @@ export function validate(fm, filename = "", knownIds = null) {
         if (!(field in fm))
             err("missing_required_field", `\`${field}\` is absent`);
     }
-    const cardId = fm["id"] ?? "";
+    const cardId = text(fm["id"]) ?? "";
     if (cardId && !OPERATION_ID.test(cardId)) {
         err("malformed_operation_id", `\`${cardId}\` is not <area>.<object>.<action>`);
     }
@@ -421,7 +440,7 @@ export function validate(fm, filename = "", knownIds = null) {
     // states — resume from finished | partial | abandoned. Measured on a live service, where the only
     // honest alternative was `from: any`, which switches the shown_when rule off. One state is written
     // as a string; a one-element set is that string wearing brackets.
-    const fromValue = fm["data_transition"] && typeof fm["data_transition"] === "object" ? fm["data_transition"].from : undefined;
+    const fromValue = map(fm["data_transition"]).from;
     if (Array.isArray(fromValue)) {
         if (fromValue.length < 2)
             err("malformed_transition", "`data_transition.from` as a set needs at least two states — one state is written as a string");
@@ -429,10 +448,10 @@ export function validate(fm, filename = "", knownIds = null) {
             err("malformed_transition", "`data_transition.from` lists the same state twice");
     }
     // ── steps ──────────────────────────────────────────────────────────────────────────────────
-    const steps = fm["steps"] ?? [];
+    const steps = list(fm["steps"]);
     const stepIds = new Set();
     for (const step of steps) {
-        const sid = step?.id ?? "";
+        const sid = text(map(step).id) ?? "";
         if (!STEP_ID.test(sid))
             err("malformed_step_id", `\`${sid}\` is not s<N>-<name>`);
         else if (stepIds.has(sid))
@@ -440,9 +459,9 @@ export function validate(fm, filename = "", knownIds = null) {
         stepIds.add(sid);
     }
     // ── maturity vs evidence ───────────────────────────────────────────────────────────────────
-    const evidence = fm["maturity_evidence"] ?? {};
-    const tests = fm["tests"] ?? [];
-    if (maturity && maturity in EVIDENCE_FOR) {
+    const evidence = map(fm["maturity_evidence"]);
+    const tests = list(fm["tests"]);
+    if (typeof maturity === "string" && has(EVIDENCE_FOR, maturity)) {
         // Every level implies the ones below it.
         for (const level of ["implemented", "tested", "in_production"]) {
             if (MATURITY.indexOf(maturity) >= MATURITY.indexOf(level)) {
@@ -460,20 +479,20 @@ export function validate(fm, filename = "", knownIds = null) {
     // claim, and it rots by hand: cards keep "5 tests" after the sixth was cited, or after one was
     // dropped. The format's own example library was clean when this arrived; the product's cards had been kept in step by hand three times in one day.
     const testedProse = evidence["tested"];
-    const testedMatch = typeof testedProse === "number" ? [null, String(testedProse)] : /^\s*(\d+)/.exec(String(testedProse ?? ""));
+    const testedMatch = typeof testedProse === "number" ? [null, String(testedProse)] : typeof testedProse === "string" ? /^\s*(\d+)/.exec(testedProse) : null;
     if (testedMatch && Number(testedMatch[1]) !== tests.length) {
         warn("tested_count_mismatch", `maturity_evidence.tested says ${testedMatch[1]}, tests[] lists ${tests.length} — the count went stale`);
     }
     // ── concurrency ────────────────────────────────────────────────────────────────────────────
-    const concurrency = fm["concurrency"] ?? {};
+    const concurrency = map(fm["concurrency"]);
     const mode = concurrency["mode"];
     if (mode !== undefined && !CONCURRENCY_MODES.includes(mode)) {
         err("invalid_enum_value", `concurrency.mode \`${mode}\` is not one of ${CONCURRENCY_MODES}`);
     }
-    if (mode && mode !== "etag_required" && !concurrency["rationale"]) {
+    if (text(mode) && mode !== "etag_required" && !text(concurrency["rationale"])) {
         err("relaxation_without_rationale", `mode \`${mode}\` weakens protection without a rationale`);
     }
-    if (mode === "idempotency_by_formula" && !concurrency["formula"]) {
+    if (mode === "idempotency_by_formula" && !text(concurrency["formula"])) {
         err("missing_required_field", "idempotency_by_formula without `formula`");
     }
     // Round 24, from the first card a pilot's backend role wrote unaided: a soft delete that reads
@@ -484,44 +503,50 @@ export function validate(fm, filename = "", knownIds = null) {
         warn("concurrency_unexplained", "concurrency.mode is `none_unexplained` — no precondition is read and the code gives no reason; a measured absence, kept visible until it is explained (`none_by_design`) or closed (an `etag_*` mode)");
     }
     // ── interfaces ─────────────────────────────────────────────────────────────────────────────
-    const interfaces = fm["interfaces"] ?? {};
+    const interfaces = map(fm["interfaces"]);
     if (Object.keys(interfaces).length === 0) {
         err("missing_required_field", "at least one interface is required");
     }
     for (const [name, iface] of Object.entries(interfaces)) {
-        const transport = iface?.transport;
-        if (!transport)
+        const transport = map(iface).transport;
+        if (absent(transport))
             err("missing_transport", `interface \`${name}\` does not declare a transport`);
         else if (!TRANSPORTS.includes(transport)) {
             err("invalid_enum_value", `interface \`${name}\`: transport \`${transport}\` is unknown`);
         }
-        for (const ref of iface?.covers_steps ?? []) {
+        for (const ref of list(map(iface).covers_steps)) {
+            if (typeof ref !== "string")
+                continue;
             if (!stepIds.has(ref))
                 err("unknown_step_reference", `interface \`${name}\` covers unknown step \`${ref}\``);
         }
     }
     // ── tests ──────────────────────────────────────────────────────────────────────────────────
     const covered = new Set();
-    for (const test of tests) {
-        const refs = Array.isArray(test?.covers) ? test.covers : [test?.covers];
+    for (const test of tests.map(map)) {
+        const id = text(test.id) ?? "";
+        const refs = Array.isArray(test.covers) ? test.covers : [test.covers];
         for (const ref of refs) {
+            if (typeof ref !== "string")
+                continue;
             if (!stepIds.has(ref))
-                err("unknown_step_reference", `test \`${test?.id}\` covers unknown step \`${ref}\``);
+                err("unknown_step_reference", `test \`${id}\` covers unknown step \`${ref}\``);
             covered.add(ref);
         }
-        if (!TEST_LEVELS.includes(test?.level)) {
-            err("invalid_enum_value", `test \`${test?.id}\`: level \`${test?.level}\` is unknown`);
+        if (test.level !== undefined && !TEST_LEVELS.includes(test.level)) {
+            err("invalid_enum_value", `test \`${id}\`: level \`${test.level}\` is unknown`);
         }
     }
-    const gaps = new Set((fm["coverage_gaps"] ?? []).map((gap) => gap?.step));
+    const gapEntries = list(fm["coverage_gaps"]).filter(isMap);
+    const gaps = new Set(gapEntries.map((gap) => gap.step).filter((step) => typeof step === "string"));
     for (const gap of gaps) {
         if (!stepIds.has(gap))
             err("unknown_step_reference", `coverage_gaps names unknown step \`${gap}\``);
     }
-    for (const entry of (fm["coverage_gaps"] ?? [])) {
-        const kind = entry?.kind;
+    for (const entry of gapEntries) {
+        const kind = entry.kind;
         if (kind !== undefined && !GAP_KINDS.includes(kind)) {
-            err("invalid_enum_value", `coverage_gaps \`${entry?.step}\`: kind \`${kind}\` is not one of ${GAP_KINDS}`);
+            err("invalid_enum_value", `coverage_gaps \`${text(entry.step) ?? ""}\`: kind \`${kind}\` is not one of ${GAP_KINDS}`);
         }
     }
     // ── a variant of another operation (§5.2e) ────────────────────────────────────────────────
@@ -530,8 +555,10 @@ export function validate(fm, filename = "", knownIds = null) {
     // shared code is its own evidence. Whether the original agrees is check 2's question.
     const inheritedSteps = new Set();
     const variant = fm["variant_of"];
-    if (variant && typeof variant === "object") {
-        for (const sid of Array.isArray(variant.inherits) ? variant.inherits : []) {
+    if (isMap(variant)) {
+        for (const sid of list(variant.inherits)) {
+            if (typeof sid !== "string")
+                continue;
             if (!stepIds.has(sid)) {
                 err("variant_inherits_unlisted_step", `\`variant_of.inherits\` names \`${sid}\`, which is not one of this card's steps — a variant lists every step it runs`);
             }
@@ -539,7 +566,8 @@ export function validate(fm, filename = "", knownIds = null) {
         }
         if (evidence["implemented"] !== undefined && typeof variant.shared === "string") {
             const own = (Array.isArray(evidence["implemented"]) ? evidence["implemented"] : [evidence["implemented"]])
-                .flatMap((item) => String(item).split("+"))
+                .filter((item) => typeof item === "string")
+                .flatMap((item) => item.split("+"))
                 .map((part) => part.trim().replace(/:\d+$/, ""));
             const shared = variant.shared.trim().replace(/:\d+$/, "");
             if (!own.includes(shared)) {
@@ -557,21 +585,24 @@ export function validate(fm, filename = "", knownIds = null) {
     // Three rules that need nothing but the card itself. Each one exists because the field it
     // guards is otherwise a claim nobody can be wrong about — and a claim nobody can be wrong
     // about is a claim nobody maintains.
-    const outcomes = fm["outcomes"] ?? [];
-    const outcomeIds = new Set(outcomes.map((o) => o?.id));
+    const outcomes = list(fm["outcomes"]).map(map);
+    const outcomeIds = new Set(outcomes.map((o) => o.id).filter((id) => typeof id === "string"));
+    const stepLines = steps.map(map);
+    const violation = (step) => map(step.on_violation);
     for (const [name, iface] of Object.entries(interfaces)) {
-        const declared = iface?.responses ?? [];
+        const declared = list(map(iface).responses).filter((code) => status(code) !== undefined);
         if (declared.length === 0)
             continue; // the field is optional; absent is not a claim
         const returned = new Map();
-        for (const step of steps) {
-            const code = step?.on_violation?.http;
-            if (typeof code === "number")
-                returned.set(code, `step \`${step.id}\``);
+        for (const step of stepLines) {
+            const code = status(violation(step).http);
+            if (code !== undefined)
+                returned.set(code, `step \`${text(step.id) ?? ""}\``);
         }
         for (const outcome of outcomes) {
-            if (typeof outcome?.http === "number")
-                returned.set(outcome.http, `outcome \`${outcome.id}\``);
+            const code = status(outcome.http);
+            if (code !== undefined)
+                returned.set(code, `outcome \`${text(outcome.id) ?? ""}\``);
         }
         for (const [code, who] of returned) {
             if (!declared.includes(code)) {
@@ -584,16 +615,17 @@ export function validate(fm, filename = "", knownIds = null) {
     // shape of `steps[]` — violated, therefore stopped, therefore an error code — does not fit it.
     // A warning, not an error, because the honest bulk card would otherwise be unwritable.
     const perItem = fm["per_item"];
-    for (const step of steps) {
-        const code = step?.on_violation?.http;
-        if (typeof code === "number" && code >= 200 && code < 300) {
-            if (perItem) {
+    for (const step of stepLines) {
+        const code = status(violation(step).http);
+        const sid = text(step.id) ?? "";
+        if (code !== undefined && code >= 200 && code < 300) {
+            if (isMap(perItem)) {
                 // With `per_item` declared there is a true place to write this, so writing it falsely
                 // is a mistake rather than a shortage of vocabulary.
-                err("per_item_failure_as_violation", `step \`${step.id}\` answers ${code}; this card declares \`per_item\`, so a per-item failure belongs there and carries no status`);
+                err("per_item_failure_as_violation", `step \`${sid}\` answers ${code}; this card declares \`per_item\`, so a per-item failure belongs there and carries no status`);
             }
             else {
-                warn("violation_with_success_status", `step \`${step.id}\` is violated yet answers ${code} — either a typo, or this is a per-item failure and belongs in \`per_item\``);
+                warn("violation_with_success_status", `step \`${sid}\` is violated yet answers ${code} — either a typo, or this is a per-item failure and belongs in \`per_item\``);
             }
         }
     }
@@ -602,10 +634,11 @@ export function validate(fm, filename = "", knownIds = null) {
     // it. A request thread suspends on `done`, a *job state*, and waits there for a person. The
     // axis survived that; its check did not.
     const continuation = fm["continuation"];
-    if (continuation && typeof continuation === "object") {
-        const jobStates = fm["async_execution"]?.job_states ?? [];
-        if (!outcomeIds.has(continuation.after) && !jobStates.includes(continuation.after)) {
-            err("continuation_without_outcome", `\`continuation.after\` names \`${continuation.after}\`, which is neither a declared outcome nor a job state`);
+    if (isMap(continuation)) {
+        const jobStates = list(map(fm["async_execution"]).job_states);
+        const after = text(continuation.after) ?? "";
+        if (!outcomeIds.has(after) && !jobStates.includes(after)) {
+            err("continuation_without_outcome", `\`continuation.after\` names \`${after}\`, which is neither a declared outcome nor a job state`);
         }
     }
     // ── covers_outcomes ────────────────────────────────────────────────────────────────────────
@@ -624,19 +657,22 @@ export function validate(fm, filename = "", knownIds = null) {
     // which asks a genuinely different question. Six errors, all false, on the first honest card.
     const outcomeVocabulary = new Map();
     for (const outcome of outcomes) {
-        if (outcome?.id)
-            outcomeVocabulary.set(outcome.id, "outcomes");
+        const id = text(outcome.id);
+        if (id)
+            outcomeVocabulary.set(id, "outcomes");
     }
     const transition = fm["data_transition"];
-    if (transition && typeof transition === "object") {
-        const targets = Array.isArray(transition.to) ? transition.to : transition.to ? [transition.to] : [];
-        for (const target of targets)
-            outcomeVocabulary.set(target, "data_transition.to");
+    if (isMap(transition)) {
+        const targets = Array.isArray(transition.to) ? transition.to : [transition.to];
+        for (const target of targets) {
+            if (text(target))
+                outcomeVocabulary.set(target, "data_transition.to");
+        }
     }
-    for (const step of steps) {
-        const error = step?.on_violation?.error;
+    for (const step of stepLines) {
+        const error = text(violation(step).error);
         if (error)
-            outcomeVocabulary.set(error, `step \`${step.id}\``);
+            outcomeVocabulary.set(error, `step \`${text(step.id) ?? ""}\``);
     }
     // Per-item failures belong here and job states do not, and the line between them is not taste.
     // A per-item failure arrives in THIS call's response — the user is looking at the screen when
@@ -644,9 +680,10 @@ export function validate(fm, filename = "", knownIds = null) {
     // measured a bulk screen that discards the response body entirely: ten items selected, three
     // rejected inside a 200, and the page says nothing at all. Without these in the vocabulary the
     // card had no way to admit it, which is the one thing this field exists to prevent.
-    for (const failure of fm["per_item"]?.failures ?? []) {
-        if (failure?.code)
-            outcomeVocabulary.set(failure.code, "per_item failure");
+    for (const failure of list(map(perItem).failures)) {
+        const code = text(map(failure).code);
+        if (code)
+            outcomeVocabulary.set(code, "per_item failure");
     }
     // Round 23 wrote two read cards whose screens could describe every refusal and not the one
     // ending the user came for. A read has no `data_transition.to`, and with a single ending it has
@@ -660,8 +697,8 @@ export function validate(fm, filename = "", knownIds = null) {
         .map(([id]) => id);
     const hasDefaultSuccess = namedSuccesses.length === 0;
     for (const [name, iface] of Object.entries(interfaces)) {
-        const covers = iface?.covers_outcomes;
-        if (!covers || typeof covers !== "object")
+        const covers = map(iface).covers_outcomes;
+        if (!isMap(covers))
             continue;
         for (const key of Object.keys(covers)) {
             if (key === "ok") {
@@ -675,7 +712,7 @@ export function validate(fm, filename = "", knownIds = null) {
             }
         }
         for (const [id, where] of outcomeVocabulary) {
-            if (!(id in covers)) {
+            if (!has(covers, id)) {
                 err("outcome_not_covered", `interface \`${name}\`: outcome \`${id}\` (${where}) is absent from covers_outcomes — write it, even as null`);
             }
             else if (covers[id] === null) {
@@ -685,7 +722,7 @@ export function validate(fm, filename = "", knownIds = null) {
         // A warning, not an error: cards written before round 23 had no way to name the success,
         // and a gate must not turn red on them for a word that did not exist when they were written.
         if (hasDefaultSuccess) {
-            if (!("ok" in covers)) {
+            if (!has(covers, "ok")) {
                 warn("default_success_uncovered", `interface \`${name}\`: the default success has no line in covers_outcomes — write \`ok:\`, even as null`);
             }
             else if (covers["ok"] === null) {
@@ -713,12 +750,13 @@ export function validate(fm, filename = "", knownIds = null) {
         }
     }
     for (const [name, iface] of Object.entries(interfaces)) {
-        for (const parameter of iface?.parameters ?? []) {
-            if (parameter?.handling !== "decorative")
+        for (const parameter of list(map(iface).parameters).map(map)) {
+            const pname = text(parameter.name);
+            if (parameter.handling !== "decorative" || pname === undefined)
                 continue;
-            const path = iface?.path ?? "";
-            if (!path.includes(`{${parameter.name}}`)) {
-                err("decorative_parameter_not_in_path", `interface \`${name}\`: \`${parameter.name}\` is declared decorative but does not appear in \`${path || "(no path)"}\``);
+            const path = text(map(iface).path) ?? "";
+            if (!path.includes(`{${pname}}`)) {
+                err("decorative_parameter_not_in_path", `interface \`${name}\`: \`${pname}\` is declared decorative but does not appear in \`${path || "(no path)"}\``);
             }
         }
     }
@@ -741,23 +779,20 @@ export function validate(fm, filename = "", knownIds = null) {
     // #1: a compliance read had to pick between two lies, and the smaller lie was still a lie.
     if ("data_transition" in fm && fm["data_transition"] === null) {
         const provenance = fm["provenance"];
-        const recordsOnly = provenance && typeof provenance === "object" && provenance.records_only === true;
-        if (!fm["mutates"] && provenance !== "none" && !recordsOnly) {
+        const recordsOnly = isMap(provenance) && provenance.records_only === true;
+        if (!writesWithoutTransition && provenance !== "none" && !recordsOnly) {
             err("write_without_effect", "`data_transition: null` with neither `mutates`, `provenance: none`, nor `records_only: true` — the write does not say what it changes");
         }
     }
     // ── cross-card references ──────────────────────────────────────────────────────────────────
     if (knownIds !== null) {
-        const reversibility = fm["reversibility"];
-        if (reversibility && typeof reversibility === "object") {
-            const target = reversibility.reversible_via;
-            if (target && !knownIds.has(target)) {
-                warn("undescribed_counterpart", `\`reversible_via\` points at undescribed \`${target}\``);
-            }
+        const target = text(map(fm["reversibility"]).reversible_via);
+        if (target && !knownIds.has(target)) {
+            warn("undescribed_counterpart", `\`reversible_via\` points at undescribed \`${target}\``);
         }
-        const serves = fm["serves_step"];
-        if (serves && !knownIds.has(serves.operation)) {
-            warn("undescribed_counterpart", `\`serves_step\` points at undescribed \`${serves.operation}\``);
+        const serves = text(map(fm["serves_step"]).operation);
+        if (serves !== undefined && !knownIds.has(serves)) {
+            warn("undescribed_counterpart", `\`serves_step\` points at undescribed \`${serves}\``);
         }
     }
     return out;