Presentation runtime

Status: implemented as an operator-local source candidate: four read-only operations (presentation.catalog.show, presentation.workspace-directory.show, presentation.project-list.show, presentation.session-list.show; catalog maia.presentation.portfolio/v3). Desktop rendered them with @json-render/react-native 0.20.0 until 70dcc02f moved it to authored pages; today no client renders them, and the CLI's presentation reads print the specifications. The terminal dashboard writes its own views until R9a (decision). Planned: R9a (full json-render migration and isolated client engines; PF/DF-27, PF/DF-28) and R10a/R10b (Jev evaluation and adaptive consumers). No Jev integration, isolation or performance result exists yet.

This is the R9a specification. Reasons for json-render and Jev: decision. The current catalog contract is in the protocol presentation README.

Scope

Full migration means one json-render catalog and rendering path for all product-view composition: shell, navigation, settings, conversation content, cards, forms and inspectors. No parallel legacy dashboard. It does not mean AI generates views or owns platform behavior:

• Authored catalog components implement connection and target indicators, trusted confirmations, receipts and accessibility. Trusted composition, never model props, controls their sensitive inputs and placement.
• Canvas, terminal, audio and other specialized engines stay authored components behind the catalog. Do not rewrite them as JSON elements or create a component per graph entity or output chunk.
• Platform bootstrap, native permission ceremonies and a minimal renderer-crash recovery boundary may stay outside json-render. Record each exception in the migration inventory. The public site is out of scope.
• Local deterministic specifications keep navigation, manual controls and trusted chrome working when Jev or remote composition fails. Offline cached data is visibly stale; offline UI invents no mutation capability.

Ownership: one personal Maia coordinator belongs to the authenticated user within one exact Control Node. Desktop and mobile are replaceable clients, not brains or backends. The user-level home Session (R3) survives reconnects; idle needs no running model. Independent Control Nodes are not federated. Session owners and coordinator visibility follow Session ownership and coordinator isolation.

Apps and authority

Node returns a versioned, json-render-compatible specification through public SDK operations: data, never React code or a remote module. Node owns the contract and authorized source data; its critical process need not run expensive presentation or model work. Registered client components render the specification through client-core Effect services.

flowchart TB
    User["User"]
    Desktop["Desktop UI engine"]
    Mobile["Mobile UI engine"]
    Core["Effect client-core and public SDK"]
    Node["Independent Maia Node authority"]
    Maia["User-level Maia Session and activation"]
    Workers["Supervised execution workers"]
    Present["Bounded presentation worker and Jev adapter"]
    Catalog["Versioned approved component catalog"]

    User --> Desktop
    User --> Mobile
    Desktop <-->|"specifications, data, explicit actions"| Core
    Mobile <-->|"specifications, data, explicit actions"| Core
    Core <--> Node
    Node --> Maia
    Node --> Workers
    Node --> Present
    Catalog --> Present
    Catalog --> Desktop
    Catalog --> Mobile

Clients share code and contracts, not one mutable client-core instance. Each client owns its Effect scopes, projection, drafts, focus, media and cursor. No client reads Node storage or connects to worker or provider pipes. Voice-provider media stays a separately admitted platform transport.

One contract, separate client views

Use one protocol and component vocabulary with independently bound view instances: not one mutable JSON document broadcast to all clients, and not a new schema per viewport.

• A view binds the authenticated user/device/client, Node identity and epoch, Session when applicable, exact owner and target set, view/request identity, catalog version and digest, authorization-policy revision and selection generation. Exact fields and limits live in the protocol contract.
• Client-declared capabilities can narrow presentation choices, never widen grants.
• Responsive layout is local: WorkerComparison can be side by side on Desktop and stacked on mobile. Node uses a capability profile only when a component genuinely differs.
• Opening an inspector on one client never navigates another. Focus and playback are not synchronized across devices. Voice references such as "this worker" bind to the originating view's exact target and generation.
• Reuse templates and safe results instead of one coordinator or Jev call per connection. A cached result needs an authorization-safe key: Node and epoch, exact principal and audience, owner visibility, policy revision, source revisions, normalized request/rubric and catalog digest. Never share across users or owners because prompts match. Policy changes invalidate in-flight results and caches.
• Detaching a subscriber cancels only its delivery; shared work continues while another admitted consumer needs it, within its original deadline and budget. Coalescing is not mutation deduplication or authority to retry an uncertain provider effect.

Voice-led experience

Text stays the default and complete fallback; capture starts only on explicit activation. Voice adds no extra history or hidden global-coordinator hop. The acceptance journey:

1. "What needs attention in Studio?" shows capture/transcript status, then an honest acknowledgement while authorized reads run.
2. Node facts fill bounded attention cards. Spoken summaries cite the same coverage and revisions; unknown usage or unseen work stays unknown.
3. "Compare those workers" selects an eligible comparison. Ambiguous references ask; exact targets need no model evaluation.
4. "Open the reviewer" updates only the originating view after exact resolution. Partial speech may show provisional hints but never repeatedly steals focus.
5. "Stop that worker" proposes an admitted operation on the exact incarnation. Only the trusted confirmation path approves it.

