faberun 0.3.0

package/src/contract/assert.mjs

@@ -0,0 +1,162 @@
+/**
+ * The primitive assertions every validator in this tree needs, in one place.
+ *
+ * They were copied instead: `requireString` stood four times, `rejectUnknown`
+ * four, `requireId` three, `requireTimestamp` three, and the copies had drifted
+ * into six behaviours. Each definition below is the superset of what its copies
+ * did, and the message wording is the majority's, because that is what the
+ * tests match on (`has unexpected field X`); the tests that cover the others
+ * match the label, not the wording, so no assertion changed meaning.
+ *
+ * Deliberately not here: `requirePacketHash` (a contract-specific format),
+ * `requireRuntime` (needs the runtime table), and `repo/integrate.mjs`'s
+ * `requireText`, which despite the name reads a file and is a different
+ * function entirely.
+ */
+
+/**
+ * @param {Record<string, unknown>} value
+ * @param {Set<string>} allowed
+ * @param {string} label
+ */
+export function rejectUnknown(value, allowed, label) {
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) throw new TypeError(`${label} has unexpected field ${key}`);
+  }
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} label
+ * @returns {asserts value is Record<string, unknown>}
+ */
+export function assertObject(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError(`${label} must be an object`);
+  }
+}
+
+/**
+ * A path-safe identifier: letters, numbers, dot, underscore, dash, and never
+ * `.` or `..` on their own. The exclusion is load-bearing -- these ids become
+ * directory names under `.runs/`.
+ *
+ * @param {unknown} value
+ * @param {string} label
+ * @returns {asserts value is string}
+ */
+export function requireId(value, label) {
+  if (typeof value !== "string" || !/^[A-Za-z0-9._-]+$/u.test(value)) {
+    throw new TypeError(`${label} must contain only letters, numbers, dot, underscore, or dash`);
+  }
+  if (value === "." || value === "..") throw new TypeError(`${label} must not be "." or ".."`);
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} label
+ * @returns {asserts value is string}
+ */
+export function requireString(value, label) {
+  if (typeof value !== "string" || !value.trim()) throw new TypeError(`${label} must be a non-empty string`);
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} label
+ * @param {number} [maxBytes]
+ * @returns {asserts value is string}
+ */
+export function requireText(value, label, maxBytes) {
+  requireString(value, label);
+  if (maxBytes !== undefined && Buffer.byteLength(/** @type {string} */ (value), "utf8") > maxBytes) {
+    throw new TypeError(`${label} exceeds ${maxBytes} bytes`);
+  }
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} label
+ * @param {number} maxBytes
+ */
+export function boundedString(value, label, maxBytes) {
+  requireText(value, label, maxBytes);
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} label
+ * @param {boolean} [nonEmpty]
+ */
+export function requireStringArray(value, label, nonEmpty = false) {
+  if (!Array.isArray(value)) throw new TypeError(`${label} must be an array`);
+  if (nonEmpty && !value.length) throw new TypeError(`${label} must not be empty`);
+  for (const [index, item] of value.entries()) requireString(item, `${label}[${index}]`);
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} label
+ * @returns {asserts value is string}
+ */
+export function requireTimestamp(value, label) {
+  if (typeof value !== "string" || !value.trim() || Number.isNaN(Date.parse(value))) {
+    throw new TypeError(`${label} must be a valid timestamp`);
+  }
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} label
+ */
+export function requireInteger(value, label) {
+  if (!Number.isInteger(value)) throw new TypeError(`${label} must be an integer`);
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} label
+ * @returns {number}
+ */
+export function positiveInteger(value, label) {
+  if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) throw new TypeError(`${label} must be a positive integer`);
+  return value;
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} label
+ * @returns {number}
+ */
+export function nonNegativeInteger(value, label) {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 0) throw new TypeError(`${label} must be a non-negative integer`);
+  return value;
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} label
+ * @returns {number}
+ */
+export function positiveNumber(value, label) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) throw new TypeError(`${label} must be a positive number`);
+  return value;
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} label
+ * @returns {number}
+ */
+export function nonNegativeNumber(value, label) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) throw new TypeError(`${label} must be a non-negative number`);
+  return value;
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} label
+ */
+export function requirePacketHash(value, label) {
+  if (typeof value !== "string" || !/^[a-f0-9]{64}$/u.test(value)) throw new TypeError(`${label} must be a SHA-256 hash`);
+}

package/src/contract/definition-of-done.mjs

