Mozaiks UI v1¶

Status: Authoritative target architecture constitution for the native Mozaiks UI framework. Contract id: mozaiks.ui.v1 (documentation contract only; runtime schema ids are introduced by the roadmap in §12). Authority: Subordinate to Mozaiks OSS Software Design and the Canonical Schema Generation Policy. Where this document and current source disagree, §11 says which is truth today; changes to this document follow §10.

This document is documentation-only. It changes no code, schema, registry, or runtime behavior. Inputs include the merged mozaiks.app_layout.v1 registry (mozaiksai/core/runtime/app/layout_registry.py, PR #286), the current Generated Frontend Surface Contract, UI Surface Model, the AG-UI / CopilotKit comparison, and the recent cross-repo UI architecture audits (Codex UI architecture audit; Claude Code UI evidence inventory), with App Zero usage read as evidence only.

1. Scope¶

Mozaiks UI is the deterministic application UI framework of the Mozaiks canonical application model. It is:

• a build-time UI generation system: strict structured outputs materialize validated, byte-stable UI artifacts into canonical app-layout paths;
• a closed-registry rendering system: pages and components resolve only through registered primitives and named components;
• a composition system: durable application pages, bounded custom routes, live workflow surfaces, and transition surfaces share one primitive/design foundation while keeping separate authoring contracts;
• an application framework: routes, shell, navigation, theme authority, module-action data binding, and entitlement-aware error recovery are first-class.

Mozaiks UI is not:

• only a chat renderer — persistent application pages are not chat artifacts;
• a generative-UI protocol — no model composes screens at runtime; UI is generated once, validated, and promoted;
• a transport specification alone — the wire contract (§5) is one layer of the framework, not the framework;
• a design system marketplace — reusable UI enters only through capability-pack and registry contracts.

External protocols. AG-UI and A2UI are comparison inputs only. They are not dependencies, not canonical authorities, and no Mozaiks contract may reference their types for canonical identity. This document makes no adapter roadmap commitment. Any future interoperability adapter requires a separate ADR and explicit product decision before implementation work starts.

2. Canonical UI surfaces¶

There are exactly four canonical surface kinds. They are already a finite generator taxonomy in mozaiksai/core/workflow/ui_surface_taxonomy.py and the Generated Frontend Surface Contract.

Admin and profile are registered extension surfaces, not fifth and sixth surface kinds. They are contract-declared compositions over the four kinds:

• Admin/operator extension surface — two tiers, per the admin two-tier model: Tier 1 schema panels declared in admin/admin_registry.yaml plus module contracts/admin.yaml (declarative composition rendered inside the unified /admin shell); Tier 2 full-page operator routes, which are custom_react_page instances registered through the same three-file route contract plus admin/index.js. admin_registry.yaml is never a route registry.
• Profile extension surface — module contracts/profile.yaml tabs/panels (mozaiks.profile.v1) hydrated by the core ProfilePage through /api/me/profile-tabs / /api/me/profile-panels. Modules contribute content; the host owns identity and the page itself.

This classification is normative: proposals to add a new top-level surface kind must show why the behavior cannot be expressed as a registered extension over the four kinds, and must follow §10.

3. Layer ownership¶

One owner per layer. No layer may grow a second owner; the Canonical Schema Generation Policy alias rules apply.

Hard exclusions. UI never owns: business authorization (module permissions[] + runtime auth own it — meta.routeAuth is a pre-render gate only, never authority); entitlement grants (EntitlementPort adapters own enforcement; UI only reacts to ENTITLEMENT_REQUIRED / INSUFFICIENT_TOKENS with declared recovery routes); billing authority; tenant identity; durable domain state (module actions own all durable mutation). A UI surface that needs a durable fact calls a module action.

4. Registry constitution¶

Two registry classes exist and must never be conflated:

Immutable contract registries — versioned, digest-stable, closed vocabularies that generators emit against and validators enforce. Changing one is a contract change (§10).

Mutable runtime mounting registries — process-local mount tables populated at boot from the immutable contracts: componentRegistry.js (a runtime Map), WorkflowUIRouter workflow-local component resolution, and shell route mounting. They may hold instances; they may never introduce names, kinds, or paths that the contract registries do not declare. A mounting registry entry without a contract-registry counterpart is a validation failure, not a feature.

Relationship to mozaiks.app_layout.v1: the layout registry owns where every UI artifact lives (app_ui_page_schema, app_ui_custom_route, app_ui_route_manifest, app_ui_extension_barrel, app_ui_module_api, module_admin_ui, module_ui_extension_barrel, workflow_ui, app_admin_registry, app_dashboard, app_brand_theme, app_shell_config). Mozaiks UI v1 owns what those artifacts may contain and how they behave. Every registry above must key its artifacts to layout artifact kinds; neither document may redefine the other's axis.

5. Native event constitution — mozaiks.ui.event.v1¶

Requirements for the future canonical UI interaction envelope. This section sets the contract bar; the concrete schema lands via §12. Nothing here changes code in this PR.

The envelope MUST provide:

1. Closed event taxonomy. A finite enum of event kinds covering: run lifecycle (started, finished, failed), text streaming, tool lifecycle (start, args, end, result), approvals and interrupts (request, response, resume), navigation intents, state snapshot and state delta, primitive refresh, and recovery/replay markers. Unknown kinds fail closed at both producer and consumer.
2. Versioned envelope. schema_version: mozaiks.ui.event.v1 on every event; consumers reject unversioned or unknown-version events.
3. Deterministic identity. Stable event_id; identity derives from content and ordering fields, never from wall-clock time.
4. Sequence and ordering. Monotonic per-stream sequence numbers; consumers can detect gaps and must not render out-of-order tool lifecycles.
5. Correlation and causation. run_id, chat_id, tool_call_id, and a caused_by reference so every render can be traced to the emitting turn.
6. Idempotency. Redelivery of the same event_id/sequence is a no-op render.
7. Replay boundaries. Replay is scoped to one session stream; a replay marker separates restored history from live events; replayed events never re-trigger side effects (tool futures, navigation).
8. Bounded payloads. Enforced maximum payload size; large artifacts travel by reference (artifact id), never inline.
9. Tenant/session scoping. Every event carries app_id and session scope; the transport layer enforces that a socket only ever receives its own session's events. Cross-tenant replay is structurally impossible, not merely filtered (§9).
10. Lifecycle, tools, approvals, interrupts, navigation, state, recovery are all first-class kinds in the taxonomy — no side channels.
11. Non-authoritative timestamps. Timestamps are display metadata; ordering and identity never depend on them.
12. Payload hygiene. No secrets, raw exception text, source file content, or model chain-of-thought in any event payload. Structured-output JSON from registered agents is durable trace data routed to the declared artifact/tool path, never projected as chat text (per the AG2 runtime-handoff rule).

Canonical workflow-render lane (conceptual resolution). The tool-call lifecycle — today carried primarily as chat.tool_call / tool_call_response — is the canonical workflow-render lane and survives. Current source still contains ui.render consumer paths from the earlier typed-UI experiment; those paths are transitional implementation evidence, not a second canonical lane. The intended migration is: preserve chat.tool_call semantics, express that lane through mozaiks.ui.event.v1 typed tool-lifecycle kinds, move any still-needed ui.render behavior into that envelope, then delete ui.render as a browser-facing render lane. After that migration, the typed ui.* primitive bus is secondary and refresh-only (never a renderer of new workflow surfaces). This follows the keep/merge/delete map already recorded in the AG-UI / CopilotKit comparison: one stream, one tool lifecycle, one response lane, a default renderer so tool activity is never invisible.

6. State ownership¶

Closed list of state domains. Each has one owner and an explicit durability class.

Rules: anything authority-bearing (approvals, module records, workflow checkpoints, entitlement assignments) is durable and server-owned. Anything the client holds is reconstructable or disposable. No state domain may be added without extending this table (§10), and no client cache may become the only holder of an authority-bearing fact.

7. Deterministic generation contract¶

The one required path for every generated UI artifact. Stages must not be skipped or reordered; each stage consumes only the previous stage's validated output.

strict structured output          AppSchemaOutput / workflow UI CodeFiles — typed, registry-bound
  → registry validation           surface kinds, primitives, page types, workflow primitives,
                                  named-component references all resolve against §4 registries
  → canonical materialization     save tools write only mozaiks.app_layout.v1 paths
                                  (app_ui_page_schema, app_ui_custom_route, workflow_ui, …)
  → route/component/action closure
                                  route → component → module → action closure; registerComponent
                                  closure; moduleAction() usage; workflow ids resolve
  → security & entitlement checks entitlement_gate → subscriptions closure; api_surface taxonomy;
                                  no secret paths; recovery-route rules for gated actions
  → byte-stable artifacts         deterministic serialization; timestamps excluded from identity
  → bundle scan                   validate_generated_app_bundle + generated_bundle_scanner
  → functional validation         scan_functional_generated_app: no 404/501/NotImplemented,
                                  registered components only, endpoint shape rules
  → real runtime boot             app_runtime_load: AppLoader boots the assembled bundle;
                                  Playwright render acceptance for the UI lane
  → promotion                     the only path from generated/ staging into an active app root

The quality gates are runtime state, not prompt prose: app_ui_quality_status and workflow_ui_quality_status must equal passed before assembly/delivery, and Playwright findings convert to structured passed | needs_revision | blocked production-readiness output. The LLM never chooses file locations (layout registry), never invents primitives or components (§4 registries), and never bypasses a gate.

8. Extension constitution¶

Every extension type has a mandatory, complete checklist. An incomplete extension fails closed — loaders, scanners, and gates reject it; nothing renders partially.

9. Security invariants¶

Non-negotiable. Violations are defects regardless of convenience.

1. No agent-invented component or action authority. Agents reference primitives, components, routes, and actions by registered name only; unresolved references fail before promotion (schema-generation policy rule 5).
2. No caller-selected dynamic imports. The frontend never imports code from a name supplied at runtime; all mounting goes through boot-time registries populated from validated contracts.
3. No UI-side authorization. meta.routeAuth and entitlement-aware helpers are UX gates; module permissions[], entitlement_gate, and runtime auth are the only authority. A UI check is never the last check.
4. No cross-tenant replay. §5 scoping: events carry tenant/session identity and transport delivers only within scope; replay never crosses sessions.
5. No unvalidated page serving. /api/pages/{name} serves only pages that passed the §7 pipeline; hand-edited artifacts in active roots are a promotion-discipline violation.
6. No unknown taxonomy fallback. Unknown surface kinds, page types, layout types, primitives, display modes, or event kinds are errors — never coerced to a default. (Current gap: PageRenderer maps unknown layouts to full-width; §11.)
7. No silent layout/shell fallback. Shell composition guarantees (admin-portal injection, appShell inference) are explicit runtime rules, not ad hoc defaults; generated output must not re-declare them.
8. No raw exception or secret payloads. UI events and page data carry typed error codes (error_code), never raw exception text, credentials, or secret names beyond the names-only contracts.
9. No runtime-generated executable UI. No surface evaluates model-produced code in the browser. Executable UI exists only as build-time artifacts that passed §7 — this is the structural difference from generative-UI protocols and it is permanent.

10. Versioning and maintenance¶

• Schema/version ownership. Each contract family carries its own version id (mozaiks.ui.surface.v1, mozaiks.ui.event.v1, mozaiks.profile.v1, …). Version ids live with the runtime owner of the contract; this document indexes them.
• Pre-production posture. Replace, don't preserve: obsolete shapes, aliases, dual-read paths, and retired names are removed in the same change that supersedes them, per the repo-wide pre-1.0 policy. No compatibility shims without an explicit current external contract.
• Retirement process. A concept is retired by: updating the structured-output model, prompts, materializer, validators, runtime consumer, docs, fixtures, and tests together; deleting the retired shape; and recording the change in CHANGELOG.md. Half-retired concepts (old name still accepted anywhere) are defects.
• Registry drift tests. Every §4 immutable registry gets a deterministic test asserting the runtime vocabulary, the structured-output enum, and the generator catalog agree (pattern: the layout registry's own drift tests against paths.py and file_contracts.yaml).
• Required tests and documentation. No UI contract change merges without: the narrowest focused tests, the affected quality-gate rules, and updates to this document's §11 table when current truth moves.
• One concept, one owner. One runtime concept gets one canonical name and one owning registry. Discovering two names for one concept triggers consolidation, not documentation of both.
• OSS/proprietary boundary. Everything in this document is OSS. Proprietary operator UI (App Zero product pages, hosted dashboards) consumes these contracts via the pinned package and the workspace reuse contract; no proprietary surface may require a private fork of any registry, renderer, or event contract.
• Prohibited shortcuts. Registering components outside barrels; serving pages that skipped gates; adding event names outside the taxonomy; introducing a second workflow-render lane; UI-side authority checks; hardcoded visual values in generated React; editing generated artifacts in place without promotion.

11. Current versus target¶

Facts about today's implementation versus the v1 target. Nothing below presents unimplemented behavior as existing.

12. Dependency-ordered implementation roadmap¶

Small PRs, each independently green, each with rollback. No PR below changes this document's authority; each cites it. No AG-UI adapter phase appears here; any interoperability adapter requires a prior explicit commercial decision gate recorded as an ADR before any implementation PR may be opened.

Each PR: worktree from fresh origin/main, focused tests + full offline suite + ruff locally, auto-merge on green, per the multi-agent coordination rules.

Relationship summary¶

mozaiks.app_layout.v1 answers where a UI artifact may exist. Mozaiks UI v1 answers what it may contain, how it renders, how it behaves, and how it changes. The Generated Frontend Surface Contract remains the working-level surface specification; this document is the constitution above it. Where the two ever disagree, this document decides — and the disagreement is a defect to fix, not a fork to maintain.