@open-mercato/core 0.8.1-develop.7296.1.2111d779db → 0.8.1-develop.7441.1.b42958b98c

package/src/modules/forms/di.ts

@@ -0,0 +1,246 @@
+import { asValue, asFunction } from 'awilix'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { AppContainer } from '@open-mercato/shared/lib/di/container'
+import { getOrm } from '@open-mercato/shared/lib/db/mikro'
+import { defaultFieldTypeRegistry } from './schema/field-type-registry'
+import { FormVersionCompiler } from './services/form-version-compiler'
+import { FormVersionDiffer } from './services/form-version-differ'
+import {
+  FormsEncryptionService,
+  resolveKmsAdapter,
+  type EncryptionService,
+} from './services/encryption-service'
+import { RolePolicyService } from './services/role-policy-service'
+import { SubmissionService } from './services/submission-service'
+import { DistributionService } from './services/distribution-service'
+import {
+  AccessAuditLogger,
+  BatchingAccessAuditLogger,
+  FormsAccessAuditLogger,
+  resolveAccessAuditBatchMs,
+  type AccessAuditEvent,
+} from './services/access-audit-logger'
+import { AnonymizeService } from './services/anonymize-service'
+import { AnalyticsService } from './services/analytics-service'
+import { ConsentRecordService } from './services/consent-record-service'
+import { ExportService } from './services/export-service'
+import { AttachmentService } from './services/attachment-service'
+import { PdfSnapshotService } from './services/pdf-snapshot-service'
+import { NoopUploadScanner, type UploadScanner } from './services/upload-scanner'
+import { resolveCaptchaVerifier, type CaptchaVerifier } from './services/captcha-verifier'
+import { DefaultPrefillResolver, type PrefillResolver } from './services/prefill-resolver'
+import { emitFormsEvent } from './events'
+import { formsEventPayloadSchemas } from './events-payloads'
+
+/**
+ * Forms module DI registrar.
+ *
+ * Registered keys (FROZEN — root AGENTS.md § BC contract § 9):
+ * - `fieldTypeRegistry` (1a) → singleton FieldTypeRegistry preloaded with the
+ *    11 v1 core field types.
+ * - `formVersionCompiler` (1a) → singleton FormVersionCompiler bound to the
+ *    same registry. Phases 1b/1c/1d resolve this to compile draft and
+ *    published form versions for AJV/Zod validation and role policy.
+ * - `formVersionDiffer` (1b) → singleton pure-function FormVersionDiffer.
+ *    Consumes compiled `fieldIndex` maps to produce added/removed/modified
+ *    field-level diffs for the publish dialog and version history modal.
+ * - `formsEncryptionService` (1c) → per-tenant envelope encryption service
+ *    used by SubmissionService for revision payloads.
+ * - `formsRolePolicyService` (1c) → resolver over compiled form versions for
+ *    role-aware read/write decisions.
+ * - `formsSubmissionService` (1c) → owns the submission lifecycle.
+ *    Lazy-resolves `em` per request from the container so EntityManager
+ *    request scoping is honoured.
+ */
+export function register(container: AppContainer): void {
+  const formVersionCompiler = new FormVersionCompiler({ registry: defaultFieldTypeRegistry })
+  const formVersionDiffer = new FormVersionDiffer()
+  const rolePolicyService = new RolePolicyService()
+
+  // T7 — async-batched access audit. `FORMS_ACCESS_AUDIT_BATCH_MS=0` (default)
+  // keeps the synchronous insert-per-read posture on the request's own EM
+  // (deterministic for tests). A positive value buffers events and flushes them
+  // as a bulk insert on a fresh forked EM, off the read hot path.
+  const accessAuditBatchMs = resolveAccessAuditBatchMs(process.env)
+  const accessAuditLogger: AccessAuditLogger =
+    accessAuditBatchMs > 0
+      ? new BatchingAccessAuditLogger({
+          batchMs: accessAuditBatchMs,
+          // Fork a fresh EM at flush time — the request EM is long gone.
+          emFactory: async (): Promise<EntityManager> => {
+            const orm = await getOrm()
+            return orm.em.fork() as unknown as EntityManager
+          },
+        })
+      : new FormsAccessAuditLogger()
+
+  container.register({
+    fieldTypeRegistry: asValue(defaultFieldTypeRegistry),
+    formVersionCompiler: asValue(formVersionCompiler),
+    formVersionDiffer: asValue(formVersionDiffer),
+    formsRolePolicyService: asValue(rolePolicyService),
+    formsAccessAuditLogger: asValue(accessAuditLogger),
+    formsEncryptionService: asFunction(({ em }: { em: EntityManager }): EncryptionService => {
+      // resolveKmsAdapter picks the production env master-key adapter (or an
+      // operator-injected cloud-KMS adapter) and refuses the DEV-ONLY fallback
+      // when NODE_ENV=production (spec W1 / risk R-1). An operator may also
+      // inject a custom adapter via setKmsAdapterFactory(...).
+      return new FormsEncryptionService({
+        emFactory: () => em,
+        kmsAdapter: resolveKmsAdapter(process.env),
+      })
+    }).proxy().singleton(),
+    formsSubmissionService: asFunction(({ em, formsEncryptionService }: { em: EntityManager; formsEncryptionService: EncryptionService }): SubmissionService => {
+      return new SubmissionService({
+        emFactory: () => em,
+        formVersionCompiler,
+        encryptionService: formsEncryptionService,
+        rolePolicyService,
+        emitEvent: async (eventId, payload) => {
+          // Validate against catalogued payload schema before forwarding to the
+          // global event bus. Keeps the event contract tight per AGENTS.md.
+          const schema = formsEventPayloadSchemas[eventId as keyof typeof formsEventPayloadSchemas]
+          const validated = schema ? schema.parse(payload) : payload
+          await emitFormsEvent(eventId, validated as never)
+        },
+        auditAccess: async (args) => {
+          // Phase 2b — replaces the no-op hook from phase 1c. Writes one
+          // row per admin-surface read/mutation. Runtime patient reads
+          // bypass this hook by calling with `surface = 'runtime'` (R1 posture).
+          if (args.surface !== 'admin') return
+          if (!args.viewerUserId) return
+          const event: AccessAuditEvent = {
+            organizationId: args.organizationId,
+            submissionId: args.submissionId,
+            accessedBy: args.viewerUserId,
+            accessPurpose: 'view',
+          }
+          await accessAuditLogger.log(em, event)
+        },
+      })
+    }).proxy().singleton(),
+    formsDistributionService: asFunction(({ em, formsSubmissionService }: { em: EntityManager; formsSubmissionService: SubmissionService }): DistributionService => {
+      return new DistributionService({
+        emFactory: () => em,
+        submissionService: formsSubmissionService,
+        emitEvent: async (eventId, payload) => {
+          const schema = formsEventPayloadSchemas[eventId as keyof typeof formsEventPayloadSchemas]
+          const validated = schema ? schema.parse(payload) : payload
+          await emitFormsEvent(eventId, validated as never)
+        },
+      })
+    }).proxy().singleton(),
+    formsAnonymizeService: asFunction(({ em, formsEncryptionService }: { em: EntityManager; formsEncryptionService: EncryptionService }): AnonymizeService => {
+      return new AnonymizeService({
+        em,
+        compiler: formVersionCompiler,
+        encryption: formsEncryptionService,
+      })
+    }).proxy().singleton(),
+    // Phase 3 Track B — aggregate, PII-safe form analytics. Decrypts revision
+    // payloads only to tally enumerable answers; never returns decrypted
+    // values. Lazy-resolves `em` per request so EM request scoping is honoured.
+    formsAnalyticsService: asFunction(({ em, formsEncryptionService }: { em: EntityManager; formsEncryptionService: EncryptionService }): AnalyticsService => {
+      return new AnalyticsService({
+        emFactory: () => em,
+        compiler: formVersionCompiler,
+        encryption: formsEncryptionService,
+      })
+    }).proxy().singleton(),
+    // Phase 3 Track D — projects signed `signature` answers into the
+    // `forms_consent_record` per-subject consent aggregate. Loads the
+    // submission via the submission service (admin/full read, no role slice)
+    // so signature answers are present, then upserts + supersedes. PII-free.
+    // Lazy-resolves `em` per request so EM request scoping is honoured.
+    formsConsentRecordService: asFunction(
+      ({ em, formsSubmissionService }: { em: EntityManager; formsSubmissionService: SubmissionService }): ConsentRecordService => {
+        return new ConsentRecordService({
+          emFactory: () => em,
+          compiler: formVersionCompiler,
+          loadSubmission: async ({ submissionId, organizationId, tenantId }) => {
+            const view = await formsSubmissionService.getCurrent({
+              submissionId,
+              organizationId,
+              tenantId,
+              // The projector has no viewer and must see `signature` answers to
+              // write consent rows. `getCurrent` fails closed on an absent role,
+              // so this opt-in is required — without it every signature reads
+              // `undefined` and consent records are silently never written.
+              unsliced: true,
+            })
+            return {
+              submission: view.submission,
+              formVersion: view.formVersion,
+              decodedData: view.decodedData,
+            }
+          },
+        })
+      },
+    ).proxy().singleton(),
+    // W5 (DP-5) — builds the structured GDPR data-subject export document.
+    // Lazy-resolves `em` per request so EM request scoping is honoured.
+    formsExportService: asFunction(({ em, formsEncryptionService }: { em: EntityManager; formsEncryptionService: EncryptionService }): ExportService => {
+      return new ExportService({
+        emFactory: () => em,
+        compiler: formVersionCompiler,
+        encryption: formsEncryptionService,
+      })
+    }).proxy().singleton(),
+    // W4 — no-op virus/malware scanner. Operators inject a real scanner by
+    // overriding `formsUploadScanner` with their own `UploadScanner`.
+    formsUploadScanner: asValue<UploadScanner>(new NoopUploadScanner()),
+    // W8 / FD-1 — default patient prefill resolver. Maps `name`/`email` from
+    // the customer auth context; anonymous principals resolve to `{}`. Stateless
+    // and pure, so `asValue` is correct. Operators inject a richer resolver
+    // (e.g. dental-os providing `dob`) by overriding `formsPrefillResolver`.
+    formsPrefillResolver: asValue<PrefillResolver>(new DefaultPrefillResolver()),
+    // T5 — pluggable CAPTCHA verifier for the public start route. Selects a
+    // provider verifier (Cloudflare Turnstile / Google reCAPTCHA) when
+    // `FORMS_CAPTCHA_PROVIDER` + `FORMS_CAPTCHA_SECRET` are set; otherwise a
+    // no-op verifier (token presence is still enforced by the route for
+    // backward-compat). Stateless, so `asValue` is correct. Operators inject a
+    // custom verifier by overriding `formsCaptchaVerifier`.
+    formsCaptchaVerifier: asValue<CaptchaVerifier>(resolveCaptchaVerifier(process.env)),
+    // W4 — encrypts + persists participant uploads as `forms_form_attachment`
+    // rows. Lazy-resolves `em` per request so EM request scoping is honoured.
+    formsAttachmentService: asFunction(
+      ({
+        em,
+        formsEncryptionService,
+        formsUploadScanner,
+      }: {
+        em: EntityManager
+        formsEncryptionService: EncryptionService
+        formsUploadScanner: UploadScanner
+      }): AttachmentService => {
+        return new AttachmentService({
+          emFactory: () => em,
+          encryptionService: formsEncryptionService,
+          scanner: formsUploadScanner,
+        })
+      },
+    ).proxy().singleton(),
+    // W3 — renders + stores the immutable signed PDF snapshot as an encrypted
+    // `forms_form_attachment` (`kind = 'snapshot'`). Generated once (on-submit
+    // subscriber or lazily on first download) and idempotent thereafter.
+    formsPdfSnapshotService: asFunction(
+      ({
+        em,
+        formsEncryptionService,
+      }: {
+        em: EntityManager
+        formsEncryptionService: EncryptionService
+      }): PdfSnapshotService => {
+        return new PdfSnapshotService({
+          emFactory: () => em,
+          encryptionService: formsEncryptionService,
+          emitEvent: async (eventId, payload) => {
+            const schema = formsEventPayloadSchemas[eventId as keyof typeof formsEventPayloadSchemas]
+            const validated = schema ? schema.parse(payload) : payload
+            await emitFormsEvent(eventId, validated as never)
+          },
+        })
+      },
+    ).proxy().singleton(),
+  })
+}

