@nimiplatform/nimi-coding 0.2.8 → 0.3.0

package/cli/lib/topic-ledger.mjs

@@ -1,281 +0,0 @@
-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,
-  };
-}

package/cli/lib/topic-lifecycle-artifacts.mjs

@@ -1,173 +0,0 @@
-import { readdir } from "node:fs/promises";
-
-function getTopicWaves(topic) {
-  return Array.isArray(topic.waves) ? topic.waves.map((entry) => ({ ...entry })) : [];
-}
-
-function fileReferencesWave(fileName, waveId) {
-  return fileName.includes(waveId);
-}
-
-function buildObservedLineage(entry) {
-  if (entry.closeouts > 0) return "closed_lineage";
-  if (entry.results > 0) return "result_lineage";
-  if (entry.packets > 0) return "packet_lineage";
-  if (entry.remediations > 0 || entry.exec_packs > 0 || entry.decision_reviews > 0) {
-    return "auxiliary_lineage";
-  }
-  return "declared_only";
-}
-
-function isRecognizedLifecycleArtifactName(fileName) {
-  if (!fileName.endsWith(".md")) return true;
-  if (fileName.startsWith("packet-")) {
-    return /^packet-wave-[a-z0-9]+(?:-[a-z0-9]+)*\.md$/.test(fileName)
-      || /^packet-true-close(?:-[a-z0-9]+)*\.md$/.test(fileName);
-  }
-  if (fileName.startsWith("result-")) {
-    return /^result-wave-[a-z0-9]+(?:-[a-z0-9]+)*\.md$/.test(fileName)
-      || /^result-topic-true-close(?:-[a-z0-9]+)*\.md$/.test(fileName)
-      || /^result-true-close(?:-[a-z0-9]+)*\.md$/.test(fileName);
-  }
-  if (fileName.startsWith("closeout-")) {
-    return /^closeout-wave-[a-z0-9]+(?:-[a-z0-9]+)*\.md$/.test(fileName)
-      || /^closeout-topic(?:-[a-z0-9]+)*\.md$/.test(fileName)
-      || /^closeout-true-close(?:-[a-z0-9]+)*\.md$/.test(fileName);
-  }
-  if (fileName.startsWith("decision-review-")) {
-    return /^decision-review-[a-z0-9]+(?:-[a-z0-9]+)*\.md$/.test(fileName);
-  }
-  if (fileName.startsWith("prompt-")) {
-    return /^prompt-[a-z0-9-]+-(worker|audit)\.md$/.test(fileName);
-  }
-  if (fileName.startsWith("overflow-continuation-")) {
-    return /^overflow-continuation-wave-[a-z0-9]+(?:-[a-z0-9]+)*\.md$/.test(fileName);
-  }
-  return true;
-}
-
-function resolveDeclaredWaveArtifactLineage(fileNames, topicWaveIds) {
-  const declared = Array.from(topicWaveIds);
-  const resolved = [];
-  const unresolved = [];
-  const ambiguous = [];
-
-  for (const fileName of fileNames) {
-    const matches = declared.filter((waveId) => fileReferencesWave(fileName, waveId));
-    if (matches.length === 1) {
-      resolved.push({ fileName, waveId: matches[0] });
-    } else if (matches.length === 0) {
-      unresolved.push(fileName);
-    } else {
-      ambiguous.push({ fileName, waveIds: matches });
-    }
-  }
-
-  return { resolved, unresolved, ambiguous };
-}
-
-function formatLifecycleLineageFailures(lineage) {
-  return [
-    ...lineage.unresolved.map((fileName) => `${fileName}:unresolved`),
-    ...lineage.ambiguous.map((entry) => `${entry.fileName}:ambiguous:${entry.waveIds.join(",")}`),
-  ];
-}
-
-async function analyzeTopicArtifacts(topicDir, topic) {
-  const files = (await readdir(topicDir, { withFileTypes: true }))
-    .filter((entry) => entry.isFile())
-    .map((entry) => entry.name);
-  const packetFiles = files.filter((name) => name.startsWith("packet-") && name.endsWith(".md"));
-  const resultFiles = files.filter((name) => name.startsWith("result-") && name.endsWith(".md"));
-  const closeoutFiles = files.filter((name) => name.startsWith("closeout-") && name.endsWith(".md"));
-  const decisionReviewFiles = files.filter((name) => name.startsWith("decision-review-") && name.endsWith(".md"));
-  const remediationFiles = files.filter((name) => name.includes("remediation") && name.endsWith(".md"));
-  const overflowFiles = files.filter((name) => name.includes("overflow-continuation") || name.includes("remediation-continuation"));
-  const execPackFiles = files.filter((name) => name.includes("exec-pack-") && name.endsWith(".md"));
-  const trueCloseFiles = files.filter((name) => name === "topic-true-close-audit.md"
-    || name.startsWith("result-topic-true-close")
-    || name === "closeout-topic-true-close.md");
-  const ambiguousLifecycleFiles = files.filter((name) => /^(packet|result|closeout|decision-review|prompt|overflow-continuation)-/.test(name)
-    && !isRecognizedLifecycleArtifactName(name));
-  const topicWaveIds = new Set(getTopicWaves(topic).map((entry) => entry.wave_id));
-  const packetWaveFiles = packetFiles.filter((name) => !name.startsWith("packet-true-close"));
-  const resultWaveFiles = resultFiles.filter((name) => !name.startsWith("result-topic-true-close") && !name.startsWith("result-true-close"));
-  const closeoutWaveFiles = closeoutFiles.filter((name) => !name.startsWith("closeout-topic") && !name.startsWith("closeout-true-close"));
-  const packetLineage = resolveDeclaredWaveArtifactLineage(packetWaveFiles, topicWaveIds);
-  const resultLineage = resolveDeclaredWaveArtifactLineage(resultWaveFiles, topicWaveIds);
-  const closeoutLineage = resolveDeclaredWaveArtifactLineage(closeoutWaveFiles, topicWaveIds);
-  const packetWaveIds = new Set(packetLineage.resolved.map((entry) => entry.waveId));
-  const resultWaveIds = resultLineage.resolved.map((entry) => entry.waveId);
-  const closeoutWaveIds = new Set(closeoutLineage.resolved.map((entry) => entry.waveId));
-  const closeoutWaveIdsArray = Array.from(closeoutWaveIds);
-  const unresolvedPacketWaveRefs = formatLifecycleLineageFailures(packetLineage);
-  const unresolvedResultWaveIds = formatLifecycleLineageFailures(resultLineage);
-  const unresolvedCloseoutWaveRefs = formatLifecycleLineageFailures(closeoutLineage);
-  const activeWaveCloseoutConflicts = getTopicWaves(topic)
-    .filter((entry) => !["closed", "retired", "superseded"].includes(entry.state)
-      && closeoutFiles.some((name) => fileReferencesWave(name, entry.wave_id) || closeoutWaveIds.has(entry.wave_id)))
-    .map((entry) => `${entry.wave_id}:${entry.state}`);
-  const topicHasOpenBlockers = getTopicWaves(topic).some((entry) => !["closed", "retired", "superseded"].includes(entry.state))
-    || (typeof topic.selected_next_target === "string"
-      && topic.selected_next_target.length > 0
-      && topic.selected_next_target !== "topic_design_baseline");
-  const prematureTrueClose = trueCloseFiles.length > 0 && topicHasOpenBlockers;
-  const observedWaveIds = Array.from(new Set([
-    ...Array.from(topicWaveIds),
-    ...Array.from(packetWaveIds),
-    ...closeoutWaveIdsArray,
-    ...resultWaveIds,
-  ])).sort();
-  const observedWaves = observedWaveIds.map((waveId) => {
-    const observed = {
-      wave_id: waveId,
-      packets: packetFiles.filter((name) => fileReferencesWave(name, waveId)).length,
-      results: resultFiles.filter((name) => fileReferencesWave(name, waveId)).length,
-      closeouts: closeoutFiles.filter((name) => fileReferencesWave(name, waveId)).length,
-      decision_reviews: decisionReviewFiles.filter((name) => fileReferencesWave(name, waveId)).length,
-      remediations: remediationFiles.filter((name) => fileReferencesWave(name, waveId)).length,
-      overflow_continuations: overflowFiles.filter((name) => fileReferencesWave(name, waveId)).length,
-      exec_packs: execPackFiles.filter((name) => fileReferencesWave(name, waveId)).length,
-      declared_in_topic_yaml: topicWaveIds.has(waveId),
-    };
-    return { ...observed, observed_lineage: buildObservedLineage(observed) };
-  });
-
-  return {
-    files,
-    counts: {
-      files: files.length,
-      packets: packetFiles.length,
-      results: resultFiles.length,
-      closeouts: closeoutFiles.length,
-      decision_reviews: decisionReviewFiles.length,
-      remediations: remediationFiles.length,
-      overflow_continuations: overflowFiles.length,
-      exec_packs: execPackFiles.length,
-      true_close_artifacts: trueCloseFiles.length,
-    },
-    waveIds: observedWaveIds,
-    observedWaves,
-    featureFlags: {
-      decision_review_lineage: decisionReviewFiles.length > 0,
-      remediation_lineage: remediationFiles.length > 0,
-      overflow_lineage: overflowFiles.length > 0,
-      true_close_lineage: trueCloseFiles.length >= 2,
-      exec_pack_lineage: execPackFiles.length > 0,
-    },
-    unresolvedPacketWaveRefs,
-    unresolvedResultWaveIds,
-    unresolvedCloseoutWaveRefs,
-    closeoutWaveIds: closeoutWaveIdsArray,
-    ambiguousLifecycleFiles,
-    activeWaveCloseoutConflicts,
-    prematureTrueClose,
-  };
-}
-
-export {
-  analyzeTopicArtifacts,
-  fileReferencesWave,
-  isRecognizedLifecycleArtifactName,
-  resolveDeclaredWaveArtifactLineage,
-};