@nimiplatform/nimi-coding 0.1.0 → 0.2.0

package/cli/lib/topic-goal.mjs

@@ -9,9 +9,10 @@ import { parseYamlText } from "./yaml-helpers.mjs";
 import { loadGovernanceConfig } from "./internal/governance/config.mjs";
 
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
-const TOPIC_GOAL_CONTRACT_REF = "nimi-coding/contracts/topic-goal.schema.yaml";
+const PACKAGE_REF_PREFIX = "package://@nimiplatform/nimi-coding/";
+const TOPIC_GOAL_CONTRACT_REF = `${PACKAGE_REF_PREFIX}contracts/topic-goal.schema.yaml`;
 const HOST_TOPIC_GOAL_CONTRACT_REF = ".nimi/contracts/topic-goal.schema.yaml";
-const FORBIDDEN_SHORTCUTS_REF = "nimi-coding/contracts/forbidden-shortcuts.catalog.yaml";
+const FORBIDDEN_SHORTCUTS_REF = `${PACKAGE_REF_PREFIX}contracts/forbidden-shortcuts.catalog.yaml`;
 const HOST_FORBIDDEN_SHORTCUTS_REF = ".nimi/contracts/forbidden-shortcuts.catalog.yaml";
 const GOAL_COMMAND_MAX_CHARS = 1500;
 
@@ -41,7 +42,8 @@ const REQUIRED_STOP_KEYS = [
   "silent_owner_cut_reopen",
 ];
 
-const EXECUTABLE_WAVE_STATES = new Set(["implementation_admitted", "implementation_active"]);
+const EXECUTION_STAGE_WAVE_STATES = new Set(["preflight_admitted", "implementation_admitted", "implementation_active"]);
+const ADMISSION_READY_WAVE_STATES = new Set(["candidate", "preflight_draft", "needs_revision"]);
 const TERMINAL_WAVE_STATES = new Set(["closed", "retired", "superseded"]);
 const WAVE_ID_PATTERN = /^wave-[a-z0-9]+(?:-[a-z0-9]+)*$/;
 