package/src/modules/forms/encryption.ts

@@ -0,0 +1,31 @@
+import type { ModuleEncryptionMap } from '@open-mercato/shared/modules/encryption'
+
+/**
+ * Forms module encryption-defaults declarations.
+ *
+ * IMPORTANT: the `data` column on `forms_form_submission_revision` is NOT
+ * routed through the global `findWithDecryption` pipeline — it is encrypted
+ * directly by `EncryptionService` (see `services/encryption-service.ts`)
+ * with per-tenant envelope encryption and a self-describing ciphertext
+ * header carrying the key version.
+ *
+ * The export here exists so any future submission-side fields that ARE
+ * suitable for the global pipeline (e.g. `submit_metadata`, `change_summary`)
+ * can be declared in additive fashion without rewiring; phase 1c does not
+ * route any column through the global pipeline.
+ *
+ * The invitation recipient PII (`recipient_email`, `recipient_name`) IS routed
+ * through the global pipeline — these are ordinary text columns at the schema
+ * level and the map below opts them into transparent at-rest encryption.
+ */
+export const defaultEncryptionMaps: ModuleEncryptionMap[] = [
+  {
+    entityId: 'forms:form_invitation',
+    fields: [
+      { field: 'recipient_email' },
+      { field: 'recipient_name' },
+    ],
+  },
+]
+
+export default defaultEncryptionMaps