A pin, newer user action, changed target, policy revocation or edited draft invalidates incompatible delayed results. Ranking never hides mandatory failures, confirmations or unknown outcomes. Stop speech, stop capture, interrupt a turn and cancel a worker stay distinct operations. Playback is local to the initiating client unless explicitly shared.

Client focus graphs and input binding

Each Desktop or mobile client keeps an ephemeral typed focus graph: open views and panels, selected resource IDs, active conversation, pins, recent navigation, foreground/presence signals and notification preferences. Several views and devices are normal; there is no global focus. Client-core Effect services own the signals. Graph nodes and edges describe local UI context, not ownership or execution dependencies. Never capture raw drafts, audio, clipboard, keystrokes or screen content as background context.

• Submit a bounded focus snapshot with input, or a coalesced meaningful context update, through the public SDK. Bind the authenticated client/device, view/conversation identity, selection generation, source revisions, observed age and expiry.
• Node validates fields, size, rate, TTL and source access before use or export. Client signals are untrusted hints, never proof of grants, attention or read acknowledgement. A broad human snapshot is filtered to the receiving coordinator's scope before evaluation.
• Missing or stale context leads to exact-target handling or clarification, never a scope-broadening guess. Retention is ephemeral; focus creates no browsing-history or transcript store.
• Freeze the input snapshot so a later focus change cannot retarget queued work or a confirmation. New focus affects only future feedback after revalidation and never moves another client's selection or draft. Node keeps the original request and view lineage after the originating client closes.
• Swarm decides whether to show, group, defer or speak. Client adapters enforce local consent, accessibility and originating-device policy. Closing a client stops its media, not Node work.

Jev and deterministic composition

Use the Node semantic evaluation owner, not a renderer-owned model backend. The coordinator handles open-ended reasoning; Jev supplies bounded Choice, Score and Boolean judgments to select supplied targets, view variants or evidence. Jev never writes React or CSS, generates layouts, grants permissions or establishes truth.

• Code filters candidates by authorization before evaluation and assembles approved component IDs, safe options and exact resource references.
• Reuse unchanged judgments; never call per render, connection, audio chunk or resource event. Include no-match, clarification, uncertainty and typed failure paths. Confidence is not correctness or permission.
• Freeze export consent, deadlines, cumulative spend and cancellation and unknown-outcome policy before live use.
• LLM and Jev are required only for the matching automated mode, never for basic rendering, manual operations, authoritative updates, trusted confirmation or tracking admitted workers. On failure, show AI unavailability and keep deterministic manual views. A slow optional job never blocks execution or receipts.

The end-to-end flow owns routing, execution and feedback; presentation is one consumer.

Specifications, data and actions are separate

• A WorkerCard references an exact worker and reads its status from the Node projection; a model cannot supply authoritative completed data. Patches and renderer $state writes never alter that projection, trusted confirmation fields, SDK credentials or mutation targets. Model-authored explanation renders as advisory content, apart from authoritative labels.
• The catalog admits no arbitrary URLs, dynamic code or modules, raw SDK method strings, on-mount effects or unsanitized HTML. Rendering never executes a mutation. Allowed actions are finite, mechanically mapped to the registry and authenticated when invoked.
• Patches use a finite, versioned, allowlisted subset of upstream SpecStream/JSON Patch. Validate incremental and final structure, references, paths, nesting, bytes, component count, props and sequence before visible commit. Freeze base revision, per-view sequence and reset semantics. Invalid, reordered, duplicate, stale, cancelled or truncated streams never partly activate controls, mutate data or destroy a retained safe view. Unknown catalogs fail closed to a deterministic fallback or explicit unavailability.
• Data changes update bound components without regenerating layout. The resource graph (authorized read projection), the orchestration task graph (input to createOrchestrationRun) and the client scene (geometry) are not interchangeable.

View-to-SDK and input-output inventory

C means an SDK symbol exists in source, not Desktop/mobile exposure or release qualification. P means a planned contract; missing operation names stay TBD. Inputs and outputs are summaries, not schemas. Before marking a view migrated, resolve each row to protocol schemas, risk/exposure, SDK binding, platform admission and tests.

Organizational Workspaces use container.* and containerId; workspace.* and workspaceId stay execution contracts until R1b. Never reinterpret either namespace in the UI.

Every mutation view reuses its owning operation: container/Project create and rename use their preview/confirm bindings; Session lifecycle and turns use their admitted methods; terminal control, execution relocation, Agent permission and future worker, routine, knowledge and integration actions keep their own authority and reconciliation contracts. A nearby method never substitutes for a missing operation. No generic updateGraph or executeAction backend.

Transport and snapshot compatibility

