@beyondwork/docx-react-component 1.0.0

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

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