hcifootprint 0.2.0

package/dist/testing/model/check.js

@@ -0,0 +1,89 @@
+/**
+ * checkGraph — the one-call health verdict.
+ *
+ * `lintGraph` returns a flat list of findings; `checkGraph` rolls them into a
+ * single answer a consumer can act on without iterating: a boolean `ok`, counts,
+ * findings grouped by the kind of drift a frontend dev recognises (control /
+ * page / flow), a per-skill feasibility list, and a ready-to-print `summary`.
+ * The whole health gate is one line:
+ *
+ *   const health = checkGraph(graph, { initialState });
+ *   if (!health.ok) { console.error(health.summary); process.exit(1); }
+ *
+ * It is STATIC and pure (same engine-free module graph as lintGraph — no
+ * Session, no footprint engine), so it runs in any CI step. It answers "does the
+ * graph hang together?" — NOT "do the real handlers match?" That behavioral
+ * question needs your handlers, so it lives in testApp (effectVerified). Keeping
+ * them apart is deliberate: a one-call auto-driver cannot know the mid-flow state
+ * a real flow sets up, so it would raise false alarms.
+ */
+import { lintGraph } from './lint.js';
+const TYPE_OF = {
+    'dangling-guard-key': 'control',
+    'unsatisfiable-guard': 'control',
+    'unreachable-page': 'page',
+    'dead-end-page': 'page',
+    'uncompletable-skill': 'flow',
+    'skill-step-order': 'flow',
+    'skill-step-cycle': 'flow',
+    'unconsumed-write': 'note',
+};
+const TYPE_LABEL = {
+    control: 'Control drift (buttons / inputs)',
+    page: 'Page drift',
+    flow: 'Flow drift (skills)',
+    note: 'Advisory notes',
+};
+/** One-call health check: lint + group by drift type + per-skill rollup + a printable summary. */
+export function checkGraph(graph, opts) {
+    const findings = lintGraph(graph, opts);
+    const byType = { control: [], page: [], flow: [], note: [] };
+    for (const finding of findings)
+        byType[TYPE_OF[finding.code] ?? 'note'].push(finding);
+    const errors = findings.filter((f) => f.severity === 'error').length;
+    const warnings = findings.filter((f) => f.severity === 'warning').length;
+    const skills = Object.values(graph.spec.skills).map((skill) => {
+        const blocking = findings.filter((f) => f.skill === skill.id && f.severity === 'error');
+        return {
+            id: skill.id,
+            feasible: blocking.length === 0,
+            blockedOn: [...new Set(blocking.flatMap((f) => f.keys ?? []))],
+        };
+    });
+    const unreachablePages = findings
+        .filter((f) => f.code === 'unreachable-page' && f.page)
+        .map((f) => f.page);
+    const ok = errors === 0;
+    return {
+        ok,
+        errors,
+        warnings,
+        findings,
+        byType,
+        skills,
+        unreachablePages,
+        summary: formatHealth(graph.id, findings, byType, errors, warnings),
+    };
+}
+const DRIFT_ORDER = ['control', 'page', 'flow'];
+function formatHealth(graphId, findings, byType, errors, warnings) {
+    const notes = byType.note.length;
+    const lines = [`Graph health — ${graphId}`];
+    if (errors === 0 && warnings === 0) {
+        lines.push(`  ✓ healthy — no drift  (${notes} advisory note${notes === 1 ? '' : 's'})`);
+        return lines.join('\n');
+    }
+    lines.push(`  ✗ ${errors} error${errors === 1 ? '' : 's'}, ${warnings} warning${warnings === 1 ? '' : 's'}`);
+    for (const type of DRIFT_ORDER) {
+        const group = byType[type].filter((f) => f.severity !== 'info');
+        if (group.length === 0)
+            continue;
+        lines.push('', `  ▸ ${TYPE_LABEL[type]}`);
+        for (const f of group) {
+            const where = f.affordance ?? f.skill ?? f.page ?? '';
+            lines.push(`     • [${f.severity.toUpperCase()}] ${where}`, `       ${f.message}`, `       → ${f.remedy}`);
+        }
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=check.js.map

package/dist/testing/model/check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.js","sourceRoot":"","sources":["../../../src/testing/model/check.ts"],"names":[],"mappings":"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"}

package/dist/testing/model/lint.d.ts

@@ -0,0 +1,54 @@
+import type { NavigationGraph } from '../../tree/types.js';
+export type LintSeverity = 'error' | 'warning' | 'info';
+export type LintCode = 'dangling-guard-key' | 'unsatisfiable-guard' | 'uncompletable-skill' | 'skill-step-order' | 'skill-step-cycle' | 'unreachable-page' | 'dead-end-page' | 'unconsumed-write';
+export interface LintFinding {
+    code: LintCode;
+    severity: LintSeverity;
+    /** Plain-language statement of what drifted or is wrong. */
+    message: string;
+    /** The two consumer remedies — surfaced, never dictated. */
+    remedy: string;
+    /** The action (affordance) the finding is about, when it is action-scoped. */
+    affordance?: string;
+    /** The skill the finding is about, when skill-scoped. */
+    skill?: string;
+    /** The page the finding is about, when page-scoped. */
+    page?: string;
+    /** The state key(s) implicated. */
+    keys?: string[];
+}
+export interface LintOptions {
+    /**
+     * The keys (or a sample object) the app guarantees before any action runs —
+     * the initial projected state. Supplying it lets the linter PROMOTE
+     * "gated on a key nothing produces" from a warning to an error: with the
+     * initial world known, an unproducible key is provably dead.
+     */
+    initialState?: string[] | Record<string, unknown>;
+    /**
+     * Keys supplied from OUTSIDE the graph's own writes (a server push, a store
+     * the app seeds, a parent app). Listed here they count as producible, so a
+     * guard over them is not flagged as dangling.
+     */
+    externalKeys?: string[];
+    /** Which page the app starts on (default: the first declared page). */
+    startPage?: string;
+}
+/**
+ * Report every stale-logic drift provable from the graph alone. Returns an
+ * empty array for a clean graph. Advisory by default; pass initialState +
+ * externalKeys to promote provably-dead findings to errors.
+ */
+export declare function lintGraph(graph: NavigationGraph, opts?: LintOptions): LintFinding[];
+/** A plain-text report of the findings, most severe first. Empty string when clean. */
+export declare function formatFindings(findings: LintFinding[]): string;
+/**
+ * Throw if the graph has stale-logic findings at or above `failOn` (default
+ * 'error'). The opt-in CI gate: `expectNoStaleLogic(graph, { initialState })`
+ * fails a commit that drifts the graph. Report-by-default stays the norm —
+ * call lintGraph directly to inspect without failing.
+ */
+export declare function expectNoStaleLogic(graph: NavigationGraph, opts?: LintOptions & {
+    failOn?: LintSeverity;
+}): void;
+//# sourceMappingURL=lint.d.ts.map

package/dist/testing/model/lint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint.d.ts","sourceRoot":"","sources":["../../../src/testing/model/lint.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAI3D,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAExD,MAAM,MAAM,QAAQ,GAChB,oBAAoB,GACpB,qBAAqB,GACrB,qBAAqB,GACrB,kBAAkB,GAClB,kBAAkB,GAClB,kBAAkB,GAClB,eAAe,GACf,kBAAkB,CAAC;AAEvB,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,YAAY,CAAC;IACvB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClD;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAmBD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,eAAe,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,WAAW,EAAE,CAsLnF;AAID,uFAAuF;AACvF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,MAAM,CAS9D;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,eAAe,EACtB,IAAI,CAAC,EAAE,WAAW,GAAG;IAAE,MAAM,CAAC,EAAE,YAAY,CAAA;CAAE,GAC7C,IAAI,CAWN"}

package/dist/testing/model/lint.js

@@ -0,0 +1,235 @@
+import { stepDependencies } from '../../graph/skill-deps.js';
+import { unsatisfiableKeys } from './satisfiable.js';
+const REMEDY_ACTION = 'Two ways to resolve, your call: update the graph so it matches the app (adjust or drop this guard/effect), ' +
+    'or treat it as a sign the app changed by mistake and revert that change. This check only surfaces the drift.';
+const REMEDY_PAGE = 'Two ways to resolve, your call: add an action that reaches/leaves this page (or remove the page if the app dropped it), ' +
+    'or confirm it is reached another way (a deep link the app syncs). This check only surfaces the drift.';
+const REMEDY_WRITE = "If the app genuinely uses this write (for its own UI, not for gating), leave it. If it's a leftover from removed " +
+    'logic, drop it from the graph. Either way, the choice is yours.';
+/** Quote a key list for a message: `a`, `b` and `c`. */
+function list(keys) {
+    const quoted = keys.map((k) => `“${k}”`);
+    if (quoted.length <= 1)
+        return quoted.join('');
+    return `${quoted.slice(0, -1).join(', ')} and ${quoted[quoted.length - 1]}`;
+}
+/**
+ * Report every stale-logic drift provable from the graph alone. Returns an
+ * empty array for a clean graph. Advisory by default; pass initialState +
+ * externalKeys to promote provably-dead findings to errors.
+ */
+export function lintGraph(graph, opts) {
+    const spec = graph.spec;
+    const affordances = spec.affordances;
+    const affList = Object.values(affordances);
+    const findings = [];
+    const initialKeys = Array.isArray(opts?.initialState)
+        ? opts.initialState
+        : opts?.initialState
+            ? Object.keys(opts.initialState)
+            : [];
+    const externalKeys = opts?.externalKeys ?? [];
+    // "Grounded" = the consumer told us the world outside the graph's own writes,
+    // so an unproducible key is provably dead (error), not merely unproven (warn).
+    // Declaring initialState AT ALL grounds it — even `{}` says "nothing is seeded".
+    const grounded = opts?.initialState !== undefined || externalKeys.length > 0;
+    const writeKeys = new Set();
+    for (const aff of affList)
+        for (const key of aff.effect?.writes ?? [])
+            writeKeys.add(key);
+    const producible = new Set([...writeKeys, ...initialKeys, ...externalKeys]);
+    // --- 1. dangling guard key: gated on state nothing produces ----------------
+    for (const aff of affList) {
+        const dangling = Object.keys(aff.guard ?? {}).filter((key) => !producible.has(key));
+        if (dangling.length > 0) {
+            findings.push({
+                code: 'dangling-guard-key',
+                severity: grounded ? 'error' : 'warning',
+                affordance: aff.id,
+                keys: dangling,
+                message: grounded
+                    ? `Action “${aff.id}” is gated on ${list(dangling)}, which nothing produces — no action writes it, and you did not list it in the initial or external state. This action can never become available.`
+                    : `Action “${aff.id}” is gated on ${list(dangling)}, which no action in the graph writes. If the app seeds it from initial or external state that is fine — declare initialState/externalKeys to confirm; otherwise the gate can never pass.`,
+                remedy: REMEDY_ACTION,
+            });
+        }
+    }
+    // --- 2. unsatisfiable guard: operators that can never be jointly true ------
+    for (const aff of affList) {
+        for (const { key, reason } of unsatisfiableKeys(aff.guard)) {
+            findings.push({
+                code: 'unsatisfiable-guard',
+                severity: 'error',
+                affordance: aff.id,
+                keys: [key],
+                message: `Action “${aff.id}” has a guard on “${key}” that can never be true (${reason}) — the control it maps to can never light up.`,
+                remedy: REMEDY_ACTION,
+            });
+        }
+    }
+    // --- 3/4/5. skill completability, step order, and cycles -------------------
+    for (const skill of Object.values(spec.skills)) {
+        const steps = skill.steps;
+        const producedSoFar = new Set([...initialKeys, ...externalKeys]);
+        for (let i = 0; i < steps.length; i++) {
+            const stepId = steps[i];
+            const aff = affordances[stepId];
+            if (!aff)
+                continue; // build() guarantees step ids resolve; defensive only
+            for (const guardKey of Object.keys(aff.guard ?? {})) {
+                if (producedSoFar.has(guardKey))
+                    continue;
+                const laterWriter = steps
+                    .slice(i + 1)
+                    .find((other) => (affordances[other]?.effect?.writes ?? []).includes(guardKey));
+                if (laterWriter) {
+                    findings.push({
+                        code: 'skill-step-order',
+                        severity: 'warning',
+                        skill: skill.id,
+                        affordance: stepId,
+                        keys: [guardKey],
+                        message: `In skill “${skill.id}”, step “${stepId}” needs “${guardKey}”, but the step that produces it (“${laterWriter}”) is listed after it. As ordered, this step is blocked when the skill reaches it.`,
+                        remedy: REMEDY_ACTION,
+                    });
+                }
+                else if (!producible.has(guardKey)) {
+                    findings.push({
+                        code: 'uncompletable-skill',
+                        severity: grounded ? 'error' : 'warning',
+                        skill: skill.id,
+                        affordance: stepId,
+                        keys: [guardKey],
+                        message: `Skill “${skill.id}” can never finish: step “${stepId}” is gated on “${guardKey}”, which nothing produces (no step writes it, and it is not in the initial/external state).`,
+                        remedy: REMEDY_ACTION,
+                    });
+                }
+            }
+            for (const written of aff.effect?.writes ?? [])
+                producedSoFar.add(written);
+        }
+        // Order-insensitive reachability from the grounded state: a step becomes
+        // runnable once all its guard keys are available, accumulating writes. A key
+        // supplied by initialState/externalKeys — or by an earlier step — breaks a
+        // structural "cycle" that is not actually a deadlock.
+        const runnable = new Set();
+        const reachable = new Set([...initialKeys, ...externalKeys]);
+        for (let changed = true; changed;) {
+            changed = false;
+            for (const stepId of steps) {
+                if (runnable.has(stepId))
+                    continue;
+                if (Object.keys(affordances[stepId]?.guard ?? {}).every((key) => reachable.has(key))) {
+                    runnable.add(stepId);
+                    for (const written of affordances[stepId]?.effect?.writes ?? [])
+                        reachable.add(written);
+                    changed = true;
+                }
+            }
+        }
+        // A true deadlock: two steps each need state the other writes AND neither is
+        // reachable from grounded state on its own.
+        for (const stepId of steps) {
+            if (runnable.has(stepId))
+                continue;
+            const deps = stepDependencies(affordances, steps, stepId);
+            for (const dep of deps) {
+                if (!runnable.has(dep.affordanceId) &&
+                    stepId < dep.affordanceId && // report each pair once
+                    stepDependencies(affordances, steps, dep.affordanceId).some((d) => d.affordanceId === stepId)) {
+                    findings.push({
+                        code: 'skill-step-cycle',
+                        severity: 'error',
+                        skill: skill.id,
+                        keys: [...new Set(dep.viaKeys)],
+                        message: `Skill “${skill.id}” has steps “${stepId}” and “${dep.affordanceId}” that each need state the other writes — a dependency cycle, so neither can go first.`,
+                        remedy: REMEDY_ACTION,
+                    });
+                }
+            }
+        }
+    }
+    // --- 6/7. page reachability ------------------------------------------------
+    const pageIds = Object.keys(spec.pages);
+    const startPage = opts?.startPage ?? pageIds[0];
+    const navTargets = new Set();
+    for (const aff of affList)
+        if (aff.effect?.navigatesTo)
+            navTargets.add(aff.effect.navigatesTo);
+    for (const pageId of pageIds) {
+        if (pageId !== startPage && !navTargets.has(pageId)) {
+            findings.push({
+                code: 'unreachable-page',
+                severity: 'warning',
+                page: pageId,
+                message: `Page “${pageId}” is not the start page and no action navigates to it — nothing in the graph can reach it.`,
+                remedy: REMEDY_PAGE,
+            });
+        }
+        if (pageIds.length > 1) {
+            const leaves = affList.some((aff) => aff.on.includes(pageId) && aff.effect?.navigatesTo && aff.effect.navigatesTo !== pageId);
+            if (!leaves) {
+                findings.push({
+                    code: 'dead-end-page',
+                    severity: 'info',
+                    page: pageId,
+                    message: `Page “${pageId}” has no action that navigates away — once here, the graph offers no way out.`,
+                    remedy: REMEDY_PAGE,
+                });
+            }
+        }
+    }
+    // --- 8. unconsumed write: a declared write no guard ever reads --------------
+    const readKeys = new Set();
+    for (const aff of affList)
+        for (const key of Object.keys(aff.guard ?? {}))
+            readKeys.add(key);
+    for (const skill of Object.values(spec.skills)) {
+        for (const key of Object.keys(skill.precondition ?? {}))
+            readKeys.add(key);
+    }
+    for (const aff of affList) {
+        const orphan = (aff.effect?.writes ?? []).filter((key) => !readKeys.has(key));
+        if (orphan.length > 0) {
+            findings.push({
+                code: 'unconsumed-write',
+                severity: 'info',
+                affordance: aff.id,
+                keys: orphan,
+                message: `Action “${aff.id}” declares it writes ${list(orphan)}, but no guard anywhere reads ${orphan.length > 1 ? 'them' : 'it'} — the write does nothing for planning (the app UI may still use it).`,
+                remedy: REMEDY_WRITE,
+            });
+        }
+    }
+    return findings;
+}
+const SEVERITY_RANK = { error: 3, warning: 2, info: 1 };
+/** A plain-text report of the findings, most severe first. Empty string when clean. */
+export function formatFindings(findings) {
+    if (findings.length === 0)
+        return '';
+    const ordered = [...findings].sort((a, b) => SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity]);
+    return ordered
+        .map((f) => {
+        const where = f.affordance ?? f.skill ?? f.page ?? '';
+        return `[${f.severity.toUpperCase()}] ${f.code}${where ? ` (${where})` : ''}\n  ${f.message}\n  → ${f.remedy}`;
+    })
+        .join('\n\n');
+}
+/**
+ * Throw if the graph has stale-logic findings at or above `failOn` (default
+ * 'error'). The opt-in CI gate: `expectNoStaleLogic(graph, { initialState })`
+ * fails a commit that drifts the graph. Report-by-default stays the norm —
+ * call lintGraph directly to inspect without failing.
+ */
+export function expectNoStaleLogic(graph, opts) {
+    const failOn = opts?.failOn ?? 'error';
+    const threshold = SEVERITY_RANK[failOn];
+    const findings = lintGraph(graph, opts);
+    const failing = findings.filter((f) => SEVERITY_RANK[f.severity] >= threshold);
+    if (failing.length > 0) {
+        throw new Error(`hcifootprint: the navigation graph has ${failing.length} stale-logic finding(s) at or above ${failOn}:\n\n` +
+            formatFindings(failing));
+    }
+}
+//# sourceMappingURL=lint.js.map

package/dist/testing/model/lint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint.js","sourceRoot":"","sources":["../../../src/testing/model/lint.ts"],"names":[],"mappings":"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"}

package/dist/testing/model/satisfiable.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Pure guard-satisfiability reasoning — "can this guard EVER be true?"
+ *
+ * The graph compiler (composeGuards) already rejects a key whose SAME operator
+ * is declared twice with different values. What it does NOT catch is a key
+ * whose DIFFERENT operators contradict each other — { gt: 5, lt: 3 },
+ * { eq: 'paid', in: ['draft', 'open'] }, { in: [] }. A control gated on such a
+ * guard can never light up, so the linter flags it.
+ *
+ * This is literal reasoning only (no state, no engine) and deliberately
+ * CONSERVATIVE: it returns a contradiction only when one is provable from the
+ * operators alone. Anything open-ended (ne / notIn / a lone range) is left
+ * unflagged — the linter never cries "dead" over something it cannot prove.
+ */
+import type { WhereFilter } from 'footprintjs';
+type Ops = Record<string, unknown>;
+/** A definite, provable contradiction among one key's operators, or null. */
+export declare function unsatisfiableReason(ops: Ops): string | null;
+/** Every key of a composed guard whose operators provably contradict. */
+export declare function unsatisfiableKeys(guard: WhereFilter | undefined): {
+    key: string;
+    reason: string;
+}[];
+export {};
+//# sourceMappingURL=satisfiable.d.ts.map

package/dist/testing/model/satisfiable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"satisfiable.d.ts","sourceRoot":"","sources":["../../../src/testing/model/satisfiable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,KAAK,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAuCnC,6EAA6E;AAC7E,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,IAAI,CAwC3D;AAED,yEAAyE;AACzE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,GAAG,SAAS,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAAE,CAUnG"}

package/dist/testing/model/satisfiable.js

@@ -0,0 +1,101 @@
+/** Whether a concrete candidate value satisfies EVERY operator on one key. */
+function satisfies(value, ops) {
+    for (const [op, target] of Object.entries(ops)) {
+        switch (op) {
+            case 'eq':
+                if (value !== target)
+                    return false;
+                break;
+            case 'ne':
+                if (value === target)
+                    return false;
+                break;
+            case 'in':
+                if (!Array.isArray(target) || !target.includes(value))
+                    return false;
+                break;
+            case 'notIn':
+                if (Array.isArray(target) && target.includes(value))
+                    return false;
+                break;
+            // Use the SAME raw comparison footprint's evaluator uses (`a > t`, JS
+            // coercion and all) — so "no candidate satisfies" is a proof against the
+            // real runtime, never a false positive from a stricter type rule.
+            case 'gt':
+                if (!(value > target))
+                    return false;
+                break;
+            case 'gte':
+                if (!(value >= target))
+                    return false;
+                break;
+            case 'lt':
+                if (!(value < target))
+                    return false;
+                break;
+            case 'lte':
+                if (!(value <= target))
+                    return false;
+                break;
+            // Unknown operators are the compiler's job to reject — treat as neutral.
+        }
+    }
+    return true;
+}
+/** A definite, provable contradiction among one key's operators, or null. */
+export function unsatisfiableReason(ops) {
+    // An empty allow-set can never match any value.
+    if (Array.isArray(ops['in']) && ops['in'].length === 0) {
+        return 'in: [] can never match any value';
+    }
+    // Numeric range inversion: lower bound above (or equal-and-exclusive to) upper.
+    const has = (k) => Object.hasOwn(ops, k);
+    const asNum = (v) => (typeof v === 'number' ? v : null);
+    const lo = has('gt')
+        ? { v: ops['gt'], inclusive: false }
+        : has('gte')
+            ? { v: ops['gte'], inclusive: true }
+            : null;
+    const hi = has('lt')
+        ? { v: ops['lt'], inclusive: false }
+        : has('lte')
+            ? { v: ops['lte'], inclusive: true }
+            : null;
+    if (lo && hi) {
+        const l = asNum(lo.v);
+        const h = asNum(hi.v);
+        if (l !== null && h !== null) {
+            if (l > h)
+                return `lower bound ${l} is above upper bound ${h}`;
+            if (l === h && !(lo.inclusive && hi.inclusive)) {
+                return `bounds around ${l} exclude every value`;
+            }
+        }
+    }
+    // When a finite candidate set exists (an exact eq, or an `in` allow-list),
+    // the answer is fully decidable: test each candidate against all operators.
+    const candidates = [];
+    if (has('eq'))
+        candidates.push(ops['eq']);
+    if (Array.isArray(ops['in']))
+        candidates.push(...ops['in']);
+    if (candidates.length > 0 && !candidates.some((value) => satisfies(value, ops))) {
+        return 'no value satisfies all of its operators at once';
+    }
+    return null;
+}
+/** Every key of a composed guard whose operators provably contradict. */
+export function unsatisfiableKeys(guard) {
+    if (!guard)
+        return [];
+    const out = [];
+    for (const [key, ops] of Object.entries(guard)) {
+        if (ops && typeof ops === 'object' && !Array.isArray(ops)) {
+            const reason = unsatisfiableReason(ops);
+            if (reason)
+                out.push({ key, reason });
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=satisfiable.js.map

package/dist/testing/model/satisfiable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"satisfiable.js","sourceRoot":"","sources":["../../../src/testing/model/satisfiable.ts"],"names":[],"mappings":"AAkBA,8EAA8E;AAC9E,SAAS,SAAS,CAAC,KAAc,EAAE,GAAQ;IACzC,KAAK,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/C,QAAQ,EAAE,EAAE,CAAC;YACX,KAAK,IAAI;gBACP,IAAI,KAAK,KAAK,MAAM;oBAAE,OAAO,KAAK,CAAC;gBACnC,MAAM;YACR,KAAK,IAAI;gBACP,IAAI,KAAK,KAAK,MAAM;oBAAE,OAAO,KAAK,CAAC;gBACnC,MAAM;YACR,KAAK,IAAI;gBACP,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;oBAAE,OAAO,KAAK,CAAC;gBACpE,MAAM;YACR,KAAK,OAAO;gBACV,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;oBAAE,OAAO,KAAK,CAAC;gBAClE,MAAM;YACR,sEAAsE;YACtE,yEAAyE;YACzE,kEAAkE;YAClE,KAAK,IAAI;gBACP,IAAI,CAAC,CAAE,KAAe,GAAI,MAAgB,CAAC;oBAAE,OAAO,KAAK,CAAC;gBAC1D,MAAM;YACR,KAAK,KAAK;gBACR,IAAI,CAAC,CAAE,KAAe,IAAK,MAAgB,CAAC;oBAAE,OAAO,KAAK,CAAC;gBAC3D,MAAM;YACR,KAAK,IAAI;gBACP,IAAI,CAAC,CAAE,KAAe,GAAI,MAAgB,CAAC;oBAAE,OAAO,KAAK,CAAC;gBAC1D,MAAM;YACR,KAAK,KAAK;gBACR,IAAI,CAAC,CAAE,KAAe,IAAK,MAAgB,CAAC;oBAAE,OAAO,KAAK,CAAC;gBAC3D,MAAM;YACR,yEAAyE;QAC3E,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,mBAAmB,CAAC,GAAQ;IAC1C,gDAAgD;IAChD,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,IAAK,GAAG,CAAC,IAAI,CAAe,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtE,OAAO,kCAAkC,CAAC;IAC5C,CAAC;IAED,gFAAgF;IAChF,MAAM,GAAG,GAAG,CAAC,CAAS,EAAW,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IAC1D,MAAM,KAAK,GAAG,CAAC,CAAU,EAAiB,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAChF,MAAM,EAAE,GAAG,GAAG,CAAC,IAAI,CAAC;QAClB,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE;QACpC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC;YACV,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE;YACpC,CAAC,CAAC,IAAI,CAAC;IACX,MAAM,EAAE,GAAG,GAAG,CAAC,IAAI,CAAC;QAClB,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE;QACpC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC;YACV,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE;YACpC,CAAC,CAAC,IAAI,CAAC;IACX,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC;QACb,MAAM,CAAC,GAAG,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QACtB,MAAM,CAAC,GAAG,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QACtB,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;YAC7B,IAAI,CAAC,GAAG,CAAC;gBAAE,OAAO,eAAe,CAAC,yBAAyB,CAAC,EAAE,CAAC;YAC/D,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,SAAS,IAAI,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC/C,OAAO,iBAAiB,CAAC,sBAAsB,CAAC;YAClD,CAAC;QACH,CAAC;IACH,CAAC;IAED,2EAA2E;IAC3E,4EAA4E;IAC5E,MAAM,UAAU,GAAc,EAAE,CAAC;IACjC,IAAI,GAAG,CAAC,IAAI,CAAC;QAAE,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;IAC1C,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAAE,UAAU,CAAC,IAAI,CAAC,GAAI,GAAG,CAAC,IAAI,CAAe,CAAC,CAAC;IAC3E,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,SAAS,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC;QAChF,OAAO,iDAAiD,CAAC;IAC3D,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,iBAAiB,CAAC,KAA8B;IAC9D,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC;IACtB,MAAM,GAAG,GAAsC,EAAE,CAAC;IAClD,KAAK,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/C,IAAI,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YAC1D,MAAM,MAAM,GAAG,mBAAmB,CAAC,GAAU,CAAC,CAAC;YAC/C,IAAI,MAAM;gBAAE,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}