create-pathfinder 4.1.0 → 4.3.0

package/skills/render-artifact/engine/validate/jsonschema.mjs

@@ -0,0 +1,312 @@
+/**
+ * A JSON Schema validator covering exactly the keywords this engine's schemas
+ * use, and nothing else.
+ *
+ * Writing one rather than depending on one is not preference. The engine ships
+ * inside `skills/`, which is copied whole into every destination project, and
+ * `NOT_A_FRAMEWORK.md` promises those projects acquire no runtime and no
+ * package manager. A dependency here would be a dependency in every installed
+ * project. The schemas are ours, so the subset is knowable: adding a keyword to
+ * a schema means adding it here, and an unknown keyword is a hard error rather
+ * than something quietly ignored — a validator that silently skips the rule you
+ * just wrote is worse than no validator.
+ *
+ * Supported: $ref, $defs, type, const, enum, properties, required,
+ * additionalProperties (false only), items, minItems, maxItems, uniqueItems,
+ * minLength, maxLength, pattern, minimum, maximum, oneOf, if/then.
+ *
+ * Note what is absent: `else`. `if`/`then` are here because a schema uses them.
+ * `else` would be a keyword implemented on speculation, never executed and
+ * never tested, and the first schema to reach for it would be relying on a
+ * branch nobody had seen work. Adding it when a schema needs it is one small
+ * change; carrying it until then is a promise this file cannot evidence.
+ */
+
+/** Keywords carrying documentation rather than constraint. */
+const ANNOTATIONS = new Set(["$id", "$schema", "title", "description", "$defs"]);
+
+const CONSTRAINTS = new Set([
+  "$ref", "type", "const", "enum", "properties", "required",
+  "additionalProperties", "items", "minItems", "maxItems", "uniqueItems",
+  "minLength", "maxLength", "pattern", "minimum", "maximum", "oneOf",
+  "if", "then",
+]);
+
+/**
+ * @typedef {object} SchemaError
+ * @property {string} path      dotted/bracketed path into the instance
+ * @property {string} keyword   the keyword that rejected it
+ * @property {string} message   what is wrong, in the reader's terms
+ * @property {string} [property] the offending property name, when there is one
+ */
+
+/** JSON's own type names, as `typeof` cannot tell array from object from null. */
+function jsonType(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  if (Number.isInteger(value)) return "integer";
+  return typeof value;
+}
+
+function typeMatches(value, expected) {
+  const actual = jsonType(value);
+  if (expected === "number") return actual === "integer" || actual === "number";
+  if (expected === "integer") return actual === "integer";
+  return actual === expected;
+}
+
+/** Stable, locale-independent rendering of a value inside a diagnostic. */
+function show(value) {
+  if (typeof value === "string") return JSON.stringify(value);
+  if (value === undefined) return "undefined";
+  return JSON.stringify(value);
+}
+
+/**
+ * A registry of schemas by `$id`, able to resolve the two ref shapes the
+ * schemas use: `other.schema.json#/$defs/name` and `#/$defs/name`.
+ */
+export class SchemaRegistry {
+  constructor() {
+    /** @type {Map<string, object>} */
+    this.byId = new Map();
+  }
+
+  add(schema) {
+    if (typeof schema?.$id !== "string") {
+      throw new Error("schema has no $id; refs could not resolve it");
+    }
+    this.byId.set(schema.$id, schema);
+    return this;
+  }
+
+  /**
+   * @param {string} ref  the `$ref` value
+   * @param {string} fromId  the `$id` of the schema the ref appeared in
+   */
+  resolve(ref, fromId) {
+    const hash = ref.indexOf("#");
+    if (hash < 0) throw new Error(`unsupported $ref without a fragment: ${ref}`);
+    const id = ref.slice(0, hash) || fromId;
+    const pointer = ref.slice(hash + 1);
+    const root = this.byId.get(id);
+    if (!root) throw new Error(`$ref names an unregistered schema: ${ref}`);
+
+    let node = root;
+    for (const rawSegment of pointer.split("/")) {
+      if (rawSegment === "") continue;
+      const segment = rawSegment.replace(/~1/g, "/").replace(/~0/g, "~");
+      node = node?.[segment];
+      if (node === undefined) throw new Error(`$ref does not resolve: ${ref}`);
+    }
+    return { schema: node, id };
+  }
+}
+
+/**
+ * Validate `instance` against the schema registered under `rootId`.
+ *
+ * Errors come back in a deterministic order: depth-first through the instance,
+ * and for object properties in the order the schema declares them, never the
+ * order the instance happens to carry or `Object.keys` happens to return.
+ *
+ * @returns {SchemaError[]}
+ */
+export function validateAgainstSchema(instance, rootId, registry) {
+  const errors = [];
+  const root = registry.byId.get(rootId);
+  if (!root) throw new Error(`no schema registered as ${rootId}`);
+  walk(instance, root, rootId, "", errors, registry);
+  return errors;
+}
+
+function push(errors, path, keyword, message, property) {
+  const error = { path: path || "(root)", keyword, message };
+  if (property !== undefined) error.property = property;
+  errors.push(error);
+}
+
+function walk(value, schema, schemaId, path, errors, registry) {
+  for (const keyword of Object.keys(schema)) {
+    if (!ANNOTATIONS.has(keyword) && !CONSTRAINTS.has(keyword)) {
+      throw new Error(
+        `schema ${schemaId} at ${path || "(root)"} uses unsupported keyword ` +
+        `\`${keyword}\`; add it to validate/jsonschema.mjs rather than ` +
+        `letting it be ignored`,
+      );
+    }
+  }
+
+  if (schema.$ref !== undefined) {
+    const { schema: target, id } = registry.resolve(schema.$ref, schemaId);
+    walk(value, target, id, path, errors, registry);
+    return;
+  }
+
+  if (schema.oneOf !== undefined) {
+    walkOneOf(value, schema.oneOf, schemaId, path, errors, registry);
+    return;
+  }
+
+  if (schema.const !== undefined && value !== schema.const) {
+    push(errors, path, "const", `must be ${show(schema.const)}, found ${show(value)}`);
+    return;
+  }
+
+  if (schema.enum !== undefined && !schema.enum.includes(value)) {
+    push(errors, path, "enum",
+      `must be one of ${schema.enum.map(show).join(", ")}, found ${show(value)}`);
+    return;
+  }
+
+  if (schema.type !== undefined && !typeMatches(value, schema.type)) {
+    push(errors, path, "type", `must be ${schema.type}, found ${jsonType(value)}`);
+    return;
+  }
+
+  const type = jsonType(value);
+  if (type === "string") walkString(value, schema, path, errors);
+  if (type === "integer" || type === "number") walkNumber(value, schema, path, errors);
+  if (type === "array") walkArray(value, schema, schemaId, path, errors, registry);
+  if (type === "object") walkObject(value, schema, schemaId, path, errors, registry);
+
+  if (schema.if !== undefined) walkConditional(value, schema, schemaId, path, errors, registry);
+}
+
+/**
+ * `if` / `then` — one rule whose applicability depends on the instance.
+ *
+ * It exists for the diagram kind's provenance: a `derived` diagram must declare
+ * a `source`, and a `proposed` one need not. That is a conditional requirement,
+ * and writing it as a conditional keeps the contract in the schema where a
+ * reader looks for it, rather than leaving the schema silent and the rule
+ * somewhere in JavaScript.
+ *
+ * The `if` branch is evaluated for its *outcome*, not its diagnostics: its
+ * errors go to a throwaway array and are discarded, because "this instance is
+ * not a derived diagram" is not a problem to report. Only `then` contributes to
+ * `errors`, so a producer sees the rule that actually applied to what they
+ * wrote and never the one that did not.
+ */
+function walkConditional(value, schema, schemaId, path, errors, registry) {
+  const probe = [];
+  walk(value, schema.if, schemaId, path, probe, registry);
+
+  if (probe.length === 0 && schema.then !== undefined) {
+    walk(value, schema.then, schemaId, path, errors, registry);
+  }
+}
+
+/**
+ * `oneOf` here is always a discriminated union over `type`, so branch selection
+ * is by the discriminator rather than by counting how many branches passed.
+ * The difference matters to the reader: "unknown section type" and a precise
+ * complaint about the branch they meant beat six parallel rejections.
+ */
+function walkOneOf(value, branches, schemaId, path, errors, registry) {
+  const resolved = branches.map((branch) =>
+    branch.$ref ? registry.resolve(branch.$ref, schemaId) : { schema: branch, id: schemaId });
+
+  const discriminators = resolved.map(({ schema }) => schema?.properties?.type?.const);
+  const known = discriminators.filter((d) => typeof d === "string");
+
+  if (known.length !== resolved.length) {
+    throw new Error(`oneOf at ${path || "(root)"} is not discriminated by a \`type\` const`);
+  }
+  if (jsonType(value) !== "object") {
+    push(errors, path, "oneOf", `must be an object, found ${jsonType(value)}`);
+    return;
+  }
+
+  const index = discriminators.indexOf(value.type);
+  if (index < 0) {
+    push(errors, `${path}.type`, "oneOf",
+      `must be one of ${known.map(show).join(", ")}, found ${show(value.type)}`,
+      "type");
+    return;
+  }
+  const branch = resolved[index];
+  walk(value, branch.schema, branch.id, path, errors, registry);
+}
+
+function walkString(value, schema, path, errors) {
+  if (schema.minLength !== undefined && value.length < schema.minLength) {
+    push(errors, path, "minLength",
+      `must be at least ${schema.minLength} character(s), found ${value.length}`);
+  }
+  if (schema.maxLength !== undefined && value.length > schema.maxLength) {
+    push(errors, path, "maxLength",
+      `must be at most ${schema.maxLength} character(s), found ${value.length}`);
+  }
+  if (schema.pattern !== undefined && !new RegExp(schema.pattern, "u").test(value)) {
+    push(errors, path, "pattern",
+      `must match ${schema.pattern}, found ${show(value)}`);
+  }
+}
+
+function walkNumber(value, schema, path, errors) {
+  if (schema.minimum !== undefined && value < schema.minimum) {
+    push(errors, path, "minimum", `must be at least ${schema.minimum}, found ${value}`);
+  }
+  if (schema.maximum !== undefined && value > schema.maximum) {
+    push(errors, path, "maximum", `must be at most ${schema.maximum}, found ${value}`);
+  }
+}
+
+function walkArray(value, schema, schemaId, path, errors, registry) {
+  if (schema.minItems !== undefined && value.length < schema.minItems) {
+    push(errors, path, "minItems",
+      `must have at least ${schema.minItems} item(s), found ${value.length}`);
+  }
+  if (schema.maxItems !== undefined && value.length > schema.maxItems) {
+    push(errors, path, "maxItems",
+      `must have at most ${schema.maxItems} item(s), found ${value.length}`);
+  }
+  if (schema.uniqueItems === true) {
+    const seen = new Set();
+    for (let index = 0; index < value.length; index += 1) {
+      const key = JSON.stringify(value[index]);
+      if (seen.has(key)) {
+        push(errors, `${path}[${index}]`, "uniqueItems",
+          `duplicates an earlier item: ${show(value[index])}`);
+      }
+      seen.add(key);
+    }
+  }
+  if (schema.items !== undefined) {
+    for (let index = 0; index < value.length; index += 1) {
+      walk(value[index], schema.items, schemaId, `${path}[${index}]`, errors, registry);
+    }
+  }
+}
+
+function walkObject(value, schema, schemaId, path, errors, registry) {
+  for (const name of schema.required ?? []) {
+    if (!Object.prototype.hasOwnProperty.call(value, name)) {
+      push(errors, path ? `${path}.${name}` : name, "required",
+        `is required and is missing`, name);
+    }
+  }
+
+  if (schema.additionalProperties === false && schema.properties) {
+    const allowed = new Set(Object.keys(schema.properties));
+    // Instance key order is producer-controlled, so sort to keep diagnostics
+    // stable. Codepoint order, never `localeCompare`.
+    const extras = Object.keys(value).filter((name) => !allowed.has(name)).sort();
+    for (const name of extras) {
+      push(errors, path ? `${path}.${name}` : name, "additionalProperties",
+        `is not part of this contract`, name);
+    }
+  } else if (schema.additionalProperties !== undefined
+             && schema.additionalProperties !== false) {
+    throw new Error(
+      `schema ${schemaId} at ${path || "(root)"} uses a non-false ` +
+      `additionalProperties, which this validator does not implement`);
+  }
+
+  for (const [name, subschema] of Object.entries(schema.properties ?? {})) {
+    if (!Object.prototype.hasOwnProperty.call(value, name)) continue;
+    walk(value[name], subschema, schemaId, path ? `${path}.${name}` : name,
+      errors, registry);
+  }
+}