package/src/modules/forms/events-payloads.ts

@@ -0,0 +1,103 @@
+import { z } from 'zod'
+
+/**
+ * Typed payload schemas for every event declared in `events.ts`.
+ *
+ * `createModuleEvents()` only enforces the event ID at compile time — payload
+ * shape is left to the emitter. To keep the cross-module contract honest,
+ * downstream phases (1b authoring, 1c submission core, 2a inbox, 2b
+ * compliance) MUST validate their emit payload against the schema for the
+ * event they emit:
+ *
+ * ```ts
+ * import { formsEventPayloadSchemas } from '@open-mercato/core/modules/forms/events-payloads'
+ * await emitFormsEvent('forms.submission.submitted', formsEventPayloadSchemas['forms.submission.submitted'].parse(payload))
+ * ```
+ *
+ * The IDs here mirror the catalog one-to-one. Adding/renaming/removing a
+ * payload field is a BC consideration just like the IDs themselves; new
+ * fields should be added as optional first.
+ */
+
+const submissionRevisionAppendedSchema = z.object({
+  submissionId: z.string().uuid(),
+  revisionId: z.string().uuid(),
+  savedBy: z.string().uuid(),
+  savedByRole: z.string().min(1),
+  changedFieldKeys: z.array(z.string()),
+})
+
+const submissionActorAssignedSchema = z.object({
+  submissionId: z.string().uuid(),
+  userId: z.string().uuid(),
+  role: z.string().min(1),
+})
+
+export const formsEventPayloadSchemas = {
+  'forms.form.created': z.object({
+    formId: z.string().uuid(),
+    organizationId: z.string().uuid(),
+  }),
+  'forms.form.archived': z.object({
+    formId: z.string().uuid(),
+  }),
+  'forms.form_version.published': z.object({
+    formId: z.string().uuid(),
+    versionId: z.string().uuid(),
+    versionNumber: z.number().int().nonnegative(),
+    publishedBy: z.string().uuid(),
+  }),
+  'forms.submission.started': z.object({
+    submissionId: z.string().uuid(),
+    formVersionId: z.string().uuid(),
+  }),
+  'forms.submission.revision_appended': submissionRevisionAppendedSchema,
+  'forms.submission.submitted': z.object({
+    submissionId: z.string().uuid(),
+  }),
+  'forms.submission.reopened': z.object({
+    submissionId: z.string().uuid(),
+  }),
+  'forms.submission.actor_assigned': submissionActorAssignedSchema,
+  'forms.submission.anonymized': z.object({
+    submissionId: z.string().uuid(),
+  }),
+  'forms.attachment.uploaded': z.object({
+    attachmentId: z.string().uuid(),
+    submissionId: z.string().uuid(),
+  }),
+  'forms.distribution.created': z.object({
+    distributionId: z.string().uuid(),
+    organizationId: z.string().uuid(),
+    formId: z.string().uuid(),
+  }),
+  'forms.distribution.closed': z.object({
+    distributionId: z.string().uuid(),
+  }),
+  'forms.invitation.created': z.object({
+    invitationId: z.string().uuid(),
+    distributionId: z.string().uuid(),
+  }),
+  'forms.invitation.sent': z.object({
+    invitationId: z.string().uuid(),
+    distributionId: z.string().uuid(),
+  }),
+  'forms.invitation.opened': z.object({
+    invitationId: z.string().uuid(),
+  }),
+  'forms.invitation.submitted': z.object({
+    invitationId: z.string().uuid(),
+    submissionId: z.string().uuid(),
+  }),
+  'forms.invitation.revoked': z.object({
+    invitationId: z.string().uuid(),
+  }),
+  'forms.consent.recorded': z.object({
+    recordId: z.string().uuid(),
+    submissionId: z.string().uuid(),
+  }),
+} as const
+
+export type FormsEventPayload = {
+  [K in keyof typeof formsEventPayloadSchemas]: z.infer<typeof formsEventPayloadSchemas[K]>
+}

