@beyondwork/docx-react-component 1.0.0 → 1.0.2

package/services/react-word-editor/lib/storage.ts

@@ -1,953 +0,0 @@
-import { randomUUID } from "node:crypto";
-import { mkdir, readFile, readdir, rename, stat, unlink, writeFile } from "node:fs/promises";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-
-import {
-  getScenarioArtifactPath,
-  loadScenarioArtifacts,
-  type ScenarioValidatorPolicy,
-} from "./scenario-artifacts.ts";
-
-export const DOCX_MIME_TYPE =
-  "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
-export const HARNESS_ALLOWED_DOCX_MIME_TYPES = [DOCX_MIME_TYPE, "application/octet-stream"] as const;
-export const HARNESS_MAX_UPLOAD_BYTES = 20 * 1024 * 1024;
-export const HARNESS_UPLOAD_RETENTION_LIMIT = 100;
-export const HARNESS_SESSION_RETENTION_LIMIT = 100;
-export const HARNESS_EXPORT_RETENTION_LIMIT = 100;
-export const HARNESS_VALIDATION_RETENTION_LIMIT = 200;
-export const HARNESS_STORAGE_INDEX_VERSION = "react-word-editor-harness/1";
-
-type HarnessStorageMode = "configured-volume-path" | "default-local-path";
-
-type HarnessStorageIndex = {
-  version: typeof HARNESS_STORAGE_INDEX_VERSION;
-  uploads: HarnessUploadSourceRecord[];
-  sessions: HarnessSessionRecord[];
-  exports: HarnessExportRecord[];
-  validationRuns: HarnessValidationRunRecord[];
-};
-
-type FixtureManifest = {
-  manifestVersion: "docx-fixtures/1";
-  fixtures: FixtureManifestEntry[];
-};
-
-type FixtureManifestEntry = {
-  fixtureId: string;
-  name: string;
-  primaryFocus: string;
-  featureClassFocus: "supported-roundtrip" | "preserve-only" | "unsupported-fatal";
-  artifactStatus: string;
-  proofBearingWaves: number[];
-};
-
-type SourceLocator =
-  | {
-      kind: "repo-file";
-      absolutePath: string;
-    }
-  | {
-      kind: "storage-file";
-      relativePath: string;
-    };
-
-type HarnessSourceRecordBase = {
-  sourceId: string;
-  sourceKind: "fixture" | "scenario" | "upload";
-  name: string;
-  sourceLabel: string;
-  fileName: string;
-  mimeType: string;
-  byteLength?: number;
-  createdAt: string;
-  updatedAt: string;
-  available: boolean;
-  retentionClass: "repo-fixture" | "scenario-artifact" | "operator-upload";
-  locator?: SourceLocator;
-};
-
-export type HarnessSourceRecord = HarnessSourceRecordBase & {
-  fixtureId?: string;
-  scenarioId?: string;
-  noteFileName?: string;
-  primaryFocus?: string;
-  featureClassFocus?: string;
-  artifactStatus?: string;
-  proofBearingWaves?: number[];
-  releaseGate?: boolean;
-  waveTargets?: number[];
-  focusAreas?: string[];
-  validatorPolicy?: ScenarioValidatorPolicy;
-  wordExpectation?: string;
-};
-
-export type HarnessUploadSourceRecord = HarnessSourceRecordBase & {
-  sourceKind: "upload";
-};
-
-export type HarnessSessionRecord = {
-  sessionId: string;
-  documentId: string;
-  sourceId: string;
-  sourceKind: HarnessSourceRecord["sourceKind"];
-  sourceLabel: string;
-  createdAt: string;
-  updatedAt: string;
-  latestExportId?: string;
-  latestValidationRunId?: string;
-};
-
-export type HarnessExportRecord = {
-  exportId: string;
-  sessionId: string;
-  fileName: string;
-  mimeType: string;
-  byteLength: number;
-  storedRelativePath: string;
-  createdAt: string;
-  reason?: string;
-};
-
-export type HarnessValidationRunRecord = {
-  runId: string;
-  sessionId?: string;
-  sourceId?: string;
-  exportId?: string;
-  targetType: "source" | "export" | "direct-upload";
-  fileName: string;
-  byteLength: number;
-  storedRelativePath: string;
-  createdAt: string;
-  service: string;
-  summary: {
-    isValid: boolean;
-    packageFindingCount: number;
-    sdkFindingCount: number;
-  };
-};
-
-export type HarnessValidationReport = {
-  service?: string;
-  validatedAtUtc?: string;
-  document?: Record<string, unknown>;
-  summary?: {
-    isValid?: boolean;
-    packageFindingCount?: number;
-    sdkFindingCount?: number;
-  };
-  package?: {
-    findings?: unknown[];
-  };
-  sdk?: {
-    findings?: unknown[];
-  };
-  [key: string]: unknown;
-};
-
-export type HarnessHealthSnapshot = {
-  storageDir: string;
-  storage: {
-    configuredStorageDir?: string;
-    mode: HarnessStorageMode;
-    persistence: "file-backed-manifest-index";
-    indexVersion: typeof HARNESS_STORAGE_INDEX_VERSION;
-  };
-  assumptions: HarnessStorageAssumptions;
-  retentionPolicy: {
-    maxUploadBytes: number;
-    uploadArtifactLimit: number;
-    sessionLimit: number;
-    exportArtifactLimit: number;
-    validationRunLimit: number;
-    mode: "volume-backed-manual-review";
-  };
-  counts: {
-    fixtures: number;
-    scenarios: number;
-    uploads: number;
-    sessions: number;
-    exports: number;
-    validationRuns: number;
-  };
-  bytes: {
-    uploads: number;
-    exports: number;
-  };
-};
-
-export type HarnessStorageAssumptions = {
-  acceptedExtensions: [".docx"];
-  acceptedMimeTypes: readonly string[];
-  maxUploadBytes: number;
-  uploadArtifactLimit: number;
-  sessionLimit: number;
-  exportArtifactLimit: number;
-  validationRunLimit: number;
-  retentionMode: "volume-backed-manual-review";
-  storageMode: HarnessStorageMode;
-  activeStorageDir: string;
-  configuredStorageDir?: string;
-};
-
-export class HarnessStorageError extends Error {
-  readonly code: string;
-  readonly status: number;
-
-  constructor(code: string, status: number, message: string) {
-    super(message);
-    this.name = "HarnessStorageError";
-    this.code = code;
-    this.status = status;
-  }
-}
-
-export function isHarnessStorageError(error: unknown): error is HarnessStorageError {
-  return error instanceof HarnessStorageError;
-}
-
-const moduleDirPath = path.dirname(fileURLToPath(import.meta.url));
-const serviceRootDir = path.resolve(moduleDirPath, "..");
-const repoRootDir = path.resolve(serviceRootDir, "../..");
-const fixturesDirPath = path.join(repoRootDir, "test/fixtures/docx");
-const fixturesManifestPath = path.join(fixturesDirPath, "fixtures.manifest.json");
-const defaultStorageDir = path.join(serviceRootDir, ".tmp/react-word-editor-harness");
-
-function getConfiguredStorageDir(): string | undefined {
-  const value = process.env.HARNESS_STORAGE_DIR?.trim();
-  return value ? value : undefined;
-}
-
-function getStorageDir(): string {
-  return getConfiguredStorageDir() || defaultStorageDir;
-}
-
-function getStorageMode(): HarnessStorageMode {
-  return getConfiguredStorageDir() ? "configured-volume-path" : "default-local-path";
-}
-
-function getIndexPath(storageDir: string): string {
-  return path.join(storageDir, "index.json");
-}
-
-function getUploadsDir(storageDir: string): string {
-  return path.join(storageDir, "uploads");
-}
-
-function getExportsDir(storageDir: string): string {
-  return path.join(storageDir, "exports");
-}
-
-function getValidationDir(storageDir: string): string {
-  return path.join(storageDir, "validation-runs");
-}
-
-function createEmptyIndex(): HarnessStorageIndex {
-  return {
-    version: HARNESS_STORAGE_INDEX_VERSION,
-    uploads: [],
-    sessions: [],
-    exports: [],
-    validationRuns: [],
-  };
-}
-
-function normalizeIndex(raw: unknown): HarnessStorageIndex {
-  if (!raw || typeof raw !== "object") {
-    return createEmptyIndex();
-  }
-
-  const candidate = raw as Partial<HarnessStorageIndex>;
-
-  return {
-    version: HARNESS_STORAGE_INDEX_VERSION,
-    uploads: Array.isArray(candidate.uploads) ? candidate.uploads : [],
-    sessions: Array.isArray(candidate.sessions) ? candidate.sessions : [],
-    exports: Array.isArray(candidate.exports) ? candidate.exports : [],
-    validationRuns: Array.isArray(candidate.validationRuns) ? candidate.validationRuns : [],
-  };
-}
-
-async function ensureStorageLayout(): Promise<string> {
-  const storageDir = getStorageDir();
-  await mkdir(storageDir, { recursive: true });
-  await mkdir(getUploadsDir(storageDir), { recursive: true });
-  await mkdir(getExportsDir(storageDir), { recursive: true });
-  await mkdir(getValidationDir(storageDir), { recursive: true });
-
-  const indexPath = getIndexPath(storageDir);
-
-  try {
-    await stat(indexPath);
-  } catch {
-    await writeFile(indexPath, JSON.stringify(createEmptyIndex(), null, 2));
-  }
-
-  return storageDir;
-}
-
-async function readIndex(): Promise<HarnessStorageIndex> {
-  const storageDir = await ensureStorageLayout();
-  const raw = await readFile(getIndexPath(storageDir), "utf8");
-  const normalized = normalizeIndex(JSON.parse(raw));
-  const serialized = JSON.stringify(normalized, null, 2);
-
-  if (raw !== serialized) {
-    await writeIndex(normalized);
-  }
-
-  return normalized;
-}
-
-async function writeIndex(index: HarnessStorageIndex): Promise<void> {
-  const storageDir = await ensureStorageLayout();
-  const normalized = normalizeIndex(index);
-  const indexPath = getIndexPath(storageDir);
-  const tempPath = `${indexPath}.${process.pid}.${Date.now()}.tmp`;
-  await writeFile(tempPath, JSON.stringify(normalized, null, 2));
-  await rename(tempPath, indexPath);
-}
-
-async function loadFixtureManifest(): Promise<FixtureManifest> {
-  const raw = await readFile(fixturesManifestPath, "utf8");
-  return JSON.parse(raw) as FixtureManifest;
-}
-
-async function findFixtureFileNameMap(): Promise<Map<string, string>> {
-  const entries = await readdir(fixturesDirPath);
-  const map = new Map<string, string>();
-
-  for (const entry of entries) {
-    const match = /^(F\d{2})-.*\.docx$/i.exec(entry);
-
-    if (match) {
-      map.set(match[1].toUpperCase(), entry);
-    }
-  }
-
-  return map;
-}
-
-async function listFixtureSources(): Promise<HarnessSourceRecord[]> {
-  const [manifest, fileNameMap] = await Promise.all([
-    loadFixtureManifest(),
-    findFixtureFileNameMap(),
-  ]);
-
-  return Promise.all(
-    manifest.fixtures.map(async (fixture) => {
-      const resolvedFileName = fileNameMap.get(fixture.fixtureId.toUpperCase());
-      const absolutePath = resolvedFileName ? path.join(fixturesDirPath, resolvedFileName) : undefined;
-      const fileStat = absolutePath ? await stat(absolutePath) : undefined;
-
-      return {
-        sourceId: `fixture:${fixture.fixtureId}`,
-        sourceKind: "fixture",
-        fixtureId: fixture.fixtureId,
-        name: fixture.name,
-        sourceLabel: `${fixture.fixtureId} ${fixture.name}`,
-        fileName: resolvedFileName ?? `${fixture.fixtureId}.docx`,
-        mimeType: DOCX_MIME_TYPE,
-        byteLength: fileStat?.size,
-        createdAt: "manifest-frozen",
-        updatedAt: "manifest-frozen",
-        available: Boolean(absolutePath),
-        retentionClass: "repo-fixture",
-        locator: absolutePath
-          ? {
-              kind: "repo-file",
-              absolutePath,
-            }
-          : undefined,
-        primaryFocus: fixture.primaryFocus,
-        featureClassFocus: fixture.featureClassFocus,
-        artifactStatus: fixture.artifactStatus,
-        proofBearingWaves: fixture.proofBearingWaves,
-      } satisfies HarnessSourceRecord;
-    }),
-  );
-}
-
-async function listScenarioSources(): Promise<HarnessSourceRecord[]> {
-  const scenarios = await loadScenarioArtifacts();
-
-  return Promise.all(
-    scenarios.map(async (scenario) => {
-      const absolutePath = getScenarioArtifactPath(scenario.fileName);
-      const fileStat = await stat(absolutePath);
-
-      return {
-        sourceId: `scenario:${scenario.scenarioId}`,
-        sourceKind: "scenario",
-        scenarioId: scenario.scenarioId,
-        name: scenario.name,
-        sourceLabel: `${scenario.scenarioId} ${scenario.name}`,
-        fileName: scenario.fileName,
-        mimeType: DOCX_MIME_TYPE,
-        byteLength: fileStat.size,
-        createdAt: "scenario-frozen",
-        updatedAt: "scenario-frozen",
-        available: true,
-        retentionClass: "scenario-artifact",
-        locator: {
-          kind: "repo-file",
-          absolutePath,
-        },
-        noteFileName: scenario.noteFileName,
-        releaseGate: scenario.releaseGate,
-        waveTargets: scenario.waveTargets,
-        focusAreas: scenario.focusAreas,
-        validatorPolicy: scenario.validatorPolicy,
-        wordExpectation: scenario.wordExpectation,
-      } satisfies HarnessSourceRecord;
-    }),
-  );
-}
-
-function sortSources(a: HarnessSourceRecord, b: HarnessSourceRecord): number {
-  const sourceOrder = {
-    fixture: 0,
-    scenario: 1,
-    upload: 2,
-  } as const;
-
-  if (sourceOrder[a.sourceKind] !== sourceOrder[b.sourceKind]) {
-    return sourceOrder[a.sourceKind] - sourceOrder[b.sourceKind];
-  }
-
-  if (a.sourceKind === "upload" && b.sourceKind === "upload") {
-    return b.createdAt.localeCompare(a.createdAt);
-  }
-
-  return a.sourceLabel.localeCompare(b.sourceLabel);
-}
-
-function sanitizeFileName(fileName: string): string {
-  const sanitized = fileName.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/-+/g, "-");
-  return sanitized.length > 0 ? sanitized : "document.docx";
-}
-
-export function getHarnessStorageAssumptions(): HarnessStorageAssumptions {
-  return {
-    acceptedExtensions: [".docx"],
-    acceptedMimeTypes: HARNESS_ALLOWED_DOCX_MIME_TYPES,
-    maxUploadBytes: HARNESS_MAX_UPLOAD_BYTES,
-    uploadArtifactLimit: HARNESS_UPLOAD_RETENTION_LIMIT,
-    sessionLimit: HARNESS_SESSION_RETENTION_LIMIT,
-    exportArtifactLimit: HARNESS_EXPORT_RETENTION_LIMIT,
-    validationRunLimit: HARNESS_VALIDATION_RETENTION_LIMIT,
-    retentionMode: "volume-backed-manual-review",
-    storageMode: getStorageMode(),
-    activeStorageDir: getStorageDir(),
-    configuredStorageDir: getConfiguredStorageDir(),
-  };
-}
-
-export function assertAcceptedDocxPayload(
-  fileName: string,
-  byteLength: number,
-  mimeType?: string,
-): void {
-  if (!fileName.toLowerCase().endsWith(".docx")) {
-    throw new HarnessStorageError(
-      "invalid_extension",
-      415,
-      "Harness uploads and exports must be `.docx` packages.",
-    );
-  }
-
-  const normalizedMimeType = mimeType?.trim().toLowerCase();
-
-  if (
-    normalizedMimeType &&
-    !HARNESS_ALLOWED_DOCX_MIME_TYPES.includes(
-      normalizedMimeType as (typeof HARNESS_ALLOWED_DOCX_MIME_TYPES)[number],
-    )
-  ) {
-    throw new HarnessStorageError(
-      "unsupported_mime_type",
-      415,
-      `Harness accepts DOCX uploads with ${HARNESS_ALLOWED_DOCX_MIME_TYPES.join(" or ")} MIME types.`,
-    );
-  }
-
-  if (byteLength <= 0) {
-    throw new HarnessStorageError("empty_file", 400, "Harness uploads cannot be empty.");
-  }
-
-  if (byteLength > HARNESS_MAX_UPLOAD_BYTES) {
-    throw new HarnessStorageError(
-      "file_too_large",
-      413,
-      `Harness uploads are capped at ${Math.round(HARNESS_MAX_UPLOAD_BYTES / (1024 * 1024))} MiB.`,
-    );
-  }
-}
-
-function createDocumentId(prefix: string): string {
-  return `${prefix}-${randomUUID().slice(0, 12)}`;
-}
-
-function summarizeValidationReport(report: HarnessValidationReport): HarnessValidationRunRecord["summary"] {
-  const packageFindingCount =
-    typeof report.summary?.packageFindingCount === "number"
-      ? report.summary.packageFindingCount
-      : Array.isArray(report.package?.findings)
-        ? report.package.findings.length
-        : 0;
-  const sdkFindingCount =
-    typeof report.summary?.sdkFindingCount === "number"
-      ? report.summary.sdkFindingCount
-      : Array.isArray(report.sdk?.findings)
-        ? report.sdk.findings.length
-        : 0;
-
-  return {
-    isValid:
-      typeof report.summary?.isValid === "boolean"
-        ? report.summary.isValid
-        : packageFindingCount === 0 && sdkFindingCount === 0,
-    packageFindingCount,
-    sdkFindingCount,
-  };
-}
-
-async function pruneArtifactsIfNeeded(index: HarnessStorageIndex): Promise<HarnessStorageIndex> {
-  const storageDir = await ensureStorageLayout();
-  let nextIndex = index;
-
-  if (nextIndex.uploads.length > HARNESS_UPLOAD_RETENTION_LIMIT) {
-    const protectedSourceIds = new Set(nextIndex.sessions.map((session) => session.sourceId));
-    const retained: HarnessUploadSourceRecord[] = [];
-    const trimmed: HarnessUploadSourceRecord[] = [];
-
-    for (const record of nextIndex.uploads) {
-      if (
-        retained.length < HARNESS_UPLOAD_RETENTION_LIMIT ||
-        protectedSourceIds.has(record.sourceId)
-      ) {
-        retained.push(record);
-      } else {
-        trimmed.push(record);
-      }
-    }
-
-    for (const record of trimmed) {
-      if (record.locator?.kind !== "storage-file") {
-        continue;
-      }
-      try {
-        await unlink(path.join(storageDir, record.locator.relativePath));
-      } catch {
-        // Best-effort cleanup for old upload artifacts.
-      }
-    }
-
-    nextIndex = {
-      ...nextIndex,
-      uploads: retained,
-    };
-  }
-
-  if (nextIndex.sessions.length > HARNESS_SESSION_RETENTION_LIMIT) {
-    const protectedSessionIds = new Set(
-      [
-        ...nextIndex.exports.map((record) => record.sessionId),
-        ...nextIndex.validationRuns
-          .map((record) => record.sessionId)
-          .filter((value): value is string => typeof value === "string"),
-      ],
-    );
-    const retained: HarnessSessionRecord[] = [];
-
-    for (const record of nextIndex.sessions) {
-      if (
-        retained.length < HARNESS_SESSION_RETENTION_LIMIT ||
-        protectedSessionIds.has(record.sessionId)
-      ) {
-        retained.push(record);
-      }
-    }
-
-    nextIndex = {
-      ...nextIndex,
-      sessions: retained,
-    };
-  }
-
-  if (nextIndex.validationRuns.length > HARNESS_VALIDATION_RETENTION_LIMIT) {
-    const retained = nextIndex.validationRuns.slice(0, HARNESS_VALIDATION_RETENTION_LIMIT);
-    const trimmed = nextIndex.validationRuns.slice(HARNESS_VALIDATION_RETENTION_LIMIT);
-
-    for (const record of trimmed) {
-      try {
-        await unlink(path.join(storageDir, record.storedRelativePath));
-      } catch {
-        // Best-effort cleanup for old validation artifacts.
-      }
-    }
-
-    nextIndex = {
-      ...nextIndex,
-      validationRuns: retained,
-    };
-  }
-
-  if (nextIndex.exports.length > HARNESS_EXPORT_RETENTION_LIMIT) {
-    const protectedExportIds = new Set(
-      nextIndex.validationRuns.map((record) => record.exportId).filter(Boolean) as string[],
-    );
-    const retained: HarnessExportRecord[] = [];
-    const trimmed: HarnessExportRecord[] = [];
-
-    for (const record of nextIndex.exports) {
-      if (
-        retained.length < HARNESS_EXPORT_RETENTION_LIMIT ||
-        protectedExportIds.has(record.exportId) ||
-        nextIndex.sessions.some((session) => session.latestExportId === record.exportId)
-      ) {
-        retained.push(record);
-      } else {
-        trimmed.push(record);
-      }
-    }
-
-    for (const record of trimmed) {
-      try {
-        await unlink(path.join(storageDir, record.storedRelativePath));
-      } catch {
-        // Best-effort cleanup for old export artifacts.
-      }
-    }
-
-    nextIndex = {
-      ...nextIndex,
-      exports: retained,
-    };
-  }
-
-  return nextIndex;
-}
-
-export async function listHarnessSources(): Promise<HarnessSourceRecord[]> {
-  const [index, fixtures, scenarios] = await Promise.all([
-    readIndex(),
-    listFixtureSources(),
-    listScenarioSources(),
-  ]);
-
-  return [...fixtures, ...scenarios, ...index.uploads].sort(sortSources);
-}
-
-export async function getHarnessSource(sourceId: string): Promise<HarnessSourceRecord | undefined> {
-  const sources = await listHarnessSources();
-  return sources.find((source) => source.sourceId === sourceId);
-}
-
-export async function readHarnessSourceBytes(sourceId: string): Promise<Uint8Array> {
-  const source = await getHarnessSource(sourceId);
-
-  if (!source?.available || !source.locator) {
-    throw new Error(`Harness source ${sourceId} is not available for session launch.`);
-  }
-
-  const storageDir = await ensureStorageLayout();
-  const absolutePath =
-    source.locator.kind === "repo-file"
-      ? source.locator.absolutePath
-      : path.join(storageDir, source.locator.relativePath);
-
-  return new Uint8Array(await readFile(absolutePath));
-}
-
-export async function createHarnessUploadSource(input: {
-  fileName: string;
-  mimeType?: string;
-  bytes: Uint8Array;
-}): Promise<HarnessUploadSourceRecord> {
-  assertAcceptedDocxPayload(input.fileName, input.bytes.byteLength, input.mimeType);
-
-  const now = new Date().toISOString();
-  const sourceId = `upload:${randomUUID()}`;
-  const storageDir = await ensureStorageLayout();
-  const safeFileName = sanitizeFileName(input.fileName);
-  const storedRelativePath = path.join("uploads", `${sourceId.replace(":", "-")}-${safeFileName}`);
-  const storedAbsolutePath = path.join(storageDir, storedRelativePath);
-
-  await mkdir(path.dirname(storedAbsolutePath), { recursive: true });
-  await writeFile(storedAbsolutePath, Buffer.from(input.bytes));
-
-  const sourceRecord: HarnessUploadSourceRecord = {
-    sourceId,
-    sourceKind: "upload",
-    name: safeFileName,
-    sourceLabel: safeFileName,
-    fileName: safeFileName,
-    mimeType: input.mimeType || DOCX_MIME_TYPE,
-    byteLength: input.bytes.byteLength,
-    createdAt: now,
-    updatedAt: now,
-    available: true,
-    retentionClass: "operator-upload",
-    locator: {
-      kind: "storage-file",
-      relativePath: storedRelativePath,
-    },
-  };
-
-  const index = await readIndex();
-  index.uploads.unshift(sourceRecord);
-  const prunedIndex = await pruneArtifactsIfNeeded(index);
-  await writeIndex(prunedIndex);
-
-  return sourceRecord;
-}
-
-export async function createHarnessSession(sourceId: string): Promise<HarnessSessionRecord> {
-  const source = await getHarnessSource(sourceId);
-
-  if (!source?.available) {
-    throw new HarnessStorageError(
-      "unknown_source",
-      404,
-      `Harness source ${sourceId} cannot be launched because its artifact is missing.`,
-    );
-  }
-
-  const now = new Date().toISOString();
-  const sessionRecord: HarnessSessionRecord = {
-    sessionId: randomUUID(),
-    documentId: createDocumentId("harness-doc"),
-    sourceId: source.sourceId,
-    sourceKind: source.sourceKind,
-    sourceLabel: source.sourceLabel,
-    createdAt: now,
-    updatedAt: now,
-  };
-
-  const index = await readIndex();
-  index.sessions.unshift(sessionRecord);
-  const prunedIndex = await pruneArtifactsIfNeeded(index);
-  await writeIndex(prunedIndex);
-
-  return sessionRecord;
-}
-
-export async function getHarnessSession(
-  sessionId: string,
-): Promise<HarnessSessionRecord | undefined> {
-  const index = await readIndex();
-  return index.sessions.find((session) => session.sessionId === sessionId);
-}
-
-export async function listHarnessSessions(): Promise<HarnessSessionRecord[]> {
-  const index = await readIndex();
-  return [...index.sessions].sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
-}
-
-export async function saveHarnessExport(input: {
-  sessionId: string;
-  fileName: string;
-  mimeType: string;
-  bytes: Uint8Array;
-  reason?: string;
-}): Promise<HarnessExportRecord> {
-  assertAcceptedDocxPayload(input.fileName, input.bytes.byteLength, input.mimeType);
-
-  const index = await readIndex();
-  const session = index.sessions.find((entry) => entry.sessionId === input.sessionId);
-
-  if (!session) {
-    throw new HarnessStorageError(
-      "unknown_session",
-      404,
-      `Harness session ${input.sessionId} does not exist.`,
-    );
-  }
-
-  const now = new Date().toISOString();
-  const exportId = randomUUID();
-  const storageDir = await ensureStorageLayout();
-  const storedRelativePath = path.join(
-    "exports",
-    `${exportId}-${sanitizeFileName(input.fileName)}`,
-  );
-  const storedAbsolutePath = path.join(storageDir, storedRelativePath);
-
-  await mkdir(path.dirname(storedAbsolutePath), { recursive: true });
-  await writeFile(storedAbsolutePath, Buffer.from(input.bytes));
-
-  const record: HarnessExportRecord = {
-    exportId,
-    sessionId: input.sessionId,
-    fileName: sanitizeFileName(input.fileName),
-    mimeType: input.mimeType || DOCX_MIME_TYPE,
-    byteLength: input.bytes.byteLength,
-    storedRelativePath,
-    createdAt: now,
-    reason: input.reason,
-  };
-
-  index.exports.unshift(record);
-  session.updatedAt = now;
-  session.latestExportId = exportId;
-
-  const prunedIndex = await pruneArtifactsIfNeeded(index);
-  await writeIndex(prunedIndex);
-
-  return record;
-}
-
-export async function listHarnessExportsForSession(
-  sessionId: string,
-): Promise<HarnessExportRecord[]> {
-  const index = await readIndex();
-  return index.exports
-    .filter((record) => record.sessionId === sessionId)
-    .sort((a, b) => b.createdAt.localeCompare(a.createdAt));
-}
-
-export async function getHarnessExport(
-  exportId: string,
-): Promise<HarnessExportRecord | undefined> {
-  const index = await readIndex();
-  return index.exports.find((record) => record.exportId === exportId);
-}
-
-export async function readHarnessExportBytes(exportId: string): Promise<Uint8Array> {
-  const record = await getHarnessExport(exportId);
-
-  if (!record) {
-    throw new Error(`Harness export ${exportId} does not exist.`);
-  }
-
-  const storageDir = await ensureStorageLayout();
-  return new Uint8Array(await readFile(path.join(storageDir, record.storedRelativePath)));
-}
-
-export async function saveHarnessValidationRun(input: {
-  report: HarnessValidationReport;
-  fileName: string;
-  byteLength: number;
-  sessionId?: string;
-  sourceId?: string;
-  exportId?: string;
-  targetType: "source" | "export" | "direct-upload";
-}): Promise<HarnessValidationRunRecord> {
-  const now = new Date().toISOString();
-  const runId = randomUUID();
-  const storageDir = await ensureStorageLayout();
-  const storedRelativePath = path.join("validation-runs", `${runId}.json`);
-  const storedAbsolutePath = path.join(storageDir, storedRelativePath);
-
-  await mkdir(path.dirname(storedAbsolutePath), { recursive: true });
-  await writeFile(storedAbsolutePath, JSON.stringify(input.report, null, 2));
-
-  const record: HarnessValidationRunRecord = {
-    runId,
-    sessionId: input.sessionId,
-    sourceId: input.sourceId,
-    exportId: input.exportId,
-    targetType: input.targetType,
-    fileName: sanitizeFileName(input.fileName),
-    byteLength: input.byteLength,
-    storedRelativePath,
-    createdAt: now,
-    service: typeof input.report.service === "string" ? input.report.service : "openxml-validator",
-    summary: summarizeValidationReport(input.report),
-  };
-
-  const index = await readIndex();
-  index.validationRuns.unshift(record);
-
-  if (input.sessionId) {
-    const session = index.sessions.find((entry) => entry.sessionId === input.sessionId);
-
-    if (session) {
-      session.updatedAt = now;
-      session.latestValidationRunId = runId;
-    }
-  }
-
-  const prunedIndex = await pruneArtifactsIfNeeded(index);
-  await writeIndex(prunedIndex);
-
-  return record;
-}
-
-export async function getHarnessValidationRun(
-  runId: string,
-): Promise<HarnessValidationRunRecord | undefined> {
-  const index = await readIndex();
-  return index.validationRuns.find((record) => record.runId === runId);
-}
-
-export async function listHarnessValidationRuns(
-  options: { sessionId?: string; limit?: number } = {},
-): Promise<HarnessValidationRunRecord[]> {
-  const index = await readIndex();
-  const filtered = options.sessionId
-    ? index.validationRuns.filter((record) => record.sessionId === options.sessionId)
-    : index.validationRuns;
-
-  return filtered
-    .slice()
-    .sort((a, b) => b.createdAt.localeCompare(a.createdAt))
-    .slice(0, options.limit ?? filtered.length);
-}
-
-export async function readHarnessValidationReport(
-  runId: string,
-): Promise<HarnessValidationReport> {
-  const record = await getHarnessValidationRun(runId);
-
-  if (!record) {
-    throw new Error(`Harness validation run ${runId} does not exist.`);
-  }
-
-  const storageDir = await ensureStorageLayout();
-  const raw = await readFile(path.join(storageDir, record.storedRelativePath), "utf8");
-  return JSON.parse(raw) as HarnessValidationReport;
-}
-
-export async function getHarnessHealthSnapshot(): Promise<HarnessHealthSnapshot> {
-  const [index, fixtures, scenarios] = await Promise.all([
-    readIndex(),
-    listFixtureSources(),
-    listScenarioSources(),
-  ]);
-
-  const assumptions = getHarnessStorageAssumptions();
-
-  return {
-    storageDir: assumptions.activeStorageDir,
-    storage: {
-      configuredStorageDir: assumptions.configuredStorageDir,
-      mode: assumptions.storageMode,
-      persistence: "file-backed-manifest-index",
-      indexVersion: HARNESS_STORAGE_INDEX_VERSION,
-    },
-    assumptions,
-    retentionPolicy: {
-      maxUploadBytes: HARNESS_MAX_UPLOAD_BYTES,
-      uploadArtifactLimit: HARNESS_UPLOAD_RETENTION_LIMIT,
-      sessionLimit: HARNESS_SESSION_RETENTION_LIMIT,
-      exportArtifactLimit: HARNESS_EXPORT_RETENTION_LIMIT,
-      validationRunLimit: HARNESS_VALIDATION_RETENTION_LIMIT,
-      mode: "volume-backed-manual-review",
-    },
-    counts: {
-      fixtures: fixtures.length,
-      scenarios: scenarios.length,
-      uploads: index.uploads.length,
-      sessions: index.sessions.length,
-      exports: index.exports.length,
-      validationRuns: index.validationRuns.length,
-    },
-    bytes: {
-      uploads: index.uploads.reduce((sum, record) => sum + (record.byteLength ?? 0), 0),
-      exports: index.exports.reduce((sum, record) => sum + record.byteLength, 0),
-    },
-  };
-}