Architecture

Distribution ownership

The coding distribution contains two independently generated Spice application targets:

spice-agentd @Application             spice-agent @Application
        |                                      |
        v                                      v
inspectable generated daemon          inspectable generated TUI/launcher
        |                                      |
        |-- authenticated local IPC            |-- explicit attach
        |-- engine and run lifecycle            |-- managed attach-or-start
        |-- configuration and policy            |-- terminal lifecycle
        `-- graceful shutdown                   `-- owned-child cleanup

spice-agentd supports explicit serve. spice-agent supports explicit attach; its default managed mode attaches to a compatible daemon or starts one. An attached daemon remains externally owned. A daemon started by managed mode is a supported process whose lease and cleanup belong to that launcher instance. Each target independently owns dependency construction, configuration, cancellation, observability, rollback, and cleanup for its boundary.

internal/distribution owns composition and packaging. internal/daemon will adapt the separately versioned host contract. internal/terminal will compose the separately versioned TUI client.

Explicit serve and attach are supported lifecycle modes. Internal packages are not alternative entrypoints, and neither generated target may bypass the other target’s protocol boundary. The security phrase “bare user-process privileges” applies to coding tools: they execute with the selected user process’s authority and are not sandboxed. It does not describe or prohibit the daemon process topology.

internal/daemoncommand and internal/terminalcommand freeze the transport-neutral CLI boundary ahead of those generated targets. They parse only the documented grammar into immutable values and invoke injected runners with caller-owned contexts. They do not import daemon, client, gRPC, IPC, or generated packages. Detailed runner errors, raw arguments, and endpoint values are never reflected through the public command diagnostics. See the command seam.

internal/architectureproof is a real generated application used to freeze the SDK composition boundary before daemon and terminal commands are added. It proves a normal provider replacing a fallback provider, three explicit auto-configured coding-tool beans, a canonical map[string]tool.Tool, reverse cleanup, and the provider → tool → provider continuation loop. The graph also constructs the dispatcher, source-guaranteed static stage.ToolPlanSource, explicit unavailable interaction broker, execution-plan metadata, and engine as ordinary inspectable beans. The metadata records every executable provider, kernel/dispatch stage, broker, and static tool with its selected module version; there are no observer or dispatcher-decorator beans in this proof. A semantic snapshot compatibility identity is explicit and stable across machines, while the kernel combines it with the exact leased tool generation and definition fingerprints for each run. Generated code lives only under internal/spicegen/architectureproof; the ownership manifest and source mappings live in .spice/architectureproof.manifest.json.

Compatibility

compatibility.json records Go 1.26.5 plus the exact immutable Spice, toolchain, Agent, OpenAI provider, and coding-tools selections exercised by the architecture proof. The TUI remains explicitly null until the terminal target adopts it. Replacing any selection requires executable compatibility tests.