AppGenerator Output Assembly Contract¶

Status: Canonical contract Purpose: Define exactly how AppGenerator turns persistent UI intent into bundle artifacts.

Owned Artifacts¶

AppGenerator emits deterministic app-bundle artifacts for persistent app UI:

• app.json
• admin/admin_registry.yaml
• ui/pages/*.yaml
• brand/theme_config.json
• config/shell.json
• config/asset_manifest.json

The artifact split is strict:

• app.json defines app identity, targets, auth intent, and startup behavior such as startup.landing_spot.
• admin/admin_registry.yaml declares all AdminPortal pages for the generated app's admin surface. Module panels reference these page ids via the page field in modules/{module}/contracts/admin.yaml. Standard generated-app admin paths use /admin; /apps/:appId/... belongs to first-party Studio or explicit hosted-operator surfaces.
• ui/pages/*.yaml define persistent page structure and route ownership.
• brand/theme_config.json defines visual tokens, shared primitives, and semantic ui.chat / ui.shell / ui.page styling.
• config/shell.json defines compact app-wide shell behavior: header logo/actions, canonical shortcuts, navigation policy, non-page-owned navigation items, and chrome mode defaults.
• config/asset_manifest.json defines reusable media inventory metadata for non-token assets (icons/images/video), including source/provenance and usage hints.

AppGenerator does not own the full build lifecycle, agent workflows, agent UI tools, or workflow transition surfaces. AgentGenerator produces workflow/agent artifacts, and the Refinement Engine governs AppContextVersion selection, validation, review, and ArtifactVersion acceptance/promotion. Generated bundle files become source of truth only through artifact acceptance and promotion.

When AppGenerator assembles module artifacts into the app workspace, companion manifests stay under modules/{module}/contracts/. Canonical event files are contracts/events.yaml, contracts/reactions.yaml, and contracts/notifications.yaml; do not flatten them to the module root or emit contracts/subscriptions.yaml. Persistent module backends use backend/schemas.py, not backend/models.py.

Upstream Inputs¶

AppGenerator should compile these inputs in priority order:

1. captured_theme_config
2. optional canonical ThemeCapture artifact

3. strongest visual source when present

4. app_build_plan

5. carries theme_preferences, brand_intent, optional shell_preset_hint, pages, entities, capability packs, auth, and integrations

6. experience_spec_document / ui_design_document

7. persistent page intent and layout guidance

8. concept_blueprint and related design docs

9. fallback context when no stronger artifact exists

Compilation Flow¶

1. ThemeCapture¶

ThemeCapture produces canonical visual evidence only.

It emits:

• theme
• identity
• assets
• primitives
• fonts
• colors
• shadows
• ui.chat
• ui.shell
• ui.page

It does not emit shell content such as header actions, profile menu items, notification copy, or footer links.

2. AppSchemaAgent¶

AppSchemaAgent compiles persistent UI into one AppSchemaOutput with six payloads:

• manifest
• pages
• custom_route_bundle
• theme_config_patch
• shell_config
• asset_manifest

Theme vs Shell Ownership¶

Two artifacts handle visual and behavioral customization:

• theme_config_patch → visual tokens only: colors, typography, spacing scale, shadows, density, ui.chat / ui.shell / ui.page semantic styling
• shell_config → shell behavior only: header logo/actions, canonical shortcuts, navigation.policy, non-page-owned navigation.items, and chrome mode overrides

shell_preset_hint is not an artifact. It is prompt-time AppGenerator guidance from factory_app/build_context/AppGenerator/shell_presets.yaml. AppSchemaAgent uses it to choose page navigation, page shell_mode, and whether a compact shell_config override is necessary. The preset id is never written into the generated app bundle.

Do not mix them. Raw spacing/width/density tokens belong in theme_config_patch. Header action labels and app-wide shell placement rules belong in shell_config.

Rules:

• manifest.default_route is persisted to app.json -> startup.landing_spot
• custom_route_bundle is a rare bounded escape hatch for persistent routes that cannot be expressed cleanly through shipped primitives
• theme_config_patch is a partial patch for brand/theme_config.json
• shell_config is a partial patch for config/shell.json
• asset_manifest is a partial patch for config/asset_manifest.json
• raw spacing, width, density, and sizing tokens belong in theme_config_patch, not shell_config
• generated shell_config.shortcuts may only contain header, profile, mobile, footer, and footerHideOnMobile
• do not emit custom shortcut catalogs or shell fields outside AppShellConfigPatch
• shell actions may use semantic variants[].when for context-aware label/target changes; do not emit path-prefix, wildcard, or query-param override rules
• page-owned shell navigation belongs on ui/pages/*.yaml -> navigation; shell_config.navigation.policy owns app-wide placement rules
• page-owned header/footer/bottom-bar intent belongs on ui/pages/*.yaml -> shell_mode; shell_config.chrome owns only app-wide mode-policy overrides
• reusable media inventory belongs in asset_manifest, not in theme_config_patch or shell_config
• custom routes must be owned exclusively by custom_route_bundle (ui/route_manifest.json + ui/pages/custom/*.jsx) and must not duplicate any ui/pages/*.yaml route
• every custom route manifest entry must have exactly one page_files entry whose registry_key matches the route component; save_app_schema synthesizes ui/index.js from that matched pair
• app/ui/index.js must register every component referenced by ui/route_manifest.json; missing registrations are export/download blockers, not runtime surprises
• scoped private routes should declare route meta.routeAuth when route path or query params identify a resource whose visibility depends on membership, ownership, tenant/workspace access, or an invitation/access state. Declarative pages use ui/pages/*.yaml -> meta.routeAuth; custom routes use ui/route_manifest.json -> pages[].meta.routeAuth.
• admin/admin_registry.yaml declares admin page and panel metadata; it is not a route registry and must not own full-page custom route components
• managed-capability pages must bind through an app-owned facade module endpoint such as /api/modules/analytics_dashboard/get_metrics, never directly to managed-capability internals
• declarative pages may launch workflow sessions through typed page actions (action_type: workflow), but workflow-local React still belongs to AgentGenerator and chat.tool_call

Managed-capability facade binding¶

When a build has a selected managed capability pack, AppGenerator must keep the generated app boundary explicit:

managed_capability
  -> app/services/integrations/{pack_id}_client.py
  -> app-owned facade module
  -> ui/pages bind to the facade module

Provider-neutral example:

managed_analytics
  -> app/services/integrations/managed_analytics_client.py
  -> modules/analytics_dashboard/
  -> ui/pages/analytics.yaml
  -> /api/modules/analytics_dashboard/get_metrics

The pack descriptor may provide surfaces, supported_domains, branding, generation_rules, adapter_template, and capability_source. Those fields are planning metadata. They do not authorize generated pages to call managed provider internals directly.

For SaaS apps that select the mozaikspay managed capability, the generated app bundle must include the portable SaaS contract, not managed provider internals:

• config/subscriptions.yaml with plans, gates, and only the token wallets, token allowances, top-up products, and usage limits required by the app's AI usage, credit, or quota model
• services/integrations/mozaikspay_client.py as the app-side connector client
• modules/billing_portal/ as the app-owned facade module
• billing and usage pages bound only to /api/modules/billing_portal/*
• no modules/mozaikspay/, managed billing module, wallet module, or direct provider SDK ownership in the generated app

Managed packs that own subscription assignment writes must declare that through provides_capabilities: [subscription_write_path] in the pack contract.yaml. The scanner uses that provider-neutral capability flag to skip entitlement_dispatch; otherwise any generated app with config/subscriptions.yaml -> assignment_store must include the entitlement_dispatch generated module so self-hosted and custom-provider apps still have a deterministic assignment writer. This rule is pack-driven and must not special-case MozaiksPay in scanner logic.

The deterministic app-bundle acceptance gate enforces this boundary on the assembled bundle, not on isolated task output. A selected managed capability must pass the generated bundle scanner and the app_runtime_load check, which materializes the same file map that generate_and_download would package and loads it through AppLoader.load(). This catches semantic drift such as pages binding to provider internals, facade handlers accepting synthetic payload wrappers, missing app-level service packages, invalid companion manifests, or template files that cannot be imported by the runtime loader.

When config/integrations.yaml declares a managed setup lane, the same scanner also rejects raw payment-provider env handles, provider webhook/checkout routes, and direct provider SDK mechanics anywhere in the generated bundle. Managed setup is a contract boundary: provider callbacks and processor mechanics stay with the managed/hosted product, while the generated app uses the managed capability client and app-owned facade.

Route/component registration drift¶

For custom full-page React routes, the route contract is complete only when all of these are true:

• ui/route_manifest.json -> pages[].component names the runtime component key
• ui/pages/custom/*.jsx contains exactly one default-exported page for that key
• ui/index.js registers the same key through registerComponent
• no declarative ui/pages/*.yaml route owns the same path
• no implicit file discovery or admin-registry fallback may substitute for the three files above

Generation should catch missing or mismatched component registrations before download/export.

Scoped route authorization¶

routeAuth is the first-class route metadata contract for declarative pages and custom full-page routes that need a pre-render authorization check. It is not app-specific and it does not encode policy in the shell. Route metadata names an app-owned module action, and the module action makes the authorization decision using the normal service/policy layer.

In AppSchemaAgent structured output, routeAuth.params is emitted as strict {key, value} entries so provider response-format validation remains enabled. save_app_schema normalizes those entries into the runtime object shape written to generated YAML/JSON.

Example:

{
  "name": "ProjectSettings",
  "route": "/projects/:projectId/settings",
  "title": "Project Settings",
  "page_type": "settings",
  "layout": "grid",
  "meta": {
    "routeAuth": {
      "module": "project_access",
      "action": "authorize_project_route",
      "params": [{ "key": "project_id", "value": "$route.projectId" }]
    }
  },
  "sections": [
    {
      "id": "project-settings-header",
      "primitive": "PageHeader",
      "config": { "title": "Project Settings" }
    }
  ]
}

The target module action must return { "allowed": true } to render the route. Returning { "allowed": false, "reason": "..." } denies the route and lets the shell show the denial reason. This gate protects deep links and avoids rendering pages before scope is known, but backend module actions must still perform their own authorization checks.

2b. AdminRegistryAgent¶

AdminRegistryAgent runs after AppUIQualityAgent passes and before AssemblyAgent.

It produces AdminRegistryOutput with two payloads:

• admin_registry — typed AdminRegistry object (page list with ids, labels, paths, icons, scope, order)
• code_files — serialized admin/admin_registry.yaml

Rules:

• Always emits overview and settings app-scope pages
• Includes additional standard pages (access, billing, usage, activity, operations, integrations, support) based on app_build_plan.capability_packs entity domains and auth_strategy
• Standard pages are modular, not a "full app" bundle preset. A generated app should only receive pages whose source capability, entity domain, integration need, or access model creates a real operator task for that page.
• Includes operator-only pages (e.g. hosting) only when capability_packs is non-empty and explicitly targets hosted/operator app management — never in plain OSS contexts without workspace build context
• Uses scope: app for all generated app pages; workspace-scope pages only for hosted operator contexts
• Hosted global operator registries belong to hosted product workspaces and must not be emitted into standard generated app bundles
• Page ids must cover every entity domain that ConfigMiddlewareAgent assigns module admin panels to
• The module contract quality gate validates at generation time that every admin.yaml panel page field resolves to a declared page id

Operator-only pages:

Add new operator-only pages here when a managed capability context introduces a new operator surface. Do not add them to the standard inclusion rules.

AssemblyAgent must include admin/admin_registry.yaml in the final bundle output.

3. save_app_schema¶

save_app_schema is the persistence tool for schema-driven app bundles.

It must:

• write generated artifacts under $MOZAIKS_GENERATED_ARTIFACTS_PATH/apps/{app_id}/{build_id}/app/
• write app.json
• write ui/pages/{name}.yaml
• write ui/route_manifest.json when custom_route_bundle exists
• write ui/pages/custom/*.jsx when custom_route_bundle exists
• synthesize ui/index.js from custom_route_bundle.page_files when custom routes exist
• reject or warn on custom route registry drift before assembly: missing page files, duplicate registry keys, .js route files, non-default-exported React, or route components that no page file registers
• deep-merge theme_config_patch into brand/theme_config.json
• deep-merge shell_config into config/shell.json
• deep-merge asset_manifest into config/asset_manifest.json
• store app_manifest, app_pages, app_custom_route_bundle, app_theme_config_patch, app_shell_config, app_asset_manifest, and app_schema_ready in workflow context

It must not write directly into an active runtime-loaded app root such as a workspace's app/ bundle or factory_app/app. Activation requires an explicit promotion step.

4. AssemblyAgent¶

When app_schema_ready == true, AssemblyAgent must emit those artifacts back out as code_files so downstream download/export tools can bundle them.

Required schema-driven outputs:

• app.json
• admin/admin_registry.yaml
• ui/pages/{name}.yaml
• ui/route_manifest.json when app_custom_route_bundle exists
• ui/pages/custom/*.jsx when app_custom_route_bundle exists
• ui/index.js when app_custom_route_bundle exists
• brand/theme_config.json when app_theme_config_patch exists
• config/shell.json when app_shell_config exists
• config/asset_manifest.json when app_asset_manifest exists

When app_schema_ready == false, AssemblyAgent should use task batch outputs via assemble_app_tasks and must still preserve the page contract.

4b. Raw Frontend Path Removed¶

AppGenerator no longer carries a secondary raw frontend page/component generation lane.

Rules:

• ordinary persistent pages still compile through AppSchemaAgent
• raw React page/component tasks do not belong in AppGenerator build plans outside the explicit custom_route_bundle contract
• shell content compiles through shell_config, not through a separate frontend shell agent
• if the primitive system is insufficient, the platform should add a primitive, pattern, or page capability rather than reviving a second frontend codegen path

5. IntegrationReadinessAgent¶

IntegrationReadinessAgent runs after AssemblyAgent and before validation or download. It is not a manual preflight step. It is the agentic aggregation point for third-party connector needs discovered while planning or executing decomposed build tasks.

Inputs:

• app_build_plan.external_integrations
• capability_packs[].required_integrations
• build_tasks[].integration_needs
• app_task_batch_results from task batch execution
• integration_needs recorded by task agents with record_integration_need

Rules:

• Reuse ready app-scoped connectors from the platform connector store.
• Prompt inline only for unresolved required credentials or required non-secret connector configuration.
• Emit structured integration.required requests with integration_id, provider/service id, purpose, required_fields, secret_fields, non_secret_fields, permissions_required, and resume context.
• Persist newly supplied credentials through the platform connector service so /apps/{appId}/integrations reflects the result.
• Treat the workspace integration catalog as inventory only. The app's integration page is driven by integration_needs and managed capability requirements, not by every available catalog entry.
• For monetized apps, save_integration_manifest records mozaikspay as a removable default app integration when the build did not explicitly declare a monetization connector. This default is optional and operator-removable; an explicit capability_packs[].required_integrations entry remains the source of truth for blocking credential requirements.
• Persist only frontend-safe non-secret config in connector metadata. Secret fields are write-only and must not be returned to chat, generated code, or frontend read APIs.
• Do not generate app-owned API-key tables, credential collections, or custom credential forms.
• If required credentials are declined or unavailable, block validation/download and return to the user with the unresolved service list.

6. generate_and_download¶

generate_and_download is the bundling tool.

It does not reason about artifact ownership. It packages the materialized file set into the downloadable app bundle after the deterministic app-bundle acceptance gate passes.

Download archives may include a single top-level folder named for the bundle such as GeneratedApp/. Studio artifact promotion treats that folder as a zip transport wrapper only when stripping it reveals an app-root bundle containing app.json. The promoted active app root must contain app.json, config/, modules/, ui/, and other app-bundle families directly; it must not require the platform host to look under GeneratedApp/.

When AgentGenerator workflow metadata is present, the acceptance gate is export-blocking. AppGenerator must wire each generated workflow through:

• modules/{module}/module.yaml capabilities[] with kind: workflow, the AgentGenerator capability_id, and the AgentGenerator workflow name as target
• modules/{module}/contracts/events.yaml declaring every workflow trigger event
• modules/{module}/module.yaml action emits[] for the trigger event that starts the workflow
• modules/{module}/contracts/reactions.yaml routing each trigger event to the AgentGenerator workflow capability id

The gate also blocks semantic drift: trigger-event capability_id values must match the workflow capability id from AgentGenerator metadata, generated app modules must not invent workflow capabilities absent from that metadata, and a workflow trigger event must not also route to a different generated workflow capability unless that route is declared by the same metadata.

When workflow integration fails, the acceptance gate writes a bounded repair contract before export can proceed:

• workflow_integration_repair_status
• workflow_integration_repair_count
• workflow_integration_repair_request
• workflow_integration_repair_failed_tests
• workflow_integration_repair_result

needs_revision routes back to ConfigMiddlewareAgent, which runs in workflow-integration repair mode. That mode emits only corrected module contract YAML for the affected module, using AgentGenerator workflow metadata and the injected [WORKFLOW INTEGRATION CONTRACT] as authority. It must not regenerate backend Python, frontend code, pages, data contracts, service foundation files, or unrelated modules. After the configured attempt limit, the status becomes blocked and the workflow returns to the user.

When the generated-bundle scanner fails on a file-family violation, the same acceptance gate writes a bundle repair contract before export can proceed:

• bundle_repair_status
• bundle_repair_target
• bundle_repair_attempt_count
• bundle_repair_max_attempts
• bundle_repair_request
• bundle_repair_errors
• bundle_repair_result

Both workflow-integration and generated-bundle repair contracts also persist a stable failure fingerprint and a no_progress flag. The acceptance gate normalizes the current failure evidence and hashes it before scheduling a repair. If validation after a repair produces the identical fingerprint, the gate marks the repair blocked immediately instead of spending another model turn on the same unchanged failure. A changed fingerprint may consume the next bounded attempt. Passing validation clears the fingerprint and no-progress state.

This makes the repair controller deterministic:

1. observe validation evidence
2. classify the narrowest owning agent
3. emit a bounded repair request
4. apply only that agent's owned file delta
5. re-run the authoritative acceptance gate
6. stop on pass, repeated evidence, or attempt exhaustion

Agent prompts may propose a patch, but they do not decide whether the loop continues. The acceptance gate, failure fingerprint, ownership table, and retry budget are the control authority.

The automated repair controller currently covers workflow-integration failures and generated-bundle scanner failures. Other acceptance failures still fail closed to the user. Browser interaction evidence (console errors, failed network requests, screenshots, and replayable user-flow assertions) is not yet a first-class automatic repair input. Closing that gap requires a typed, environment-scoped verification-evidence contract that maps each failure to an owning agent and replays the same scenario after the patch. Browser evidence may inform repair, but it must not bypass deterministic acceptance, review, or promotion.

The target must be the narrowest owning agent: AppSchemaAgent for page/schema endpoint drift, ConfigMiddlewareAgent for config or managed-capability client drift, ServiceAgent for backend Python/service drift, and FrontendStubAgent for generated frontend helper drift. A repair agent may remove stale or invalid artifacts by emitting deleted_files; AssemblyAgent, the acceptance gate, and DownloadAgent all apply those deletions before validation or packaging.

Deterministic smoke coverage:

python scripts\smoke_appgenerator_live_acceptance.py --repair-loop

This smoke injects an app-local token wallet ledger, verifies that scanner repair routes to ServiceAgent, applies deleted_files, re-runs acceptance, checks the export gate, and proves packaging no longer contains the removed artifact.

When a build/export context requests deployment output, or the generated files already contain deployment.manifest.json, Dockerfile, docker-compose.yml, .github/workflows/readiness.yml, or .github/workflows/deploy.yml, the acceptance gate runs the provider-neutral deployment artifact validator. Deployment-ready bundles must include valid deployment artifacts such as Dockerfile, .env.example, .env.staging.example, .env.production.example, and deployment.manifest.json; missing deployment artifacts block export/promotion instead of being discovered by a later hosting adapter.

The acceptance gate also runs app_runtime_load, a no-live-call runtime loader check. It writes the assembled file map to a temporary app/ root and calls AppLoader.load(). Export and promotion are blocked when the app manifest, module contracts, companion manifests, handler entrypoints, runtime extension contracts, data/subscription config, or app-level services.* imports cannot load. The check persists app_runtime_load_passed and app_runtime_load_result into workflow context and includes app_runtime_load in app_bundle_acceptance_result.validation_evidence.

7. AppValidation Strategy¶

AppValidationAgent must use an explicit validation strategy contract instead of implicit E2B-only behavior.

Canonical strategy values:

• e2b
• docker
• local
• skip

Canonical status values:

• passed
• failed
• skipped

Rules:

• Studio/hosted environments may prefer e2b when sandbox credentials are available.
• Local environments with a running Docker daemon resolve to docker, which also exposes a preview URL (see app-validation-sandboxes.md).
• CLI/local environments may resolve to local or explicit skip.
• generation/export must not be blocked solely because E2B is unavailable.
• skip is explicit and deterministic; it is not a hidden fallback and it is not reported as passed.
• export gating must allow only passed or explicit skipped, and still requires integration readiness and wiring checks to pass.

Materialization rule:

• typed agent outputs such as app_backend_admin_config, python_files, and js_files are the source of truth for their owned lanes
• the same applies to database_files, model_files, and service_foundation_bundle.files
• extraction may regenerate canonical file content from those typed fields before packaging
• raw code_files are the serialized mirror, not the authority, when a typed lane exists

Bundle Rules¶

Do:

• keep persistent pages declarative
• keep shell content separate from shell styling
• reuse ThemeCapture output when available
• deep-merge generated theme/shell patches into canonical runtime files

Do not:

• generate raw React files for persistent pages by default
• generate any AppGenerator-managed raw React page/component files for persistent pages
• place header/footer action content in theme_config.json
• place spacing/padding/density tokens in shell.json
• place reusable media inventory in theme_config.json or shell.json
• route visual shell concerns through AgentGenerator

Why This Exists¶

Without this split, AppGenerator either under-specifies visual/media control or mixes styling, shell behavior, and asset inventory. The contract above keeps bundle generation deterministic, keeps ThemeCapture reusable, and gives the runtime a stable set of artifacts to consume.