package/src/modules/forms/events.ts

@@ -0,0 +1,50 @@
+import { createModuleEvents } from '@open-mercato/shared/modules/events'
+
+/**
+ * Forms module event catalog.
+ *
+ * Every event ID listed here is a CONTRACT SURFACE (root AGENTS.md
+ * § Backward Compatibility Contract § 5 — Event IDs are FROZEN). Adding new
+ * IDs is additive; renaming or removing an existing ID is a breaking change
+ * that requires the deprecation protocol.
+ *
+ * Phase 1a declares the catalog only. Emission lands in:
+ *  - `forms.form.created` / `forms.form.archived`        — phase 1b
+ *  - `forms.form_version.published`                       — phase 1b
+ *  - `forms.submission.started` / `revision_appended`     — phase 1c
+ *  - `forms.submission.submitted` / `reopened`            — phase 1c / 2a
+ *  - `forms.submission.actor_assigned`                    — phase 2a
+ *  - `forms.submission.anonymized`                        — phase 2b
+ *  - `forms.attachment.uploaded`                          — phase 2c
+ */
+const events = [
+  { id: 'forms.form.created', label: 'Form Created', entity: 'form', category: 'crud' as const },
+  { id: 'forms.form.archived', label: 'Form Archived', entity: 'form', category: 'lifecycle' as const },
+  { id: 'forms.form_version.published', label: 'Form Version Published', entity: 'form_version', category: 'lifecycle' as const },
+  { id: 'forms.submission.started', label: 'Submission Started', entity: 'submission', category: 'lifecycle' as const },
+  { id: 'forms.submission.revision_appended', label: 'Submission Revision Appended', entity: 'submission', category: 'lifecycle' as const, portalBroadcast: true },
+  { id: 'forms.submission.submitted', label: 'Submission Submitted', entity: 'submission', category: 'lifecycle' as const, clientBroadcast: true, portalBroadcast: true },
+  { id: 'forms.submission.reopened', label: 'Submission Reopened', entity: 'submission', category: 'lifecycle' as const },
+  { id: 'forms.submission.actor_assigned', label: 'Submission Actor Assigned', entity: 'submission', category: 'lifecycle' as const },
+  { id: 'forms.submission.anonymized', label: 'Submission Anonymized', entity: 'submission', category: 'lifecycle' as const },
+  { id: 'forms.attachment.uploaded', label: 'Attachment Uploaded', entity: 'attachment', category: 'crud' as const },
+  { id: 'forms.distribution.created', label: 'Distribution Created', entity: 'distribution', category: 'crud' as const },
+  { id: 'forms.distribution.closed', label: 'Distribution Closed', entity: 'distribution', category: 'lifecycle' as const },
+  { id: 'forms.invitation.created', label: 'Invitation Created', entity: 'invitation', category: 'crud' as const },
+  { id: 'forms.invitation.sent', label: 'Invitation Sent', entity: 'invitation', category: 'lifecycle' as const },
+  { id: 'forms.invitation.opened', label: 'Invitation Opened', entity: 'invitation', category: 'lifecycle' as const },
+  { id: 'forms.invitation.submitted', label: 'Invitation Submitted', entity: 'invitation', category: 'lifecycle' as const },
+  { id: 'forms.invitation.revoked', label: 'Invitation Revoked', entity: 'invitation', category: 'lifecycle' as const },
+  { id: 'forms.consent.recorded', label: 'Consent Recorded', entity: 'consent', category: 'lifecycle' as const },
+] as const
+
+export const eventsConfig = createModuleEvents({
+  moduleId: 'forms',
+  events,
+})
+
+export const emitFormsEvent = eventsConfig.emit
+
+export type FormsEventId = typeof events[number]['id']
+
+export default eventsConfig

