@beyondwork/docx-react-component 1.0.0

package/services/react-word-editor/README.md

@@ -0,0 +1,254 @@
+# React Word Editor Harness
+
+This service is the internal Railway harness for the editor.
+
+## Purpose
+
+The harness exists to make it easy to:
+
+- upload `.docx` documents
+- browse the permanent fixture corpus and representative scenario artifacts
+- launch an embedded `WordReviewEditor` session
+- export generated `.docx` files
+- inspect compatibility reports
+- send exports to the internal Open XML validator
+
+This is an internal test surface, not the customer-facing product.
+
+## Runtime Shape
+
+- framework: Next.js App Router
+- deploy target: Railway
+- persistence: volume-backed file storage with a manifest index
+- validation dependency: internal `openxml-validator` service over Railway private networking
+- operator posture: internal-only QA and certification harness, not a public app surface
+
+## Expected Environment
+
+- `PORT`
+- `HARNESS_PRIVATE_MODE`
+- `OPENXML_VALIDATOR_BASE_URL`
+- `OPENXML_VALIDATOR_AUTH_TOKEN`
+- `HARNESS_STORAGE_DIR`
+
+`HARNESS_PRIVATE_MODE` must be set to `enabled` before the harness serves routes. When it is
+unset, middleware returns a structured `503` JSON response with `error`, `detail`, and `hint`
+fields instead of exposing the internal QA surface.
+
+Railway should health-check `GET /api/deploy-health` rather than `/` so public fail-closed
+deploys can stay healthy without reopening the harness.
+
+`HARNESS_STORAGE_DIR` should point at the mounted Railway volume path in staging. If it is
+unset, the harness falls back to the local repo `.tmp` path and reports that fallback through
+`GET /api/health`.
+
+For Railway private networking, `OPENXML_VALIDATOR_BASE_URL` should include the
+internal hostname and the validator port:
+
+```text
+http://openxml-validator.railway.internal:8080
+```
+
+If Railway private networking is unavailable, point `OPENXML_VALIDATOR_BASE_URL` at the
+validator's public domain instead and set `OPENXML_VALIDATOR_AUTH_TOKEN` to the same shared
+secret configured as `VALIDATOR_AUTH_TOKEN` on the validator service.
+
+## Internal Routes
+
+- `/`
+- `/fixtures`
+- `/dashboard`
+- `/certification`
+- `/certification/[runId]`
+- `/editor/[sessionId]`
+- `/runs/[runId]`
+- `/demo`
+- `GET /api/deploy-health`
+- `GET /api/health`
+- `POST /api/fixtures/[fixtureId]/run`
+- `POST /api/scenarios/[scenarioId]/run`
+- `POST /api/uploads`
+- `POST /api/exports`
+- `POST /api/validate`
+- `GET /api/runs/[runId]`
+
+The browser must never call the private validator host directly. Validation is always bridged
+through the harness server.
+
+`GET /api/deploy-health` is the one public-safe probe route. It returns a minimal `200` payload
+for Railway health checks without exposing storage, validator, or operator workflow data.
+
+`GET /api/health` intentionally redacts the absolute storage path and private validator hostname.
+It reports only the storage mode, persistence model, manifest index version, aggregate counts and
+byte totals, retention assumptions, and either a validator health payload or a configuration/error
+summary.
+
+## Railway Monorepo Deploy Rule
+
+This harness lives inside a shared pnpm workspace, so Railway must not treat
+`services/react-word-editor/` as an isolated root directory.
+
+Use one of these Railway configurations instead:
+
+- point the service at `services/react-word-editor/Dockerfile`
+- or set the service's custom config file path to
+  `/services/react-word-editor/railway.json`
+
+The repo-owned config file pins the Dockerfile path, watch paths, and deploy
+health settings for the harness service.
+
+## Storage Model
+
+Wave 8 uses one file-backed internal record model across:
+
+- source records for the frozen fixture corpus, scenario artifacts, and operator uploads
+- session records for launched editor sessions
+- export records for saved `.docx` artifacts
+- validation-run records for stored Open XML validator results
+
+The default local storage directory is:
+
+```text
+services/react-word-editor/.tmp/react-word-editor-harness
+```
+
+Set `HARNESS_STORAGE_DIR` to a Railway volume mount in staging.
+
+The storage index is durable JSON at `<storage>/index.json` and is written atomically through a
+same-directory temp file rename so uploads, session launches, export persistence, and validation
+snapshots do not depend on process memory.
+
+## Upload, Export, And Retention Assumptions
+
+- accepted source type: `.docx` only
+- accepted upload/export MIME types: `application/vnd.openxmlformats-officedocument.wordprocessingml.document`, `application/octet-stream`, or blank browser file metadata paired with a `.docx` filename
+- upload cap: `20 MiB`
+- exports retained in the local manifest until the harness exceeds `100` saved export artifacts
+- validation reports retained until the harness exceeds `200` stored validation snapshots
+- fixture and scenario source records stay repo-backed and are never copied into the storage volume
+
+The retention behavior is deliberately conservative in Wave 8:
+
+- uploads remain durable so sessions keep their source packages
+- old exports and validation reports may be trimmed only after the stored limits are exceeded
+- the storage volume is still an internal operator surface, so staging runbooks must record retention checks explicitly
+
+`GET /api/health` now returns the storage mode derived from `HARNESS_STORAGE_DIR` versus the
+fallback local path, the manifest index version, aggregate artifact counts and bytes, and the
+exact upload/retention assumptions used by `/api/uploads`, `/api/exports`, and `/api/validate`.
+
+Operationally, the harness still assumes manual retention review on the mounted volume:
+
+- uploads stay durable so active sessions retain their source package bytes
+- sessions are indexed durably but not garbage-collected by age
+- old exports and validation snapshots are trimmed only when their configured limits are exceeded
+- fixture and scenario sources remain repo-backed and should not be copied into the volume
+
+## Shared Review Workspace
+
+The harness now uses one review UX across launch and session routes.
+
+- launcher route: `/demo`
+- mounted session route: `/editor/[sessionId]`
+- launcher source: `app/demo/page.tsx`
+- mounted host source: `components/harness-editor-session-client.tsx`
+- workspace shell: `src/ui-tailwind/tw-review-workspace.tsx`
+- shared UI helpers: `src/ui/shared/revision-filters.ts`, `src/ui/headless/comment-decoration-model.ts`, `src/ui/headless/revision-decoration-model.ts`
+- guide: `docs/reference/word-review-editor-ux-guide.md`
+- session brokering API: `app/api/demo-sessions/route.ts`
+- mounted session persistence API: `app/api/sessions/[sessionId]/route.ts`
+
+`/demo` is no longer a separate prototype editor. It is the internal launcher for the same
+prototype-designed `WordReviewEditor` shell that the mounted runtime uses after a session opens.
+
+The host harness may add upload, validation, and QA metadata above the editor, but the
+workspace itself remains the canonical live shell with:
+
+- compact toolbar
+- centered document stage
+- floating contextual toolbar
+- unified `Comments`, `Changes`, and `Health` rail
+- minimal bottom status strip
+
+The mounted editor now loads from the saved session snapshot when one exists,
+autosaves through `/api/sessions/[sessionId]`, and persists toolbar exports
+through that same session route before validation or certification surfaces read
+the resulting export record.
+
+Future-wave affordances may stay visible as disabled controls, but the mounted editor remains the
+truth surface for what is live today.
+
+## Scenario Artifacts
+
+The harness should treat `test/fixtures/scenarios/docx/` as a separate source set from the frozen F01-F21 fixture corpus.
+
+- scenario artifacts are representative acceptance docs, not release-gate fixtures
+- source documents may already carry SDK findings, so the harness must store source-vs-export validator deltas
+- Word reopen and preserve-only survival still decide whether a scenario run passes
+
+## Wave 10 QA Surfaces
+
+Wave 10 adds three internal QA surfaces on top of the existing fixture and editor routes:
+
+- `/dashboard`
+  - reads the durable Wave 10 bundle and keeps regression, freshness, validator, signoff, and run-history state in one operator view
+- `/certification`
+  - captures manual Word desktop and Word web notes against exact validation runs or export ids
+- `/certification/[runId]`
+  - shows the full release-gate corpus plus representative scenarios, anchored to a concrete Wave 10 source run or validator run
+
+The automation routes `POST /api/fixtures/[fixtureId]/run` and `POST /api/scenarios/[scenarioId]/run` now persist Wave-aware proof context, execution outcome, classification, and compatibility summary for certification reporting.
+
+`GET /api/runs/[runId]` now returns derived Wave 10 diagnostics alongside the stored validator model so the dashboard and certification bundle can link back to exact run history.
+
+## Wave 8 Closure Status
+
+The repo now contains:
+
+- a dedicated workspace package for the harness
+- a Next.js App Router shell under `app/`
+- a file-backed storage layer under `lib/storage.ts`
+- a server-only validator bridge under `lib/validator-client.ts`
+- operator pages for fixtures, sessions, and stored runs
+- real upload, export, health, and validate routes
+- an embedded `WordReviewEditor` session path that loads actual package bytes
+- a deployment `Dockerfile`
+- environment contract notes for Railway-oriented deployment
+- `lib/harness-config.json` as a durable harness inventory artifact
+- `lib/harness-config.test.mjs` as unit proof for the build-order and panel contract
+
+The Wave 8 hardening changes are now in source, but authoritative closure is blocked pending a
+fresh private-mode Railway redeploy and proof recapture. The older public early-access bundle under
+`.tmp/wave-8-railway-pilot/` is historical evidence only and must not be used as the current closure line.
+
+Historical artifact bundle includes:
+
+- live harness health on `docx-react-component-early-access.up.railway.app`
+- live validator health and restart evidence for `openxml-validator`
+- one mounted `F11` `.docx -> add comment -> review action -> export -> validate` run with
+  linked export and validation artifacts
+
+Before Wave 9 pilot claims can stand again, Wave 8 must be rerun on the private-mode deploy posture.
+
+## Fleet-Ready Gaps
+
+Wave 10 keeps this surface as an internal QA harness rather than promoting it into a multi-tenant
+service tier.
+
+The current Wave 10 bundle is fresh and explicit, but still blocked:
+
+- `F09` and `F13` are validator-clean again in the stored machine-backed bundle
+- `S02` remains in scope as an explicit fail-closed scenario, not as a required exportable review path
+- required Word desktop and Word web notes are still pending for `F01`, `F03`, `F05`, `F09`, `F11`, `F12`, `F15`, `F20`, and `S01`
+- accessibility, DESIGN, and performance review docs have been refreshed on the current worktree
+- the stored Wave 10 bundle still needs a current-commit rerun before it can serve as the proof base for Wave 11 release-readiness work
+
+Current assumptions and blockers:
+
+- access posture is still environment-gated/internal-deploy based rather than identity-backed
+- retention is count-based and manually reviewed; there is no operator-managed archival or expiry
+  workflow for uploads, sessions, exports, and validator reports
+- storage durability depends on the mounted Railway volume and manifest rename semantics; there is
+  no secondary replica or external database mirror
+- validator availability is a single private dependency through `OPENXML_VALIDATOR_BASE_URL`; there
+  is no retry queue or asynchronous validation pipeline yet