@@ -83,7 +85,7 @@ function projectRef(projectRoot, absolutePath) {
 }
 
 function packagePath(relativePath) {
-  return path.join(PACKAGE_ROOT, relativePath.replace(/^nimi-coding\//, ""));
+  return path.join(PACKAGE_ROOT, relativePath.replace(PACKAGE_REF_PREFIX, ""));
 }
 
 function check(id, ok, message, extra = {}) {
@@ -112,12 +114,58 @@ function hasUnresolvedPlaceholder(text) {
     || /\?\?\?/.test(text);
 }
 
+function normalizeCommandText(command) {
+  return String(command ?? "").replace(/\s+/g, " ").trim();
+}
+
+function validationCommandScope(command) {
+  const scopeMatch = command.match(/(?:^|\s)--scope\s+([^\s]+)/u);
+  if (scopeMatch) {
+    return scopeMatch[1];
+  }
+  if (command.includes("topic validate graph")) {
+    return "graph";
+  }
+  if (command.includes("topic validate")) {
+    return "topic";
+  }
+  if (command.includes("test")) {
+    return "test";
+  }
+  return "selected wave";
+}
+
+function validationCommandEntry(command) {
+  const normalized = normalizeCommandText(command);
+  return {
+    command: normalized,
+    cwd: ".",
+    profile: null,
+    scope: validationCommandScope(normalized),
+    required: true,
+    expected_exit_code: 0,
+  };
+}
+
+function mergeValidationCommandEntries(entries) {
+  const seen = new Set();
+  const output = [];
+  for (const entry of entries) {
+    if (!entry.command || seen.has(entry.command)) {
+      continue;
+    }
+    seen.add(entry.command);
+    output.push(entry);
+  }
+  return output;
+}
+
 function parseValidationCommands(artifactTexts) {
   const commands = [];
   const commandPattern = /\b(?:pnpm|npm|npx|node|go|cargo)\s+[^\n`]+/g;
   for (const { text } of artifactTexts) {
     for (const match of text.matchAll(commandPattern)) {
-      const command = match[0].replace(/[.)\]]+$/u, "").trim();
+      const command = normalizeCommandText(match[0].replace(/[.)\]]+$/u, ""));
       if (command.includes("<") || command.includes("topic goal")) {
         continue;
       }
@@ -126,20 +174,18 @@ function parseValidationCommands(artifactTexts) {
       }
     }
   }
-  return commands.map((command) => ({
-    command,
-    cwd: ".",
-    profile: null,
-    scope: command.includes("topic validate graph")
-      ? "graph"
-      : command.includes("topic validate")
-        ? "topic"
-        : command.includes("test")
-          ? "test"
-          : "selected wave",
-    required: true,
-    expected_exit_code: 0,
-  }));
+  return commands.map(validationCommandEntry);
+}
+
+function selectedWaveValidationCommands(selectedWave) {
+  const commands = [
+    ...(Array.isArray(selectedWave?.validation_commands) ? selectedWave.validation_commands : []),
+    ...(Array.isArray(selectedWave?.source_sweep_design?.validation_commands) ? selectedWave.source_sweep_design.validation_commands : []),
+  ];
+  return commands
+    .map(normalizeCommandText)
+    .filter((command) => command.length > 0)
+    .map(validationCommandEntry);
 }
 
 function parseHumanGates(preflightText) {
@@ -212,10 +258,23 @@ function selectedWaveResolution(topic) {
   const selectedTarget = typeof topic.selected_next_target === "string" ? topic.selected_next_target : null;
   const matchingWaves = selectedTarget === null ? [] : waves.filter((wave) => wave.wave_id === selectedTarget);
   const selectedWaves = waves.filter((wave) => wave.selected === true);
+  const terminalIds = new Set(waves.filter((wave) => TERMINAL_WAVE_STATES.has(wave.state)).map((wave) => wave.wave_id));
+  const allWavesTerminal = waves.length > 0 && waves.every((wave) => TERMINAL_WAVE_STATES.has(wave.state));
+  const deterministicNextWave = allWavesTerminal ? null : waves.find((wave) => {
+    if (TERMINAL_WAVE_STATES.has(wave.state)) return false;
+    if (!ADMISSION_READY_WAVE_STATES.has(wave.state)) return false;
+    const deps = Array.isArray(wave.deps) ? wave.deps : [];
+    return deps.every((dep) => terminalIds.has(dep));
+  }) ?? null;
+  const selectedWave = matchingWaves.length === 1 ? matchingWaves[0] : null;
+  const executionStartWave = selectedWave ?? deterministicNextWave;
   return {
     waves,
     selectedTarget,
-    selectedWave: matchingWaves.length === 1 ? matchingWaves[0] : null,
+    selectedWave,
+    executionStartWave,
+    deterministicNextWave,
+    allWavesTerminal,
     matchingWaveCount: matchingWaves.length,
     selectedWaves,
   };
@@ -225,9 +284,12 @@ function dependencyEvidence(lineageRefs, depId) {
   return lineageRefs.some((ref) => fileReferencesWave(ref, depId) && /^(result|closeout)-/.test(ref));
 }
 
-function buildGoalCommand(topicId, waveId, sourceArtifacts) {
+function buildGoalCommand(topicId, executionStartWave, sourceArtifacts) {
   const artifactList = sourceArtifacts.map((ref) => path.basename(ref)).join(", ");
-  return `/goal Execute topic ${topicId} from selected admitted wave ${waveId}. Treat ${artifactList} as the execution contract. Implement only the admitted scope. Do not reinterpret scope, change authority ownership, lower readiness gates, mutate topic state during goal generation, invoke Codex automatically, delete evidence, skip admitted coverage, or emit fallback goals. After meaningful implementation steps, run topic validate, topic validate graph, and focused tests. Stop only for declared human gates, authority/scope changes, lowered gates, destructive evidence deletion, or blockers requiring contract changes. Complete by writing required result/closeout artifacts and reporting validation evidence, blockers, and residual risk.`;
+  const cursorClause = executionStartWave
+    ? `, starting at execution cursor ${executionStartWave.wave_id}`
+    : "";
+  return `/goal Execute topic ${topicId} to completion${cursorClause}. This is a topic-level goal: do not mark complete after a single wave closeout. Use nimicoding topic-runner run ${topicId} --run-id <run-id> --adapter codex to advance deterministic wave admission, preflight, implementation, validation, result recording, wave closeout, and next-wave selection. Treat ${artifactList} as the execution contract. Wave closeout is a validation boundary only. Complete only after all waves are terminal and topic true-close/closeout evidence is recorded. Stop only for declared human gates, authority/scope changes, lowered gates, destructive evidence deletion, unresolved blockers, or required contract changes.`;
 }
 
 async function checkHostProjection(projectRoot) {
@@ -276,6 +338,7 @@ export async function buildTopicGoal(projectRoot, options) {
   const lineageWaveIds = [
     ...new Set([
       resolution.selectedTarget,
+      resolution.executionStartWave?.wave_id,
       ...resolution.waves.flatMap((wave) => Array.isArray(wave.deps) ? wave.deps : []),
     ].filter(Boolean)),
   ];
@@ -287,16 +350,31 @@ export async function buildTopicGoal(projectRoot, options) {
   }
   const sourceArtifacts = [...REQUIRED_ARTIFACTS, ...lineageRefs];
   const sourceArtifactTexts = [...artifactTexts, ...lineageTexts];
-  const validationCommands = parseValidationCommands(sourceArtifactTexts);
+  const validationCommands = mergeValidationCommandEntries([
+    ...selectedWaveValidationCommands(resolution.executionStartWave),
+    ...parseValidationCommands(sourceArtifactTexts.filter((artifact) => artifact.ref !== "topic.yaml")),
+  ]);
   const humanGates = parseHumanGates(textByRef.get("preflight.md") ?? "");
   const forbiddenCatalog = await loadForbiddenShortcutsCatalog(projectRoot);
   const hostProjection = await checkHostProjection(projectRoot);
-  const selectedWave = resolution.selectedWave;
-  const deps = Array.isArray(selectedWave?.deps) ? selectedWave.deps : [];
+  const executionStartWave = resolution.executionStartWave;
+  const deps = Array.isArray(executionStartWave?.deps) ? executionStartWave.deps : [];
   const depFailures = deps.filter((depId) => {
     const depWave = resolution.waves.find((wave) => wave.wave_id === depId);
     return !depWave || !TERMINAL_WAVE_STATES.has(depWave.state) || !dependencyEvidence(lineageRefs, depId);
   });
+  const selectedTargetReady = resolution.selectedTarget === null || resolution.selectedTarget === "topic_design_baseline"
+    ? resolution.deterministicNextWave !== null || resolution.allWavesTerminal
+    : resolution.matchingWaveCount === 1 && WAVE_ID_PATTERN.test(resolution.selectedTarget);
+  const selectedWaveSourceReady = resolution.selectedTarget === null || resolution.selectedTarget === "topic_design_baseline"
+    ? resolution.selectedWaves.length === 0
+    : resolution.selectedWaves.length === 1 && resolution.selectedWaves[0]?.wave_id === resolution.selectedTarget;
+  const executionStartWaveReady = executionStartWave
+    ? EXECUTION_STAGE_WAVE_STATES.has(executionStartWave.state) || ADMISSION_READY_WAVE_STATES.has(executionStartWave.state)
+    : resolution.allWavesTerminal;
+  const executionStartGoalPresent = executionStartWave
+    ? typeof executionStartWave.primary_closure_goal === "string" && executionStartWave.primary_closure_goal.trim().length > 0
+    : resolution.allWavesTerminal;
   const commands = validationCommands.map((entry) => entry.command);
 
   const checks = [
@@ -307,12 +385,12 @@ export async function buildTopicGoal(projectRoot, options) {
     check("strict_policy_active", topicReport.ignoredByPolicy !== true, topicReport.ignoredByPolicy ? "topic root is ignored by strict validation policy" : "topic root is under strict validation policy"),
     check("parallel_truth_forbidden", loaded.topic.parallel_truth === "forbidden", `parallel_truth is ${loaded.topic.parallel_truth ?? "missing"}`),
     check("profile_resolves", profile.ok, profile.ok ? `profile resolves as ${profile.profile}` : `unknown or mismatched profile ${profile.profile ?? "missing"}`),
-    check("selected_target_wave_resolves", resolution.matchingWaveCount === 1 && WAVE_ID_PATTERN.test(resolution.selectedTarget ?? ""), `selected_next_target is ${resolution.selectedTarget ?? "missing"}`),
-    check("selected_wave_single_source", resolution.selectedWaves.length === 1 && resolution.selectedWaves[0]?.wave_id === resolution.selectedTarget, `selected waves: ${resolution.selectedWaves.map((wave) => wave.wave_id).join(", ") || "none"}`),
-    check("wave_option_matches_selected", options.wave === null || options.wave === resolution.selectedTarget, options.wave === null ? "no wave assertion provided" : `--wave is ${options.wave}`),
-    check("selected_wave_executable", selectedWave ? EXECUTABLE_WAVE_STATES.has(selectedWave.state) : false, selectedWave ? `selected wave state is ${selectedWave.state}` : "selected wave does not resolve"),
+    check("selected_target_wave_resolves", selectedTargetReady, resolution.selectedTarget ? `selected_next_target is ${resolution.selectedTarget}` : `execution cursor is ${executionStartWave?.wave_id ?? (resolution.allWavesTerminal ? "topic closeout" : "missing")}`),
+    check("selected_wave_single_source", selectedWaveSourceReady, `selected waves: ${resolution.selectedWaves.map((wave) => wave.wave_id).join(", ") || "none"}`),
+    check("wave_option_matches_selected", options.wave === null || options.wave === executionStartWave?.wave_id, options.wave === null ? "no wave assertion provided" : `--wave is ${options.wave}`),
+    check("selected_wave_executable", executionStartWaveReady, executionStartWave ? `execution cursor wave state is ${executionStartWave.state}` : resolution.allWavesTerminal ? "topic is ready for topic closeout" : "execution cursor does not resolve"),
     check("selected_wave_dependencies_terminal", depFailures.length === 0, depFailures.length === 0 ? "selected wave dependencies are terminal by lifecycle evidence" : `dependencies are not terminal by evidence: ${depFailures.join(", ")}`),
-    check("selected_wave_goal_present", typeof selectedWave?.primary_closure_goal === "string" && selectedWave.primary_closure_goal.trim().length > 0, selectedWave?.primary_closure_goal ? "selected wave declares primary_closure_goal" : "selected wave is missing primary_closure_goal"),
+    check("selected_wave_goal_present", executionStartGoalPresent, executionStartWave?.primary_closure_goal ? "execution cursor declares primary_closure_goal" : resolution.allWavesTerminal ? "all waves terminal; topic closeout is the next goal" : "execution cursor is missing primary_closure_goal"),
     check("forbidden_shortcuts_present", REQUIRED_STOP_KEYS.every((key) => (loaded.topic.forbidden_shortcuts ?? []).includes(key)) && REQUIRED_STOP_KEYS.every((key) => forbiddenCatalog.keys.includes(key)), "topic forbidden_shortcuts include required package catalog keys"),
     check("forbidden_shortcuts_catalog_aligned", forbiddenCatalog.aligned, forbiddenCatalog.aligned ? "host forbidden-shortcuts projection is aligned or absent" : "host forbidden-shortcuts projection differs from package catalog"),
     check("required_artifacts_present", missing.length === 0, missing.length === 0 ? "all required artifacts are present" : `missing artifacts: ${missing.join(", ")}`),
@@ -328,11 +406,11 @@ export async function buildTopicGoal(projectRoot, options) {
   ];
 
   const preliminaryOk = checks.every((entry) => entry.status === "pass");
-  const preliminaryGoal = preliminaryOk && selectedWave ? buildGoalCommand(loaded.topicId, selectedWave.wave_id, sourceArtifacts) : null;
+  const preliminaryGoal = preliminaryOk ? buildGoalCommand(loaded.topicId, executionStartWave, sourceArtifacts) : null;
   checks.push(check("goal_size_within_limit", preliminaryGoal === null || preliminaryGoal.length <= GOAL_COMMAND_MAX_CHARS, preliminaryGoal === null ? "goal size check skipped until readiness passes" : `goal command length is ${preliminaryGoal.length}`));
 
   const readinessOk = checks.every((entry) => entry.status === "pass");
-  const goalCommand = readinessOk && selectedWave ? preliminaryGoal : null;
+  const goalCommand = readinessOk ? preliminaryGoal : null;
   return {
     ok: readinessOk,
     topic_id: loaded.topicId,
@@ -341,7 +419,8 @@ export async function buildTopicGoal(projectRoot, options) {
     true_close_status: loaded.topic.current_true_close_status ?? null,
     profile: profile.profile ?? null,
     selected_next_target: loaded.topic.selected_next_target ?? null,
-    selected_wave_id: selectedWave?.wave_id ?? null,
+    selected_wave_id: executionStartWave?.wave_id ?? null,
+    execution_start_wave_id: executionStartWave?.wave_id ?? null,
     topic_state_hash: buildStateHash(sourceArtifactTexts, [
       { ref: TOPIC_GOAL_CONTRACT_REF, text: await readTextIfFile(packagePath(TOPIC_GOAL_CONTRACT_REF)) ?? "" },
     ]),

package/cli/lib/topic-ledger.mjs

@@ -0,0 +1,281 @@
+import { readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import YAML from "yaml";
+
+import { pathExists, readTextIfFile } from "./fs-helpers.mjs";
+import { parseYamlText } from "./yaml-helpers.mjs";
+import { loadTopicRuntimeAuthority, toPortableRelativePath } from "./topic-common.mjs";
+import { isIsoUtcTimestamp, loadTopicReport } from "./topic-scaffold.mjs";
+import { readFrontmatterObject } from "./topic-artifacts.mjs";
+
+const RUN_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+export function validateRunId(value) {
+  return typeof value == "string" && RUN_ID_PATTERN.test(value);
+}
+export function runLedgerFilename(runId) {
+  return `run-ledger-${runId}.yaml`;
+}
+export function runEventFilename(runId, eventIndex, eventKind) {
+  return `run-event-${runId}-${String(eventIndex).padStart(4, "0")}-${eventKind}.yaml`;
+}
+export function stopClassToRunStatus(stopClass) {
+  return stopClass === "continue"
+    ? "running"
+    : stopClass === "require_human_confirmation"
+      ? "awaiting_human_confirmation"
+      : stopClass === "await_external_evidence"
+        ? "awaiting_external_evidence"
+        : stopClass === "blocked"
+          ? "blocked"
+          : stopClass === "completed"
+            ? "completed"
+            : "blocked";
+}
+export function retryPostureForEvent(event) {
+  return event.stop_class === "require_human_confirmation"
+    ? "retry_forbidden_until_human_gate"
+    : event.stop_class === "blocked"
+      ? "retry_requires_new_packet"
+      : event.stop_class === "await_external_evidence"
+        ? "retry_allowed_same_command"
+        : "not_applicable";
+}
+export function normalizeArtifactRefs(input) {
+  const refs = {};
+  for (const [key, value] of Object.entries(input ?? {}))
+    typeof key == "string" &&
+      key.length > 0 &&
+      typeof value == "string" &&
+      value.length > 0 &&
+      (refs[key] = value);
+  return refs;
+}
+export async function validatePortableRefExists(projectRoot, ref, label) {
+  return path.isAbsolute(ref)
+    ? `${label} must be project-relative: ${ref}`
+    : (await pathExists(path.join(projectRoot, ref)))?.isFile()
+      ? null
+      : `${label} does not resolve to a file: ${ref}`;
+}
+export async function loadTopicRunEvents(topicDir, runId) {
+  const entries = await readdir(topicDir, { withFileTypes: true }),
+    events = [];
+  for (const entry of entries) {
+    if (
+      !entry.isFile() ||
+      !entry.name.startsWith(`run-event-${runId}-`) ||
+      !entry.name.endsWith(".yaml")
+    )
+      continue;
+    const eventPath = path.join(topicDir, entry.name),
+      eventText = await readTextIfFile(eventPath),
+      event = parseYamlText(eventText ?? "");
+    !event ||
+      typeof event != "object" ||
+      event.run_id !== runId ||
+      events.push({ event, eventRef: entry.name, eventPath });
+  }
+  return events.sort((left, right) => {
+    const leftIndex = Number(left.event.event_index ?? 0),
+      rightIndex = Number(right.event.event_index ?? 0);
+    return leftIndex - rightIndex || left.eventRef.localeCompare(right.eventRef);
+  });
+}
+export function latestArtifactRef(events, key) {
+  for (const entry of [...events].reverse()) {
+    const value = entry.event.artifact_refs?.[key];
+    if (typeof value == "string" && value.length > 0) return value;
+  }
+  return null;
+}
+export function buildCurrentHumanGate(events) {
+  const gateClosingEvents = new Set(["human_gate_resolved", "wave_closed", "topic_closed"]);
+  for (const entry of [...events].reverse()) {
+    const event = entry.event;
+    if (gateClosingEvents.has(event.event_kind)) return null;
+    if (
+      event.stop_class === "require_human_confirmation" ||
+      event.event_kind === "human_gate_opened"
+    )
+      return {
+        event_ref: entry.eventRef,
+        wave_id: event.wave_id ?? null,
+        recommended_action: event.recommended_action,
+        summary: event.summary,
+        source_ref: event.source_ref,
+      };
+  }
+  return null;
+}
+export function buildTopicRunLedgerProjection(topic, runId, events, updatedAt) {
+  const latest = events.at(-1) ?? null,
+    latestEvent = latest?.event ?? null;
+  return {
+    ledger_id: `${topic.topic_id}:${runId}`,
+    topic_id: topic.topic_id,
+    run_id: runId,
+    kind: "topic-run-ledger",
+    run_status: latestEvent ? stopClassToRunStatus(latestEvent.stop_class) : "running",
+    event_count: events.length,
+    event_refs: events.map((entry) => entry.eventRef),
+    latest_event_ref: latest?.eventRef ?? null,
+    current_wave_id: latestEvent?.wave_id ?? topic.selected_next_target ?? null,
+    latest_decision_ref: latestArtifactRef(events, "decision_ref"),
+    latest_packet_ref: latestArtifactRef(events, "packet_ref"),
+    latest_prompt_ref: latestArtifactRef(events, "prompt_ref"),
+    latest_result_ref: latestArtifactRef(events, "result_ref"),
+    latest_closeout_ref: latestArtifactRef(events, "closeout_ref"),
+    current_human_gate: buildCurrentHumanGate(events),
+    retry_posture: latestEvent ? retryPostureForEvent(latestEvent) : "not_applicable",
+    updated_at: updatedAt,
+  };
+}
+export async function writeTopicRunLedger(projectRoot, loaded, runId, events, updatedAt) {
+  const ledger = buildTopicRunLedgerProjection(loaded.topic, runId, events, updatedAt),
+    ledgerPath = path.join(loaded.topicDir, runLedgerFilename(runId));
+  return (
+    await writeFile(ledgerPath, YAML.stringify(ledger), "utf8"),
+    {
+      ok: true,
+      topicId: loaded.topicId,
+      topicRef: toPortableRelativePath(path.relative(projectRoot, loaded.topicDir)),
+      runId,
+      ledgerRef: toPortableRelativePath(path.relative(projectRoot, ledgerPath)),
+      ledger,
+    }
+  );
+}
+export async function initTopicRunLedger(projectRoot, input, runId, startedAt = new Date().toISOString()) {
+  if (!validateRunId(runId))
+    return { ok: false, error: `Topic run ledger refused: invalid run id ${runId}` };
+  const loaded = await loadTopicReport(projectRoot, input);
+  if (!loaded.ok) return loaded;
+  const ledgerPath = path.join(loaded.topicDir, runLedgerFilename(runId));
+  if ((await readTextIfFile(ledgerPath)) !== null)
+    return { ok: false, error: `Topic run ledger already exists: ${runId}` };
+  const report = await writeTopicRunLedger(projectRoot, loaded, runId, [], startedAt);
+  return { ...report, runStatus: report.ledger.run_status, eventCount: report.ledger.event_count };
+}
+export async function recordTopicRunEvent(projectRoot, input, options) {
+  if (!validateRunId(options.runId))
+    return { ok: false, error: `Topic run event refused: invalid run id ${options.runId}` };
+  const loaded = await loadTopicReport(projectRoot, input);
+  if (!loaded.ok) return loaded;
+  const authority = await loadTopicRuntimeAuthority(projectRoot);
+  if (!authority.topicRunLedger.eventKinds.includes(options.eventKind))
+    return {
+      ok: false,
+      error: `Topic run event refused: unsupported event kind ${options.eventKind}`,
+    };
+  if (!authority.topicStepDecision.stopClasses.includes(options.stopClass))
+    return {
+      ok: false,
+      error: `Topic run event refused: unsupported stop class ${options.stopClass}`,
+    };
+  if (!authority.topicStepDecision.recommendedActions.includes(options.recommendedAction))
+    return {
+      ok: false,
+      error: `Topic run event refused: unsupported recommended action ${options.recommendedAction}`,
+    };
+  if (!isIsoUtcTimestamp(options.recordedAt))
+    return {
+      ok: false,
+      error: `Topic run event refused: --verified-at must be an ISO-8601 UTC timestamp: ${options.recordedAt}`,
+    };
+  if (!options.sourceRef || !options.summary)
+    return { ok: false, error: "Topic run event refused: --source and --summary are required" };
+  const sourceError = await validatePortableRefExists(projectRoot, options.sourceRef, "source_ref");
+  if (sourceError) return { ok: false, error: `Topic run event refused: ${sourceError}` };
+  const ledgerPath = path.join(loaded.topicDir, runLedgerFilename(options.runId));
+  if ((await readTextIfFile(ledgerPath)) === null)
+    return {
+      ok: false,
+      error: `Topic run event refused: run ledger does not exist: ${options.runId}`,
+    };
+  const artifactRefs = normalizeArtifactRefs(options.artifactRefs),
+    invalidArtifactKeys = Object.keys(artifactRefs).filter(
+      (key) => !authority.topicRunLedger.artifactRefKeys.includes(key),
+    );
+  if (invalidArtifactKeys.length > 0)
+    return {
+      ok: false,
+      error: `Topic run event refused: unsupported artifact ref keys: ${invalidArtifactKeys.join(", ")}`,
+    };
+  for (const [key, ref] of Object.entries(artifactRefs)) {
+    const artifactError = await validatePortableRefExists(projectRoot, ref, key);
+    if (artifactError) return { ok: false, error: `Topic run event refused: ${artifactError}` };
+  }
+  const eventIndex = (await loadTopicRunEvents(loaded.topicDir, options.runId)).length + 1,
+    event = {
+      event_id: `${options.runId}:${String(eventIndex).padStart(4, "0")}:${options.eventKind}`,
+      topic_id: loaded.topicId,
+      run_id: options.runId,
+      event_index: eventIndex,
+      event_kind: options.eventKind,
+      stop_class: options.stopClass,
+      recommended_action: options.recommendedAction,
+      wave_id: options.waveId ?? loaded.topic.selected_next_target ?? null,
+      source_ref: options.sourceRef,
+      summary: options.summary,
+      recorded_at: options.recordedAt,
+      artifact_refs: artifactRefs,
+    },
+    eventPath = path.join(
+      loaded.topicDir,
+      runEventFilename(options.runId, eventIndex, options.eventKind),
+    );
+  await writeFile(eventPath, YAML.stringify(event), "utf8");
+  const updatedEvents = await loadTopicRunEvents(loaded.topicDir, options.runId),
+    report = await writeTopicRunLedger(
+      projectRoot,
+      loaded,
+      options.runId,
+      updatedEvents,
+      options.recordedAt,
+    );
+  return {
+    ...report,
+    eventId: event.event_id,
+    eventRef: toPortableRelativePath(path.relative(projectRoot, eventPath)),
+    runStatus: report.ledger.run_status,
+    eventCount: report.ledger.event_count,
+  };
+}
+export async function buildTopicRunLedger(
+  projectRoot,
+  input,
+  runId,
+  updatedAt = new Date().toISOString(),
+) {
+  if (!validateRunId(runId))
+    return { ok: false, error: `Topic run ledger refused: invalid run id ${runId}` };
+  const loaded = await loadTopicReport(projectRoot, input);
+  if (!loaded.ok) return loaded;
+  const ledgerPath = path.join(loaded.topicDir, runLedgerFilename(runId));
+  if ((await readTextIfFile(ledgerPath)) === null)
+    return { ok: false, error: `Topic run ledger not found: ${runId}` };
+  const events = await loadTopicRunEvents(loaded.topicDir, runId),
+    report = await writeTopicRunLedger(projectRoot, loaded, runId, events, updatedAt);
+  return { ...report, runStatus: report.ledger.run_status, eventCount: report.ledger.event_count };
+}
+export async function readTopicRunLedger(projectRoot, input, runId) {
+  if (!validateRunId(runId))
+    return { ok: false, error: `Topic run ledger refused: invalid run id ${runId}` };
+  const loaded = await loadTopicReport(projectRoot, input);
+  if (!loaded.ok) return loaded;
+  const ledgerPath = path.join(loaded.topicDir, runLedgerFilename(runId)),
+    ledgerText = await readTextIfFile(ledgerPath);
+  if (ledgerText === null) return { ok: false, error: `Topic run ledger not found: ${runId}` };
+  const ledger = parseYamlText(ledgerText);
+  return {
+    ok: true,
+    topicId: loaded.topicId,
+    topicRef: toPortableRelativePath(path.relative(projectRoot, loaded.topicDir)),
+    runId,
+    ledgerRef: toPortableRelativePath(path.relative(projectRoot, ledgerPath)),
+    ledger,
+    runStatus: ledger.run_status,
+    eventCount: ledger.event_count,
+  };
+}