package/src/modules/forms/extension-points.ts

@@ -0,0 +1,41 @@
+import { defineModuleExtensionPoints, injectionExtensionHost } from '@open-mercato/shared/modules/widgets/extension-points'
+
+/**
+ * Injection hosts the submission drawer mounts. The drawer renders only the
+ * `<InjectionSpot>` mount points; the PDF download trigger, the anonymize
+ * action, the access-audit trail and the "this view is logged" note all live in
+ * `widgets/injection/` and are mapped onto these spots by
+ * `widgets/injection-table.ts`, so a third-party module can copy the pattern
+ * unchanged.
+ */
+export const extensionPoints = defineModuleExtensionPoints({
+  moduleId: 'forms',
+  hosts: {
+    submissionDrawerHeaderActions: injectionExtensionHost({
+      family: 'detail',
+      spotId: 'submission-drawer:header-actions',
+      supported: ['render-widget'],
+      source: 'backend/forms/[id]/submissions/components/SubmissionDrawer.tsx',
+    }),
+    submissionDrawerAnonymizeAction: injectionExtensionHost({
+      family: 'detail',
+      spotId: 'submission-drawer:anonymize-action',
+      supported: ['render-widget'],
+      source: 'backend/forms/[id]/submissions/components/SubmissionDrawer.tsx',
+    }),
+    submissionDrawerAccessAudit: injectionExtensionHost({
+      family: 'detail',
+      spotId: 'submission-drawer:access-audit',
+      supported: ['render-widget'],
+      source: 'backend/forms/[id]/submissions/components/SubmissionDrawer.tsx',
+    }),
+    submissionDrawerFooter: injectionExtensionHost({
+      family: 'detail',
+      spotId: 'submission-drawer:footer',
+      supported: ['render-widget'],
+      source: 'backend/forms/[id]/submissions/components/SubmissionDrawer.tsx',
+    }),
+  },
+})
+
+export default extensionPoints