package/skills/render-artifact/engine/validate/structural.mjs

@@ -0,0 +1,241 @@
+/**
+ * Layer 1 — structural. The specification satisfies its schema.
+ *
+ * This is also where an unsupported `kind` is refused. A kind the renderer does
+ * not have is never permission to improvise: there is no fallback schema, no
+ * generic renderer, and no "render it as best you can" path out of here.
+ */
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+import { SCHEMA_VERSION } from "../version.mjs";
+import { cellWidth } from "../render/graph/width.mjs";
+import { SchemaRegistry, validateAgainstSchema } from "./jsonschema.mjs";
+import { diagramEvidenceSites } from "./diagram-parts.mjs";
+import { diagnostic, isPresentationControl } from "./diagnostics.mjs";
+
+const SCHEMA_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "schemas");
+
+/**
+ * The kind registry: the discriminator's only meaning.
+ *
+ * Two entries, and there is deliberately no placeholder for any future kind. A
+ * placeholder entry is a promise the renderer cannot keep, and the first thing
+ * it would do is turn a clean refusal into a half-render.
+ */
+export const KINDS = Object.freeze({
+  lesson: { schema: "lesson.schema.json" },
+  diagram: { schema: "diagram.schema.json" },
+});
+
+/**
+ * The topologies the `diagram` kind supports, and the layout each selects.
+ *
+ * `graph` is the only one. A second topology is a second layout engine, not a
+ * value in a list, so an unsupported topology is refused here for the same
+ * reason an unsupported kind is: there is no generic layout to fall back on
+ * and no "draw it as best you can" path out.
+ */
+export const TOPOLOGIES = Object.freeze(["graph"]);
+
+let registry = null;
+
+/** Load and register the schemas once. Ordering is fixed by this list. */
+export function schemaRegistry() {
+  if (registry) return registry;
+  const next = new SchemaRegistry();
+  for (const file of ["common.schema.json", "lesson.schema.json",
+    "diagram.schema.json"]) {
+    next.add(JSON.parse(readFileSync(join(SCHEMA_DIR, file), "utf8")));
+  }
+  registry = next;
+  return registry;
+}
+
+/**
+ * @param {unknown} spec the parsed specification
+ * @returns {import("./diagnostics.mjs").Diagnostic[]}
+ */
+export function validateStructure(spec) {
+  if (spec === null || typeof spec !== "object" || Array.isArray(spec)) {
+    return [diagnostic("structural", "specification_not_an_object", "(root)",
+      "a specification must be a JSON object")];
+  }
+
+  if (spec.schema_version !== SCHEMA_VERSION) {
+    return [diagnostic("structural", "schema_version_unsupported", "schema_version",
+      `this engine implements schema_version ${JSON.stringify(SCHEMA_VERSION)}; ` +
+      `the specification declares ${JSON.stringify(spec.schema_version ?? null)}`)];
+  }
+
+  const kind = spec.kind;
+  if (!Object.prototype.hasOwnProperty.call(KINDS, kind)) {
+    const supported = Object.keys(KINDS).map((k) => `\`${k}\``).join(", ");
+    return [diagnostic("structural", "kind_unsupported", "kind",
+      `${JSON.stringify(kind ?? null)} is not an artifact kind this renderer ` +
+      `supports. Supported: ${supported}. A missing kind is a refusal, not a ` +
+      `reason to hand-author HTML.`)];
+  }
+
+  // The topology refusal comes before the schema for the same reason the kind
+  // refusal does: `enum` would reject it too, but "must be one of \"graph\"" is
+  // a sentence about a list, and the thing that went wrong was asking for a
+  // layout this renderer does not have.
+  if (kind === "diagram") {
+    const topology = spec.diagram?.topology;
+    if (topology !== undefined && !TOPOLOGIES.includes(topology)) {
+      const supported = TOPOLOGIES.map((t) => `\`${t}\``).join(", ");
+      return [diagnostic("structural", "topology_unsupported", "diagram.topology",
+        `${JSON.stringify(topology)} is not a topology this renderer supports. ` +
+        `Supported: ${supported}. A topology is a layout, not a label, so a ` +
+        `missing one is a refusal rather than a reason to approximate it.`,
+        "topology")];
+    }
+
+    // Ahead of the schema for the same reason the two refusals above are. The
+    // schema's own conditional says `source` is required when provenance is
+    // `derived`, and would reject this too — as "`source` is required and is
+    // missing", a sentence about a field. What went wrong is a claim: the
+    // specification says it was derived from a repository and does not say
+    // which, so there is nothing for a citation to resolve against.
+    if (spec.provenance === "derived"
+        && !Object.prototype.hasOwnProperty.call(spec, "source")) {
+      return [diagnostic("structural", "source_required_for_derived", "source",
+        `a \`derived\` diagram maps what a repository asserts about itself at ` +
+        `a declared commit, so it must say which repository and which commit. ` +
+        `Without a source there is nothing for its citations to resolve ` +
+        `against, and nothing that makes it derived from anything. A diagram ` +
+        `describing a system with no repository behind it is \`proposed\`.`,
+        "source")];
+    }
+  }
+
+  const errors = validateAgainstSchema(spec, KINDS[kind].schema, schemaRegistry())
+    .map(toDiagnostic);
+  if (errors.length > 0) return errors;
+
+  // Label caps are counted in columns, which is why they are here rather than
+  // as a `maxLength`. A column is not a character: `漢` is one character and two
+  // columns, a Devanagari matra is one character and none, and `String.length`
+  // is not even a character count but a count of UTF-16 units. Capping on any
+  // of those would give a producer writing in one script a different allowance
+  // from a producer writing in another.
+  return kind === "diagram"
+    ? [...provenanceErrors(spec), ...labelWidthErrors(spec)]
+    : [];
+}
+
+/**
+ * The two provenance rules a schema cannot express, both refusals rather than
+ * anything the engine works around.
+ *
+ * **A citation with no source.** There is nothing to resolve it against: no
+ * repository, no commit, no history. Accepting it and moving on would be the
+ * engine holding an unchecked citation and saying nothing about it, and the
+ * artifact would then display a file path and a line range as though they had
+ * been verified. It is refused here, in the structural layer, because it is a
+ * contradiction in the specification's own shape rather than a citation that
+ * failed to resolve — the evidence layer never runs for such a specification,
+ * so a rule living there would never fire.
+ *
+ * **`artifact.summary` on a `derived` diagram.** Every other place prose can
+ * make a claim is covered by the evidence rules. `artifact.summary` is the one
+ * that is not addressed to any node, edge or group, so it has nothing to carry
+ * a citation of its own — which makes it the exit a claim would leave by. The
+ * subtitle stays available, and so does every node's `summary`; what is refused
+ * is an uncited assertion at the top of a document whose whole premise is that
+ * its assertions are cited.
+ */
+function provenanceErrors(spec) {
+  const out = [];
+  const hasSource = Object.prototype.hasOwnProperty.call(spec, "source");
+
+  if (!hasSource) {
+    for (const site of diagramEvidenceSites(spec.diagram)) {
+      if (site.evidence.length === 0) continue;
+      out.push(diagnostic("structural", "citation_without_source", site.path,
+        `${site.subject} cites \`${site.evidence[0].path}\`, and this ` +
+        `specification declares no source. A citation resolves against a ` +
+        `commit; with no repository and no commit there is nothing to resolve ` +
+        `it against, so it is refused rather than displayed as though it had ` +
+        `been checked. Either declare a source, or remove the citation and ` +
+        `let the diagram describe an intended system.`, site.subject));
+    }
+  }
+
+  if (spec.provenance === "derived" && spec.artifact.summary !== undefined) {
+    out.push(diagnostic("structural", "artifact_summary_forbidden",
+      "artifact.summary",
+      `a \`derived\` diagram carries no \`artifact.summary\`. Every other ` +
+      `place prose asserts something — a node, an edge, a group, a path, a ` +
+      `view — carries evidence for it, and this one cannot: it belongs to the ` +
+      `document rather than to anything in the diagram, so there is nowhere ` +
+      `for its citation to go. Put the claim on the thing it is about and ` +
+      `cite it there, or use \`artifact.subtitle\`, which names the diagram ` +
+      `rather than asserting anything about the system.`, "summary"));
+  }
+
+  return out;
+}
+
+/** The column cap for each place a label appears. */
+const LABEL_CELLS = Object.freeze({ node: 32, group: 32, path: 32, view: 32, edge: 24 });
+
+/**
+ * Refuse a label wider than its cap, naming the width in columns.
+ *
+ * Refused, never shortened. The renderer owns where a label goes and how it
+ * wraps; it owns none of the words, and a label that arrives too wide is a
+ * conversation with the producer rather than something to quietly trim.
+ */
+function labelWidthErrors(spec) {
+  const out = [];
+  const check = (label, cap, path, what) => {
+    if (label === undefined) return;
+    const width = cellWidth(label);
+    if (width <= cap) return;
+    out.push(diagnostic("structural", "label_too_long", path,
+      `${what} is ${width} columns wide and the cap is ${cap}. Columns, not ` +
+      `characters: a wide character counts two and a combining mark counts ` +
+      `none. Shorten the label — the renderer will not do it for you, because ` +
+      `the words are yours.`, label));
+  };
+
+  const { diagram } = spec;
+  diagram.nodes.forEach((node, i) =>
+    check(node.label, LABEL_CELLS.node, `diagram.nodes[${i}].label`, `node label "${node.label}"`));
+  (diagram.groups ?? []).forEach((group, i) =>
+    check(group.label, LABEL_CELLS.group, `diagram.groups[${i}].label`, `group label "${group.label}"`));
+  diagram.edges.forEach((edge, i) =>
+    check(edge.label, LABEL_CELLS.edge, `diagram.edges[${i}].label`, `edge label "${edge.label}"`));
+  (diagram.paths ?? []).forEach((path, i) =>
+    check(path.label, LABEL_CELLS.path, `diagram.paths[${i}].label`, `path label "${path.label}"`));
+  (diagram.views ?? []).forEach((view, i) =>
+    check(view.label, LABEL_CELLS.view, `diagram.views[${i}].label`, `view label "${view.label}"`));
+  return out;
+}
+
+/**
+ * Turn a schema error into a diagnostic, upgrading the ones that are really a
+ * producer reaching for presentation control.
+ */
+function toDiagnostic(error) {
+  if (error.keyword === "additionalProperties" && isPresentationControl(error.property)) {
+    return diagnostic("structural", "presentation_control", error.path,
+      `\`${error.property}\` is presentation control and belongs to the ` +
+      `renderer, not to the specification. Rejected rather than ignored: a ` +
+      `field silently dropped is a producer believing it had an effect.`,
+      error.property);
+  }
+  if (error.keyword === "additionalProperties") {
+    return diagnostic("structural", "unknown_field", error.path,
+      `\`${error.property}\` is not part of this contract`, error.property);
+  }
+  if (error.keyword === "required") {
+    return diagnostic("structural", "missing_field", error.path,
+      `\`${error.property}\` is required and is missing`, error.property);
+  }
+  return diagnostic("structural", `schema_${error.keyword}`, error.path, error.message);
+}

