@beyondwork/docx-react-component 1.0.0

package/services/react-word-editor/lib/run-artifacts.ts

@@ -0,0 +1,934 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  createHarnessSession,
+  DOCX_MIME_TYPE,
+  getHarnessSource,
+  readHarnessSourceBytes,
+  saveHarnessExport,
+  saveHarnessValidationRun,
+  type HarnessExportRecord,
+  type HarnessSessionRecord,
+  type HarnessSourceRecord,
+  type HarnessValidationReport,
+  type HarnessValidationRunRecord,
+} from "./storage.ts";
+import { validateDocxWithService } from "./validator-client.ts";
+import * as docxSessionModule from "../../../src/io/docx-session.ts";
+import * as documentRuntimeModule from "../../../src/runtime/document-runtime.ts";
+
+const moduleDirPath = path.dirname(fileURLToPath(import.meta.url));
+const serviceRootDir = path.resolve(moduleDirPath, "..");
+const repoRootDir = path.resolve(serviceRootDir, "../..");
+const LEGACY_PILOT_ROOT_DIR = path.join(repoRootDir, ".tmp/wave-9-pilot");
+const WAVE_10_CERTIFICATION_ROOT_DIR = path.join(repoRootDir, ".tmp/wave-10-certification");
+const proofBundleRoots = {
+  9: LEGACY_PILOT_ROOT_DIR,
+  10: WAVE_10_CERTIFICATION_ROOT_DIR,
+} as const;
+
+const RUN_STORY_VERSION = "wave-proof-run-story/1";
+const ARTIFACT_MANIFEST_VERSION = "wave-proof-artifact-manifest/1";
+const RUN_LINKAGE_CHECK_VERSION = "wave-proof-run-linkage-check/1";
+const DEFAULT_PROOF_WAVE = 9 as const;
+
+export type ProofWave = keyof typeof proofBundleRoots;
+
+type RunTrigger =
+  | "fixture-route"
+  | "scenario-route"
+  | "validate-route"
+  | "manual-attachment"
+  | "proof-smoke";
+
+type ProofContext = {
+  proofWave: ProofWave;
+  bundleId: string;
+};
+
+type RunStorySource = {
+  sourceId: string;
+  sourceKind: HarnessSourceRecord["sourceKind"];
+  sourceLabel: string;
+  fileName: string;
+  byteLength?: number;
+  fixtureId?: string;
+  scenarioId?: string;
+  validatorPolicy?: HarnessSourceRecord["validatorPolicy"];
+};
+
+type RunStorySession = {
+  sessionId: string;
+  documentId: string;
+  createdAt: string;
+};
+
+type RunStoryExportArtifact = {
+  exportId: string;
+  sessionId: string;
+  fileName: string;
+  byteLength: number;
+  createdAt: string;
+  apiPath: string;
+  artifactRelativePath: string;
+};
+
+type RunStoryValidationDelta = {
+  packageFindingDelta: number;
+  sdkFindingDelta: number;
+};
+
+type RunStoryValidationArtifact = {
+  validationRunId: string;
+  exportId?: string;
+  sourceId?: string;
+  sessionId?: string;
+  targetType: HarnessValidationRunRecord["targetType"];
+  fileName: string;
+  byteLength: number;
+  createdAt: string;
+  service: string;
+  apiPath: string;
+  artifactRelativePath: string;
+  summary: HarnessValidationRunRecord["summary"];
+  deltaFromSource?: RunStoryValidationDelta;
+};
+
+type RunStoryManualCertification = {
+  state: "pending" | "attached";
+  artifactRelativePath: string;
+  routeHint: "/api/certification";
+  note: string;
+  attachedAt?: string;
+};
+
+export type RunCompatibilitySummary = {
+  featureClassFocus?: HarnessSourceRecord["featureClassFocus"];
+  readOnly: boolean;
+  blockExport: boolean;
+  blockExportReasons: string[];
+  warningCount: number;
+  errorCount: number;
+  supportedFeatureCount: number;
+  preserveOnlyFeatureCount: number;
+  unsupportedFatalFeatureCount: number;
+  fatalError?: {
+    code: string;
+    message: string;
+  };
+};
+
+export type RunExecutionOutcome =
+  | {
+      state: "exported-and-validated";
+    }
+  | {
+      state: "blocked-before-export";
+      reason: string;
+    };
+
+export type HarnessRunStory = {
+  schemaVersion: typeof RUN_STORY_VERSION;
+  runId: string;
+  trigger: RunTrigger;
+  createdAt: string;
+  updatedAt: string;
+  proofContext: ProofContext;
+  source: RunStorySource;
+  session?: RunStorySession;
+  compatibilitySummary?: RunCompatibilitySummary;
+  executionOutcome?: RunExecutionOutcome;
+  exportArtifact?: RunStoryExportArtifact;
+  validationArtifact?: RunStoryValidationArtifact;
+  manualCertification: RunStoryManualCertification;
+};
+
+type ArtifactManifestEntry = {
+  runId: string;
+  trigger: RunTrigger;
+  proofWave: ProofWave;
+  bundleId: string;
+  sourceId: string;
+  sourceKind: HarnessSourceRecord["sourceKind"];
+  sourceLabel: string;
+  sessionId?: string;
+  exportId?: string;
+  validationRunId?: string;
+  manualCertificationState: RunStoryManualCertification["state"];
+  storyRelativePath: string;
+  exportArtifactRelativePath?: string;
+  validationArtifactRelativePath?: string;
+  updatedAt: string;
+};
+
+type ArtifactManifest = {
+  schemaVersion: typeof ARTIFACT_MANIFEST_VERSION;
+  generatedAt: string;
+  runs: ArtifactManifestEntry[];
+};
+
+type RunLinkageCheckEntry = {
+  runId: string;
+  state: "ok" | "gap";
+  sourceKind: HarnessSourceRecord["sourceKind"];
+  checks: {
+    storyFilePresent: boolean;
+    manualSlotReserved: boolean;
+    exportLinked: boolean;
+    validationLinked: boolean;
+    validationMatchesExport: boolean;
+    sessionLinked: boolean;
+  };
+  detail: string;
+};
+
+type RunLinkageCheck = {
+  schemaVersion: typeof RUN_LINKAGE_CHECK_VERSION;
+  checkedAt: string;
+  summary: {
+    runCount: number;
+    okCount: number;
+    gapCount: number;
+  };
+  runs: RunLinkageCheckEntry[];
+};
+
+type ManualCertificationPlaceholder = {
+  schemaVersion: "wave-proof-manual-certification-slot/1";
+  runId: string;
+  proofWave: ProofWave;
+  bundleId: string;
+  state: RunStoryManualCertification["state"];
+  routeHint: RunStoryManualCertification["routeHint"];
+  note: string;
+  sourceId: string;
+  sourceKind: HarnessSourceRecord["sourceKind"];
+};
+
+function withBlockedExportReason(
+  compatibilitySummary: RunCompatibilitySummary,
+  blockedReason: string,
+): RunCompatibilitySummary {
+  const blockExportReasons = compatibilitySummary.blockExportReasons.includes(blockedReason)
+    ? compatibilitySummary.blockExportReasons
+    : [...compatibilitySummary.blockExportReasons, blockedReason];
+
+  return {
+    ...compatibilitySummary,
+    blockExport: true,
+    blockExportReasons,
+  };
+}
+
+function isProofWave(value: number | undefined): value is ProofWave {
+  return value === 9 || value === 10;
+}
+
+function getProofBundleRootDir(proofWave: ProofWave): string {
+  return proofBundleRoots[proofWave];
+}
+
+function getRunsDir(proofWave: ProofWave): string {
+  return path.join(getProofBundleRootDir(proofWave), "runs");
+}
+
+function getArtifactManifestPath(proofWave: ProofWave): string {
+  return path.join(getProofBundleRootDir(proofWave), "artifact-manifest.json");
+}
+
+function getRunLinkageCheckPath(proofWave: ProofWave): string {
+  return path.join(getProofBundleRootDir(proofWave), "run-linkage-check.json");
+}
+
+function sanitizeFileName(fileName: string): string {
+  const sanitized = fileName.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/-+/g, "-");
+  return sanitized.length > 0 ? sanitized : "document.docx";
+}
+
+function resolveLoadDocxEditorSession() {
+  const candidate =
+    (docxSessionModule as { loadDocxEditorSession?: unknown }).loadDocxEditorSession ||
+    (docxSessionModule as { default?: { loadDocxEditorSession?: unknown } }).default
+      ?.loadDocxEditorSession;
+
+  if (typeof candidate !== "function") {
+    throw new Error("loadDocxEditorSession is not available in the current runtime.");
+  }
+
+  return candidate as typeof import("../../../src/io/docx-session.ts").loadDocxEditorSession;
+}
+
+function resolveCreateDocumentRuntime() {
+  const candidate =
+    (documentRuntimeModule as { createDocumentRuntime?: unknown }).createDocumentRuntime ||
+    (documentRuntimeModule as { default?: { createDocumentRuntime?: unknown } }).default
+      ?.createDocumentRuntime;
+
+  if (typeof candidate !== "function") {
+    throw new Error("createDocumentRuntime is not available in the current runtime.");
+  }
+
+  return candidate as typeof import("../../../src/runtime/document-runtime.ts").createDocumentRuntime;
+}
+
+function buildRunId(prefix = "wave9-run"): string {
+  return `${prefix}-${randomUUID().slice(0, 12)}`;
+}
+
+function getRunDir(proofWave: ProofWave, runId: string): string {
+  return path.join(getRunsDir(proofWave), runId);
+}
+
+function getRunStoryPath(proofWave: ProofWave, runId: string): string {
+  return path.join(getRunDir(proofWave, runId), "story.json");
+}
+
+function getRunStoryRelativePath(proofWave: ProofWave, runId: string): string {
+  return path.relative(getProofBundleRootDir(proofWave), getRunStoryPath(proofWave, runId));
+}
+
+function getManualCertificationRelativePath(runId: string): string {
+  return path.join("runs", runId, "manual-certification.json");
+}
+
+async function ensureBundleLayout(proofWave: ProofWave): Promise<void> {
+  await mkdir(getRunsDir(proofWave), { recursive: true });
+}
+
+async function writeJsonAtomic(filePath: string, value: unknown): Promise<void> {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  await writeFile(tempPath, JSON.stringify(value, null, 2));
+  await rename(tempPath, filePath);
+}
+
+async function writeBuffer(filePath: string, value: Uint8Array): Promise<void> {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, Buffer.from(value));
+}
+
+async function readRunStoryFromWave(
+  proofWave: ProofWave,
+  runId: string,
+): Promise<HarnessRunStory | undefined> {
+  try {
+    const raw = await readFile(getRunStoryPath(proofWave, runId), "utf8");
+    const parsed = JSON.parse(raw) as Partial<HarnessRunStory>;
+    return {
+      ...parsed,
+      schemaVersion: RUN_STORY_VERSION,
+      runId: parsed.runId || runId,
+      trigger: parsed.trigger || "proof-smoke",
+      createdAt: parsed.createdAt || new Date().toISOString(),
+      updatedAt: parsed.updatedAt || parsed.createdAt || new Date().toISOString(),
+      proofContext: parsed.proofContext || {
+        proofWave,
+        bundleId: `wave-${proofWave}-legacy`,
+      },
+      source: parsed.source as HarnessRunStory["source"],
+      manualCertification:
+        parsed.manualCertification ||
+        ({
+          state: "pending",
+          artifactRelativePath: getManualCertificationRelativePath(runId),
+          routeHint: "/api/certification",
+          note: "Reserved slot for manual Word certification evidence linked to this run.",
+        } satisfies HarnessRunStory["manualCertification"]),
+    } as HarnessRunStory;
+  } catch {
+    return undefined;
+  }
+}
+
+async function readRunStory(runId: string): Promise<HarnessRunStory | undefined> {
+  for (const proofWave of [10, 9] as const) {
+    const story = await readRunStoryFromWave(proofWave, runId);
+
+    if (story) {
+      return story;
+    }
+  }
+
+  return undefined;
+}
+
+async function writeManualCertificationPlaceholder(story: HarnessRunStory): Promise<void> {
+  const placeholder: ManualCertificationPlaceholder = {
+    schemaVersion: "wave-proof-manual-certification-slot/1",
+    runId: story.runId,
+    proofWave: story.proofContext.proofWave,
+    bundleId: story.proofContext.bundleId,
+    state: story.manualCertification.state,
+    routeHint: story.manualCertification.routeHint,
+    note: story.manualCertification.note,
+    sourceId: story.source.sourceId,
+    sourceKind: story.source.sourceKind,
+  };
+
+  await writeJsonAtomic(
+    path.join(
+      getProofBundleRootDir(story.proofContext.proofWave),
+      story.manualCertification.artifactRelativePath,
+    ),
+    placeholder,
+  );
+}
+
+async function writeRunStory(story: HarnessRunStory): Promise<HarnessRunStory> {
+  await ensureBundleLayout(story.proofContext.proofWave);
+  const normalized: HarnessRunStory = {
+    ...story,
+    schemaVersion: RUN_STORY_VERSION,
+    updatedAt: new Date().toISOString(),
+  };
+  await writeJsonAtomic(
+    getRunStoryPath(normalized.proofContext.proofWave, normalized.runId),
+    normalized,
+  );
+  await writeManualCertificationPlaceholder(normalized);
+  await syncPilotIndexes(normalized.proofContext.proofWave);
+  return normalized;
+}
+
+async function listRunStories(proofWave: ProofWave): Promise<HarnessRunStory[]> {
+  await ensureBundleLayout(proofWave);
+
+  const entries = await readdir(getRunsDir(proofWave), { withFileTypes: true });
+  const stories = await Promise.all(
+    entries
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => readRunStoryFromWave(proofWave, entry.name)),
+  );
+
+  return stories
+    .filter((story): story is HarnessRunStory => Boolean(story))
+    .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+}
+
+function buildValidationDelta(
+  source: HarnessSourceRecord,
+  run: HarnessValidationRunRecord,
+): RunStoryValidationDelta | undefined {
+  if (!source.validatorPolicy) {
+    return undefined;
+  }
+
+  return {
+    packageFindingDelta:
+      run.summary.packageFindingCount - source.validatorPolicy.sourcePackageFindingCount,
+    sdkFindingDelta:
+      run.summary.sdkFindingCount - source.validatorPolicy.sourceSdkFindingCount,
+  };
+}
+
+async function syncPilotIndexes(proofWave: ProofWave): Promise<void> {
+  const stories = await listRunStories(proofWave);
+  const manifest: ArtifactManifest = {
+    schemaVersion: ARTIFACT_MANIFEST_VERSION,
+    generatedAt: new Date().toISOString(),
+    runs: stories.map((story) => ({
+      runId: story.runId,
+      trigger: story.trigger,
+      proofWave: story.proofContext.proofWave,
+      bundleId: story.proofContext.bundleId,
+      sourceId: story.source.sourceId,
+      sourceKind: story.source.sourceKind,
+      sourceLabel: story.source.sourceLabel,
+      sessionId: story.session?.sessionId,
+      exportId: story.exportArtifact?.exportId,
+      validationRunId: story.validationArtifact?.validationRunId,
+      manualCertificationState: story.manualCertification.state,
+      storyRelativePath: getRunStoryRelativePath(story.proofContext.proofWave, story.runId),
+      exportArtifactRelativePath: story.exportArtifact?.artifactRelativePath,
+      validationArtifactRelativePath: story.validationArtifact?.artifactRelativePath,
+      updatedAt: story.updatedAt,
+    })),
+  };
+
+  const linkageEntries: RunLinkageCheckEntry[] = stories.map((story) => {
+    const checks = {
+      storyFilePresent: true,
+      manualSlotReserved: story.manualCertification.artifactRelativePath.length > 0,
+      exportLinked: Boolean(story.exportArtifact?.exportId && story.exportArtifact.apiPath),
+      validationLinked: Boolean(
+        story.validationArtifact?.validationRunId && story.validationArtifact.apiPath,
+      ),
+      validationMatchesExport:
+        !story.validationArtifact?.exportId ||
+        story.validationArtifact.exportId === story.exportArtifact?.exportId,
+      sessionLinked: Boolean(story.session?.sessionId),
+    };
+
+    const state =
+      checks.storyFilePresent &&
+      checks.manualSlotReserved &&
+      checks.exportLinked &&
+      checks.validationLinked &&
+      checks.validationMatchesExport &&
+      checks.sessionLinked
+        ? "ok"
+        : "gap";
+
+    return {
+      runId: story.runId,
+      state,
+      sourceKind: story.source.sourceKind,
+      checks,
+      detail:
+        state === "ok"
+          ? "linked run story has session, export, validation, and manual-certification slot"
+          : "linked run story is missing at least one required artifact or linkage",
+    };
+  });
+
+  const linkage: RunLinkageCheck = {
+    schemaVersion: RUN_LINKAGE_CHECK_VERSION,
+    checkedAt: new Date().toISOString(),
+    summary: {
+      runCount: linkageEntries.length,
+      okCount: linkageEntries.filter((entry) => entry.state === "ok").length,
+      gapCount: linkageEntries.filter((entry) => entry.state === "gap").length,
+    },
+    runs: linkageEntries,
+  };
+
+  await writeJsonAtomic(getArtifactManifestPath(proofWave), manifest);
+  await writeJsonAtomic(getRunLinkageCheckPath(proofWave), linkage);
+}
+
+async function requireRunStory(runId: string): Promise<HarnessRunStory> {
+  const story = await readRunStory(runId);
+
+  if (!story) {
+    throw new Error(`Linked run story ${runId} does not exist.`);
+  }
+
+  return story;
+}
+
+async function copyExportArtifact(runId: string, exportRecord: HarnessExportRecord, bytes: Uint8Array) {
+  const story = await requireRunStory(runId);
+  const artifactRelativePath = path.join(
+    "runs",
+    runId,
+    `${exportRecord.exportId}-${sanitizeFileName(exportRecord.fileName)}`,
+  );
+  await writeBuffer(
+    path.join(getProofBundleRootDir(story.proofContext.proofWave), artifactRelativePath),
+    bytes,
+  );
+  return artifactRelativePath;
+}
+
+async function copyValidationArtifact(
+  runId: string,
+  validationRun: HarnessValidationRunRecord,
+  report: HarnessValidationReport,
+) {
+  const story = await requireRunStory(runId);
+  const artifactRelativePath = path.join(
+    "runs",
+    runId,
+    `validation-${validationRun.runId}.json`,
+  );
+  await writeJsonAtomic(
+    path.join(getProofBundleRootDir(story.proofContext.proofWave), artifactRelativePath),
+    report,
+  );
+  return artifactRelativePath;
+}
+
+export async function createRunStoryForSource(input: {
+  sourceId: string;
+  requestedRunId?: string;
+  trigger: Extract<RunTrigger, "fixture-route" | "scenario-route" | "proof-smoke">;
+  proofWave?: number;
+  bundleId?: string;
+}): Promise<{
+  runStory: HarnessRunStory;
+  source: HarnessSourceRecord;
+  session: HarnessSessionRecord;
+}> {
+  const source = await getHarnessSource(input.sourceId);
+
+  if (!source?.available) {
+    throw new Error(`Harness source ${input.sourceId} is not available for automated runs.`);
+  }
+
+  const session = await createHarnessSession(source.sourceId);
+  const now = new Date().toISOString();
+  const proofWave = isProofWave(input.proofWave) ? input.proofWave : DEFAULT_PROOF_WAVE;
+  const bundleId = input.bundleId?.trim() || `wave-${proofWave}-${now.slice(0, 10)}`;
+  const runId =
+    input.requestedRunId?.trim() || buildRunId(`wave${proofWave}-${source.sourceKind}`);
+
+  const existing = await readRunStory(runId);
+  const story: HarnessRunStory = {
+    schemaVersion: RUN_STORY_VERSION,
+    runId,
+    trigger: input.trigger,
+    createdAt: existing?.createdAt || now,
+    updatedAt: now,
+    proofContext: existing?.proofContext || {
+      proofWave,
+      bundleId,
+    },
+    source: {
+      sourceId: source.sourceId,
+      sourceKind: source.sourceKind,
+      sourceLabel: source.sourceLabel,
+      fileName: source.fileName,
+      byteLength: source.byteLength,
+      fixtureId: source.fixtureId,
+      scenarioId: source.scenarioId,
+      validatorPolicy: source.validatorPolicy,
+    },
+    session: {
+      sessionId: session.sessionId,
+      documentId: session.documentId,
+      createdAt: session.createdAt,
+    },
+    compatibilitySummary: existing?.compatibilitySummary,
+    executionOutcome: existing?.executionOutcome,
+    exportArtifact: existing?.exportArtifact,
+    validationArtifact: existing?.validationArtifact,
+    manualCertification: existing?.manualCertification || {
+      state: "pending",
+      artifactRelativePath: getManualCertificationRelativePath(runId),
+      routeHint: "/api/certification",
+      note: "Reserved slot for manual Word certification evidence linked to this run.",
+    },
+  };
+
+  return {
+    runStory: await writeRunStory(story),
+    source,
+    session,
+  };
+}
+
+export async function attachExportArtifactToRun(input: {
+  runId: string;
+  sessionId: string;
+  fileName: string;
+  mimeType?: string;
+  bytes: Uint8Array;
+  reason?: string;
+}): Promise<{
+  runStory: HarnessRunStory;
+  exportRecord: HarnessExportRecord;
+}> {
+  const story = await requireRunStory(input.runId);
+  const exportRecord = await saveHarnessExport({
+    sessionId: input.sessionId,
+    fileName: input.fileName,
+    mimeType: input.mimeType || DOCX_MIME_TYPE,
+    bytes: input.bytes,
+    reason: input.reason,
+  });
+  const artifactRelativePath = await copyExportArtifact(input.runId, exportRecord, input.bytes);
+
+  const nextStory = await writeRunStory({
+    ...story,
+    exportArtifact: {
+      exportId: exportRecord.exportId,
+      sessionId: exportRecord.sessionId,
+      fileName: exportRecord.fileName,
+      byteLength: exportRecord.byteLength,
+      createdAt: exportRecord.createdAt,
+      apiPath: `/api/exports/${exportRecord.exportId}`,
+      artifactRelativePath,
+    },
+  });
+
+  return {
+    runStory: nextStory,
+    exportRecord,
+  };
+}
+
+export async function attachValidationArtifactToRun(input: {
+  runId: string;
+  bytes: Uint8Array;
+  fileName: string;
+  byteLength: number;
+  sessionId?: string;
+  sourceId?: string;
+  exportId?: string;
+  targetType: HarnessValidationRunRecord["targetType"];
+}): Promise<{
+  runStory: HarnessRunStory;
+  report: HarnessValidationReport;
+  validationRun: HarnessValidationRunRecord;
+}> {
+  const story = await requireRunStory(input.runId);
+  const report = await validateDocxWithService({
+    bytes: input.bytes,
+    fileName: input.fileName,
+  });
+  const validationRun = await saveHarnessValidationRun({
+    report,
+    fileName: input.fileName,
+    byteLength: input.byteLength,
+    sessionId: input.sessionId,
+    sourceId: input.sourceId,
+    exportId: input.exportId,
+    targetType: input.targetType,
+  });
+  const source = input.sourceId ? await getHarnessSource(input.sourceId) : undefined;
+  const artifactRelativePath = await copyValidationArtifact(input.runId, validationRun, report);
+
+  const nextStory = await writeRunStory({
+    ...story,
+    validationArtifact: {
+      validationRunId: validationRun.runId,
+      exportId: validationRun.exportId,
+      sourceId: validationRun.sourceId,
+      sessionId: validationRun.sessionId,
+      targetType: validationRun.targetType,
+      fileName: validationRun.fileName,
+      byteLength: validationRun.byteLength,
+      createdAt: validationRun.createdAt,
+      service: validationRun.service,
+      apiPath: `/api/runs/${validationRun.runId}`,
+      artifactRelativePath,
+      summary: validationRun.summary,
+      deltaFromSource: source ? buildValidationDelta(source, validationRun) : undefined,
+    },
+  });
+
+  return {
+    runStory: nextStory,
+    report,
+    validationRun,
+  };
+}
+
+export async function executeAutomatedSourceRun(input: {
+  sourceId: string;
+  trigger: Extract<RunTrigger, "fixture-route" | "scenario-route" | "proof-smoke">;
+  requestedRunId?: string;
+  exportReason?: string;
+  exportFileName?: string;
+  proofWave?: number;
+  bundleId?: string;
+}): Promise<{
+  runStory: HarnessRunStory;
+  source: HarnessSourceRecord;
+  session: HarnessSessionRecord;
+  exportRecord?: HarnessExportRecord;
+  report?: HarnessValidationReport;
+  validationRun?: HarnessValidationRunRecord;
+  compatibilitySummary: RunCompatibilitySummary;
+  executionOutcome: RunExecutionOutcome;
+}> {
+  const { runStory: createdRunStory, source, session } = await createRunStoryForSource({
+    sourceId: input.sourceId,
+    requestedRunId: input.requestedRunId,
+    trigger: input.trigger,
+    proofWave: input.proofWave,
+    bundleId: input.bundleId,
+  });
+
+  const sourceBytes = await readHarnessSourceBytes(source.sourceId);
+  const exportFileName =
+    input.exportFileName ||
+    `${createdRunStory.runId}-${sanitizeFileName(source.fileName)}`;
+  const docxSession = resolveLoadDocxEditorSession()({
+    documentId: session.documentId,
+    sourceLabel: source.sourceLabel,
+    bytes: sourceBytes,
+    editorBuild: "harness-automated-run",
+  });
+  const runtime = resolveCreateDocumentRuntime()({
+    documentId: session.documentId,
+    initialSnapshot: docxSession.initialSnapshot,
+    sourceKind: "docx",
+    sourceLabel: source.sourceLabel,
+    readOnly: docxSession.readOnly,
+    editorBuild: docxSession.initialSnapshot.editorBuild,
+    fatalError: docxSession.fatalError,
+    exportDocx: docxSession.exportDocx,
+    defaultAuthorId: "harness-operator",
+  });
+  const initialRenderSnapshot = runtime.getRenderSnapshot();
+  const compatibility = initialRenderSnapshot.compatibility || {
+    blockExport: false,
+    blockExportReasons: [],
+    warnings: [],
+    errors: [],
+    featureEntries: [],
+  };
+  const compatibilitySummary: RunCompatibilitySummary = {
+    featureClassFocus: source.featureClassFocus,
+    readOnly: initialRenderSnapshot.readOnly,
+    blockExport: compatibility.blockExport,
+    blockExportReasons: compatibility.blockExportReasons ?? [],
+    warningCount: (compatibility.warnings ?? []).length,
+    errorCount: (compatibility.errors ?? []).length,
+    supportedFeatureCount: (compatibility.featureEntries ?? []).filter(
+      (entry) => entry.featureClass === "supported-roundtrip",
+    ).length,
+    preserveOnlyFeatureCount: (compatibility.featureEntries ?? []).filter(
+      (entry) => entry.featureClass === "preserve-only",
+    ).length,
+    unsupportedFatalFeatureCount: (compatibility.featureEntries ?? []).filter(
+      (entry) => entry.featureClass === "unsupported-fatal",
+    ).length,
+    fatalError: initialRenderSnapshot.fatalError
+      ? {
+          code: initialRenderSnapshot.fatalError.code,
+          message: initialRenderSnapshot.fatalError.message,
+        }
+      : undefined,
+  };
+
+  if (source.featureClassFocus === "unsupported-fatal" || compatibility.blockExport) {
+    const blockedReason =
+      (compatibility.blockExportReasons ?? [])[0] ||
+      initialRenderSnapshot.fatalError?.message ||
+      "Automated run blocked export before validation.";
+    const blockedCompatibilitySummary = withBlockedExportReason(
+      compatibilitySummary,
+      blockedReason,
+    );
+    const runStory = await writeRunStory({
+      ...createdRunStory,
+      compatibilitySummary: blockedCompatibilitySummary,
+      executionOutcome: {
+        state: "blocked-before-export",
+        reason: blockedReason,
+      },
+      exportArtifact: undefined,
+      validationArtifact: undefined,
+    });
+
+    return {
+      runStory,
+      source,
+      session,
+      compatibilitySummary: blockedCompatibilitySummary,
+      executionOutcome: runStory.executionOutcome!,
+    };
+  }
+
+  let runtimeExport;
+
+  try {
+    runtimeExport = await runtime.exportDocx({
+      fileName: exportFileName,
+      reason:
+        input.exportReason ||
+        `Automated ${source.sourceKind} run ${createdRunStory.runId} exported the current runtime session package.`,
+    });
+  } catch (error) {
+    const blockedReason =
+      error instanceof Error
+        ? error.message
+        : "Automated run blocked export before validation.";
+    const blockedCompatibilitySummary = withBlockedExportReason(
+      compatibilitySummary,
+      blockedReason,
+    );
+    const runStory = await writeRunStory({
+      ...createdRunStory,
+      compatibilitySummary: blockedCompatibilitySummary,
+      executionOutcome: {
+        state: "blocked-before-export",
+        reason: blockedReason,
+      },
+      exportArtifact: undefined,
+      validationArtifact: undefined,
+    });
+
+    return {
+      runStory,
+      source,
+      session,
+      compatibilitySummary: blockedCompatibilitySummary,
+      executionOutcome: runStory.executionOutcome!,
+    };
+  }
+  const exportBytes = new Uint8Array(runtimeExport.bytes);
+
+  const { exportRecord } = await attachExportArtifactToRun({
+    runId: createdRunStory.runId,
+    sessionId: session.sessionId,
+    fileName: runtimeExport.fileName,
+    mimeType: runtimeExport.mimeType || DOCX_MIME_TYPE,
+    bytes: exportBytes,
+    reason:
+      input.exportReason ||
+      `Automated ${source.sourceKind} run ${createdRunStory.runId} exported the current runtime session package.`,
+  });
+
+  const { runStory, report, validationRun } = await attachValidationArtifactToRun({
+    runId: createdRunStory.runId,
+    bytes: exportBytes,
+    fileName: exportRecord.fileName,
+    byteLength: exportRecord.byteLength,
+    sessionId: session.sessionId,
+    sourceId: source.sourceId,
+    exportId: exportRecord.exportId,
+    targetType: "export",
+  });
+
+  return {
+    runStory: await writeRunStory({
+      ...runStory,
+      compatibilitySummary,
+      executionOutcome: {
+        state: "exported-and-validated",
+      },
+    }),
+    source,
+    session,
+    exportRecord,
+    report,
+    validationRun,
+    compatibilitySummary,
+    executionOutcome: {
+      state: "exported-and-validated",
+    },
+  };
+}
+
+export async function getPilotArtifactPaths(): Promise<{
+  pilotRootDir: string;
+  artifactManifestPath: string;
+  runLinkageCheckPath: string;
+}> {
+  await ensureBundleLayout(DEFAULT_PROOF_WAVE);
+
+  return {
+    pilotRootDir: getProofBundleRootDir(DEFAULT_PROOF_WAVE),
+    artifactManifestPath: getArtifactManifestPath(DEFAULT_PROOF_WAVE),
+    runLinkageCheckPath: getRunLinkageCheckPath(DEFAULT_PROOF_WAVE),
+  };
+}
+
+export async function getRunStory(runId: string): Promise<HarnessRunStory | undefined> {
+  return readRunStory(runId);
+}
+
+export async function recordProofSmokeArtifact(value: unknown): Promise<string> {
+  await ensureBundleLayout(DEFAULT_PROOF_WAVE);
+  const targetPath = path.join(
+    getProofBundleRootDir(DEFAULT_PROOF_WAVE),
+    "fixture-runner-smoke.json",
+  );
+  await writeJsonAtomic(targetPath, value);
+  return targetPath;
+}
+
+export async function pilotArtifactExists(relativePath: string): Promise<boolean> {
+  try {
+    await stat(path.join(getProofBundleRootDir(DEFAULT_PROOF_WAVE), relativePath));
+    return true;
+  } catch {
+    return false;
+  }
+}