• Operations use authenticated POST /api/v1/operations with the envelope protocolVersion, kind: request, messageId and payload: { method, parameters }; the correlated response holds ok/result or a structured error. SDK methods return validated typed results; views never parse envelopes. Post-dispatch uncertainty is not proof of failure.
• observe.events at /api/v1/observations streams bounded frames: aggregate revision snapshots, transition metadata, heartbeat, gap, reset, error and summary. The Node-side SDK adapter is subscribeNodeApiObservations; Desktop relays the stream through the native observation_subscribe command only to refresh the Session list. It is not rich chat content or the resource graph, and mobile has no transport for it.
• The target aggregate API is P client.observations.snapshot/subscribe/session/pipeline (SDK reference). Freeze the remaining presentation operations and bindings; never reuse observation frames as unversioned UI patches.
• Planned projections: Workspace, Project, Session, Worker, Task, Execution Environment, Execution Node and Execution Profile snapshots, tool, context and configuration manifests, and GraphSnapshot. They keep typed owner identities, bounded pages, revisions, freshness, coverage, redaction and source watermarks.

Failure isolation and independent lifetime

Node is an independent supervised service, not a child of an app window. Closing or updating a client releases its own media, reads and subscriptions, never admitted tasks, coordinator activations or workers. Reopening reads history and reconciles original receipts; it never redispatches work. Worker leases belong to Node and the execution supervisor, not to UI presence. A pending confirmation may expire; it never auto-approves on disconnect.

Renderer failures affect only that client or view; an outer recovery control still reports them. Expensive server-side specification work and evaluation run as bounded supervised presentation work outside Node's critical process when process isolation is claimed, reusing existing Node worker and Effect service boundaries. Catching a Promise rejection or using a fiber is not process isolation.

Separate processes do not promise immunity to shared CPU, memory, network or host failure.

Multi-client admission and performance contract

The requirement is no cross-client correctness coupling and bounded, measured performance isolation, not zero shared-resource contention. One bounded aggregate subscription per client and Node context; device count never changes worker or provider emission.

• Node enforces finite per-view, per-client, per-principal and global quotas for connections, reads, queued bytes and records, specification elements and patches, graph expansion, model calls, CPU work and concurrent presentation jobs. Extra connections never evade a principal's budget. Freeze numeric limits before implementation and test limit-plus-one.
• Healthy clients get fair bounded service. Control, receipt and lease handling are reserved separately from optional presentation work. No unbounded broadcast await, global view lock or renderer acknowledgement in the worker path.
• A stalled consumer exhausts only its own queue, receives typed saturation/gap/reset and is disconnected when necessary. Coalescing never drops required authoritative transitions.
• Cap composition and evaluation cost and aggregate memory. Cancel stale queued work, bound cache entries and TTL, reclaim disconnected view state, enforce deadlines on follow-ups and reset storms, and never retry uncertain paid effects.
• Rendering uses client-local frame coalescing and bounded queues. Another client's viewport changes never trigger this client's layout or fetch.

Qualification targets (DF-28), not results:

• 1, 2 and at least 8 simultaneously admitted clients per declared host profile, plus 2x the frozen admission ceiling as overload attempts, with the DF-20 workload identical in paired baseline and noisy-neighbor runs. A profile that cannot admit the minimum stays blocked.
• Healthy-client observation-to-visible p95 stays under 250 ms (Desktop) and 500 ms (mobile); focus under 100 ms and 150 ms. p95 for healthy reads, committed observations and worker dispatch/receipt handling rises at most 10% over the matched baseline.
• At least five paired runs with frozen hardware, build, seed, offered rates, warm-up, samples and duration; keep distributions and absolute values. One offending client stalls, floods, reconnects, sends oversized specifications or repeats evaluation requests while healthy traffic stays constant. Correctness, zero unauthorized effects and bounded memory are exact assertions.
• If a budget fails, reduce work or improve admission; never weaken bounds during a run. Real hardware, provider and audio measurements need separate permission.

Dependency and delivery gates

• Pinned today: @json-render/react-native 0.20.0 in apps/client for the three mounted lists. Any further package needs reviewed versions, integrity, licenses, provenance, transitive closure, platform compatibility and rollback before installation.
• Upstream catalog examples use Zod. Generate or qualify the catalog boundary from Maia's Effect schemas; never hand-maintain duplicate validators or weaken strict object, byte or proof checks. If that is impossible, report the gate and get approval first.
• Use json-render's compile and render capabilities behind Effect. Its example useUIStream loop and /api/generate server must not become an application HTTP backend, model client or lifecycle owner. Catalog metadata is presentation vocabulary only; protocol stays authoritative for operations, risk, errors and exposure. No speculative UI package, plugin loader or workflow framework.
• Delivery follows R9a: protocol -> SDK -> Node -> headless contract fixtures -> product projections; business operations finish their CLI-first slice first. R10a supplies Jev evaluation and R10b the adaptive consumers. Deterministic migration need not wait for live Jev. PF/DF-27 close the view inventory; PF/DF-28 close isolation and performance.