Status#
Proposed successor to approved ADR-0083, document 9b0e549a-6453-834e-a597-a15b969cf738 revision 4, prepared 2026-10-09. Independent approval is required before implementation admission. The original v1 confirmation contract remains supported. Family: eve-interactive-artifacts.
Context#
The current UI registry admits one deterministic confirmation candidate inside an authoritative action_confirm event. It deliberately grants no executable markup, component imports or action authority. The new product requires progressively rendered visual answers, persistent data-bound dashboards, deterministic scenarios and editable motion. Existing task 8.15 owns the artifact workspace; DS01 owns the scoped admin/BFF design content path; existing design and connector tasks retain their responsibilities.
Decision 1: a typed UI specification compiled into trusted renderers#
Introduce a capability-negotiated successor schema composed from allowlisted data and visual nodes. The server and client validate exact shapes, stable IDs, bounded text/tree size, versioned props, binding types and permitted events. The model supplies a declarative specification and names authorized result handles; it never supplies React imports, arbitrary JavaScript, HTML, URLs or execution privileges to the trusted component layer. Keep v1 confirmation behavior unchanged.
Compile validated complete nodes and patches incrementally using existing SSE turn infrastructure. Bind each operation to session, turn, artifact and monotonically versioned state. Define replay, reconnect, invalid partial state, cancellation and finalization explicitly. Retain useful accepted content when later generation fails and label the result partial. A fallback does not silently count as a fully generated interface.
Use existing design tokens and a small component library. Choose text when no interaction materially helps. Native clients use the same semantic contract with supported native renderers or accessible fallbacks, not a hidden raw-web-code escape hatch.
Decision 2: retain canonical content and action authority#
Canonical saved operator dashboard, scenario and motion specifications are reviewed extensions of the existing design-format model, stored as Eve document revisions through the scoped DS01 BFF path. Session artifacts and conversation history store references/accepted transient state; they are not a second source of truth for saved workspace content. Snapshot rows and binary outputs are operational/media records referenced by the canonical artifact. ART.01 depends on DS01.1, DS01.2, DS01.5 and DS01.8.
Design-only credentials may save admitted design drafts only. This decision does not grant broader content kinds, submit, approve, publish or key issuance. PRDs/ADRs/architecture stay under existing proposal and approval rules. Any schema or permission admission needed for these subtypes is reviewed and tested explicitly. Reuse the existing one-shot confirmation bridge for writes; an interactive control cannot derive authority from displayed data.
Decision 3: separate editable specifications from immutable observations#
Every saved artifact has identity, owner/scope, schema version, origin and immutable specification revisions. Each data observation records query identifier/version, parameters, permission scope, source IDs/revisions, measured time, result hash and warnings. Each calculation records formula version, units, assumptions and input snapshot. Each export records artifact revision, source snapshot, asset hashes, design-system pin, renderer version and output hash.
Refresh creates a new observation and advances a latest-success pointer atomically; it does not overwrite an earlier observation or rewrite the spec. Render/export jobs use an explicit frozen snapshot. Concurrent edits use optimistic revision checks and the existing disjoint-patch rebase contract, with conflicts exposed rather than last-write-wins.
Decision 4: named authorized queries and a governed connector adapter#
The model chooses only registered metric/query plans with typed parameters. The BFF resolves and authorizes the plan, applies row/resource limits and timeouts, executes through authoritative Eve APIs or a justified dedicated read model, and attaches provenance. No unrestricted model-authored SQL is admitted against the live Eve board. Heavy analytics use a copy/read model, not board locks. Direct permitted diagnostics remain READ ONLY with a statement_timeout and named application identity.
Metric definitions explicitly encode units, filters, denominators, time zone, missing values and historical availability. Cache keys include effective permission scope, query version and normalized parameters. Scheduled refresh uses an approved job identity and reauthorizes every execution; revocation cancels or refuses future work. Sources fail independently with honest partial/stale state.
External data enters through the existing operator connector registry, not a second credential store. Begin with actual authorized OpenRouter usage fields. Never promote an unsupported provider breakdown into a metric. CSV/JSON sources have bounded parsing, explicit schema and content hash. Imported/source text is untrusted data, never instructions.
Decision 5: deterministic controls and calculations#
Filters, selection and display operations remain local when possible. Named server interactions are versioned and authorized. Scenario evaluation uses a bounded deterministic registry, with no arbitrary code execution requirement and no model call for each slider movement. The separate existing sandboxed-code task 17.25 remains responsible for general code execution and is not bypassed here.
Decision 6: editable motion and isolated rendering#
Motion is a structured timeline of scenes containing text, shapes, charts and authorized assets with exact frame/time semantics. Reuse presentation/design identities through adapters. Preview and export share a deterministic rendering implementation. Narrative text and charts retain claim/source references. Captions and a transcript are editable; narration is optional and separately governed.
MOTION.01 selects and pins the renderer only after a real preview/MP4 spike, fidelity/resource measurement and license review. Remotion is a candidate, not an adopted dependency or an authorization to purchase. Queue exports to an isolated self-hosted worker with duration, resolution, concurrency, CPU/memory and filesystem limits; network access is disabled except explicitly approved source staging outside the render sandbox. Jobs are idempotent, cancelable, recoverable and delivered through the existing operation/conversation runtime.
Decision 7: preserve the decided workspace scope#
Admin studio authoring remains in apps/oshun/admin through BFF APIs; Eve content owns canonical documents. Customer and mobile rendering reuse semantics under their own authorization. Collaboration is Elikem plus agent lanes, with origin attribution and comments. DS07.2's rejected public links remain rejected. Exports are authenticated downloads. Publication, UAT promotion, privileged keys and spending remain Elikem's acts under existing policy.
Admission and migration#
GOV.01 must record approved document revisions/hashes and ratified budgets. GOV.02 reconciles reused prerequisite contracts and their real edges before work proceeds. Changes must include contract/persistence/API tests, touched-project typechecking and actual browser/native verification proportionate to the touched flow. Version migration must preserve old conversations and v1 action confirmation. Roll out behind capability flags with explicit availability, stage Dev through normal release gates and retain rollback.
Unknown components, hostile markup, cross-session replay, stale revisions, unauthorized source handles, connector injection, cache leakage, post-revocation downloads, cancellation races, resource exhaustion and malformed render outputs are hard failure/fallback tests. Model evaluation measures usefulness and format choice against text, separately from deterministic correctness. The author does not approve its own work.
Alternatives and consequences#
Unrestricted generated HTML/JS would increase flexibility but also expand execution, compatibility and review scope; the typed library covers the approved first feature set. A separate dashboard/BI service would duplicate content and authorization; use bounded adapters and add a read model only when measurements require it. A generative-video workflow would make exact text, numbers and timing difficult to revise; deterministic motion fits this feature. A multi-human collaboration system conflicts with current operator decisions; retain existing human-agent semantics.
The approach depends on real completion of 8.15 and the selected DS01/DS07/DS08/DS12/DS13 and connector tasks. Their open/later states are not existing capabilities. New models, more connectors and richer animation can be admitted later without weakening the source, execution and permission contracts.