package/services/react-word-editor/app/api/certification/route.ts

@@ -0,0 +1,79 @@
+import {
+  getCertificationDashboardModel,
+  getCertificationStoreSnapshot,
+  isCertificationStoreError,
+  parseAndCreateManualCertification,
+} from "../../../lib/certification-store";
+import { getHarnessStorageAssumptions } from "../../../lib/storage";
+
+export const dynamic = "force-dynamic";
+
+export async function GET() {
+  const model = await getCertificationDashboardModel();
+
+  return Response.json(
+    {
+      summary: model.summary,
+      recentCertifications: model.recentCertifications,
+      validationCandidates: model.validationCandidates,
+      exportCandidates: model.exportCandidates,
+      certificationStore: model.storage,
+      storage: getHarnessStorageAssumptions(),
+    },
+    {
+      headers: {
+        "cache-control": "no-store",
+      },
+    },
+  );
+}
+
+export async function POST(request: Request) {
+  try {
+    const contentType = request.headers.get("content-type") || "";
+    const body = contentType.startsWith("application/json")
+      ? ((await request.json()) as Record<string, string | undefined>)
+      : Object.fromEntries((await request.formData()).entries()) as Record<string, string | undefined>;
+
+    const certification = await parseAndCreateManualCertification({
+      operator: typeof body.operator === "string" ? body.operator : undefined,
+      surface: typeof body.surface === "string" ? body.surface : undefined,
+      outcome: typeof body.outcome === "string" ? body.outcome : undefined,
+      summary: typeof body.summary === "string" ? body.summary : undefined,
+      notes: typeof body.notes === "string" ? body.notes : undefined,
+      observedAt: typeof body.observedAt === "string" ? body.observedAt : undefined,
+      targetType: typeof body.targetType === "string" ? body.targetType : undefined,
+      targetId: typeof body.targetId === "string" ? body.targetId : undefined,
+    });
+
+    return Response.json(
+      {
+        certification,
+        certificationStore: getCertificationStoreSnapshot(),
+        storage: getHarnessStorageAssumptions(),
+      },
+      {
+        status: 201,
+        headers: {
+          "cache-control": "no-store",
+        },
+      },
+    );
+  } catch (error) {
+    return Response.json(
+      {
+        error: isCertificationStoreError(error) ? error.code : "certification_failed",
+        detail:
+          error instanceof Error ? error.message : "Manual certification capture failed.",
+        certificationStore: getCertificationStoreSnapshot(),
+        storage: getHarnessStorageAssumptions(),
+      },
+      {
+        status: isCertificationStoreError(error) ? error.status : 400,
+        headers: {
+          "cache-control": "no-store",
+        },
+      },
+    );
+  }
+}