@@ -0,0 +1,97 @@
+import { rejectUnknown, requireId, requireString } from "./assert.mjs";
+/**
+ * Schema 2 Definition of Done items. Each item is an object that names an
+ * observable outcome and declares how it is proven: mechanically through a
+ * `proof` (a verification `command`, a workspace `path`, or a `verification`
+ * entry reused by reference) or by judge `judgment`. The schema-1 string item
+ * is rejected; there is no converter and no dual acceptance.
+ */
+
+/** @typedef {{kind: "command"|"path"|"verification", ref: string}} DefinitionOfDoneProof */
+
+/** @typedef {{id: string, text: string, proof?: DefinitionOfDoneProof, judgment?: true}} DefinitionOfDoneItem */
+
+/**
+ * @param {unknown} value
+ * @param {string} label
+ * @param {{verificationCount?: number, recordableCount?: number}} [options]
+ * @returns {DefinitionOfDoneItem[]}
+ */
+export function validateDefinitionOfDone(value, label, options = {}) {
+  if (!Array.isArray(value)) throw new TypeError(`${label} must be an array of Definition of Done objects`);
+  return value.map((item, index) => {
+    const itemLabel = `${label}[${index}]`;
+    if (typeof item === "string") {
+      throw new TypeError(`${itemLabel} must be an object, not a schema-1 string item`);
+    }
+    if (!item || typeof item !== "object" || Array.isArray(item)) {
+      throw new TypeError(`${itemLabel} must be an object with id, text, and proof or judgment: true`);
+    }
+    const record = /** @type {Record<string, unknown>} */ (item);
+    rejectUnknown(record, new Set(["id", "text", "proof", "judgment"]), itemLabel);
+    requireId(record.id, `${itemLabel}.id`);
+    requireString(record.text, `${itemLabel}.text`);
+    if (record.judgment !== undefined && record.judgment !== true) {
+      throw new TypeError(`${itemLabel}.judgment must be true when present`);
+    }
+    const proof = record.proof === undefined
+      ? undefined
+      : validateProof(record.proof, `${itemLabel}.proof`, options);
+    if (proof === undefined && record.judgment !== true) {
+      throw new TypeError(`${itemLabel} must declare proof or judgment: true`);
+    }
+    return {
+      id: /** @type {string} */ (record.id),
+      text: /** @type {string} */ (record.text),
+      ...(proof === undefined ? {} : { proof }),
+      ...(record.judgment === true ? { judgment: true } : {}),
+    };
+  });
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} label
+ * @param {{verificationCount?: number, recordableCount?: number}} options
+ * @returns {DefinitionOfDoneProof}
+ */
+function validateProof(value, label, options) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError(`${label} must be an object with kind and ref`);
+  }
+  const record = /** @type {Record<string, unknown>} */ (value);
+  rejectUnknown(record, new Set(["kind", "ref"]), label);
+  const kind = record.kind;
+  if (kind !== "command" && kind !== "path" && kind !== "verification") {
+    throw new TypeError(`${label}.kind must be "command", "path", or "verification"`);
+  }
+  if (kind === "verification") return { kind, ref: validateVerificationRef(record.ref, label, options) };
+  requireString(record.ref, `${label}.ref`);
+  return { kind, ref: /** @type {string} */ (record.ref) };
+}
+
+/**
+ * A `verification` proof reuses a recorded controller verification result by
+ * position, never by comparing command strings: a joined argv loses argument
+ * boundaries and shell semantics, so the reference is the only sound name.
+ *
+ * @param {unknown} value
+ * @param {string} label
+ * @param {{verificationCount?: number, recordableCount?: number}} options
+ * @returns {string}
+ */
+function validateVerificationRef(value, label, options) {
+  const text = typeof value === "number" ? String(value) : value;
+  if (typeof text !== "string" || !/^\d+$/u.test(text.trim())) {
+    throw new TypeError(`${label}.ref must be the zero-based index of a verification command`);
+  }
+  const index = Number.parseInt(text, 10);
+  if (typeof options.verificationCount === "number" && index >= options.verificationCount) {
+    throw new TypeError(`${label}.ref ${index} names no verification command: the packet declares ${options.verificationCount}`);
+  }
+  if (typeof options.recordableCount === "number" && index >= options.recordableCount) {
+    throw new TypeError(`${label}.ref ${index} cannot be reused at gate time: only the first ${options.recordableCount} verification commands are recorded on the node`);
+  }
+  return String(index);
+}
+

package/src/contract/final-verification.mjs

