create-anpunkit 2.1.0 → 2.2.0

package/template/scripts/spec-conformance.sh

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+# spec-conformance.sh — block GREEN until the phase spec is fully filled and every
+# case is verified by a boundary test (v2.2). Runs between RED and GREEN, replacing
+# the v2.1 human TEST REVIEW gate. (§5.55, rule 18)
+#
+# Two checks, both loud-fail (nonzero), no side effects:
+#   1. NO `TBD` remains in docs/spec-phase-<n>.md or any fixture it references.
+#   2. EVERY case-id in the spec table is cited by a test via `# spec: <case-id>`
+#      (or `// spec: <case-id>`) under tests/ or e2e/.
+#
+#   bash scripts/spec-conformance.sh <phase-n>
+#
+# The case→test citation here, plus the placement convention (contract/transition
+# tests live in tests/regression/), is what closes the rule-14 chain: reachable
+# transition → filled case (rule 14) → cited boundary test (this) → regression corpus.
+set -euo pipefail
+cd "${CLAUDE_PROJECT_DIR:-.}"
+
+N="${1:-}"
+[ -n "$N" ] || { echo "spec-conformance: usage: spec-conformance.sh <phase-n>" >&2; exit 2; }
+
+SPEC="docs/spec-phase-${N}.md"
+[ -f "$SPEC" ] || { echo "spec-conformance: $SPEC not found." >&2; exit 2; }
+
+FAIL=0
+
+# ---- 1. no TBD left in the spec ----
+if grep -nE '\bTBD\b' "$SPEC" >/dev/null 2>&1; then
+  echo "spec-conformance: FAIL — unfilled 'TBD' marker(s) remain in $SPEC:" >&2
+  grep -nE '\bTBD\b' "$SPEC" | sed 's/^/    /' >&2
+  echo "  Every case must be filled (or escalated as CASE-SET-DIVERGENCE) before GREEN." >&2
+  FAIL=1
+fi
+
+# ---- referenced fixtures: must exist + carry no TBD ----
+FIXREFS="$(grep -oE 'fixtures/[A-Za-z0-9_./-]+\.json' "$SPEC" | sort -u || true)"
+if [ -n "$FIXREFS" ]; then
+  while IFS= read -r fx; do
+    [ -n "$fx" ] || continue
+    if [ ! -f "$fx" ]; then
+      echo "spec-conformance: FAIL — referenced fixture missing: $fx" >&2
+      FAIL=1
+    elif grep -nE '\bTBD\b' "$fx" >/dev/null 2>&1; then
+      echo "spec-conformance: FAIL — 'TBD' marker in fixture: $fx" >&2
+      FAIL=1
+    fi
+  done <<EOF
+$FIXREFS
+EOF
+fi
+
+# ---- 2. every case-id cited by a boundary test ----
+# case-ids = the FIRST table-column cell of each row, matching PH<n>-... exactly.
+# (Parse the column, not a free grep — else `fixtures/PH1-ORDER-01-input.json`
+#  would yield a bogus `PH1-ORDER-01-input` case-id.)
+CASE_IDS="$(grep -E '^\|' "$SPEC" \
+  | awk -F'|' '{ id=$2; gsub(/^[ \t]+|[ \t]+$/,"",id); print id }' \
+  | grep -E "^PH${N}-[A-Za-z0-9_-]+$" | sort -u || true)"
+if [ -z "$CASE_IDS" ]; then
+  echo "spec-conformance: WARN — no PH${N}-* case-ids found in $SPEC (empty spec?)." >&2
+fi
+
+SEARCH_DIRS=""
+[ -d tests ] && SEARCH_DIRS="$SEARCH_DIRS tests"
+[ -d e2e ]   && SEARCH_DIRS="$SEARCH_DIRS e2e"
+
+if [ -n "$CASE_IDS" ]; then
+  if [ -z "$SEARCH_DIRS" ]; then
+    echo "spec-conformance: FAIL — case-ids exist but no tests/ or e2e/ dir to cite them." >&2
+    FAIL=1
+  else
+    while IFS= read -r cid; do
+      [ -n "$cid" ] || continue
+      # cite convention: `spec: <case-id>` with a non-id char (or EOL) after, so
+      # PH2-ORDER-01 does not match PH2-ORDER-011.
+      if grep -rEq -- "spec:[[:space:]]*${cid}([^0-9A-Za-z_-]|$)" $SEARCH_DIRS 2>/dev/null; then
+        :
+      else
+        echo "spec-conformance: FAIL — case ${cid} has no boundary test citing it (# spec: ${cid})." >&2
+        FAIL=1
+      fi
+    done <<EOF
+$CASE_IDS
+EOF
+  fi
+fi
+
+if [ "$FAIL" -ne 0 ]; then
+  echo "spec-conformance: BLOCKED — fix the above before GREEN." >&2
+  exit 1
+fi
+echo "spec-conformance: OK — phase ${N} spec fully filled; every case-id cited by a boundary test."
+exit 0