package/services/react-word-editor/app/api/demo-sessions/route.ts

@@ -0,0 +1,109 @@
+import {
+  createHarnessSession,
+  createHarnessUploadSource,
+  DOCX_MIME_TYPE,
+  HARNESS_MAX_UPLOAD_BYTES,
+  isHarnessStorageError,
+} from "../../../lib/storage";
+import { getHarnessDashboardModel } from "../../../lib/harness-client";
+
+export const dynamic = "force-dynamic";
+
+function jsonNoStore(body: unknown, init?: ResponseInit): Response {
+  return Response.json(body, {
+    ...init,
+    headers: {
+      "cache-control": "no-store",
+      ...(init?.headers ?? {}),
+    },
+  });
+}
+
+export async function GET() {
+  const model = await getHarnessDashboardModel();
+
+  return jsonNoStore({
+    sources: model.browseableSources,
+    recentSessions: model.recentSessions,
+  });
+}
+
+export async function POST(request: Request) {
+  try {
+    const contentType = request.headers.get("content-type") || "";
+
+    if (contentType.startsWith("application/json")) {
+      const body = (await request.json()) as {
+        sourceId?: string;
+      };
+
+      if (typeof body.sourceId !== "string" || body.sourceId.length === 0) {
+        return jsonNoStore(
+          {
+            error: "missing_source_id",
+            detail: "Creating a demo session from JSON requires a sourceId.",
+          },
+          { status: 400 },
+        );
+      }
+
+      const session = await createHarnessSession(body.sourceId);
+      return jsonNoStore({ session }, { status: 201 });
+    }
+
+    const formData = await request.formData();
+    const sourceId = formData.get("sourceId");
+    const file = formData.get("file");
+
+    if (typeof sourceId === "string" && sourceId.length > 0) {
+      const session = await createHarnessSession(sourceId);
+      return jsonNoStore({ session }, { status: 201 });
+    }
+
+    if (!(file instanceof File)) {
+      return jsonNoStore(
+        {
+          error: "missing_source",
+          detail: "Creating a demo session requires a sourceId or uploaded .docx file.",
+        },
+        { status: 400 },
+      );
+    }
+
+    const uploadBytes = new Uint8Array(await file.arrayBuffer());
+
+    if (uploadBytes.byteLength > HARNESS_MAX_UPLOAD_BYTES) {
+      return jsonNoStore(
+        {
+          error: "upload_too_large",
+          detail: `Uploads must be ${HARNESS_MAX_UPLOAD_BYTES} bytes or smaller.`,
+        },
+        { status: 413 },
+      );
+    }
+
+    const source = await createHarnessUploadSource({
+      fileName: file.name,
+      mimeType: file.type || DOCX_MIME_TYPE,
+      bytes: uploadBytes,
+    });
+    const session = await createHarnessSession(source.sourceId);
+
+    return jsonNoStore(
+      {
+        session,
+        source,
+      },
+      { status: 201 },
+    );
+  } catch (error) {
+    return jsonNoStore(
+      {
+        error: isHarnessStorageError(error) ? error.code : "demo_session_failed",
+        detail:
+          error instanceof Error ? error.message : "Could not create the demo session.",
+      },
+      { status: isHarnessStorageError(error) ? error.status : 400 },
+    );
+  }
+}