package/src/modules/forms/frontend/[orgSlug]/portal/forms/[key]/page.meta.ts

@@ -0,0 +1,9 @@
+import type { PageMetadata } from '@open-mercato/shared/modules/registry'
+
+export const metadata: PageMetadata = {
+  requireCustomerAuth: true,
+  titleKey: 'forms.runner.loading',
+  title: 'Form',
+}
+
+export default metadata

package/src/modules/forms/frontend/[orgSlug]/portal/forms/[key]/page.tsx

@@ -0,0 +1,45 @@
+"use client"
+
+import * as React from 'react'
+import { navigateWithPageReload } from '@open-mercato/shared/lib/navigation/pageReload'
+import { Spinner } from '@open-mercato/ui/primitives/spinner'
+import { usePortalContext } from '@open-mercato/ui/portal/PortalContext'
+import { EmbeddedForm } from '../../../../../ui/public'
+
+type Props = { params: { orgSlug: string; key: string } }
+
+export default function PortalFormRunnerPage({ params }: Props) {
+  // Read from the `params` prop the (frontend) catch-all passes, as every other
+  // portal page in the repo does. `useParams()` does NOT work here: under the
+  // catch-all the client-side route is `[...slug]`, so it returns `{ slug }`
+  // and nothing else — `key` came back undefined, `formKey` was always empty,
+  // and this page could never load a form.
+  const orgSlug = String(params?.orgSlug ?? '')
+  const formKey = String(params?.key ?? '')
+  const { auth } = usePortalContext()
+  const { user, loading } = auth
+  const subjectType = 'customer'
+  const subjectId = user?.id ?? ''
+
+  if (loading) {
+    return (
+      <div className="flex items-center justify-center py-20">
+        <Spinner />
+      </div>
+    )
+  }
+  if (!user) return null
+
+  return (
+    <main className="px-4 py-6 sm:px-6 lg:px-8">
+      <EmbeddedForm
+        source={{ kind: 'portal', formKey, subjectType, subjectId }}
+        onReturnHome={() => {
+          if (typeof window !== 'undefined') {
+            navigateWithPageReload(`/${orgSlug}/portal`)
+          }
+        }}
+      />
+    </main>
+  )
+}

