@nimiplatform/nimi-coding 0.1.0 → 0.2.1

package/cli/lib/sweep-design-runtime/results.mjs

@@ -0,0 +1,324 @@
+import path from "node:path";
+
+import {
+  assertDesignArtifact,
+  FINAL_OUTCOME_STATES,
+  inputError,
+  loadYamlRef,
+  nowIso,
+  requireRunId,
+  safeDesignId,
+  TRANSIENT_STATES,
+  writeYamlRef,
+} from "./common.mjs";
+import {
+  decisionQueueRef,
+  finalOutcomeState,
+  finalStateReportRef,
+  isLlmAuditorResult,
+  isSyntheticAuditorResult,
+  ledgerRef,
+  loadInventory,
+  loadOrCreateLedger,
+  normalizeRevisionEntry,
+  packetRef,
+  resultRef,
+  stopClassForResult,
+  updateLedgerHashes,
+  validateAuditorResult,
+  validateLedger,
+  validateOutcome,
+  validatePacket,
+  validateWave,
+  wavePlanRef,
+} from "./engine.mjs";
+
+export async function runResultIngest(projectRoot, options) {
+  const run = requireRunId(options);
+  if (!run.ok) return run;
+  if (!options.from) return inputError("nimicoding sweep design refused: result-ingest requires --from.\n");
+  const result = await loadYamlRef(projectRoot, options.from) ?? await import("node:fs/promises").then(async ({ readFile }) => {
+    const YAML = await import("yaml");
+    return YAML.parse(await readFile(path.resolve(projectRoot, options.from), "utf8"));
+  }).catch(() => null);
+  const errors = validateAuditorResult(result);
+  if (errors.length > 0) return inputError(`nimicoding sweep design refused: ${errors.join("; ")}.\n`);
+  if (isSyntheticAuditorResult(result) && options.allowSyntheticTrial !== true) {
+    return inputError("nimicoding sweep design refused: synthetic_trial results require --allow-synthetic-trial and do not satisfy true LLM closeout.\n");
+  }
+  if (!safeDesignId(result.packet_id)) return inputError("nimicoding sweep design refused: result packet_id must be a stable id.\n");
+  if (!safeDesignId(result.result_id)) return inputError("nimicoding sweep design refused: result_id must be a stable id.\n");
+  if (result.run_id !== run.runId) return inputError("nimicoding sweep design refused: result run_id does not match --run-id.\n");
+  const packet = await assertDesignArtifact(projectRoot, packetRef(run.runId, result.packet_id), "sweep-design-design-auditor-packet", "design auditor packet");
+  if (!packet.ok) return packet;
+  if (result.packet_ref !== packet.ref) return inputError("nimicoding sweep design refused: result packet_ref does not match canonical packet artifact.\n");
+  const packetErrors = validatePacket(packet.value);
+  if (packetErrors.length > 0) return inputError(`nimicoding sweep design refused: ${packetErrors.join("; ")}.\n`);
+  const timestamp = options.verifiedAt ?? nowIso();
+  const ledger = await loadOrCreateLedger(projectRoot, run.runId, timestamp);
+  if (!ledger.ok) return ledger;
+  const previousSnapshotHash = ledger.value.ledger_snapshot_hash;
+  const normalizedRevisionEntries = [];
+  const revisionErrors = [];
+  const context = {
+    ledger: ledger.value,
+    normalized: normalizedRevisionEntries,
+    errors: revisionErrors,
+    resultId: result.result_id,
+    resultArtifactRef: resultRef(run.runId, result.result_id),
+    timestamp,
+    auditorProvenance: {
+      auditor: result.auditor,
+      auditor_family: result.auditor_family,
+      auditor_mode: result.auditor_mode,
+      auditor_result_origin: result.auditor_result_origin,
+      session_ref: result.session_ref,
+      transcript_ref: result.transcript_ref,
+      llm_session_ref: result.llm_session_ref ?? null,
+      llm_transcript_ref: result.llm_transcript_ref ?? null,
+      llm_prompt_ref: result.llm_prompt_ref ?? null,
+      packet_ref: result.packet_ref,
+      result_ref: resultRef(run.runId, result.result_id),
+    },
+  };
+  for (const entry of result.revision_entries) {
+    normalizedRevisionEntries.push(normalizeRevisionEntry(entry, context));
+  }
+  if (revisionErrors.length > 0) return inputError(`nimicoding sweep design refused: ${revisionErrors.join("; ")}.\n`);
+  const outcomeErrors = [];
+  for (const outcome of result.finding_outcomes) {
+    validateOutcome(outcome, { errors: outcomeErrors });
+  }
+  const includedFindingIds = new Set(packet.value.included_finding_ids);
+  const outcomeFindingIds = result.finding_outcomes.map((outcome) => outcome.finding_id);
+  const uniqueOutcomeFindingIds = new Set(outcomeFindingIds);
+  if (uniqueOutcomeFindingIds.size !== outcomeFindingIds.length) {
+    outcomeErrors.push("finding_outcomes[] contains duplicate finding_id entries");
+  }
+  const missingOutcomeIds = packet.value.included_finding_ids.filter((findingId) => !uniqueOutcomeFindingIds.has(findingId));
+  if (missingOutcomeIds.length > 0) {
+    outcomeErrors.push(`design auditor result is missing final outcomes for included findings: ${missingOutcomeIds.join(", ")}`);
+  }
+  const outOfPacketOutcomeIds = outcomeFindingIds.filter((findingId) => !includedFindingIds.has(findingId));
+  if (outOfPacketOutcomeIds.length > 0) {
+    outcomeErrors.push(`design auditor result includes outcomes outside the packet: ${[...new Set(outOfPacketOutcomeIds)].join(", ")}`);
+  }
+  const normalizedRevisionRefs = new Set(normalizedRevisionEntries.map((entry) => `${ledger.ref}#${entry.revision_entry_id}`));
+  for (const outcome of result.finding_outcomes) {
+    for (const ref of outcome.revision_ledger_entry_refs ?? []) {
+      if (!normalizedRevisionRefs.has(ref)) {
+        outcomeErrors.push(`finding_outcomes[] revision_ledger_entry_refs must reference revision entries from this ingest: ${ref}`);
+      }
+    }
+  }
+  if (outcomeErrors.length > 0) return inputError(`nimicoding sweep design refused: ${outcomeErrors.join("; ")}.\n`);
+  const storedResult = {
+    ...result,
+    closeout_eligible: isLlmAuditorResult(result),
+    ingested_at: timestamp,
+    normalized_revision_entry_refs: normalizedRevisionEntries.map((entry) => `${ledger.ref}#${entry.revision_entry_id}`),
+  };
+  const storedResultRef = await writeYamlRef(projectRoot, resultRef(run.runId, result.result_id), storedResult);
+  ledger.value.entries.push(...normalizedRevisionEntries);
+  updateLedgerHashes(ledger.value, previousSnapshotHash, timestamp);
+  await writeYamlRef(projectRoot, ledger.ref, ledger.value);
+  const decisionItems = result.finding_outcomes
+    .filter((outcome) => finalOutcomeState(outcome) === "needs_user_decision")
+    .map((outcome) => ({
+      decision_queue_item_ref: outcome.decision_queue_item_ref,
+      finding_id: outcome.finding_id,
+      decision_packet_ref: outcome.decision_packet_ref,
+      recommended_decision: outcome.recommended_decision,
+      queue_status: outcome.queue_status,
+      blocked_downstream_wave_refs: outcome.blocked_downstream_wave_refs,
+    }));
+  if (decisionItems.length > 0 || result.human_decision_requests.length > 0) {
+    await writeYamlRef(projectRoot, decisionQueueRef(run.runId), {
+      version: 2,
+      kind: "sweep-design-decision-queue",
+      run_id: run.runId,
+      source_design_auditor_result_ref: storedResultRef,
+      queue_policy: "focused_mode_stops_immediately_all_mode_batches_until_audit_complete",
+      original_findings_mutation_policy: "read_only_never_update_from_sweep_design",
+      pending_decision_count: decisionItems.length + result.human_decision_requests.length,
+      items: decisionItems,
+      human_decision_requests: result.human_decision_requests,
+      created_at: timestamp,
+    });
+  }
+  const stopClass = stopClassForResult(result);
+  const mode = options.mode ?? result.auditor_mode;
+  const focusedStop = mode === "focused" && stopClass;
+  return {
+    ok: true,
+    exitCode: focusedStop ? 2 : 0,
+    runId: run.runId,
+    resultRef: storedResultRef,
+    ledgerRef: ledger.ref,
+    revisionEntryCount: normalizedRevisionEntries.length,
+    findingOutcomeCount: result.finding_outcomes.length,
+    closeoutEligible: isLlmAuditorResult(result),
+    stopped: Boolean(focusedStop),
+    stopClass: focusedStop ? stopClass : null,
+    stopReason: focusedStop ? "focused_mode_requires_manager_or_human_resolution" : null,
+  };
+}
+
+export async function runLedgerValidate(projectRoot, options) {
+  const run = requireRunId(options);
+  if (!run.ok) return run;
+  const ledger = await assertDesignArtifact(projectRoot, ledgerRef(run.runId), "sweep-design-revision-ledger", "revision ledger");
+  if (!ledger.ok) return ledger;
+  const errors = validateLedger(ledger.value);
+  if (errors.length > 0) return inputError(`nimicoding sweep design refused: ${errors.join("; ")}.\n`);
+  return {
+    ok: true,
+    exitCode: 0,
+    runId: run.runId,
+    ledgerRef: ledger.ref,
+    revisionEntryCount: ledger.value.entries.length,
+    ledgerSnapshotHash: ledger.value.ledger_snapshot_hash,
+  };
+}
+
+export async function runFinalize(projectRoot, options) {
+  const run = requireRunId(options);
+  if (!run.ok) return run;
+  const inventory = await loadInventory(projectRoot, run.runId);
+  if (!inventory.ok) return inventory;
+  const ledger = await assertDesignArtifact(projectRoot, ledgerRef(run.runId), "sweep-design-revision-ledger", "revision ledger");
+  if (!ledger.ok) return ledger;
+  const ledgerErrors = validateLedger(ledger.value);
+  if (ledgerErrors.length > 0) return inputError(`nimicoding sweep design refused: ${ledgerErrors.join("; ")}.\n`);
+  const outcomes = new Map();
+  const resultRefs = new Set();
+  const nonLlmResultRefs = [];
+  for (const entry of ledger.value.entries) {
+    for (const ref of entry.replacement_artifact_refs ?? []) {
+      if (ref.includes("/design-auditor-results/")) resultRefs.add(ref);
+    }
+  }
+  for (const ref of resultRefs) {
+    const result = await loadYamlRef(projectRoot, ref);
+    if (result?.kind !== "sweep-design-design-auditor-result") continue;
+    if (!isLlmAuditorResult(result)) nonLlmResultRefs.push(ref);
+    for (const outcome of result.finding_outcomes ?? []) {
+      outcomes.set(outcome.finding_id, { ...outcome, source_result_ref: ref });
+    }
+  }
+  const findings = inventory.value.findings.map((finding) => {
+    const outcome = outcomes.get(finding.finding_id);
+    if (!outcome) {
+      return {
+        finding_id: finding.finding_id,
+        state: "raw",
+        final_outcome: false,
+        transient: true,
+        reason: "missing_design_auditor_final_outcome",
+      };
+    }
+    const state = finalOutcomeState(outcome);
+    return {
+      finding_id: finding.finding_id,
+      state,
+      final_outcome: FINAL_OUTCOME_STATES.has(state),
+      transient: TRANSIENT_STATES.has(state),
+      source_result_ref: outcome.source_result_ref,
+      design_auditor_packet_ref: outcome.design_auditor_packet_ref,
+      revision_ledger_entry_refs: outcome.revision_ledger_entry_refs,
+    };
+  });
+  const transient = findings.filter((finding) => finding.transient || !finding.final_outcome);
+  const finalOutcomeComplete = transient.length === 0;
+  const llmCloseoutEligible = nonLlmResultRefs.length === 0;
+  const complete = finalOutcomeComplete && (llmCloseoutEligible || options.allowSyntheticCloseout === true);
+  const artifact = {
+    version: 2,
+    kind: "sweep-design-final-state-report",
+    run_id: run.runId,
+    source_inventory_ref: inventory.ref,
+    source_revision_ledger_ref: ledger.ref,
+    final_state_policy: "every_finding_must_have_final_sweep_design_outcome_with_llm_packet_result_ledger_provenance",
+    source_findings_mutation_policy: "read_only_never_update_from_sweep_design",
+    complete,
+    final_outcome_complete: finalOutcomeComplete,
+    llm_closeout_eligible: llmCloseoutEligible,
+    non_llm_result_refs: nonLlmResultRefs,
+    total_finding_count: findings.length,
+    final_finding_count: findings.length - transient.length,
+    transient_finding_count: transient.length,
+    final_outcome_states: [...FINAL_OUTCOME_STATES].sort(),
+    transient_states: [...TRANSIENT_STATES].sort(),
+    blocking_findings: transient.map((finding) => ({
+      finding_id: finding.finding_id,
+      state: finding.state,
+      reason: finding.reason ?? "transient_or_missing_final_outcome",
+    })),
+    findings,
+    created_at: options.verifiedAt ?? nowIso(),
+  };
+  const ref = await writeYamlRef(projectRoot, finalStateReportRef(run.runId), artifact);
+  return {
+    ok: true,
+    exitCode: complete ? 0 : 2,
+    runId: run.runId,
+    finalStateReportRef: ref,
+    finalComplete: complete,
+    finalOutcomeComplete,
+    llmCloseoutEligible,
+    nonLlmResultCount: nonLlmResultRefs.length,
+    totalFindingCount: artifact.total_finding_count,
+    finalFindingCount: artifact.final_finding_count,
+    transientFindingCount: artifact.transient_finding_count,
+    stopped: !complete,
+    stopClass: complete ? null : finalOutcomeComplete ? "non_llm_result_provenance" : "incomplete_final_state",
+    stopReason: complete ? null : finalOutcomeComplete ? "synthetic_or_non_llm_results_do_not_satisfy_true_llm_closeout" : "missing_or_transient_final_outcomes_remaining",
+  };
+}
+
+export async function runWavePlan(projectRoot, options) {
+  const run = requireRunId(options);
+  if (!run.ok) return run;
+  if (!options.topicId) return inputError("nimicoding sweep design refused: --topic-id is required.\n");
+  const ledger = await assertDesignArtifact(projectRoot, ledgerRef(run.runId), "sweep-design-revision-ledger", "revision ledger");
+  if (!ledger.ok) return ledger;
+  const ledgerErrors = validateLedger(ledger.value);
+  if (ledgerErrors.length > 0) return inputError(`nimicoding sweep design refused: ${ledgerErrors.join("; ")}.\n`);
+  const waves = [];
+  const errors = [];
+  const resultRefs = new Set();
+  for (const entry of ledger.value.entries) {
+    for (const ref of entry.replacement_artifact_refs ?? []) {
+      if (ref.includes("/design-auditor-results/")) resultRefs.add(ref);
+    }
+  }
+  for (const ref of resultRefs) {
+    const result = await loadYamlRef(projectRoot, ref);
+    if (result?.kind !== "sweep-design-design-auditor-result") continue;
+    if (!isLlmAuditorResult(result) && options.allowSyntheticTrial !== true) {
+      errors.push(`wave-plan result ${ref} is not closeout-eligible LLM provenance; pass --allow-synthetic-trial only for load tests`);
+      continue;
+    }
+    for (const wave of result.wave_changes ?? []) {
+      if (wave.state === "ready_for_implementation" || wave.ready_for_implementation_wave === true) {
+        validateWave(wave, errors);
+        waves.push({ ...wave, source_design_auditor_result_ref: ref });
+      }
+    }
+  }
+  if (errors.length > 0) return inputError(`nimicoding sweep design refused: ${errors.join("; ")}.\n`);
+  const artifact = {
+    version: 2,
+    kind: "sweep-design-wave-plan",
+    run_id: run.runId,
+    topic_id: options.topicId,
+    source_revision_ledger_ref: ledger.ref,
+    mutates_topic_state: false,
+    worker_dispatch_allowed: false,
+    wave_count: waves.length,
+    waves,
+    created_at: options.verifiedAt ?? nowIso(),
+  };
+  const ref = await writeYamlRef(projectRoot, wavePlanRef(run.runId), artifact);
+  return { ok: true, exitCode: 0, runId: run.runId, wavePlanRef: ref, waveCount: waves.length };
+}