package/services/react-word-editor/app/api/deploy-health/route.ts

@@ -0,0 +1,23 @@
+import { isHarnessPrivateModeEnabled } from "../../../lib/private-mode";
+
+export const dynamic = "force-dynamic";
+
+export function GET() {
+  const privateModeEnabled = isHarnessPrivateModeEnabled();
+
+  return Response.json(
+    {
+      service: "react-word-editor-harness",
+      status: "ok",
+      harnessAccess: privateModeEnabled ? "enabled" : "disabled",
+      detail: privateModeEnabled
+        ? "The internal QA harness is enabled for this deployment."
+        : "The internal QA harness is disabled for this deployment.",
+    },
+    {
+      headers: {
+        "cache-control": "no-store",
+      },
+    },
+  );
+}

package/services/react-word-editor/app/api/exports/[exportId]/route.ts

@@ -0,0 +1,34 @@
+import { getHarnessExport, readHarnessExportBytes } from "../../../../lib/storage";
+
+export async function GET(
+  _request: Request,
+  context: {
+    params: Promise<{
+      exportId: string;
+    }>;
+  },
+) {
+  const { exportId } = await context.params;
+  const record = await getHarnessExport(exportId);
+
+  if (!record) {
+    return Response.json(
+      {
+        error: "unknown_export",
+        detail: `Export ${exportId} does not exist.`,
+      },
+      { status: 404 },
+    );
+  }
+
+  const bytes = await readHarnessExportBytes(exportId);
+
+  return new Response(Buffer.from(bytes), {
+    status: 200,
+    headers: {
+      "content-type": record.mimeType,
+      "content-disposition": `attachment; filename="${record.fileName}"`,
+      "cache-control": "no-store",
+    },
+  });
+}

