Migrate Forms Runtime interface patterns

docs/INTERFACE_PATTERN_MIGRATION.md

@@ -0,0 +1,33 @@
+# Forms Runtime Interface Pattern Migration
+
+This migration applies the GovOPlaN interface pattern language to the Forms
+Runtime list, instance, submission, and native handoff surfaces. Core owns the
+shared controls and interaction states. Forms Runtime keeps ownership of
+instance revisions, validation, receipts, and handoff evidence.
+
+## Surface Inventory
+
+| Surface | Archetype | Consequence class | Contract |
+| --- | --- | --- | --- |
+| `/forms-runtime` | Filtered work queue | Select assigned or authorized instance | Shared loading/error/empty/help states and locale-aware dates |
+| `/forms-runtime/:instanceId` | Guided runtime form | Change draft values or inspect immutable submission | Definition-provided fields/help, permission/lifecycle blocker, guarded draft |
+| Save and submit actions | Consequential editor | Save revision or issue immutable receipt | Explained disabled reasons; submission confirmation; server validation remains authoritative |
+| Case/Workflow handoffs | External-effect recovery queue | Record intent, execute, retry, reconcile, compensate | Permission reason, start confirmation, explicit unknown-outcome and compensation semantics |
+| History and revisions | Evidence/provenance | Reconstruct status and value revisions | Immutable chronological evidence with platform-locale timestamps |
+
+## Consequence And Availability Rules
+
+- Runtime localization follows the platform-selected language, not the browser
+  language independently of the active account preference.
+- A draft save requires changed values and a reason. Submission is separately
+  confirmed and creates an immutable receipt after server validation.
+- Read-only fields explain whether permission or lifecycle caused the state.
+- Handoff intent is persisted before provider execution. Unknown outcomes are
+  reconciled before retry; compensation records verified absence only.
+- Optional Files, Policy, Case, Workflow, Approval, Portal, and Audit behavior
+  remains behind declared capabilities and interfaces.
+
+Native controls preserve keyboard order, shared dialogs manage focus, changed
+values use the global unsaved-draft guard, and bounded list/detail regions keep
+their existing responsive scrolling. English and German catalogues cover
+module-owned copy; definition content uses its own published localization.