package/cli/lib/sweep-design.mjs

@@ -0,0 +1,8 @@
+export {
+  runAuditorPrompt,
+  runIntake,
+  runPacketBuild,
+  runPacketBuildBatch,
+} from "./sweep-design-runtime/engine.mjs";
+export { runFixTopic } from "./sweep-design-runtime/fix-topic.mjs";
+export { runFinalize, runLedgerValidate, runResultIngest, runWavePlan } from "./sweep-design-runtime/results.mjs";

package/cli/lib/sync.mjs

@@ -0,0 +1,143 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { getBootstrapSeedEntries } from "../seeds/bootstrap.mjs";
+import { pathExists, readTextIfFile } from "./fs-helpers.mjs";
+
+export const SYNC_MODE = {
+  DRY_RUN: "dry_run",
+  APPLY: "apply",
+  CHECK: "check",
+};
+
+const STATUS = {
+  IN_SYNC: "in_sync",
+  CREATED: "created",
+  UPDATED: "updated",
+  WOULD_CREATE: "would_create",
+  WOULD_UPDATE: "would_update",
+  DRIFTED_PRESERVED: "drifted_preserved",
+  MISSING_PACKAGE_CANONICAL: "missing_package_canonical",
+  MISSING_HOST_STATE_SEED: "missing_host_state_seed",
+  DRIFTED_PACKAGE_CANONICAL: "drifted_package_canonical",
+};
+
+const HOST_OWNED_SEED_OWNERSHIPS = new Set(["host_state_seed", "host_profile_override"]);
+
+async function evaluateSeedEntry(projectRoot, entry, mode) {
+  const absolutePath = path.join(projectRoot, entry.outputRelativePath);
+  const info = await pathExists(absolutePath);
+  const fileExists = Boolean(info && info.isFile());
+
+  if (!fileExists) {
+    if (mode === SYNC_MODE.APPLY) {
+      await mkdir(path.dirname(absolutePath), { recursive: true });
+      await writeFile(absolutePath, entry.content, "utf8");
+      return {
+        outputRelativePath: entry.outputRelativePath,
+        ownership: entry.ownership,
+        status: STATUS.CREATED,
+        detail: "missing host file was seeded from package source",
+      };
+    }
+    return {
+      outputRelativePath: entry.outputRelativePath,
+      ownership: entry.ownership,
+      status: HOST_OWNED_SEED_OWNERSHIPS.has(entry.ownership)
+        ? STATUS.MISSING_HOST_STATE_SEED
+        : STATUS.MISSING_PACKAGE_CANONICAL,
+      detail: mode === SYNC_MODE.CHECK
+        ? "host file is missing"
+        : "host file is missing and would be seeded on --apply",
+    };
+  }
+
+  const actual = await readTextIfFile(absolutePath);
+  if (actual === entry.content) {
+    return {
+      outputRelativePath: entry.outputRelativePath,
+      ownership: entry.ownership,
+      status: STATUS.IN_SYNC,
+      detail: "host file matches package source byte-for-byte",
+    };
+  }
+
+  if (HOST_OWNED_SEED_OWNERSHIPS.has(entry.ownership)) {
+    return {
+      outputRelativePath: entry.outputRelativePath,
+      ownership: entry.ownership,
+      status: STATUS.DRIFTED_PRESERVED,
+      detail: `${entry.ownership}: host owns canonical content; sync preserves host copy`,
+    };
+  }
+
+  if (mode === SYNC_MODE.APPLY) {
+    await writeFile(absolutePath, entry.content, "utf8");
+    return {
+      outputRelativePath: entry.outputRelativePath,
+      ownership: entry.ownership,
+      status: STATUS.UPDATED,
+      detail: "drifted package_canonical file rewritten to package source",
+    };
+  }
+
+  return {
+    outputRelativePath: entry.outputRelativePath,
+    ownership: entry.ownership,
+    status: mode === SYNC_MODE.CHECK
+      ? STATUS.DRIFTED_PACKAGE_CANONICAL
+      : STATUS.WOULD_UPDATE,
+    detail: "host file diverges from package_canonical source",
+  };
+}
+
+export async function runSeedSync(projectRoot, mode = SYNC_MODE.DRY_RUN) {
+  const entries = await getBootstrapSeedEntries();
+  const results = [];
+  for (const entry of entries) {
+    results.push(await evaluateSeedEntry(projectRoot, entry, mode));
+  }
+
+  const summary = {
+    total: results.length,
+    in_sync: 0,
+    created: 0,
+    updated: 0,
+    would_create: 0,
+    would_update: 0,
+    drifted_preserved: 0,
+    missing_host_state_seed: 0,
+    missing_package_canonical: 0,
+    drifted_package_canonical: 0,
+  };
+
+  for (const result of results) {
+    summary[result.status] = (summary[result.status] ?? 0) + 1;
+  }
+
+  // Re-derive dry-run status counters when no apply happened.
+  if (mode === SYNC_MODE.DRY_RUN) {
+    summary.would_create = results.filter((r) =>
+      r.status === STATUS.MISSING_HOST_STATE_SEED || r.status === STATUS.MISSING_PACKAGE_CANONICAL,
+    ).length;
+    summary.would_update = results.filter((r) => r.status === STATUS.WOULD_UPDATE).length;
+  }
+
+  const checkFailures = mode === SYNC_MODE.CHECK
+    ? results.filter((r) =>
+      r.status === STATUS.MISSING_PACKAGE_CANONICAL
+      || r.status === STATUS.MISSING_HOST_STATE_SEED
+      || r.status === STATUS.DRIFTED_PACKAGE_CANONICAL,
+    )
+    : [];
+
+  return {
+    mode,
+    summary,
+    results,
+    ok: mode === SYNC_MODE.CHECK ? checkFailures.length === 0 : true,
+    checkFailures,
+  };
+}
+
+export const SYNC_RESULT_STATUS = STATUS;