package/services/react-word-editor/app/api/exports/route.ts

@@ -0,0 +1,81 @@
+import {
+  DOCX_MIME_TYPE,
+  HARNESS_MAX_UPLOAD_BYTES,
+  getHarnessStorageAssumptions,
+  isHarnessStorageError,
+  saveHarnessExport,
+} from "../../../lib/storage.ts";
+import {
+  assertContentLengthWithinLimit,
+  isHarnessRouteError,
+} from "../../../lib/private-mode.ts";
+
+export async function POST(request: Request) {
+  try {
+    assertContentLengthWithinLimit(request, HARNESS_MAX_UPLOAD_BYTES);
+    const formData = await request.formData();
+    const sessionId = formData.get("sessionId");
+    const file = formData.get("file");
+    const reason = formData.get("reason");
+
+    if (typeof sessionId !== "string" || sessionId.length === 0) {
+      return Response.json(
+        {
+          error: "missing_session",
+          detail: "Export persistence requires a `sessionId` field.",
+          storage: getHarnessStorageAssumptions(),
+        },
+        { status: 400, headers: { "cache-control": "no-store" } },
+      );
+    }
+
+    if (!(file instanceof File)) {
+      return Response.json(
+        {
+          error: "missing_file",
+          detail: "Export persistence requires a `file` field.",
+          storage: getHarnessStorageAssumptions(),
+        },
+        { status: 400, headers: { "cache-control": "no-store" } },
+      );
+    }
+
+    const bytes = new Uint8Array(await file.arrayBuffer());
+    const exportRecord = await saveHarnessExport({
+      sessionId,
+      fileName: file.name,
+      mimeType: file.type || DOCX_MIME_TYPE,
+      bytes,
+      reason: typeof reason === "string" && reason.length > 0 ? reason : undefined,
+    });
+
+    return Response.json({
+      exportRecord,
+      storage: getHarnessStorageAssumptions(),
+    }, {
+      headers: {
+        "cache-control": "no-store",
+      },
+    });
+  } catch (error) {
+    return Response.json(
+      {
+        error:
+          isHarnessStorageError(error) || isHarnessRouteError(error)
+            ? error.code
+            : "export_persist_failed",
+        detail: error instanceof Error ? error.message : "Could not persist the export artifact.",
+        storage: getHarnessStorageAssumptions(),
+      },
+      {
+        status:
+          isHarnessStorageError(error) || isHarnessRouteError(error)
+            ? error.status
+            : 400,
+        headers: {
+          "cache-control": "no-store",
+        },
+      },
+    );
+  }
+}