package/src/modules/forms/frontend/[orgSlug]/portal/submissions/[id]/continue/page.meta.ts

@@ -0,0 +1,9 @@
+import type { PageMetadata } from '@open-mercato/shared/modules/registry'
+
+export const metadata: PageMetadata = {
+  requireCustomerAuth: true,
+  titleKey: 'forms.runner.loading',
+  title: 'Continue submission',
+}
+
+export default metadata

package/src/modules/forms/frontend/[orgSlug]/portal/submissions/[id]/continue/page.tsx

@@ -0,0 +1,56 @@
+"use client"
+
+import * as React from 'react'
+import { useSearchParams } from 'next/navigation'
+import { navigateWithPageReload } from '@open-mercato/shared/lib/navigation/pageReload'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { Spinner } from '@open-mercato/ui/primitives/spinner'
+import { usePortalContext } from '@open-mercato/ui/portal/PortalContext'
+import { FormRunner } from '../../../../../../ui/public'
+
+type Props = { params: { orgSlug: string; id: string } }
+
+export default function PortalSubmissionContinuePage({ params }: Props) {
+  const t = useT()
+  // Route params come from the `params` prop the (frontend) catch-all passes.
+  // `useParams()` returns `{ slug }` under the catch-all, so `id` was undefined
+  // and this page could never resume a submission. Query-string values still
+  // come from `useSearchParams()`, which is unaffected.
+  const search = useSearchParams()
+  const orgSlug = String(params?.orgSlug ?? '')
+  const submissionId = String(params?.id ?? '')
+  const formKey = String(search?.get('formKey') ?? '')
+  const subjectType = String(search?.get('subjectType') ?? 'customer')
+  const { auth } = usePortalContext()
+  const { user, loading } = auth
+  const subjectId = user?.id ?? ''
+
+  if (loading) {
+    return (
+      <div className="flex items-center justify-center py-20">
+        <Spinner />
+      </div>
+    )
+  }
+  if (!user) return null
+
+  return (
+    <main className="px-4 py-6 sm:px-6 lg:px-8">
+      {formKey && subjectId ? (
+        <FormRunner
+          formKey={formKey}
+          subjectType={subjectType}
+          subjectId={subjectId}
+          initialSubmissionId={submissionId}
+          onReturnHome={() => {
+            if (typeof window !== 'undefined') {
+              navigateWithPageReload(`/${orgSlug}/portal`)
+            }
+          }}
+        />
+      ) : (
+        <p className="text-sm text-muted-foreground">{t('forms.runner.loading')}</p>
+      )}
+    </main>
+  )
+}

