@tacuchi/agent-workflow-cli 20.26.0 → 21.1.0

package/dist/domain/design/artifact.js

@@ -0,0 +1,750 @@
+import { PLACEHOLDER, bodyCriteria, bodyDigests, bodyReferences, checkHeadings, conditionalKeys, parseBody, } from "./artifact-body.js";
+import { CANONICAL_SCHEMAS } from "./capability.js";
+import { ARTIFACT_PREFIX, anchorIsTheProblem, isDigest, isPackageId, isRevision, parseArtifactId, parseArtifactRef, } from "./identity.js";
+import { Reader, eachRecord, isNonEmptyString, isRecord, } from "./validation.js";
+import { parseYamlSubset } from "./yaml-subset.js";
+/**
+ * Flow and Screen Specifications v1 — the two documents that carry the design
+ * semantics of a package.
+ *
+ * The contract's whole point: **identity, graph, states, dependencies and
+ * traceability resolve from the frontmatter alone**. Nothing normative may
+ * require reading a sentence. The body still has a contract (fixed headings,
+ * real text), but it is checked AGAINST the frontmatter, never trusted instead
+ * of it — and where the body cites an artifact, it must cite one the
+ * frontmatter already declares.
+ */
+export const FLOW_SCHEMA_ID = CANONICAL_SCHEMAS.flow;
+export const SCREEN_SCHEMA_ID = CANONICAL_SCHEMAS.screen;
+export const SCHEMA_ID = {
+    flow: FLOW_SCHEMA_ID,
+    screen: SCREEN_SCHEMA_ID,
+};
+export const CRITERION_CLASSIFICATIONS = [
+    "visual",
+    "interaction",
+    "not_visual",
+];
+const COMMON_KEYS = [
+    "schema",
+    "id",
+    "revision",
+    "maturity",
+    "supersedes",
+    "purpose",
+    "platform",
+    "trace",
+    "unknowns",
+    "not_applicable",
+    "external",
+];
+export const FLOW_ALLOWED_KEYS = {
+    "": [...COMMON_KEYS, "actors", "entry", "nodes", "edges", "dependencies"],
+    "edges[]": ["from", "trigger", "action", "condition", "to"],
+    "trace[]": ["criterion", "source"],
+    "unknowns[]": ["question", "blocking"],
+    "external[]": ["provider", "revision", "digest"],
+};
+export const SCREEN_ALLOWED_KEYS = {
+    "": [...COMMON_KEYS, "title", "default_state", "states", "flow_refs", "dependencies"],
+    "states[]": ["anchor", "purpose"],
+    "trace[]": ["criterion", "source", "classification", "states", "renditions", "reason"],
+    "unknowns[]": ["question", "blocking"],
+    "external[]": ["provider", "revision", "digest"],
+    dependencies: ["rules", "tokens", "assets"],
+};
+export const ALLOWED_KEYS = {
+    flow: FLOW_ALLOWED_KEYS,
+    screen: SCREEN_ALLOWED_KEYS,
+};
+const ANCHOR_RE = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+/**
+ * A free-text frontmatter field, checked against the SAME placeholder list the
+ * body uses. AC-SEM-08 forbids `N/A` in identity, purpose, platform, base state,
+ * references and traceability — and the only sanctioned way to say "does not
+ * apply" is `not_applicable.<section>`, which covers sections, never fields.
+ */
+function checkText(r, artifact, field, value, action) {
+    if (!isNonEmptyString(value)) {
+        r.invalid(artifact, `'${field}' es obligatorio y no admite vacío`, action);
+        return false;
+    }
+    if (PLACEHOLDER.test(value.trim())) {
+        r.fail("DESIGN_FIELD_PLACEHOLDER", artifact, `'${field}' dice solo '${value.trim()}'`, "un campo del frontmatter no se declara no aplicable: escribí su valor");
+        return false;
+    }
+    return true;
+}
+const DELIMITER = "---";
+/** Split `---`-fenced frontmatter from the Markdown body. */
+export function splitDesignDocument(text) {
+    const lines = text.split(/\r?\n/);
+    if ((lines[0] ?? "").trim() !== DELIMITER)
+        return null;
+    for (let i = 1; i < lines.length; i++) {
+        if ((lines[i] ?? "").trim() !== DELIMITER)
+            continue;
+        return {
+            frontmatter: lines.slice(1, i).join("\n"),
+            body: lines.slice(i + 1).join("\n"),
+            bodyLine: i + 2,
+        };
+    }
+    return null;
+}
+export function validateDesignArtifact(text, kind, artifact) {
+    const r = new Reader(ALLOWED_KEYS[kind]);
+    const split = splitDesignDocument(text);
+    if (split === null) {
+        r.fail("DESIGN_FRONTMATTER_MISSING", artifact, "el documento no abre y cierra un frontmatter '---'", `empezá el archivo con '---', el frontmatter ${SCHEMA_ID[kind]} y otro '---'`);
+        return { ok: false, value: null, failures: r.failures, touched: r.touched };
+    }
+    const parsed = parseYamlSubset(split.frontmatter);
+    if (!parsed.ok) {
+        r.fail("DESIGN_FRONTMATTER_UNREADABLE", artifact, `el frontmatter no es legible (línea ${parsed.line + 1}): ${parsed.why}`, "el contrato admite un subconjunto de YAML: mappings, secuencias, flow style y escalares");
+        return { ok: false, value: null, failures: r.failures, touched: r.touched };
+    }
+    const front = parsed.value;
+    // The version gate runs first and alone: reading fields off a frontmatter
+    // whose shape we do not know would report a pile of derived nonsense.
+    const schema = r.read(front, "schema");
+    if (schema !== SCHEMA_ID[kind]) {
+        r.fail("DESIGN_SCHEMA_UNKNOWN", artifact, `versión de formato no soportada: ${JSON.stringify(schema)}`, `este Workline entiende ${SCHEMA_ID[kind]}`);
+        return { ok: false, value: null, failures: r.failures, touched: r.touched };
+    }
+    r.closed(front, "", artifact);
+    const common = readCommon(r, front, kind, artifact);
+    const specific = kind === "flow" ? readFlow(r, front, artifact) : readScreen(r, front, artifact);
+    const body = parseBody(split.body, split.bodyLine);
+    checkHeadings(r, body, kind, artifact);
+    checkNotApplicable(r, common.not_applicable, kind, artifact);
+    // The classification matrix names states, so it can only be checked once the
+    // states have been read. Coherence only — whether the matrix is COMPLETE is
+    // the `handoff` gate's question, and an `outline` is allowed to leave it open.
+    if (kind === "screen") {
+        checkTraceCoherence(r, artifact, common.trace, specific.states);
+    }
+    checkBodyAgainstFrontmatter(r, body, kind, artifact, common, specific);
+    if (r.failures.length > 0) {
+        return { ok: false, value: null, failures: r.failures, touched: r.touched };
+    }
+    return {
+        ok: true,
+        value: { kind, ...common, ...specific },
+        failures: [],
+        touched: r.touched,
+    };
+}
+function readCommon(r, front, kind, artifact) {
+    const rawId = r.read(front, "id");
+    const parsedId = parseArtifactId(rawId);
+    const expectedPrefix = ARTIFACT_PREFIX[kind];
+    if (parsedId === null || !parsedId.artifact.startsWith(`${expectedPrefix}-`)) {
+        r.invalid(artifact, `'id' debe ser DES-NNN/${expectedPrefix}-NNN y llegó ${JSON.stringify(rawId)}`, `escribí la identidad completa, por ejemplo DES-001/${expectedPrefix}-001`);
+    }
+    const revision = r.read(front, "revision");
+    if (!isRevision(revision)) {
+        r.invalid(artifact, "'revision' debe ser un entero >= 1", "las revisiones son lógicas y empiezan en 1");
+    }
+    const maturity = r.read(front, "maturity");
+    if (maturity !== "outline" && maturity !== "handoff") {
+        r.invalid(artifact, `'maturity' debe ser 'outline' o 'handoff' y llegó ${JSON.stringify(maturity)}`, "declará la madurez de esta revisión");
+    }
+    const supersedes = r.read(front, "supersedes");
+    checkSupersedes(r, supersedes, artifact, rawId, revision);
+    const purpose = r.read(front, "purpose");
+    checkText(r, artifact, "purpose", purpose, "escribí para qué existe este artefacto");
+    const platform = r.read(front, "platform");
+    checkText(r, artifact, "platform", platform, "declará la plataforma, por ejemplo web");
+    return {
+        schema: SCHEMA_ID[kind],
+        id: typeof rawId === "string" ? rawId : "",
+        revision: isRevision(revision) ? revision : 0,
+        maturity: maturity === "handoff" ? "handoff" : "outline",
+        supersedes: typeof supersedes === "string" ? supersedes : null,
+        purpose: typeof purpose === "string" ? purpose : "",
+        platform: typeof platform === "string" ? platform : "",
+        trace: readTrace(r, front, artifact, kind),
+        unknowns: readUnknowns(r, front, artifact),
+        not_applicable: readNotApplicable(r, front, artifact),
+        external: readExternal(r, front, artifact),
+    };
+}
+/**
+ * The design systems this revision borrows from (AC-PKG-09).
+ *
+ * Pinning is the whole point: a provider without a revision and a digest is a
+ * promise that can change underneath the artifact, which is the situation
+ * `outline` exists to describe.
+ */
+function readExternal(r, front, artifact) {
+    const raw = r.read(front, "external");
+    if (raw === undefined) {
+        r.invalid(artifact, "'external' es obligatorio", "usá [] si no dependés de otro design system");
+        return [];
+    }
+    const out = [];
+    for (const entry of eachRecord(r, front, "external", artifact)) {
+        const provider = r.read(entry, "external[].provider");
+        const revision = r.read(entry, "external[].revision");
+        const digest = r.read(entry, "external[].digest");
+        if (!isPackageId(provider) || !isRevision(revision) || !isDigest(digest)) {
+            r.invalid(artifact, "cada 'external' fija provider DES-NNN, revision entera y digest sha256", "sin proveedor, revisión y digest la dependencia no está fijada");
+            continue;
+        }
+        out.push({ provider: provider, revision, digest: digest });
+    }
+    return out;
+}
+/**
+ * A revision may only supersede an EARLIER revision of ITSELF. Pointing at
+ * another artifact would make `supersedes` a second, weaker way of saying
+ * "replaces", and currentness is derived from it.
+ */
+function checkSupersedes(r, supersedes, artifact, rawId, revision) {
+    if (supersedes === undefined) {
+        r.invalid(artifact, "falta 'supersedes': el contrato la declara obligatoria", "poné 'supersedes: null' si esta revisión no reemplaza a ninguna");
+        return;
+    }
+    if (supersedes === null)
+        return;
+    if (anchorIsTheProblem(supersedes)) {
+        r.invalid(artifact, `'supersedes' lleva un anchor de estado y supersede una REVISIÓN entera`, "quitá el anchor: se supersede la revisión, no uno de sus estados");
+        return;
+    }
+    const ref = parseArtifactRef(supersedes);
+    if (ref === null) {
+        r.invalid(artifact, `'supersedes' debe ser null o DES-NNN/XXX-NNN@rN y llegó ${JSON.stringify(supersedes)}`, "referenciá la revisión anterior completa, o null");
+        return;
+    }
+    if (ref.state !== undefined) {
+        r.invalid(artifact, `'supersedes' lleva un anchor de estado (#${ref.state}) y supersede una REVISIÓN entera`, "quitá el anchor: se supersede la revisión, no uno de sus estados");
+        return;
+    }
+    const own = parseArtifactId(rawId);
+    if (own !== null && (ref.package !== own.package || ref.artifact !== own.artifact)) {
+        r.fail("DESIGN_RELATION_BROKEN", artifact, `'supersedes' apunta a ${ref.package}/${ref.artifact} y este artefacto es ${rawId}`, "una revisión solo supersede a una revisión anterior de sí misma");
+        return;
+    }
+    if (isRevision(revision) && ref.revision >= revision) {
+        r.fail("DESIGN_RELATION_BROKEN", artifact, `'supersedes' apunta a r${ref.revision} y esta revisión es r${revision}`, "solo se supersede una revisión anterior");
+    }
+}
+function readTrace(r, front, artifact, kind) {
+    const out = [];
+    for (const entry of eachRecord(r, front, "trace", artifact, " de entradas de trazabilidad")) {
+        const criterion = r.read(entry, "trace[].criterion");
+        const source = r.read(entry, "trace[].source");
+        if (!checkText(r, artifact, "trace[].criterion", criterion, "citá el acceptance criterion, por ejemplo S013/AC-SEM-11")) {
+            continue;
+        }
+        if (source !== null &&
+            source !== undefined &&
+            !checkText(r, artifact, `trace[${criterion}].source`, source, "poné el path del documento que define el criterio, o null")) {
+            continue;
+        }
+        const base = { criterion, source: typeof source === "string" ? source : null };
+        // Only a screen declares the evidence half, so only a screen's validator may
+        // READ those properties: the drift guard proves a validator reads nothing the
+        // published schema does not declare, and `ui-flow/v1` does not declare them.
+        out.push(kind === "flow" ? base : { ...base, ...readEvidence(r, entry, artifact, criterion) });
+    }
+    return out;
+}
+/** The evidence half of a screen's trace entry. Shape only — completeness is the gate's. */
+function readEvidence(r, entry, artifact, criterion) {
+    const empty = { classification: null, states: [], renditions: [], reason: null };
+    const raw = r.read(entry, "trace[].classification");
+    const states = r.read(entry, "trace[].states");
+    const renditions = r.read(entry, "trace[].renditions");
+    const reason = r.read(entry, "trace[].reason");
+    const classification = raw === undefined || raw === null
+        ? null
+        : CRITERION_CLASSIFICATIONS.includes(raw)
+            ? raw
+            : undefined;
+    if (classification === undefined) {
+        r.invalid(artifact, `trace['${criterion}']: 'classification' debe ser ${CRITERION_CLASSIFICATIONS.join(", ")} o null y llegó ${JSON.stringify(raw)}`, "clasificá cómo se demuestra el criterio, o dejalo en null hasta hacerlo");
+        return empty;
+    }
+    const anchors = readAnchorList(r, artifact, `trace['${criterion}'].states`, states);
+    const shown = readRenditionList(r, artifact, `trace['${criterion}'].renditions`, renditions);
+    const why = reason === null || reason === undefined
+        ? null
+        : checkText(r, artifact, `trace['${criterion}'].reason`, reason, "escribí por qué el criterio no tiene nada que mirar, o poné null")
+            ? reason
+            : null;
+    const contradiction = contradictionIn(classification, anchors.length + shown.length, why);
+    if (contradiction !== null) {
+        r.invalid(artifact, `trace['${criterion}']: ${contradiction.what}`, contradiction.action);
+        return empty;
+    }
+    return { classification, states: anchors, renditions: shown, reason: why };
+}
+/**
+ * The three ways the evidence half can contradict its own classification.
+ *
+ * A contradiction is malformed whatever the maturity: `not_visual` MEANS there is
+ * nothing to look at, so enumerating a picture of it is not an incomplete claim to
+ * be finished later — it is two claims that cannot both hold. Incompleteness is a
+ * different verdict and belongs to the `handoff` gate.
+ */
+function contradictionIn(classification, enumerated, reason) {
+    if (classification === null) {
+        if (enumerated === 0 && reason === null)
+            return null;
+        return {
+            what: "declara evidencia sin clasificar el criterio",
+            action: "poné 'classification' en visual, interaction o not_visual",
+        };
+    }
+    if (classification === "not_visual") {
+        if (enumerated === 0)
+            return null;
+        return {
+            what: "está clasificado 'not_visual' y enumera estados o renditions",
+            action: "si hay algo que mirar, clasificalo 'visual' o 'interaction'",
+        };
+    }
+    if (reason === null)
+        return null;
+    return {
+        what: `'reason' explica por qué NO hay nada que mirar y este criterio es '${classification}'`,
+        action: "quitá 'reason', o reclasificá el criterio como 'not_visual'",
+    };
+}
+function readAnchorList(r, artifact, path, raw) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw)) {
+        r.invalid(artifact, `'${path}' debe ser un array de anchors`, `escribí '${path}': []`);
+        return [];
+    }
+    const out = [];
+    for (const value of raw) {
+        if (typeof value !== "string" || !ANCHOR_RE.test(value)) {
+            r.invalid(artifact, `'${path}' trae un anchor inválido: ${JSON.stringify(value)}`, "nombrá el anchor de un estado declarado, sin '#'");
+            continue;
+        }
+        if (out.includes(value)) {
+            r.fail("DESIGN_ID_DUPLICATE", artifact, `'${path}' repite '${value}'`, "dejá una sola aparición");
+            continue;
+        }
+        out.push(value);
+    }
+    return out;
+}
+function readRenditionList(r, artifact, path, raw) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw)) {
+        r.invalid(artifact, `'${path}' debe ser un array de referencias`, `escribí '${path}': []`);
+        return [];
+    }
+    const out = [];
+    for (const value of raw) {
+        const ref = parseArtifactRef(value);
+        if (ref === null || !ref.artifact.startsWith("VIS-")) {
+            r.invalid(artifact, `'${path}' solo admite renditions DES-NNN/VIS-NNN@rN y llegó ${JSON.stringify(value)}`, "referenciá la rendition exacta que muestra el criterio");
+            continue;
+        }
+        if (out.includes(value)) {
+            r.fail("DESIGN_ID_DUPLICATE", artifact, `'${path}' repite ${value}`, "dejá una sola aparición");
+            continue;
+        }
+        out.push(value);
+    }
+    return out;
+}
+/**
+ * The matrix names states of THIS screen. A criterion demonstrated on an anchor
+ * the revision does not declare points at nothing, and a gate that accepted it
+ * would report coverage of a state nobody can open.
+ */
+function checkTraceCoherence(r, artifact, trace, states) {
+    if (states.length === 0)
+        return; // ya reportado por readScreen
+    const anchors = new Set(states.map((s) => s.anchor));
+    for (const entry of trace) {
+        for (const anchor of entry.states ?? []) {
+            if (anchors.has(anchor))
+                continue;
+            r.fail("DESIGN_RELATION_BROKEN", artifact, `trace['${entry.criterion}'] se demuestra en '${anchor}' y no está entre los states declarados (${[...anchors].join(", ")})`, "declaralo en 'states' o nombrá uno existente");
+        }
+    }
+}
+function readUnknowns(r, front, artifact) {
+    const out = [];
+    for (const entry of eachRecord(r, front, "unknowns", artifact, " (vacío si no quedan incógnitas)")) {
+        const question = r.read(entry, "unknowns[].question");
+        const blocking = r.read(entry, "unknowns[].blocking");
+        if (!isNonEmptyString(question)) {
+            r.invalid(artifact, "cada entrada de 'unknowns' necesita 'question' no vacía", "escribí la incógnita como pregunta");
+            continue;
+        }
+        if (typeof blocking !== "boolean") {
+            r.invalid(artifact, `unknowns['${question}']: 'blocking' debe ser true o false`, "declará si resolverla puede cambiar comportamiento o aceptación");
+            continue;
+        }
+        out.push({ question, blocking });
+    }
+    return out;
+}
+function readNotApplicable(r, front, artifact) {
+    const node = r.read(front, "not_applicable");
+    if (node === undefined) {
+        r.invalid(artifact, "falta 'not_applicable': el contrato la declara obligatoria", "escribí 'not_applicable: {}' si todo aplica");
+        return {};
+    }
+    if (node === null)
+        return {};
+    if (!isRecord(node)) {
+        r.invalid(artifact, "'not_applicable' debe ser un mapping de sección a razón", "escribí 'not_applicable: {}' si todo aplica");
+        return {};
+    }
+    const out = {};
+    for (const [key, reason] of Object.entries(node)) {
+        out[key] = typeof reason === "string" ? reason : "";
+    }
+    return out;
+}
+/**
+ * Non-applicability is a claim with a price: it names a CONDITIONAL section and
+ * it states why. An essential section cannot be waived at all, and a reason left
+ * empty is the same refusal to answer that "N/A" was.
+ */
+function checkNotApplicable(r, declared, kind, artifact) {
+    const allowed = conditionalKeys(kind);
+    for (const [key, reason] of Object.entries(declared)) {
+        if (!allowed.includes(key)) {
+            r.fail("DESIGN_NOT_APPLICABLE_FORBIDDEN", artifact, `'not_applicable.${key}' no es una sección condicional de ${kind} v1`, `solo estas admiten no-aplicabilidad: ${allowed.join(", ")}`);
+            continue;
+        }
+        if (reason.trim().length === 0 || PLACEHOLDER.test(reason.trim())) {
+            r.fail("DESIGN_NOT_APPLICABLE_NO_REASON", artifact, `'not_applicable.${key}' no explica por qué no aplica`, "escribí la razón; ni vacía ni 'N/A' satisfacen el contrato");
+        }
+    }
+}
+function readFlow(r, front, artifact) {
+    const actors = readStringList(r, front, "actors", artifact, "un actor");
+    const nodes = readRefList(r, front, "nodes", artifact, "screen", true);
+    const dependencies = readRefList(r, front, "dependencies", artifact, null);
+    const entry = r.read(front, "entry");
+    const entryRef = parseArtifactRef(entry);
+    if (entryRef === null) {
+        r.invalid(artifact, `'entry' debe ser el estado de pantalla por el que arranca el flow y llegó ${JSON.stringify(entry)}`, "escribí DES-NNN/SCR-NNN@rN#estado");
+    }
+    else if (entryRef.state === undefined) {
+        r.invalid(artifact, "'entry' debe apuntar a un ESTADO de pantalla", "agregá el anchor, por ejemplo @r2#default");
+    }
+    else if (typeof entry === "string" && nodes.length > 0 && !nodes.includes(entry)) {
+        r.fail("DESIGN_RELATION_BROKEN", artifact, `'entry' (${entry}) no está en 'nodes'`, "el punto de entrada es uno de los nodos del grafo: agregalo a 'nodes'");
+    }
+    const edges = readEdges(r, front, artifact, nodes);
+    // With no nodes, every containment check above is vacuous — an edge could point
+    // anywhere and nobody would say so. One diagnostic for the root cause beats a
+    // pile of derived ones, and beats silence.
+    if (nodes.length === 0 && (edges.length > 0 || typeof entry === "string")) {
+        r.fail("DESIGN_RELATION_BROKEN", artifact, "'nodes' está vacío y el flow declara entrada o transiciones", "enumerá en 'nodes' los estados de pantalla que el recorrido visita");
+    }
+    return { actors, entry: typeof entry === "string" ? entry : "", nodes, edges, dependencies };
+}
+function readEdges(r, front, artifact, nodes) {
+    const out = [];
+    for (const entry of eachRecord(r, front, "edges", artifact, " de transiciones")) {
+        const edge = readEdge(r, entry, artifact, nodes);
+        if (edge !== null)
+            out.push(edge);
+    }
+    return out;
+}
+function readEdge(r, entry, artifact, nodes) {
+    const from = r.read(entry, "edges[].from");
+    const trigger = r.read(entry, "edges[].trigger");
+    const action = r.read(entry, "edges[].action");
+    const condition = r.read(entry, "edges[].condition");
+    const to = r.read(entry, "edges[].to");
+    if (!isNonEmptyString(trigger)) {
+        r.invalid(artifact, "cada arista necesita 'trigger' no vacío", "declará qué dispara la transición");
+        return null;
+    }
+    let ok = true;
+    for (const [side, value] of [
+        ["from", from],
+        ["to", to],
+    ]) {
+        if (!checkEndpoint(r, artifact, trigger, side, value, nodes))
+            ok = false;
+    }
+    for (const [label, value] of [
+        ["action", action],
+        ["condition", condition],
+    ]) {
+        if (value === null || value === undefined || isNonEmptyString(value))
+            continue;
+        r.invalid(artifact, `edges['${trigger}']: '${label}' debe ser texto o null`, `escribí ${label} o poné null`);
+        ok = false;
+    }
+    if (!ok)
+        return null;
+    return {
+        from: from,
+        trigger,
+        action: typeof action === "string" ? action : null,
+        condition: typeof condition === "string" ? condition : null,
+        to: to,
+    };
+}
+/**
+ * The graph has to close on itself: an endpoint nobody declared as a node is a
+ * transition into a screen the flow never says it visits.
+ */
+function checkEndpoint(r, artifact, trigger, side, value, nodes) {
+    const ref = parseArtifactRef(value);
+    if (ref === null) {
+        r.invalid(artifact, `edges['${trigger}']: '${side}' debe ser DES-NNN/SCR-NNN@rN#estado y llegó ${JSON.stringify(value)}`, "referenciá el estado de pantalla completo");
+        return false;
+    }
+    // Checked BEFORE membership: without it the author is told to add the
+    // unanchored reference to `nodes`, which is the wrong fix for the real problem.
+    if (ref.state === undefined) {
+        r.invalid(artifact, `edges['${trigger}']: '${side}' (${String(value)}) apunta a una pantalla y una arista conecta ESTADOS`, "agregá el anchor del estado, por ejemplo @r2#default");
+        return false;
+    }
+    if (nodes.length > 0 && !nodes.includes(value)) {
+        r.fail("DESIGN_RELATION_BROKEN", artifact, `edges['${trigger}']: '${side}' (${String(value)}) no está en 'nodes'`, "agregá ese estado a 'nodes' o corregí la arista");
+        return false;
+    }
+    return true;
+}
+function readScreen(r, front, artifact) {
+    const title = r.read(front, "title");
+    checkText(r, artifact, "title", title, "poné el título profesional de la pantalla");
+    const states = readStates(r, front, artifact);
+    const anchors = states.map((s) => s.anchor);
+    const defaultState = r.read(front, "default_state");
+    if (!isNonEmptyString(defaultState)) {
+        r.invalid(artifact, "'default_state' es obligatorio", "nombrá el anchor del estado base");
+    }
+    else if (states.length > 0 && !anchors.includes(defaultState)) {
+        r.fail("DESIGN_RELATION_BROKEN", artifact, `'default_state' es '${defaultState}' y no está entre los states declarados (${anchors.join(", ")})`, "declaralo en 'states' o apuntá a uno existente");
+    }
+    if (states.length === 0) {
+        r.invalid(artifact, "'states' está vacío: una screen sin estados no tiene nada direccionable", "declará al menos el estado base con su anchor y su propósito");
+    }
+    const flowRefs = readRefList(r, front, "flow_refs", artifact, "flow");
+    return {
+        title: typeof title === "string" ? title : "",
+        default_state: typeof defaultState === "string" ? defaultState : "",
+        states,
+        flow_refs: flowRefs,
+        dependencies: readScreenDependencies(r, front, artifact),
+    };
+}
+/**
+ * Screen states. The anchor is what every flow, task and rendition addresses
+ * (`DES-001/SCR-002@r2#empty`), so it has to be unique WITHIN THIS REVISION —
+ * two states answering to one anchor make every reference to it ambiguous.
+ */
+function readStates(r, front, artifact) {
+    const out = [];
+    const seen = new Set();
+    for (const entry of eachRecord(r, front, "states", artifact, " de estados")) {
+        const anchor = r.read(entry, "states[].anchor");
+        const purpose = r.read(entry, "states[].purpose");
+        if (typeof anchor !== "string" || !ANCHOR_RE.test(anchor)) {
+            r.invalid(artifact, `anchor de estado inválido: ${JSON.stringify(anchor)}`, "usá letras, números, guion y guion bajo, empezando por alfanumérico (default, empty, permission-denied)");
+            continue;
+        }
+        if (seen.has(anchor)) {
+            r.fail("DESIGN_ID_DUPLICATE", artifact, `el anchor de estado '${anchor}' está declarado dos veces`, "un anchor identifica un solo estado dentro de la revisión: renombrá el repetido");
+            continue;
+        }
+        seen.add(anchor);
+        if (!checkText(r, artifact, `states['${anchor}'].purpose`, purpose, "escribí qué muestra ese estado")) {
+            continue;
+        }
+        out.push({ anchor, purpose });
+    }
+    return out;
+}
+function readScreenDependencies(r, front, artifact) {
+    const node = r.read(front, "dependencies");
+    const empty = { rules: [], tokens: [], assets: [] };
+    if (!isRecord(node)) {
+        r.invalid(artifact, "'dependencies' debe ser un objeto con 'rules', 'tokens' y 'assets'", "escribí las tres claves, con array vacío donde no haya dependencias");
+        return empty;
+    }
+    r.closed(node, "dependencies", artifact);
+    return {
+        rules: readRefList(r, node, "dependencies.rules", artifact, "rule"),
+        tokens: readRefList(r, node, "dependencies.tokens", artifact, "token"),
+        assets: readDigestList(r, node, "dependencies.assets", artifact),
+    };
+}
+/** A list of exact artifact references, optionally constrained to one kind. */
+function readRefList(r, node, path, artifact, kind, requireAnchor = false) {
+    const raw = r.read(node, path);
+    if (!Array.isArray(raw)) {
+        r.invalid(artifact, `'${path}' debe ser un array de referencias`, `escribí '${path}': []`);
+        return [];
+    }
+    const out = [];
+    for (const value of raw) {
+        if (!checkRef(r, artifact, path, value, kind, requireAnchor))
+            continue;
+        if (out.includes(value)) {
+            r.fail("DESIGN_ID_DUPLICATE", artifact, `'${path}' repite ${String(value)}`, "dejá una sola aparición");
+            continue;
+        }
+        out.push(value);
+    }
+    return out;
+}
+/** One reference: well-formed, of the expected kind, and anchored or not as declared. */
+function checkRef(r, artifact, path, value, kind, requireAnchor) {
+    if (anchorIsTheProblem(value)) {
+        r.invalid(artifact, `'${path}' referencia revisiones enteras y ${String(value)} lleva un anchor de estado`, "quitá el '#estado' de la referencia: solo una screen tiene estados");
+        return false;
+    }
+    const ref = parseArtifactRef(value);
+    if (ref === null) {
+        r.invalid(artifact, `'${path}' solo admite referencias DES-NNN/XXX-NNN@rN y llegó ${JSON.stringify(value)}`, "referenciá el artefacto completo, con package y revisión");
+        return false;
+    }
+    if (requireAnchor !== (ref.state !== undefined)) {
+        r.invalid(artifact, requireAnchor
+            ? `'${path}' referencia ESTADOS de pantalla y ${String(value)} no lleva anchor`
+            : `'${path}' referencia revisiones enteras y ${String(value)} lleva un anchor de estado`, requireAnchor
+            ? "agregá el anchor, por ejemplo @r2#default"
+            : "quitá el '#estado' de la referencia");
+        return false;
+    }
+    const prefix = kind === null ? null : ARTIFACT_PREFIX[kind];
+    if (prefix !== null && !ref.artifact.startsWith(`${prefix}-`)) {
+        r.invalid(artifact, `'${path}' espera artefactos ${prefix}- y llegó ${String(value)}`, `referenciá un ${kind}`);
+        return false;
+    }
+    return true;
+}
+function readDigestList(r, node, path, artifact) {
+    const raw = r.read(node, path);
+    if (!Array.isArray(raw)) {
+        r.invalid(artifact, `'${path}' debe ser un array de digests`, `escribí '${path}': []`);
+        return [];
+    }
+    const out = [];
+    for (const value of raw) {
+        if (!isDigest(value)) {
+            r.invalid(artifact, `'${path}' referencia assets por digest y llegó ${JSON.stringify(value)}`, "usá 'sha256:' + 64 hex: los assets son content-addressed");
+            continue;
+        }
+        if (!out.includes(value))
+            out.push(value);
+    }
+    return out;
+}
+function readStringList(r, node, path, artifact, what) {
+    const raw = r.read(node, path);
+    if (!Array.isArray(raw)) {
+        r.invalid(artifact, `'${path}' debe ser un array`, `escribí '${path}': []`);
+        return [];
+    }
+    const out = [];
+    for (const value of raw) {
+        if (!checkText(r, artifact, `${path}[]`, value, `revisá '${path}': ${what}`))
+            continue;
+        if (!out.includes(value))
+            out.push(value);
+    }
+    return out;
+}
+/**
+ * Cross-validation. Only the canonical reference form is extracted from the
+ * body, so this never depends on interpreting prose: a mention the frontmatter
+ * does not declare is either a typo or a relation nobody made machine-readable,
+ * and both are errors.
+ */
+function checkBodyAgainstFrontmatter(r, body, kind, artifact, common, specific) {
+    checkBodyRefs(r, body, kind, artifact, common, specific);
+    checkBodyCriteria(r, body, artifact, common);
+    if ("states" in specific)
+        checkBodyAssets(r, body, artifact, specific.dependencies.assets);
+}
+function checkBodyRefs(r, body, kind, artifact, common, specific) {
+    const declared = declaredReferences(common, specific);
+    const own = parseArtifactId(common.id);
+    const ownAnchors = "states" in specific ? specific.states.map((s) => s.anchor) : [];
+    for (const ref of bodyReferences(body)) {
+        const parsedRef = parseArtifactRef(ref);
+        if (parsedRef === null)
+            continue;
+        if (own !== null && parsedRef.package === own.package && parsedRef.artifact === own.artifact) {
+            // A reference to THIS artifact is legitimate without being declared — but
+            // if it names a state, the state has to exist in this revision.
+            checkOwnAnchor(r, artifact, kind, parsedRef.state, ownAnchors);
+            continue;
+        }
+        if (declared.has(ref))
+            continue;
+        r.fail("DESIGN_BODY_REFERENCE_UNKNOWN", artifact, `el cuerpo cita ${ref} y el frontmatter no lo declara`, kind === "flow"
+            ? "agregá esa referencia a 'nodes' o a 'dependencies', o quitala del texto"
+            : "agregá esa referencia a 'flow_refs' o a 'dependencies', o quitala del texto");
+    }
+}
+/**
+ * The spec asks for FOUR things to be contrasted, not one: references, states,
+ * criteria and dependencies. A criterion narrated in the body and absent from
+ * `trace` is traceability that exists only in prose — the exact thing the
+ * frontmatter exists to prevent.
+ */
+function checkBodyCriteria(r, body, artifact, common) {
+    const traced = new Set(common.trace.map((t) => t.criterion));
+    for (const criterion of bodyCriteria(body)) {
+        if (traced.has(criterion))
+            continue;
+        r.fail("DESIGN_BODY_CRITERION_UNKNOWN", artifact, `el cuerpo cita el criterio ${criterion} y 'trace' no lo declara`, "agregalo a 'trace' con su documento fuente, o quitalo del texto");
+    }
+}
+function checkBodyAssets(r, body, artifact, declared) {
+    const assets = new Set(declared);
+    for (const digest of bodyDigests(body)) {
+        if (assets.has(digest))
+            continue;
+        r.fail("DESIGN_BODY_REFERENCE_UNKNOWN", artifact, `el cuerpo cita el asset ${digest} y 'dependencies.assets' no lo declara`, "agregá ese digest a 'dependencies.assets' o quitalo del texto");
+    }
+}
+function checkOwnAnchor(r, artifact, kind, state, ownAnchors) {
+    if (kind !== "screen" || state === undefined || ownAnchors.includes(state))
+        return;
+    r.fail("DESIGN_RELATION_BROKEN", artifact, `el cuerpo cita el estado '#${state}' y 'states' no lo declara`, `declaralo en 'states' o citá uno de: ${ownAnchors.join(", ") || "(ninguno)"}`);
+}
+/** Every reference the frontmatter makes machine-readable. */
+function declaredReferences(common, specific) {
+    const declared = new Set();
+    if (common.supersedes !== null)
+        declared.add(common.supersedes);
+    // The evidence a screen's matrix enumerates IS declared in the frontmatter, so
+    // prose that names it is citing something the document already committed to.
+    // Without this, the section that explains the evidence could not mention it.
+    for (const entry of common.trace) {
+        for (const ref of entry.renditions ?? [])
+            declared.add(ref);
+    }
+    if ("nodes" in specific) {
+        for (const ref of [...specific.nodes, ...specific.dependencies])
+            declared.add(ref);
+        if (specific.entry.length > 0)
+            declared.add(specific.entry);
+        return declared;
+    }
+    for (const ref of [
+        ...specific.flow_refs,
+        ...specific.dependencies.rules,
+        ...specific.dependencies.tokens,
+    ]) {
+        declared.add(ref);
+    }
+    return declared;
+}
+//# sourceMappingURL=artifact.js.map