@nextcommerce/campaigns-os 1.33.0

package/src/run-record.mjs

@@ -0,0 +1,839 @@
+// Run Telemetry — per-run Run Record capture for Campaigns OS.
+// See docs/workflow-findings-sidecar.md (Run Telemetry).
+//
+// A Run Record is a per-run MANIFEST keyed by one canonical run_id. It
+// REFERENCES source artifacts by {path, schema_version, sha256,
+// material_fingerprint} where available and carries normalized observation
+// arrays; it never re-embeds full artifact bodies, so it survives upstream schema
+// drift. Capture is ALWAYS local — consent gates remit only (see consent.mjs).
+// This module owns the schema validator and the local assemble/write surface; it
+// has no network or credential dependencies.
+
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { ADAPTER_DECISION_STRATEGY_FIELDS } from "./adapter-decision-contract.mjs";
+
+export const RUN_RECORD_SCHEMA = "campaigns-os-run-record/v0";
+export const RUN_RECORDS_DIR_REL_PATH = ".campaign-runtime/run-records";
+
+// Improvement-surface taxonomy: a list, not an enum — real signal is rarely
+// one surface (see Improvement-Surface Taxonomy in the design).
+export const RUN_RECORD_SURFACES = [
+  "skill",
+  "cli",
+  "template",
+  "design-source",
+  "docs",
+  "spec-rule",
+  "platform",
+];
+
+export const RUN_RECORD_ARTIFACT_KINDS = [
+  "build_packet",
+  "build_brief",
+  "design_source_package",
+  "build_context",
+  "assembly_report",
+  "page_kit_build_summary",
+  "qa_verdict",
+  "findings_journal",
+];
+
+export const RUN_RECORD_CONSENT_STATES = ["on", "off"];
+// Toolkit provenance shapes. One definition each: the validator, the assembler
+// and the CLI stamp all read these, and the JSON Schema carries the same
+// literal (a schema cannot reference a JS constant; the schema test pins them
+// equal).
+export const RUN_RECORD_SURFACE_VERSION_PATTERN = /^[0-9]+\.[0-9]+\.[0-9]+$/;
+export const RUN_RECORD_COMMIT_PATTERN = /^[0-9a-f]{7,40}$/;
+export const RUN_RECORD_REMIT_STATES = ["skipped", "pending", "ok", "failed"];
+// What the receiver answered, and where the send went, as kinds. The schema
+// carries the same literals; src/remit.mjs classifies into the first and
+// resolves the second.
+export const RUN_RECORD_REMIT_RESULTS = ["stored", "already_stored", "ok_unparsed_ack", "refused", "transport_error"];
+export const RUN_RECORD_REMIT_BASE_KINDS = ["canonical", "loopback", "proxy"];
+// The QA verdict publish outcome a record may carry beside its remit: which
+// verdict went out, who sent it, and what the QA portal answered, classified
+// into the same result vocabulary as the remit. `qa publish` reads the block
+// to refuse re-posting a verdict the portal already holds.
+export const RUN_RECORD_QA_VERDICT_PUBLISH_STATES = ["skipped", "ok", "failed"];
+export const RUN_RECORD_QA_VERDICT_PUBLISHERS = ["qa run", "qa publish"];
+
+// Required core. Strict here; permissive about optional sub-structures (the
+// validator checks shapes, not nested artifact bodies — those are referenced
+// by hash, not embedded).
+const REQUIRED_FIELDS = [
+  "schema_version",
+  "run_id",
+  "package_version",
+  "command",
+  "created_at",
+];
+
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function isStringArray(value) {
+  return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+
+/**
+ * Hand-rolled validator matching the repo convention (no AJV). Checks the
+ * stable envelope + the shapes of the observation arrays and artifact refs;
+ * it does NOT re-validate nested artifact bodies (those are referenced by
+ * hash, not embedded). Returns `{ ok, errors }` where each error is
+ * `{ code, message }`.
+ */
+export function validateRunRecord(record) {
+  const errors = [];
+  const add = (code, message) => errors.push({ code, message });
+
+  if (!record || typeof record !== "object" || Array.isArray(record)) {
+    add("record.type", "Run Record must be a JSON object.");
+    return { ok: false, errors };
+  }
+
+  for (const field of REQUIRED_FIELDS) {
+    if (!isNonEmptyString(record[field])) {
+      add(`record.${field}`, `Missing or empty required field "${field}".`);
+    }
+  }
+
+  if (record.schema_version != null && record.schema_version !== RUN_RECORD_SCHEMA) {
+    add("record.schema_version", `Expected schema_version "${RUN_RECORD_SCHEMA}".`);
+  }
+
+  if (record.argv_shape == null || !isStringArray(record.argv_shape)) {
+    add("record.argv_shape", "argv_shape is required and must be an array of strings (flag names, never values).");
+  }
+
+  // Toolkit provenance is optional and nullable: a missing manifest or a
+  // tarball install without gitHead must never block capture. When present
+  // the shapes are strict so the server-side segmentation can trust them.
+  if (record.surface_version != null && !(typeof record.surface_version === "string" && RUN_RECORD_SURFACE_VERSION_PATTERN.test(record.surface_version))) {
+    add("record.surface_version", "surface_version must be a MAJOR.MINOR.PATCH string or null.");
+  }
+  if (record.toolkit_commit != null && !(typeof record.toolkit_commit === "string" && RUN_RECORD_COMMIT_PATTERN.test(record.toolkit_commit))) {
+    add("record.toolkit_commit", "toolkit_commit must be a 7–40 character lowercase hex commit or null.");
+  }
+
+  if (!RUN_RECORD_CONSENT_STATES.includes(record.consent_state)) {
+    add("record.consent_state", `consent_state is required and must be one of: ${RUN_RECORD_CONSENT_STATES.join(", ")}.`);
+  }
+  if (record.consent_source != null && !["env", "file", "default"].includes(record.consent_source)) {
+    add("record.consent_source", 'consent_source must be one of: env, file, default (or omitted).');
+  }
+
+  if (typeof record.remit_attempted !== "boolean") {
+    add("record.remit_attempted", "remit_attempted is required and must be a boolean.");
+  }
+  if (record.remit_ok != null && typeof record.remit_ok !== "boolean") {
+    add("record.remit_ok", "remit_ok must be a boolean or null.");
+  }
+  if (record.remit_error != null && typeof record.remit_error !== "string") {
+    add("record.remit_error", "remit_error must be a string or null.");
+  }
+  if (record.remit_endpoint != null && (!isNonEmptyString(record.remit_endpoint) || !record.remit_endpoint.startsWith("/"))) {
+    add("record.remit_endpoint", "remit_endpoint must be a path beginning with / or null.");
+  }
+  if (record.remit_state != null && !RUN_RECORD_REMIT_STATES.includes(record.remit_state)) {
+    add("record.remit_state", `remit_state must be one of: ${RUN_RECORD_REMIT_STATES.join(", ")}.`);
+  }
+  if (record.remit_result != null && !RUN_RECORD_REMIT_RESULTS.includes(record.remit_result)) {
+    add("record.remit_result", `remit_result must be one of: ${RUN_RECORD_REMIT_RESULTS.join(", ")} (or null).`);
+  }
+  if (record.remit_base_kind != null && !RUN_RECORD_REMIT_BASE_KINDS.includes(record.remit_base_kind)) {
+    add("record.remit_base_kind", `remit_base_kind must be one of: ${RUN_RECORD_REMIT_BASE_KINDS.join(", ")} (or null).`);
+  }
+
+  if (record.qa_verdict_publish != null) {
+    for (const error of validateQaVerdictPublish(record.qa_verdict_publish)) errors.push(error);
+  }
+
+  if (record.identity != null) {
+    if (typeof record.identity !== "object" || Array.isArray(record.identity)) {
+      add("record.identity", "identity must be an object when present.");
+    }
+  }
+
+  if (record.artifacts != null) {
+    if (!Array.isArray(record.artifacts)) {
+      add("record.artifacts", "artifacts must be an array when present.");
+    } else {
+      record.artifacts.forEach((ref, index) => {
+        if (!ref || typeof ref !== "object" || Array.isArray(ref)) {
+          add(`record.artifacts[${index}]`, "each artifact ref must be an object.");
+          return;
+        }
+        if (!RUN_RECORD_ARTIFACT_KINDS.includes(ref.kind)) {
+          add(`record.artifacts[${index}].kind`, `unknown artifact kind "${ref.kind}". Allowed: ${RUN_RECORD_ARTIFACT_KINDS.join(", ")}.`);
+        }
+        if (!isNonEmptyString(ref.path)) {
+          add(`record.artifacts[${index}].path`, "artifact ref path is required and must be a non-empty string.");
+        }
+      });
+    }
+  }
+
+  if (record.observations != null) {
+    const obs = record.observations;
+    if (typeof obs !== "object" || Array.isArray(obs)) {
+      add("record.observations", "observations must be an object when present.");
+    } else {
+      if (obs.spec_validation_rule_ids != null && !isStringArray(obs.spec_validation_rule_ids)) {
+        add("record.observations.spec_validation_rule_ids", "spec_validation_rule_ids must be an array of strings.");
+      }
+      if (obs.finding_ids != null && !isStringArray(obs.finding_ids)) {
+        add("record.observations.finding_ids", "finding_ids must be an array of strings.");
+      }
+      if (obs.findings_journal != null) {
+        const j = obs.findings_journal;
+        if (typeof j !== "object" || Array.isArray(j)) {
+          add("record.observations.findings_journal", "findings_journal must be an object.");
+        } else {
+          if (j.malformed_count != null && !Number.isInteger(j.malformed_count)) add("record.observations.findings_journal.malformed_count", "malformed_count must be an integer.");
+          if (j.malformed_lines != null && (!Array.isArray(j.malformed_lines) || !j.malformed_lines.every(Number.isInteger))) {
+            add("record.observations.findings_journal.malformed_lines", "malformed_lines must be an array of integers.");
+          }
+        }
+      }
+      if (obs.doctor != null) {
+        const d = obs.doctor;
+        if (typeof d !== "object" || Array.isArray(d)) {
+          add("record.observations.doctor", "doctor must be an object.");
+        } else {
+          if (d.error_codes != null && !isStringArray(d.error_codes)) add("record.observations.doctor.error_codes", "error_codes must be an array of strings.");
+          if (d.warning_codes != null && !isStringArray(d.warning_codes)) add("record.observations.doctor.warning_codes", "warning_codes must be an array of strings.");
+        }
+      }
+      if (obs.qa != null) {
+        const q = obs.qa;
+        if (typeof q !== "object" || Array.isArray(q)) {
+          add("record.observations.qa", "qa must be an object.");
+        } else if (q.gap_classes != null && !isStringArray(q.gap_classes)) {
+          add("record.observations.qa.gap_classes", "gap_classes must be an array of strings.");
+        }
+      }
+    }
+  }
+
+  if (record.agent_usage != null) {
+    const usage = record.agent_usage;
+    if (typeof usage !== "object" || Array.isArray(usage)) {
+      add("record.agent_usage", "agent_usage must be an object when present.");
+    } else {
+      for (const field of ["input_tokens", "output_tokens", "tool_output_tokens", "total_tokens", "elapsed_ms"]) {
+        if (usage[field] != null && (!Number.isInteger(usage[field]) || usage[field] < 0)) {
+          add(`record.agent_usage.${field}`, `${field} must be a non-negative integer when present.`);
+        }
+      }
+      if (usage.model != null && typeof usage.model !== "string") add("record.agent_usage.model", "model must be a string when present.");
+      if (usage.source != null && typeof usage.source !== "string") add("record.agent_usage.source", "source must be a string when present.");
+    }
+  }
+
+  if (record.surfaces != null) {
+    if (!Array.isArray(record.surfaces)) {
+      add("record.surfaces", "surfaces must be an array when present.");
+    } else {
+      const unknown = record.surfaces.filter((s) => !RUN_RECORD_SURFACES.includes(s));
+      if (unknown.length) add("record.surfaces", `unknown surface(s): ${unknown.join(", ")}. Allowed: ${RUN_RECORD_SURFACES.join(", ")}.`);
+    }
+  }
+  if (record.primary_surface != null && !RUN_RECORD_SURFACES.includes(record.primary_surface)) {
+    add("record.primary_surface", `unknown primary_surface "${record.primary_surface}". Allowed: ${RUN_RECORD_SURFACES.join(", ")}.`);
+  }
+
+  if (record.lifecycle != null) {
+    for (const error of validateRunRecordLifecycle(record.lifecycle)) errors.push(error);
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+// Validate the embedded lifecycle block against the SAME rules the published
+// JSON schema enforces (types + stages[].name + numeric duration_ms). Exported
+// so the CLI can drop a corrupt/foreign lifecycle journal entry BEFORE assembly
+// rather than fail the whole Run Record at write time. Returns an error array.
+/**
+ * The `qa_verdict_publish` block: the same shape discipline as the remit
+ * fields, scoped to one verdict. Returns `{ code, message }` errors.
+ */
+export function validateQaVerdictPublish(block) {
+  const errors = [];
+  const add = (code, message) => errors.push({ code, message });
+  if (!block || typeof block !== "object" || Array.isArray(block)) {
+    add("record.qa_verdict_publish", "qa_verdict_publish must be an object or null.");
+    return errors;
+  }
+  if (!isNonEmptyString(block.verdict_run_id)) {
+    add("record.qa_verdict_publish.verdict_run_id", "verdict_run_id is required and must be a non-empty string.");
+  }
+  if (!RUN_RECORD_QA_VERDICT_PUBLISHERS.includes(block.publisher)) {
+    add("record.qa_verdict_publish.publisher", `publisher must be one of: ${RUN_RECORD_QA_VERDICT_PUBLISHERS.join(", ")}.`);
+  }
+  if (typeof block.attempted !== "boolean") {
+    add("record.qa_verdict_publish.attempted", "attempted is required and must be a boolean.");
+  }
+  if (block.ok != null && typeof block.ok !== "boolean") {
+    add("record.qa_verdict_publish.ok", "ok must be a boolean or null.");
+  }
+  if (block.error != null && typeof block.error !== "string") {
+    add("record.qa_verdict_publish.error", "error must be a string or null.");
+  }
+  if (block.endpoint != null && (!isNonEmptyString(block.endpoint) || !block.endpoint.startsWith("/"))) {
+    add("record.qa_verdict_publish.endpoint", "endpoint must be a path beginning with / or null.");
+  }
+  if (!RUN_RECORD_QA_VERDICT_PUBLISH_STATES.includes(block.state)) {
+    add("record.qa_verdict_publish.state", `state must be one of: ${RUN_RECORD_QA_VERDICT_PUBLISH_STATES.join(", ")}.`);
+  }
+  if (block.result != null && !RUN_RECORD_REMIT_RESULTS.includes(block.result)) {
+    add("record.qa_verdict_publish.result", `result must be one of: ${RUN_RECORD_REMIT_RESULTS.join(", ")} (or null).`);
+  }
+  if (block.base_kind != null && !RUN_RECORD_REMIT_BASE_KINDS.includes(block.base_kind)) {
+    add("record.qa_verdict_publish.base_kind", `base_kind must be one of: ${RUN_RECORD_REMIT_BASE_KINDS.join(", ")} (or null).`);
+  }
+  if (block.published_at != null && !isNonEmptyString(block.published_at)) {
+    add("record.qa_verdict_publish.published_at", "published_at must be a non-empty string or null.");
+  }
+  const allowed = new Set(["verdict_run_id", "publisher", "attempted", "ok", "error", "endpoint", "state", "result", "base_kind", "published_at"]);
+  for (const key of Object.keys(block)) {
+    if (!allowed.has(key)) add(`record.qa_verdict_publish.${key}`, `unknown qa_verdict_publish field "${key}".`);
+  }
+  return errors;
+}
+
+export function validateRunRecordLifecycle(lc) {
+  const errors = [];
+  const add = (code, message) => errors.push({ code, message });
+  if (typeof lc !== "object" || lc === null || Array.isArray(lc)) {
+    add("record.lifecycle", "lifecycle must be an object when present.");
+    return errors;
+  }
+  if (lc.command != null && typeof lc.command !== "string") add("record.lifecycle.command", "command must be a string.");
+  if (lc.run_id != null && typeof lc.run_id !== "string") add("record.lifecycle.run_id", "run_id must be a string or null.");
+  if (lc.argv_shape != null && !isStringArray(lc.argv_shape)) add("record.lifecycle.argv_shape", "argv_shape must be an array of strings.");
+  if (lc.exit_status != null && !Number.isInteger(lc.exit_status)) add("record.lifecycle.exit_status", "exit_status must be an integer or null.");
+  if (lc.started_at != null && typeof lc.started_at !== "string") add("record.lifecycle.started_at", "started_at must be a string or null.");
+  if (lc.completed_at != null && typeof lc.completed_at !== "string") add("record.lifecycle.completed_at", "completed_at must be a string or null.");
+  if (lc.duration_ms != null && typeof lc.duration_ms !== "number") add("record.lifecycle.duration_ms", "duration_ms must be a number or null.");
+  if (lc.wall_clock_duration_ms != null && typeof lc.wall_clock_duration_ms !== "number") add("record.lifecycle.wall_clock_duration_ms", "wall_clock_duration_ms must be a number or null.");
+  if (lc.repair_loop_count != null && !Number.isInteger(lc.repair_loop_count)) add("record.lifecycle.repair_loop_count", "repair_loop_count must be an integer or null.");
+  if (lc.stages != null) {
+    if (!Array.isArray(lc.stages)) {
+      add("record.lifecycle.stages", "stages must be an array when present.");
+    } else {
+      lc.stages.forEach((stage, index) => {
+        if (!stage || typeof stage !== "object" || Array.isArray(stage) || typeof stage.name !== "string") {
+          add(`record.lifecycle.stages[${index}].name`, "each stage requires a string name (matches the published schema).");
+        } else {
+          if (stage.duration_ms != null && typeof stage.duration_ms !== "number") add(`record.lifecycle.stages[${index}].duration_ms`, "stage duration_ms must be a number or null.");
+          if (stage.exit_status != null && !Number.isInteger(stage.exit_status)) add(`record.lifecycle.stages[${index}].exit_status`, "stage exit_status must be an integer or null.");
+        }
+      });
+    }
+  }
+  return errors;
+}
+
+// ---------------------------------------------------------------------------
+// Capture: mint a canonical run_id, assemble the manifest from already-read
+// artifacts (the CLI reuses the same readers `findings harvest` uses), and
+// write it to .campaign-runtime/run-records/<run_id>.json. Assembly is a pure
+// function over inputs so it is unit-testable without a packet on disk.
+// ---------------------------------------------------------------------------
+
+/**
+ * Mint the single canonical run_id at the run boundary. Threaded through the
+ * run so every artifact and finding correlates, and used as the remit
+ * idempotency key.
+ */
+export function mintRunId(now = new Date()) {
+  return `run_${now.getTime()}_${randomBytes(4).toString("hex")}`;
+}
+
+function sanitizeRunId(runId) {
+  return String(runId).replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 128) || "unnamed";
+}
+
+/**
+ * Resolve where a Run Record is written: <baseDir>/.campaign-runtime/
+ * run-records/<run_id>.json. baseDir is the run root (the CLI passes the
+ * packet's directory) so the records sit next to the findings journal.
+ */
+export function resolveRunRecordPath(runId, baseDir = process.cwd()) {
+  return join(resolve(baseDir), RUN_RECORDS_DIR_REL_PATH, `${sanitizeRunId(runId)}.json`);
+}
+
+function extractDoctorObservations(doctor) {
+  if (!doctor || typeof doctor !== "object") return null;
+  const codes = (issues) => (Array.isArray(issues) ? issues : []).map((issue) => issue?.code).filter((code) => typeof code === "string");
+  return {
+    status: typeof doctor.status === "string" ? doctor.status : null,
+    error_codes: codes(doctor.errors),
+    warning_codes: codes(doctor.warnings),
+    ready_count: Array.isArray(doctor.ready) ? doctor.ready.length : null,
+  };
+}
+
+// spec.validation issues carry the per-violation rule identity in `detail`
+// (ruleId + path + data). Pull the rule IDs so a finding maps back to the
+// exact rule that fired.
+function extractSpecValidationRuleIds(doctor) {
+  if (!doctor || typeof doctor !== "object") return [];
+  const ids = [];
+  for (const issue of [...(doctor.errors || []), ...(doctor.warnings || [])]) {
+    if (issue?.code === "spec.validation" && typeof issue.detail?.ruleId === "string") {
+      ids.push(issue.detail.ruleId);
+    }
+  }
+  return [...new Set(ids)];
+}
+
+function extractQaObservations(verdict) {
+  if (!verdict || typeof verdict !== "object") return null;
+  const families = new Set();
+  for (const exception of Array.isArray(verdict.exceptions) ? verdict.exceptions : []) {
+    if (typeof exception?.family === "string") families.add(exception.family);
+  }
+  return {
+    disposition: typeof verdict.disposition === "string" ? verdict.disposition : null,
+    gap_classes: [...families],
+  };
+}
+
+// Adapter decisions live in (precedence): report.adapter_decisions ->
+// context.adapter_decisions -> packet.source_html.adapter_contract — the same
+// precedence the doctor uses when it validates them.
+function selectAdapterDecisions({ packet, report, context }) {
+  return (
+    report?.adapter_decisions
+    || context?.adapter_decisions
+    || packet?.source_html?.adapter_contract
+    || null
+  );
+}
+
+function extractAdapterDecisions(decisions) {
+  if (!decisions || typeof decisions !== "object" || Array.isArray(decisions)) return null;
+  const out = {};
+  for (const key of ADAPTER_DECISION_STRATEGY_FIELDS) {
+    if (typeof decisions[key] === "string") out[key] = decisions[key];
+  }
+  if (typeof decisions.template_files_copied?.status === "string") {
+    out.template_files_copied_status = decisions.template_files_copied.status;
+  }
+  return Object.keys(out).length ? out : null;
+}
+
+function selectRunFindings(journal, runId) {
+  const findings = Array.isArray(journal?.findings)
+    ? journal.findings
+    : Array.isArray(journal)
+      ? journal
+      : [];
+  return findings.filter((finding) => typeof finding?.id === "string" && finding.run_id === runId);
+}
+
+/**
+ * The per-run findings snapshot, by ID. Exact (not time-inferred): only
+ * findings explicitly stamped with this run_id are included. Findings
+ * captured before Run Telemetry (no run_id) are correctly excluded.
+ */
+export function selectRunFindingIds(journal, runId) {
+  return selectRunFindings(journal, runId).map((finding) => finding.id);
+}
+
+function normalizeIdentity(identity = {}) {
+  return {
+    map_id: identity.map_id ?? null,
+    campaign_slug: identity.campaign_slug ?? null,
+    template_family: identity.template_family ?? null,
+    entry_point_shape: identity.entry_point_shape ?? null,
+  };
+}
+
+function normalizeRemitState(remit) {
+  if (RUN_RECORD_REMIT_STATES.includes(remit?.state)) return remit.state;
+  if (remit?.attempted) return remit.ok === true ? "ok" : "failed";
+  return "skipped";
+}
+
+function normalizeAgentUsage(usage) {
+  if (!usage || typeof usage !== "object" || Array.isArray(usage)) return null;
+  const out = {};
+  for (const field of ["input_tokens", "output_tokens", "tool_output_tokens", "total_tokens", "elapsed_ms"]) {
+    if (Number.isInteger(usage[field]) && usage[field] >= 0) out[field] = usage[field];
+  }
+  if (isNonEmptyString(usage.model)) out.model = usage.model.trim();
+  if (isNonEmptyString(usage.source)) out.source = usage.source.trim();
+  return Object.keys(out).length ? out : null;
+}
+
+const PRIMARY_SURFACE_PRIORITY = ["platform", "template", "design-source", "spec-rule", "cli", "skill", "docs"];
+
+const ADAPTER_DECISION_SURFACE_BY_FIELD = {
+  raw_html_conversion_status: "design-source",
+  source_asset_strategy: "design-source",
+  route_rewrite_policy: "design-source",
+  wrapper_policy: "design-source",
+  script_style_reference_policy: "design-source",
+  cta_rewrite_policy: "design-source",
+  config_script_strategy: "template",
+  commerce_shell_adoption: "template",
+  frontmatter_policy: "template",
+  layout_choice: "template",
+  template_files_copied_status: "template",
+};
+
+function addSurface(counts, surface) {
+  if (!RUN_RECORD_SURFACES.includes(surface)) return;
+  counts.set(surface, (counts.get(surface) || 0) + 1);
+}
+
+function surfaceFromOwner(value) {
+  if (!isNonEmptyString(value)) return null;
+  const normalized = value.trim().toLowerCase().replace(/_/g, "-");
+  if (RUN_RECORD_SURFACES.includes(normalized)) return normalized;
+  const aliases = {
+    design: "design-source",
+    source: "design-source",
+    "source-html": "design-source",
+    spec: "spec-rule",
+    rule: "spec-rule",
+    rules: "spec-rule",
+    "spec-rules": "spec-rule",
+    doc: "docs",
+    documentation: "docs",
+    tooling: "cli",
+    tool: "cli",
+    automation: "cli",
+    templates: "template",
+  };
+  return aliases[normalized] || null;
+}
+
+function addIssueSurfaces(counts, code) {
+  if (!isNonEmptyString(code)) return;
+  const normalized = code.trim();
+  if (normalized === "spec.validation" || normalized.startsWith("scope.") || normalized.startsWith("build_brief.")) {
+    addSurface(counts, "spec-rule");
+  }
+  if (normalized.startsWith("adapter.") || normalized.startsWith("source_html.") || normalized === "context.prompts_required") {
+    addSurface(counts, "design-source");
+  }
+  if (normalized.startsWith("template_contract.") || normalized.startsWith("frontmatter.")) {
+    addSurface(counts, "template");
+  }
+  if (normalized.startsWith("qa.") || normalized.startsWith("report.proof_policy") || normalized.startsWith("deploy.") || normalized === "campaign.allowed_domains_confirmed") {
+    addSurface(counts, "platform");
+  }
+}
+
+function addFindingSurfaces(counts, finding) {
+  const ownerSurface = surfaceFromOwner(finding?.suggested_owner);
+  if (ownerSurface) addSurface(counts, ownerSurface);
+
+  switch (finding?.kind) {
+    case "docs_gap":
+      addSurface(counts, "docs");
+      break;
+    case "missing_prompt":
+      addSurface(counts, "skill");
+      break;
+    case "automation_gap":
+      addSurface(counts, "cli");
+      break;
+  }
+
+  switch (finding?.stage) {
+    case "setup":
+    case "build":
+    case "polish":
+      addSurface(counts, "template");
+      break;
+    case "deploy":
+    case "qa":
+    case "test-order":
+      addSurface(counts, "platform");
+      break;
+    case "intake":
+    case "start":
+      addSurface(counts, "design-source");
+      break;
+    case "doctor":
+      addSurface(counts, "spec-rule");
+      break;
+    case "next":
+      addSurface(counts, "cli");
+      break;
+  }
+}
+
+function addAdapterDecisionSurfaces(counts, adapter) {
+  if (!adapter) return;
+  for (const [field, surface] of Object.entries(ADAPTER_DECISION_SURFACE_BY_FIELD)) {
+    if (adapter[field] != null) addSurface(counts, surface);
+  }
+}
+
+function deriveSurfaceCounts({ doctor, adapter, qaObs, journal, runId }) {
+  const counts = new Map();
+
+  // Counts are signal-strength hints for primary-surface selection, not exact
+  // event tallies; one run can legitimately emit several signals for a surface.
+  for (const issue of [...(doctor?.errors || []), ...(doctor?.warnings || [])]) {
+    addIssueSurfaces(counts, issue?.code);
+  }
+  addAdapterDecisionSurfaces(counts, adapter);
+  if (qaObs && (qaObs.disposition || qaObs.gap_classes?.length)) addSurface(counts, "platform");
+
+  for (const finding of selectRunFindings(journal, runId)) {
+    addFindingSurfaces(counts, finding);
+  }
+
+  return counts;
+}
+
+function rankSurface(surface, counts, preferredSurfaces) {
+  const base = rankSurfaceByPriority(surface, counts);
+  const preferredIndex = preferredSurfaces.indexOf(surface);
+  return {
+    ...base,
+    preferredIndex: preferredIndex === -1 ? Number.POSITIVE_INFINITY : preferredIndex,
+  };
+}
+
+function rankSurfaceByPriority(surface, counts) {
+  const priority = PRIMARY_SURFACE_PRIORITY.indexOf(surface);
+  return {
+    count: counts.get(surface) || 0,
+    priority: priority === -1 ? PRIMARY_SURFACE_PRIORITY.length : priority,
+  };
+}
+
+function selectPrimarySurface(surfaces, counts, preferredSurfaces = []) {
+  return [...surfaces].sort((a, b) => {
+    const left = rankSurface(a, counts, preferredSurfaces);
+    const right = rankSurface(b, counts, preferredSurfaces);
+    return right.count - left.count
+      || left.preferredIndex - right.preferredIndex
+      || left.priority - right.priority
+      || a.localeCompare(b);
+  })[0] || null;
+}
+
+function uniqueEntries(entries) {
+  const out = [];
+  const seen = new Set();
+  for (const entry of entries) {
+    if (!entry || seen.has(entry)) continue;
+    seen.add(entry);
+    out.push(entry);
+  }
+  return out;
+}
+
+/**
+ * Assemble a Run Record manifest from already-read inputs. Pure: the caller
+ * does the file reading (reusing the doctor / packet / report / verdict /
+ * journal readers) and passes the parsed structures in. Missing identity or
+ * absent artifacts never throw — capture is best-effort.
+ */
+export function assembleRunRecord({
+  runId,
+  packageVersion,
+  surfaceVersion = null,
+  toolkitCommit = null,
+  command,
+  argvShape = [],
+  consent = { state: "off", source: "default" },
+  remit = { attempted: false, ok: null, error: null, endpoint: null },
+  identity = {},
+  artifacts = [],
+  packet = null,
+  doctor = null,
+  report = null,
+  context = null,
+  qaVerdict = null,
+  journal = { findings: [] },
+  surfaces = [],
+  primarySurface = null,
+  surfaceConfidence = null,
+  lifecycle = null,
+  agentUsage = null,
+  qaVerdictPublish = null,
+  now = new Date(),
+} = {}) {
+  const observations = {};
+  const doctorObs = extractDoctorObservations(doctor);
+  if (doctorObs) {
+    observations.doctor = doctorObs;
+    observations.spec_validation_rule_ids = extractSpecValidationRuleIds(doctor);
+  }
+  const adapter = extractAdapterDecisions(selectAdapterDecisions({ packet, report, context }));
+  if (adapter) observations.adapter_decisions = adapter;
+  const qaObs = extractQaObservations(qaVerdict);
+  if (qaObs) observations.qa = qaObs;
+  observations.finding_ids = selectRunFindingIds(journal, runId);
+  const malformedJournalLines = Array.isArray(journal?.malformed)
+    ? journal.malformed.map((entry) => entry?.line).filter(Number.isInteger)
+    : [];
+  if (malformedJournalLines.length) {
+    observations.findings_journal = {
+      malformed_count: malformedJournalLines.length,
+      malformed_lines: malformedJournalLines,
+    };
+  }
+
+  const record = {
+    schema_version: RUN_RECORD_SCHEMA,
+    run_id: runId,
+    package_version: packageVersion,
+    surface_version: typeof surfaceVersion === "string" && RUN_RECORD_SURFACE_VERSION_PATTERN.test(surfaceVersion) ? surfaceVersion : null,
+    toolkit_commit: typeof toolkitCommit === "string" && RUN_RECORD_COMMIT_PATTERN.test(toolkitCommit) ? toolkitCommit : null,
+    command,
+    argv_shape: Array.isArray(argvShape) ? argvShape : [],
+    created_at: now.toISOString(),
+    consent_state: consent?.state === "on" ? "on" : "off",
+    consent_source: consent?.source ?? null,
+    remit_attempted: Boolean(remit?.attempted),
+    remit_ok: remit?.ok ?? null,
+    remit_error: remit?.error ?? null,
+    remit_endpoint: remit?.endpoint ?? null,
+    remit_state: normalizeRemitState(remit),
+    remit_result: RUN_RECORD_REMIT_RESULTS.includes(remit?.result) ? remit.result : null,
+    remit_base_kind: RUN_RECORD_REMIT_BASE_KINDS.includes(remit?.base_kind) ? remit.base_kind : null,
+    identity: normalizeIdentity(identity),
+    artifacts: Array.isArray(artifacts) ? artifacts : [],
+    observations,
+  };
+
+  const surfaceCounts = deriveSurfaceCounts({ doctor, adapter, qaObs, journal, runId });
+  const inferredSurfaces = PRIMARY_SURFACE_PRIORITY.filter((surface) => surfaceCounts.has(surface));
+  const cleanSurfaces = Array.isArray(surfaces)
+    ? surfaces.filter(isNonEmptyString).map((surface) => surface.trim()).filter((surface) => RUN_RECORD_SURFACES.includes(surface))
+    : [];
+  const combinedSurfaces = uniqueEntries([...cleanSurfaces, ...inferredSurfaces]);
+  if (combinedSurfaces.length) record.surfaces = combinedSurfaces;
+  if (isNonEmptyString(primarySurface)) {
+    record.primary_surface = primarySurface.trim();
+  } else {
+    const explicitSurfaces = cleanSurfaces.filter((surface) => RUN_RECORD_SURFACES.includes(surface));
+    const candidateSurfaces = combinedSurfaces.filter((surface) => RUN_RECORD_SURFACES.includes(surface));
+    const inferredPrimary = selectPrimarySurface(candidateSurfaces, surfaceCounts, explicitSurfaces);
+    if (inferredPrimary) record.primary_surface = inferredPrimary;
+  }
+  if (surfaceConfidence) record.surface_confidence = surfaceConfidence;
+  if (lifecycle && typeof lifecycle === "object" && !Array.isArray(lifecycle)) record.lifecycle = lifecycle;
+  const normalizedUsage = normalizeAgentUsage(agentUsage);
+  if (normalizedUsage) record.agent_usage = normalizedUsage;
+  // Present only when a publish outcome is known: an absent block reads as
+  // "nothing recorded", which is what every record before this field says.
+  if (qaVerdictPublish && typeof qaVerdictPublish === "object" && !Array.isArray(qaVerdictPublish)) record.qa_verdict_publish = qaVerdictPublish;
+
+  return record;
+}
+
+/**
+ * Validate then write a Run Record to its canonical path. Throws on an
+ * invalid record (a malformed manifest is a build-tooling bug, not run state
+ * to swallow). Returns the written path.
+ */
+export function writeRunRecord(record, { baseDir = process.cwd() } = {}) {
+  const validation = validateRunRecord(record);
+  if (!validation.ok) {
+    const detail = validation.errors.map((error) => `[${error.code}] ${error.message}`).join("; ");
+    throw new Error(`Run Record failed validation; refusing to write: ${detail}`);
+  }
+  const path = resolveRunRecordPath(record.run_id, baseDir);
+  mkdirSync(dirname(path), { recursive: true });
+  const tmpPath = `${path}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+  writeFileSync(tmpPath, `${JSON.stringify(record, null, 2)}\n`);
+  renameSync(tmpPath, path);
+  return path;
+}
+
+// Run Records are machine-local (they are in the runtime-state ignore block), so
+// `next` reads them best-effort: an absent directory is the normal case, not an
+// error, and a slow or hostile records directory must never stall orchestration.
+// Bounded, but bounded well above any plausible per-target history rather than
+// at the working-set size. The old bound was 50, which is reachable on a
+// long-lived campaign, and truncation here is not a performance trade — it
+// silently changes the ANSWER: an older matching record outside the window
+// reads as `no_record` or `foreign_campaign`, which asks the operator to
+// re-make a record that already exists. That is the exact regression this
+// closeout work is closing, so the cap is now a runaway-directory guard and
+// nothing else. The parse cost stays tolerable because `readJson` failures are
+// swallowed per file, so a malformed record still costs one failed parse rather
+// than aborting the scan.
+const RUN_RECORDS_SCAN_LIMIT = 5000;
+
+// Run ids are `run_<epoch-ms>_<hex>`, and `readdirSync().sort().reverse()` only
+// ordered those correctly by accident: lexicographic order matches numeric order
+// only while every id has the same digit count. A 13-to-14 digit rollover (or a
+// hand-named file, or an id minted on a machine with a different clock) flips
+// "newest" silently. Parse the timestamp and compare it as a number; anything
+// unparseable sorts last, because a file that cannot say when it was written
+// must never displace one that can.
+// A Run Record file is named for its run id, which always carries the `run_`
+// prefix. Admitting every *.json in the directory means an operator note, an
+// editor backup, or any unrelated artifact that happens to land there gets
+// parsed as run state and — worse — can be selected as THE previous run.
+// Filter at scan time rather than leaning on the orderer's
+// unstamped-sorts-last fallback: that fallback keeps ordering deterministic,
+// it does not make a stray file not a record.
+//
+// Prefix, deliberately, and not the full minted `run_<epoch-ms>_<hex>` shape.
+// mintRunId produces that shape, but `--run-id` lets an operator supply their
+// own and writeRunRecord writes whatever it is given after sanitizing — so a
+// digits-required pattern would hide real records (the closeout suite writes
+// `run_synth_*` ones) and report a run that exists as missing. That failure is
+// worse than the one this filter closes.
+export const RUN_RECORD_FILE_NAME_PATTERN = /^run_.+\.json$/;
+
+export function orderRunRecordFileNames(names) {
+  const stamp = (name) => {
+    const match = /^run_(\d+)_/.exec(name);
+    if (!match) return null;
+    const value = Number(match[1]);
+    return Number.isSafeInteger(value) ? value : null;
+  };
+  return [...names].sort((a, b) => {
+    const left = stamp(a);
+    const right = stamp(b);
+    if (left !== right) {
+      if (left === null) return 1;
+      if (right === null) return -1;
+      return right - left;
+    }
+    // Same stamp, or both unstamped: fall back to a stable name comparison so
+    // the order is at least deterministic across platforms.
+    return a < b ? 1 : a > b ? -1 : 0;
+  });
+}
+
+export function readRunRecordsForTarget(baseDir) {
+  try {
+    const dir = join(resolve(baseDir), RUN_RECORDS_DIR_REL_PATH);
+    if (!existsSync(dir) || !statSync(dir).isDirectory()) return [];
+    const names = orderRunRecordFileNames(readdirSync(dir).filter((name) => RUN_RECORD_FILE_NAME_PATTERN.test(name)))
+      .slice(0, RUN_RECORDS_SCAN_LIMIT);
+    const entries = [];
+    for (const name of names) {
+      const path = join(dir, name);
+      try {
+        entries.push({ path, record: JSON.parse(readFileSync(path, "utf8")) });
+      } catch {
+        // One corrupt record must not hide a good one beside it. The assessor
+        // ignores unreadable entries rather than treating them as evidence.
+        entries.push({ path, record: null });
+      }
+    }
+    return entries;
+  } catch {
+    return [];
+  }
+}