ADR-007: AI Design Living Form V2 authority

Status

Accepted / implemented, amended 2026-09-16

Amended on 2026-09-07 to define operation-scoped public activity as transient presentation state beneath the matching optimistic user message.

Amended on 2026-09-16 to prepare a coherent video draft before quotation and expose an explicit starting-image binding with capability-driven controls.

Date

2026-08-30

Last amended: 2026-09-16

Context

ADR-001 modeled a Workspace as multiple independently selected Conversations, each with its own Brief, mutable Quote, and persistent Session. That split made chat, form edits, Quote options, and provider prompts competing representations of the same design. The coordinated Works Square and MakeLore V2 cutover now provides one versioned Design Specification and a persistent form throughout the design flow.

The September 7 Canvas presentation refinement keeps that authority model while making the current production plan easier to edit: conversation and the sole active plan stay together, Workspace navigation moves to a right Works rail, and references are expressed through public Prompt aliases bound to canonical Assets.

Decision

One Workspace exposes one current Direction, one persistent Agent Session, one Current Design Specification, one Living Form projection, one conversation timeline, immutable Quotes, Tasks, and Assets.
Chat, direct field edits, decision responses, accepted proposals, lock changes, Asset binding, and restore actions enter the same server-owned reducer. Renderer drafts are temporary buffers and never semantic authority.
Every mutation carries stable command and semantic operation identities. An unknown transport result keeps the same command for replay; revision conflicts refresh canonical state without discarding local drafts.
While a chat operation is pending, Electron Main may normalize the server's closed design.assistant.progress lifecycle into fixed youth-safe stages, and Renderer may show one transient activity panel beneath the matching optimistic user message. Activity is not a canonical Turn, Current Specification state, assistant content, or evidence that a change committed. Model chain-of-thought, prompts, Provider responses, tool arguments, and unvalidated model text are never rendered.
Generation is a compile-and-confirm boundary. The server returns an immutable Quote for one exact Specification revision; the client displays the public output plan, warnings, expiry, and Token Point amount and confirms only the Quote ID. Provider prompts, models, routing, storage, safety evidence, and billing atoms stay server-private.
Before requesting a Quote, the client applies prepare_generation through the same Main-owned input contract and uses the returned current revision. Preparation never fabricates a chat Turn or confirms paid generation. A definitive preparation failure stops quotation even when a live blocker event was missed; transport-unknown recovery keeps the original operation identity.
Media availability, ratios, duration and output limits come from the server's per-medium generation_options, not invented client defaults. The selected supported duration must be saved, not merely displayed. Semantic video motion is arranged by the server Reasoner and the returned creator prompt becomes visible.
Electron Main is the only Canvas network authority. Development and packaged builds use the Works Square V2 contract; there is no V1 DTO adapter, local semantic adapter, mutable Quote PATCH, editable provider Prompt, or cloud-failure fallback.
The visible Canvas has two regions: a flexible central conversation timeline with the only active editable production plan, and a full-height right Works rail for Workspace navigation. Compact layouts expose that rail as a right Sheet. Terminal submitted plans collapse into conversation history; they do not create a second current-plan authority.
The public content.concept projection is the directly editable final Prompt. References retain stable reference IDs and typed Workspace Asset bindings while appearing in that Prompt as continuous @图片N aliases. The Prompt is the only visible expression of creative reference intent; the adjacent row manages binding/file state and explicitly selects the video starting image. That selection binds both first_frame role and Asset identity, independently of an alias token. Unsupported retained references remain visible until the user explicitly changes or unbinds them; their Assets are never silently deleted. An unbound referenced alias blocks Quote availability and exposes a targeted upload slot.
Prompt, reference binding, type, aspect-ratio, duration, or output-count changes enter the existing typed reducer and create a new Specification revision. An offered plan must be recompiled to a fresh immutable Quote before confirmation. Reference count/media limits come from service capabilities, not client-only constants.

Rationale

The Living Form makes the current Specification the sole rebuild and generation authority while keeping conversational continuity visible. One reducer removes client/server drift, and immutable Quotes plus stable operation IDs make confirmation and uncertain retries auditable without exposing provider internals.

Consequences

Client and server V2 must move together after the stopped deployment passes the server cutover dry-run/apply/validate gate.
Existing V1 data remains historical evidence and frozen execution recovery input; old clients and V1 semantic writers receive no compatibility window.
Production database cutover, paid Provider activation, and real-account installed client smoke remain separate operator gates.
Replayed activity and generic terminal Gateway events reconcile by the original operation identity. They do not create another message, form, or retry intent.
Layout and reference aliases are public projections, not new semantic authorities. Any future UI must preserve one active plan, stable Asset identity, and the exact Specification-revision/Quote boundary even if its visual arrangement changes.

Supersedes

ADR-001: AI 绘画 Workspace / Conversation 状态归属.

Video preparation source 1acca836fe035dd462110cdc7683645c1e031f54, task 20260916-design-media-client-a7d3e9c1, integrated by 20260916-merge-design-video-client-4f6d28a1 with matching server 1a3df8df08033adb2bec8d268ca2c18e7b785e1e.
Client source b0b5a602b501308a23eb27e2f51a5169b9e46b1e
Server source b5351d54f595ce8eb873593e462e4a556bea0b05
Server ADR ADR-2026-08-28-001
Canvas refinement source 1562a49
Canvas refinement integration merge ea1219c
Source task 20260906-canvas-reference-images-c4e97a

6.7 KiB Raw Blame History