@beyondwork/docx-react-component 1.0.0 → 1.0.1

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

@@ -1,254 +0,0 @@
-# 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

@@ -1,79 +0,0 @@
-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

@@ -1,109 +0,0 @@
-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

@@ -1,23 +0,0 @@
-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

@@ -1,34 +0,0 @@
-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

@@ -1,81 +0,0 @@
-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

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