package/services/react-word-editor/app/api/fixtures/[fixtureId]/run/route.ts

@@ -0,0 +1,100 @@
+import {
+  getHarnessStorageAssumptions,
+  getHarnessSource,
+  isHarnessStorageError,
+} from "../../../../../lib/storage";
+import { executeAutomatedSourceRun } from "../../../../../lib/run-artifacts";
+import { loadWave10CertificationManifest } from "../../../../../lib/regression-report";
+
+export async function POST(
+  request: Request,
+  context: {
+    params: Promise<{
+      fixtureId: string;
+    }>;
+  },
+) {
+  try {
+    const { fixtureId } = await context.params;
+    const normalizedFixtureId = fixtureId.toUpperCase();
+    const body = (await request.json().catch(() => ({}))) as {
+      exportFileName?: string;
+      reason?: string;
+      runId?: string;
+      proofWave?: number;
+      bundleId?: string;
+    };
+    const sourceId = `fixture:${normalizedFixtureId}`;
+    const [manifest, source] = await Promise.all([
+      loadWave10CertificationManifest(),
+      getHarnessSource(sourceId),
+    ]);
+
+    if (
+      !source ||
+      source.sourceKind !== "fixture" ||
+      !manifest.releaseGateFixtures.includes(normalizedFixtureId)
+    ) {
+      return Response.json(
+        {
+          error: "unknown_fixture",
+          detail: `Fixture ${normalizedFixtureId} does not exist in the frozen Wave 10 release-gate corpus.`,
+          storage: getHarnessStorageAssumptions(),
+        },
+        { status: 404, headers: { "cache-control": "no-store" } },
+      );
+    }
+
+    const result = await executeAutomatedSourceRun({
+      sourceId,
+      trigger: "fixture-route",
+      requestedRunId: body.runId,
+      exportReason: body.reason,
+      exportFileName: body.exportFileName,
+      proofWave: body.proofWave,
+      bundleId: body.bundleId,
+    });
+
+    return Response.json(
+      {
+        runId: result.runStory.runId,
+        proofContext: result.runStory.proofContext,
+        classification: source.featureClassFocus,
+        releaseGate: {
+          fixtureId: normalizedFixtureId,
+          corpus: "frozen-v1",
+          harnessPath: manifest.automationRoute,
+          manualReviewRequired: manifest.manualReviewFixtures.includes(normalizedFixtureId),
+        },
+        executionOutcome: result.executionOutcome,
+        compatibilitySummary: result.compatibilitySummary,
+        source: result.source,
+        session: result.session,
+        exportRecord: result.exportRecord,
+        validationRun: result.validationRun,
+        report: result.report,
+        runStory: result.runStory,
+        storage: getHarnessStorageAssumptions(),
+      },
+      {
+        headers: {
+          "cache-control": "no-store",
+        },
+      },
+    );
+  } catch (error) {
+    return Response.json(
+      {
+        error: isHarnessStorageError(error) ? error.code : "fixture_run_failed",
+        detail: error instanceof Error ? error.message : "Fixture run failed.",
+        storage: getHarnessStorageAssumptions(),
+      },
+      {
+        status: isHarnessStorageError(error) ? error.status : 400,
+        headers: {
+          "cache-control": "no-store",
+        },
+      },
+    );
+  }
+}