package/skills/render-artifact/engine/verification.mjs

@@ -0,0 +1,76 @@
+/**
+ * Proof that this engine validated something, in a form a caller cannot fake.
+ *
+ * The rule this exists to enforce:
+ *
+ *   render()   does not prove validation
+ *   validate() does not prove delivery
+ *   deliver()  may claim verification only after performing it
+ *
+ * An artifact carries a sentence in its provenance block saying its evidence
+ * was checked against the named commit. That sentence is worth exactly what it
+ * costs to obtain. Before this module it cost nothing: `render()` is a public
+ * export, so any caller could hand it an unvalidated specification and get back
+ * a page asserting that every citation had been verified.
+ *
+ * So the claim is now gated on an attestation, and an attestation can only be
+ * minted from a validation result this engine produced and that passed. The
+ * brand is a module-private symbol — not `Symbol.for`, so it is not reachable
+ * through the global registry, and not a string key a caller could guess and
+ * set. `attest()` refuses anything unbranded, which means the only route to a
+ * verification claim is to actually pass validation.
+ *
+ * Deliberately importable by the render path: this file imports nothing at all,
+ * so it does not put a `node:` builtin anywhere near rendering.
+ *
+ * There is no producer-facing counterpart. No `verified`, no
+ * `validation_status`, no field of any name in the specification can influence
+ * this — a producer asserting its own work was checked is precisely the claim
+ * this module exists to make impossible.
+ */
+
+const PASSED = Symbol("pathfinder.render-artifact.validated");
+
+/**
+ * Brand a passing validation result. Called by the validator, and nowhere else.
+ * The brand is non-enumerable, so it never reaches JSON, a receipt, or a log.
+ */
+export function markPassed(result) {
+  Object.defineProperty(result, PASSED, { value: true, enumerable: false });
+  return result;
+}
+
+/**
+ * Mint an attestation from a validation this engine performed and that passed.
+ *
+ * The attestation carries *what* passed, not merely that something did, because
+ * the sentence an artifact is entitled to depends on it. `layers` says which
+ * layers ran — the evidence layer does not run for a specification with no
+ * source — and `resolvedCitations` says how many citations actually resolved at
+ * the declared commit.
+ *
+ * That count is the guard against a vacuous claim. A specification carrying no
+ * citations passes the evidence layer by having nothing to fail, and an artifact
+ * that said "every citation above was verified" on the strength of that would be
+ * making a stronger statement than anyone made. Zero is therefore a number the
+ * shell reads and declines to claim on, rather than a pass it cannot see.
+ *
+ * @throws when handed anything else — an unbranded object, a hand-built
+ *         `{ ok: true }`, or a result that failed.
+ */
+export function attest(result) {
+  if (!result || result[PASSED] !== true) {
+    throw new Error(
+      "a verification claim can only be minted from a validation this engine " +
+      "performed and that passed; nothing else can vouch for an artifact");
+  }
+  return markPassed({
+    layers: Object.freeze([...result.ran]),
+    resolvedCitations: result.resolvedCitations ?? 0,
+  });
+}
+
+/** Is this a real attestation? Used by the shell to decide whether to claim. */
+export function isAttestation(value) {
+  return Boolean(value) && value[PASSED] === true;
+}

package/skills/render-artifact/engine/version.mjs

@@ -0,0 +1,24 @@
+/**
+ * The renderer's own version, and the single source of truth for it.
+ *
+ * This is deliberately not the Pathfinder release version and deliberately not
+ * carried by a `package.json`. Two reasons, both structural:
+ *
+ * 1. Everything under `skills/` is copied into every destination project. A
+ *    manifest here would ship into other people's repositories and read as a
+ *    dependency the kit does not have. `NOT_A_FRAMEWORK.md` is the promise
+ *    that would break.
+ * 2. The determinism invariant is *same specification bytes + same renderer
+ *    version -> same artifact bytes*. That makes this constant part of the
+ *    compiler's input, so it has to move exactly when rendered output can
+ *    move, and at no other time. A kit release that does not touch rendering
+ *    must leave it alone; tying it to the kit version would make every release
+ *    look like an intentional output change.
+ *
+ * Bump this in the same commit as any change that can alter rendered HTML --
+ * markup, CSS, inline behaviour, ordering, or escaping.
+ */
+export const RENDERER_VERSION = "0.5.0";
+
+/** The specification `schema_version` this engine understands. */
+export const SCHEMA_VERSION = "1.0";