package/src/modules/forms/frontend/embed/[slug]/page.meta.ts

@@ -0,0 +1,42 @@
+import type { PageMetadata } from '@open-mercato/shared/modules/registry'
+
+/**
+ * External iframe host page for an embeddable OPEN distribution (spec
+ * `2026-05-21-forms-render-surfaces.md`, S4 / D4–D6). Unauthenticated by design
+ * — the slug is the bearer of access, and the anonymous public runtime enforces
+ * availability / cap / CAPTCHA exactly as `/f/:slug`.
+ *
+ * SECURITY (R-RS-1) — HOST PLUMBING NOT WIRED IN THIS REPO.
+ *
+ * The design calls for this route to be served with a per-distribution
+ * `Content-Security-Policy: frame-ancestors <allowedDomains>` header and no
+ * `X-Frame-Options`, with the app's global frame protection carving `/embed/`
+ * out so the dynamic header is the sole authority, resolved via
+ * `GET /api/forms/public/distributions/:slug/embed-policy`
+ * (→ `buildFrameAncestorsCsp` in `lib/embed-frame-policy.ts`).
+ *
+ * Neither half exists yet. `apps/mercato/next.config.ts` applies
+ * `frame-ancestors 'self'` plus `X-Frame-Options: SAMEORIGIN` to `/:path*` with
+ * no `/embed/` carve-out, and `apps/mercato/src/proxy.ts` never calls the
+ * embed-policy endpoint. It was absent from the module's original repository
+ * too — that sandbox app declared no `headers()` at all, so `/embed/:slug` was
+ * framable there by default rather than by policy.
+ *
+ * Consequence: cross-origin framing of this page is currently BLOCKED by the
+ * app's global policy. That is the fail-closed direction, so the page is safe
+ * and the embed surface is inert. Everything below the header is complete and
+ * tested — availability / cap / CAPTCHA enforcement, theme application, the
+ * allowlist normalizer, the `embed-policy` endpoint. Only the header is missing.
+ *
+ * Both halves are load-bearing: a carve-out without the dynamic header would
+ * leave this page framable by anyone. A per-request response header cannot come
+ * from a React Server Component, so it belongs in the proxy. Tracked in
+ * `.ai/specs/2026-09-30-forms-module-into-core.md` § Known limitations.
+ */
+export const metadata: PageMetadata = {
+  requireAuth: false,
+  titleKey: 'forms.runner.loading',
+  title: 'Form',
+}
+
+export default metadata