@@ -0,0 +1,96 @@
+/**
+ * Verification schema that is not part of a task packet (TECH-SPEC section 6.2,
+ * rule 12).
+ *
+ * `contract.finalVerification` is the contract-wide proof that the phase as a
+ * whole closes: the controller runs it before the judge on the phase-terminal
+ * node (the node no other node depends on), so no final checkpoint is ever
+ * approved on partial verification. The persisted node-snapshot shape for
+ * verification evidence lives here too, next to the schema it records.
+ */
+
+import { Buffer } from "node:buffer";
+import { validateVerificationCommands } from "./verification.mjs";
+import { assertObject, nonNegativeInteger, positiveInteger, rejectUnknown, requireInteger, requireString, requireTimestamp } from "./assert.mjs";
+
+/** @typedef {Record<string, unknown>} JsonObject */
+/** @typedef {import("./verification.mjs").VerificationCommand} VerificationCommand */
+
+/**
+ * Validate the optional contract-level `finalVerification` field. It carries
+ * the full verification-command schema and nothing else.
+ *
+ * @param {unknown} value
+ * @param {string} label
+ * @returns {VerificationCommand[]|undefined}
+ */
+export function validateFinalVerification(value, label = "contract.finalVerification") {
+  if (value === undefined) return undefined;
+  return validateVerificationCommands(value, label);
+}
+
+/**
+ * The contract's `finalVerification` commands when this node is the one that
+ * closes the phase, otherwise none. A node is phase-terminal when no other
+ * node in the contract depends on it.
+ *
+ * @param {{finalVerification?: VerificationCommand[], nodes: {id: string, dependsOn: string[]}[]}} contract
+ * @param {{id: string}} node
+ * @returns {VerificationCommand[]}
+ */
+export function finalVerificationCommands(contract, node) {
+  const commands = contract.finalVerification ?? [];
+  if (commands.length === 0) return [];
+  const hasDependant = contract.nodes.some((candidate) => candidate.dependsOn.includes(node.id));
+  return hasDependant ? [] : commands;
+}
+
+/**
+ * @param {unknown} value
+ */
+export function validateVerificationSnapshot(value) {
+  assertObject(value, "node snapshot.verification");
+  if (typeof value.passed !== "boolean" || !Array.isArray(value.commands) || value.commands.length > 32) {
+    throw new TypeError("node snapshot.verification is invalid");
+  }
+  if (value.completed !== undefined && typeof value.completed !== "boolean") throw new TypeError("node snapshot.verification.completed is invalid");
+  if (value.attempts !== undefined) {
+    if (!Array.isArray(value.attempts) || value.attempts.length > 16) throw new TypeError("node snapshot.verification.attempts is invalid");
+    const attempts = /** @type {unknown[]} */ (value.attempts);
+    for (const [index, attempt] of attempts.entries()) validateVerificationAttempt(attempt, `node snapshot.verification.attempts[${index}]`);
+  }
+  if (value.error !== undefined && (typeof value.error !== "string" || Buffer.byteLength(value.error, "utf8") > 4096)) {
+    throw new TypeError("node snapshot.verification.error is invalid");
+  }
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} label
+ */
+function validateVerificationAttempt(value, label) {
+  assertObject(value, label);
+  rejectUnknown(value, new Set([
+    "invocationId", "commandIndex", "attempt", "pid", "processStartToken", "processGroupId",
+    "startedAt", "deadlineAt", "status", "completedAt", "result",
+  ]), label);
+  requireString(value.invocationId, `${label}.invocationId`);
+  nonNegativeInteger(value.commandIndex, `${label}.commandIndex`);
+  positiveInteger(value.attempt, `${label}.attempt`);
+  if (value.pid !== null) requireInteger(value.pid, `${label}.pid`);
+  if (value.processGroupId !== null) requireInteger(value.processGroupId, `${label}.processGroupId`);
+  if (value.processStartToken !== null) requireString(value.processStartToken, `${label}.processStartToken`);
+  requireTimestamp(value.startedAt, `${label}.startedAt`);
+  requireTimestamp(value.deadlineAt, `${label}.deadlineAt`);
+  if (!["active", "closed", "failed", "crashed", "canceled"].includes(/** @type {string} */ (value.status))) throw new TypeError(`${label}.status is invalid`);
+  if (value.completedAt !== null) requireTimestamp(value.completedAt, `${label}.completedAt`);
+  if (value.result !== null) {
+    assertObject(value.result, `${label}.result`);
+    const result = /** @type {JsonObject} */ (value.result);
+    for (const key of ["stdout", "stderr", "error"]) {
+      if (result[key] !== null && result[key] !== undefined && (typeof result[key] !== "string" || Buffer.byteLength(result[key], "utf8") > 2048)) throw new TypeError(`${label}.result.${key} is invalid`);
+    }
+    if (typeof result.passed !== "boolean") throw new TypeError(`${label}.result.passed is invalid`);
+  }
+}
+