package/cli/lib/topic-artifacts.mjs

@@ -0,0 +1,186 @@
+import { readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import YAML from "yaml";
+
+import { readTextIfFile } from "./fs-helpers.mjs";
+import { packetAuthorityCoverage, packetAuthorityCoverageError } from "./topic-authority-coverage.mjs";
+import { isRecognizedLifecycleArtifactName } from "./topic-lifecycle-artifacts.mjs";
+import { parseYamlText } from "./yaml-helpers.mjs";
+import { loadTopicRuntimeAuthority, toPortableRelativePath } from "./topic-common.mjs";
+import { getTopicWaves, loadTopicReport, topicHasEnrichedShape } from "./topic-scaffold.mjs";
+
+export function readFrontmatterObject(text) {
+  const parsed = parsePacketDraft(text);
+  return parsed && typeof parsed == "object" ? parsed : null;
+}
+export function parsePacketDraft(text) {
+  if (!text) return null;
+  if (
+    text.startsWith(`---
+`)
+  ) {
+    const closing = text.indexOf(
+      `
+---
+`,
+      4,
+    );
+    if (closing !== -1) {
+      const frontmatter = text.slice(4, closing);
+      return parseYamlText(frontmatter);
+    }
+  }
+  return parseYamlText(text);
+}
+export function packetFilenameFromId(packetId) {
+  return `packet-${packetId}.md`;
+}
+export function resultFilename(waveId, slug, resultKind) {
+  return `result-${waveId}-${resultKind}.md`;
+}
+export function decisionReviewFilename(slug) {
+  return `decision-review-${slug}.md`;
+}
+export function remediationFilename(waveId, kind, reason) {
+  return `packet-${waveId}-remediation-${kind}-${reason}.md`;
+}
+export function overflowContinuationFilename(waveId, continuationPacketId) {
+  return `overflow-continuation-${waveId}-${continuationPacketId}.md`;
+}
+export function waveCloseoutFilename(waveId) {
+  return `closeout-${waveId}.md`;
+}
+export function topicCloseoutFilename() {
+  return "closeout-topic.md";
+}
+export function topicTrueCloseAuditFilename() {
+  return "topic-true-close-audit.md";
+}
+export function topicTrueCloseJudgementFilename() {
+  return "result-topic-true-close-audit.md";
+}
+export function topicTrueCloseRecordFilename() {
+  return "result-topic-true-close.md";
+}
+export function pendingNoteFilename() {
+  return "pending-note.md";
+}
+export function pendingNoteMarkdown(note) {
+  return `---
+${YAML.stringify(note).trimEnd()}
+---
+
+# Pending Note
+
+Recorded by \`nimicoding topic hold\`.
+`;
+}
+export function packetMarkdown(packet) {
+  return `---
+${YAML.stringify(packet).trimEnd()}
+---
+
+# Packet ${packet.packet_id}
+
+Frozen by \`nimicoding topic packet freeze\`.
+`;
+}
+export async function freezePacketForTopic(projectRoot, input, draftPath) {
+  const loaded = await loadTopicReport(projectRoot, input);
+  if (!loaded.ok) return loaded;
+  const authority = await loadTopicRuntimeAuthority(projectRoot);
+  if (!topicHasEnrichedShape(loaded.topic, authority))
+    return { ok: false, error: "Packet freeze requires an enriched topic root." };
+  const draftText = await readTextIfFile(path.resolve(projectRoot, draftPath));
+  if (draftText === null) return { ok: false, error: `Draft packet not found: ${draftPath}` };
+  const packet = parsePacketDraft(draftText);
+  if (!packet || typeof packet != "object")
+    return { ok: false, error: `Draft packet is not valid YAML/frontmatter: ${draftPath}` };
+  const missingFields = authority.packetRequiredFields.filter((field) => {
+    const value = packet[field];
+    return value == null || value === "" || (Array.isArray(value) && value.length === 0);
+  });
+  if (missingFields.length > 0)
+    return {
+      ok: false,
+      error: `Draft packet is missing required fields: ${missingFields.join(", ")}`,
+    };
+  if (packet.topic_id !== loaded.topicId)
+    return {
+      ok: false,
+      error: `Draft packet topic_id does not match topic (${packet.topic_id} vs ${loaded.topicId})`,
+    };
+  if (!getTopicWaves(loaded.topic).find((entry) => entry.wave_id === packet.wave_id))
+    return {
+      ok: false,
+      error: `Draft packet wave_id does not resolve inside the topic: ${packet.wave_id}`,
+    };
+  const wave = getTopicWaves(loaded.topic).find((entry) => entry.wave_id === packet.wave_id);
+  const coverage = packetAuthorityCoverage(packet, wave);
+  if (!coverage.ok)
+    return {
+      ok: false,
+      error: packetAuthorityCoverageError(coverage),
+      missingAuthorityOwnerRefs: coverage.missingAuthorityOwnerRefs,
+      missingCanonicalSeamRefs: coverage.missingCanonicalSeamRefs,
+    };
+  if (!authority.packetFreezeAllowedStatuses.includes(packet.status))
+    return { ok: false, error: `Draft packet status is not freezeable: ${packet.status}` };
+  const packetFileName = packetFilenameFromId(packet.packet_id);
+  if (!isRecognizedLifecycleArtifactName(packetFileName))
+    return {
+      ok: false,
+      error: `Draft packet packet_id would create an ambiguous lifecycle artifact name: ${packetFileName}. Use a wave-prefixed packet id such as ${packet.wave_id}-${packet.packet_id}.`,
+    };
+  packet.status = "candidate";
+  const packetPath = path.join(loaded.topicDir, packetFileName);
+  return (
+    await writeFile(packetPath, packetMarkdown(packet), "utf8"),
+    {
+      ok: true,
+      topicId: loaded.topicId,
+      topicRef: toPortableRelativePath(path.relative(projectRoot, loaded.topicDir)),
+      packetId: packet.packet_id,
+      packetRef: toPortableRelativePath(path.relative(projectRoot, packetPath)),
+      waveId: packet.wave_id,
+      status: packet.status,
+    }
+  );
+}
+export async function loadTopicPacket(projectRoot, input, packetId) {
+  const loaded = await loadTopicReport(projectRoot, input);
+  if (!loaded.ok) return loaded;
+  const packetPath = path.join(loaded.topicDir, packetFilenameFromId(packetId)),
+    packetText = await readTextIfFile(packetPath);
+  if (packetText === null) return { ok: false, error: `Packet not found: ${packetId}` };
+  const packet = parsePacketDraft(packetText);
+  return !packet || typeof packet != "object"
+    ? { ok: false, error: `Packet is not valid YAML/frontmatter: ${packetId}` }
+    : { ok: true, ...loaded, packetPath, packet };
+}
+export async function listWavePackets(topicDir, waveId) {
+  const entries = await readdir(topicDir, { withFileTypes: true }),
+    packets = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.startsWith("packet-") || !entry.name.endsWith(".md"))
+      continue;
+    const packetPath = path.join(topicDir, entry.name),
+      packetText = await readTextIfFile(packetPath),
+      packet = readFrontmatterObject(packetText ?? "");
+    packet?.wave_id === waveId && packets.push({ packet, packetPath, packetRefName: entry.name });
+  }
+  return packets.sort((left, right) => left.packetRefName.localeCompare(right.packetRefName));
+}
+export async function listWaveResults(topicDir, waveId) {
+  const entries = await readdir(topicDir, { withFileTypes: true }),
+    results = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.startsWith("result-") || !entry.name.endsWith(".md"))
+      continue;
+    const resultPath = path.join(topicDir, entry.name),
+      resultText = await readTextIfFile(resultPath),
+      result = readFrontmatterObject(resultText ?? "");
+    result?.wave_id === waveId && results.push({ result, resultPath, resultRefName: entry.name });
+  }
+  return results.sort((left, right) => left.resultRefName.localeCompare(right.resultRefName));
+}