@beyondwork/docx-react-component 1.0.0 → 1.0.1

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

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