package/template/scripts/spec-staleness.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+# spec-staleness.sh — guard the per-phase spec header against upstream drift (v2.2).
+#
+# The behavioral contract docs/spec-phase-<n>.md carries a GENERATED header that
+# transcludes the phase's PLAN.md `- acceptance:` line + the in-scope DATAFLOW.md
+# transition rows, plus an embedded hash. If PLAN.md / DATAFLOW.md change after the
+# skeleton was stamped (e.g. via /replan), the stored hash no longer matches the
+# upstream → the spec must be regenerated/re-filled before SPEC REVIEW. (§5.55, rule 17)
+#
+# Hashing lives ONLY here (no duplication in agent prompts):
+#   bash scripts/spec-staleness.sh stamp <n>    # compute + embed the hash (at /overview, on regenerate)
+#   bash scripts/spec-staleness.sh check <n>    # default: recompute + compare; nonzero on drift
+#   bash scripts/spec-staleness.sh <n>          # alias for: check <n>
+#
+# set -euo pipefail; nonzero = loud fail; `stamp` is the only side effect.
+set -euo pipefail
+cd "${CLAUDE_PROJECT_DIR:-.}"
+
+# ---- args ----
+SUB="check"
+case "${1:-}" in
+  stamp) SUB="stamp"; shift;;
+  check) SUB="check"; shift;;
+esac
+N="${1:-}"
+[ -n "$N" ] || { echo "spec-staleness: usage: spec-staleness.sh [stamp|check] <phase-n>" >&2; exit 2; }
+
+SPEC="docs/spec-phase-${N}.md"
+PLAN="docs/PLAN.md"
+DATAFLOW="docs/DATAFLOW.md"
+[ -f "$SPEC" ] || { echo "spec-staleness: $SPEC not found." >&2; exit 2; }
+[ -f "$PLAN" ] || { echo "spec-staleness: $PLAN not found." >&2; exit 2; }
+
+# ---- sha256 of stdin (portable: sha256sum -> shasum -> node) ----
+sha_stdin() {
+  if   command -v sha256sum >/dev/null 2>&1; then sha256sum | cut -d' ' -f1
+  elif command -v shasum    >/dev/null 2>&1; then shasum -a 256 | cut -d' ' -f1
+  else node -e "let d='';process.stdin.on('data',c=>d+=c).on('end',()=>console.log(require('crypto').createHash('sha256').update(d).digest('hex')))"
+  fi
+}
+
+# normalize: NFC-ish arrow unify (→ -> ->), collapse spaces, trim. Content-sensitive,
+# whitespace-insensitive — so cosmetic reflow does not trip the guard, content does.
+norm() { sed -e 's/→/->/g' -e 's/[[:space:]]\{1,\}/ /g' -e 's/^ //' -e 's/ $//'; }
+
+# ---- extract this phase's block from PLAN.md (## Phase <n>: ... up to next ## Phase) ----
+phase_block() {
+  awk -v n="$N" '
+    $0 ~ ("^## Phase " n ":") {inblk=1; print; next}
+    inblk && /^## Phase /      {inblk=0}
+    inblk                      {print}
+  ' "$PLAN"
+}
+
+BLOCK="$(phase_block || true)"
+[ -n "$BLOCK" ] || { echo "spec-staleness: no '## Phase ${N}:' block in $PLAN." >&2; exit 2; }
+
+# acceptance line(s) + dataflow line, normalized
+ACC_LINE="$(printf '%s\n' "$BLOCK"   | grep -E '^- acceptance:' | norm || true)"
+DF_LINE="$(printf '%s\n'  "$BLOCK"   | grep -E '^- dataflow:'   | norm || true)"
+
+# in-scope transition tokens (from->to) named on the dataflow line
+TOKENS="$(printf '%s\n' "$DF_LINE" | norm | grep -oE '[A-Za-z0-9_]+->[A-Za-z0-9_]+' | sort -u || true)"
+
+# matching DATAFLOW.md data-rows (table rows naming an in-scope transition)
+DF_ROWS=""
+if [ -n "$TOKENS" ] && [ -f "$DATAFLOW" ]; then
+  while IFS= read -r tok; do
+    [ -n "$tok" ] || continue
+    rows="$(grep -E '^\|' "$DATAFLOW" | norm | grep -F "$tok" || true)"
+    DF_ROWS="${DF_ROWS}${rows}
+"
+  done <<EOF
+$TOKENS
+EOF
+fi
+DF_ROWS="$(printf '%s\n' "$DF_ROWS" | grep -v '^$' | sort -u || true)"
+
+# ---- the upstream signature + its hash ----
+SIG="$(printf 'ACC:%s\nDF:%s\nROWS:\n%s\n' "$ACC_LINE" "$DF_LINE" "$DF_ROWS")"
+WANT="$(printf '%s' "$SIG" | sha_stdin)"
+
+HASH_RE='^<!-- spec-hash: .* -->$'
+HAVE="$(grep -E "$HASH_RE" "$SPEC" | head -1 | sed -E 's/^<!-- spec-hash: (.*) -->$/\1/' || true)"
+
+if [ "$SUB" = "stamp" ]; then
+  if grep -qE "$HASH_RE" "$SPEC"; then
+    tmp="$(mktemp)"
+    awk -v h="$WANT" '
+      /^<!-- spec-hash: .* -->$/ && !done { print "<!-- spec-hash: " h " -->"; done=1; next }
+      { print }
+    ' "$SPEC" > "$tmp" && mv "$tmp" "$SPEC"
+  else
+    echo "spec-staleness: $SPEC has no '<!-- spec-hash: ... -->' header line to stamp." >&2
+    exit 2
+  fi
+  echo "spec-staleness: stamped phase ${N} -> ${WANT}"
+  exit 0
+fi
+
+# ---- check ----
+if [ -z "$HAVE" ] || [ "$HAVE" = "PENDING" ]; then
+  echo "spec-staleness: FAIL — phase ${N} spec hash is unstamped (${HAVE:-missing})." >&2
+  echo "  Run: bash scripts/spec-staleness.sh stamp ${N}" >&2
+  exit 1
+fi
+if [ "$HAVE" != "$WANT" ]; then
+  echo "spec-staleness: FAIL — phase ${N} spec is STALE." >&2
+  echo "  Upstream PLAN.md acceptance / DATAFLOW.md rows changed since the skeleton was stamped." >&2
+  echo "  stored=${HAVE}  current=${WANT}" >&2
+  echo "  Regenerate the skeleton header from current PLAN/DATAFLOW, re-stamp, and re-fill." >&2
+  exit 1
+fi
+echo "spec-staleness: OK — phase ${N} spec header matches upstream (${WANT})."
+exit 0

package/template/tests/helpers/spec-assert.py

@@ -0,0 +1,162 @@
+"""spec-assert.py — kit-versioned matcher-aware deep-equality comparator (v2.2).
+
+The generated `data` boundary harness (test-author) asserts an actual response
+against `fixtures/<case-id>-expected.json` via `spec_assert(actual, expected)`.
+Deep equality, EXCEPT that volatile fields in the expected fixture carry a matcher
+token instead of a literal (see §5.49). This is the ONLY comparator — no per-project
+assertion logic. One file per supported test language; this is the Python one.
+
+Matcher tokens (string values in the expected fixture):
+
+    "<UUID>"            any UUID v4 string
+    "<ISO8601>"         any ISO 8601 datetime string
+    "<ANY_STRING>"      any non-null string
+    "<ANY_NUMBER>"      any finite number (not bool)
+    "<UNORDERED>"       any array (presence + shape only)
+    "<MATCHES:regex>"   any string matching the pattern (re.search)
+
+Order-insensitive array WITH item checking: wrap the expected array as
+    {"<UNORDERED>": [item, item, ...]}
+and the actual must be a list that is an order-insensitive deep-equal multiset of
+those items.
+
+A matcher token asserts PRESENCE + SHAPE — never "ignore this field". A missing
+volatile field still fails (strict key sets). Extra actual keys also fail.
+
+Usage (pytest or any runner):
+
+    from importlib import import_module
+    spec_assert = import_module("tests.helpers.spec-assert").spec_assert  # if importable
+    # or load directly:
+    #   import importlib.util, pathlib
+    #   spec = importlib.util.spec_from_file_location("spec_assert", ".../spec-assert.py")
+    ...
+    spec_assert(actual, expected)          # raises AssertionError with a JSON path on mismatch
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from numbers import Number
+from pathlib import Path
+from typing import Any
+
+_UUID4 = re.compile(
+    r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
+)
+_ISO8601 = re.compile(
+    r"^\d{4}-\d{2}-\d{2}[Tt ]\d{2}:\d{2}:\d{2}(\.\d+)?([Zz]|[+-]\d{2}:?\d{2})?$"
+)
+_MATCHES_PREFIX = "<MATCHES:"
+
+
+class SpecMismatch(AssertionError):
+    """Raised when actual does not satisfy the expected fixture (with a JSON path)."""
+
+
+def load_fixture(path: str | Path) -> Any:
+    """Convenience loader for fixtures/<case-id>-*.json."""
+    return json.loads(Path(path).read_text(encoding="utf-8"))
+
+
+def _is_real_number(v: Any) -> bool:
+    # bool is a subclass of int in Python — exclude it explicitly.
+    return isinstance(v, Number) and not isinstance(v, bool)
+
+
+def _fail(path: str, msg: str) -> None:
+    raise SpecMismatch(f"spec-assert mismatch at {path}: {msg}")
+
+
+def _match_token(actual: Any, token: str, path: str) -> bool:
+    """Return True if `token` is a known matcher and `actual` satisfies it.
+    Raises on a known token that is NOT satisfied. Returns False if not a token."""
+    if token == "<UUID>":
+        if not (isinstance(actual, str) and _UUID4.match(actual)):
+            _fail(path, f"expected a UUID v4 string, got {actual!r}")
+        return True
+    if token == "<ISO8601>":
+        if not (isinstance(actual, str) and _ISO8601.match(actual)):
+            _fail(path, f"expected an ISO 8601 datetime string, got {actual!r}")
+        return True
+    if token == "<ANY_STRING>":
+        if not isinstance(actual, str):
+            _fail(path, f"expected any string, got {type(actual).__name__}")
+        return True
+    if token == "<ANY_NUMBER>":
+        if not _is_real_number(actual):
+            _fail(path, f"expected any finite number, got {actual!r}")
+        return True
+    if token == "<UNORDERED>":
+        if not isinstance(actual, list):
+            _fail(path, f"expected any array, got {type(actual).__name__}")
+        return True
+    if token.startswith(_MATCHES_PREFIX) and token.endswith(">"):
+        pattern = token[len(_MATCHES_PREFIX):-1]
+        if not (isinstance(actual, str) and re.search(pattern, actual)):
+            _fail(path, f"expected a string matching /{pattern}/, got {actual!r}")
+        return True
+    return False
+
+
+def _unordered_equal(actual: list, items: list, path: str) -> None:
+    if not isinstance(actual, list):
+        _fail(path, f"expected an array (unordered), got {type(actual).__name__}")
+    if len(actual) != len(items):
+        _fail(path, f"array length {len(actual)} != expected {len(items)} (unordered)")
+    remaining = list(actual)
+    for i, exp in enumerate(items):
+        found = -1
+        for j, act in enumerate(remaining):
+            try:
+                spec_assert(act, exp, f"{path}[unordered:{i}]")
+                found = j
+                break
+            except SpecMismatch:
+                continue
+        if found < 0:
+            _fail(path, f"no actual element matches expected item #{i}: {exp!r}")
+        remaining.pop(found)
+
+
+def spec_assert(actual: Any, expected: Any, path: str = "$") -> None:
+    """Assert `actual` deep-equals `expected`, honoring matcher tokens. Raises
+    SpecMismatch (an AssertionError) with a JSON path on the first divergence."""
+    # scalar matcher token
+    if isinstance(expected, str) and _match_token(actual, expected, path):
+        return
+
+    # {"<UNORDERED>": [...]} wrapper → order-insensitive item compare
+    if isinstance(expected, dict) and list(expected.keys()) == ["<UNORDERED>"]:
+        _unordered_equal(actual, expected["<UNORDERED>"], path)
+        return
+
+    if isinstance(expected, dict):
+        if not isinstance(actual, dict):
+            _fail(path, f"expected object, got {type(actual).__name__}")
+        exp_keys, act_keys = set(expected), set(actual)
+        if exp_keys != act_keys:
+            missing = exp_keys - act_keys
+            extra = act_keys - exp_keys
+            _fail(path, f"key mismatch (missing={sorted(missing)}, extra={sorted(extra)})")
+        for k in expected:
+            spec_assert(actual[k], expected[k], f"{path}.{k}")
+        return
+
+    if isinstance(expected, list):
+        if not isinstance(actual, list):
+            _fail(path, f"expected array, got {type(actual).__name__}")
+        if len(actual) != len(expected):
+            _fail(path, f"array length {len(actual)} != expected {len(expected)}")
+        for i, (a, e) in enumerate(zip(actual, expected)):
+            spec_assert(a, e, f"{path}[{i}]")
+        return
+
+    # scalar literal — strict equality (bool/int kept distinct)
+    if type(actual) is not type(expected) and not (
+        _is_real_number(actual) and _is_real_number(expected)
+    ):
+        _fail(path, f"type {type(actual).__name__} != expected {type(expected).__name__}")
+    if actual != expected:
+        _fail(path, f"{actual!r} != expected {expected!r}")

package/template/tests/helpers/spec-assert.ts

@@ -0,0 +1,158 @@
+/**
+ * spec-assert.ts — kit-versioned matcher-aware deep-equality comparator (v2.2).
+ *
+ * The generated `data`/`ui` boundary harness asserts an actual value against
+ * `fixtures/<case-id>-expected.json` via `specAssert(actual, expected)`. Deep
+ * equality, EXCEPT that volatile fields in the expected fixture carry a matcher
+ * token instead of a literal (§5.49). This is the ONLY comparator — no per-project
+ * assertion logic. One file per supported test language; this is the TS/JS one.
+ *
+ * Matcher tokens (string values in the expected fixture):
+ *
+ *   "<UUID>"            any UUID v4 string
+ *   "<ISO8601>"         any ISO 8601 datetime string
+ *   "<ANY_STRING>"      any string
+ *   "<ANY_NUMBER>"      any finite number
+ *   "<UNORDERED>"       any array (presence + shape only)
+ *   "<MATCHES:regex>"   any string matching the pattern (RegExp.test)
+ *
+ * Order-insensitive array WITH item checking: wrap the expected array as
+ *   { "<UNORDERED>": [item, item, ...] }
+ * and the actual must be an array that is an order-insensitive deep-equal multiset.
+ *
+ * A token asserts PRESENCE + SHAPE — never "ignore this field". Missing volatile
+ * fields fail (strict key sets); extra actual keys also fail.
+ *
+ *   import { specAssert, loadFixture } from "../helpers/spec-assert";
+ *   specAssert(actual, loadFixture("fixtures/PH2-ORDER-01-expected.json"));
+ */
+
+import { readFileSync } from "node:fs";
+
+const UUID4 =
+  /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$/;
+const ISO8601 =
+  /^\d{4}-\d{2}-\d{2}[Tt ]\d{2}:\d{2}:\d{2}(\.\d+)?([Zz]|[+-]\d{2}:?\d{2})?$/;
+const MATCHES_PREFIX = "<MATCHES:";
+
+export class SpecMismatch extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "SpecMismatch";
+  }
+}
+
+export function loadFixture<T = unknown>(path: string): T {
+  return JSON.parse(readFileSync(path, "utf-8")) as T;
+}
+
+function fail(path: string, msg: string): never {
+  throw new SpecMismatch(`spec-assert mismatch at ${path}: ${msg}`);
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function typeName(v: unknown): string {
+  if (v === null) return "null";
+  if (Array.isArray(v)) return "array";
+  return typeof v;
+}
+
+/** Returns true if `token` is a known matcher and `actual` satisfies it.
+ *  Throws on a known token that is NOT satisfied. Returns false if not a token. */
+function matchToken(actual: unknown, token: string, path: string): boolean {
+  switch (token) {
+    case "<UUID>":
+      if (!(typeof actual === "string" && UUID4.test(actual)))
+        fail(path, `expected a UUID v4 string, got ${JSON.stringify(actual)}`);
+      return true;
+    case "<ISO8601>":
+      if (!(typeof actual === "string" && ISO8601.test(actual)))
+        fail(path, `expected an ISO 8601 datetime string, got ${JSON.stringify(actual)}`);
+      return true;
+    case "<ANY_STRING>":
+      if (typeof actual !== "string")
+        fail(path, `expected any string, got ${typeName(actual)}`);
+      return true;
+    case "<ANY_NUMBER>":
+      if (typeof actual !== "number" || !Number.isFinite(actual))
+        fail(path, `expected any finite number, got ${JSON.stringify(actual)}`);
+      return true;
+    case "<UNORDERED>":
+      if (!Array.isArray(actual))
+        fail(path, `expected any array, got ${typeName(actual)}`);
+      return true;
+  }
+  if (token.startsWith(MATCHES_PREFIX) && token.endsWith(">")) {
+    const pattern = token.slice(MATCHES_PREFIX.length, -1);
+    if (!(typeof actual === "string" && new RegExp(pattern).test(actual)))
+      fail(path, `expected a string matching /${pattern}/, got ${JSON.stringify(actual)}`);
+    return true;
+  }
+  return false;
+}
+
+function unorderedEqual(actual: unknown, items: unknown[], path: string): void {
+  if (!Array.isArray(actual))
+    fail(path, `expected an array (unordered), got ${typeName(actual)}`);
+  if (actual.length !== items.length)
+    fail(path, `array length ${actual.length} != expected ${items.length} (unordered)`);
+  const remaining = [...actual];
+  items.forEach((exp, i) => {
+    let found = -1;
+    for (let j = 0; j < remaining.length; j++) {
+      try {
+        specAssert(remaining[j], exp, `${path}[unordered:${i}]`);
+        found = j;
+        break;
+      } catch (e) {
+        if (e instanceof SpecMismatch) continue;
+        throw e;
+      }
+    }
+    if (found < 0) fail(path, `no actual element matches expected item #${i}: ${JSON.stringify(exp)}`);
+    remaining.splice(found, 1);
+  });
+}
+
+/** Assert `actual` deep-equals `expected`, honoring matcher tokens. Throws
+ *  SpecMismatch with a JSON path on the first divergence. */
+export function specAssert(actual: unknown, expected: unknown, path = "$"): void {
+  // scalar matcher token
+  if (typeof expected === "string" && matchToken(actual, expected, path)) return;
+
+  // { "<UNORDERED>": [...] } wrapper → order-insensitive item compare
+  if (isPlainObject(expected)) {
+    const keys = Object.keys(expected);
+    if (keys.length === 1 && keys[0] === "<UNORDERED>") {
+      unorderedEqual(actual, expected["<UNORDERED>"] as unknown[], path);
+      return;
+    }
+    if (!isPlainObject(actual)) fail(path, `expected object, got ${typeName(actual)}`);
+    const expKeys = new Set(keys);
+    const actKeys = new Set(Object.keys(actual));
+    const missing = [...expKeys].filter((k) => !actKeys.has(k));
+    const extra = [...actKeys].filter((k) => !expKeys.has(k));
+    if (missing.length || extra.length)
+      fail(path, `key mismatch (missing=${JSON.stringify(missing)}, extra=${JSON.stringify(extra)})`);
+    for (const k of keys) specAssert(actual[k], expected[k], `${path}.${k}`);
+    return;
+  }
+
+  if (Array.isArray(expected)) {
+    if (!Array.isArray(actual)) fail(path, `expected array, got ${typeName(actual)}`);
+    if (actual.length !== expected.length)
+      fail(path, `array length ${actual.length} != expected ${expected.length}`);
+    for (let i = 0; i < expected.length; i++)
+      specAssert(actual[i], expected[i], `${path}[${i}]`);
+    return;
+  }
+
+  // scalar literal — strict equality (typeof must agree; NaN-safe)
+  if (typeName(actual) !== typeName(expected))
+    fail(path, `type ${typeName(actual)} != expected ${typeName(expected)}`);
+  if (actual !== expected && !(Number.isNaN(actual) && Number.isNaN(expected)))
+    fail(path, `${JSON.stringify(actual)} != expected ${JSON.stringify(expected)}`);
+}