# ADR-0006: Session-scoped deterministic conversation

**Status:** Accepted

**Date:** 2026-07-11

## Context

Known application workflows must execute without model interpretation, while unresolved input must retain the complete AgentsKit chat lifecycle. Conversation progress cannot live on a shared `ChatDefinition`, because the same definition may mount in multiple users, renderers, or tests.

## Decision

`createChatSession(definition)` creates a fresh application session and derives an upstream `ChatConfig` by wrapping only its `AdapterFactory`.

Routes are evaluated in declaration order. A route is eligible only when its state restriction matches and its event is a declared transition from the current state. A match emits an upstream-compatible deterministic `StreamSource`, commits the declared transition, and records its turn classification. A miss delegates the unchanged request to the original adapter and records an `agentic` turn.

Conversation state, allowed events, and allowed actions are projected from the active state. The trace taxonomy is `deterministic`, `agentic`, `repaired`, and `fallback`; traces contain decision metadata, never prompt content.

Deterministic decisions are cached by user-message identity and input. Retry and regenerate replay the same decision without model dispatch; a subsequent dispatch rebuilds conversation state from the retained user-message history before resolving an edited turn and prunes removed decisions. History mutations that do not dispatch a turn do not themselves transition the application machine. Route callback failures return an upstream error stream without committing a transition. Trace observers are best-effort and cannot affect dispatch.

Every renderer compiles one session-scoped config per definition mount and continues to use its official AgentsKit binding.

## Alternatives considered

1. A second chat controller — rejected because AgentsKit owns lifecycle, streaming, tools, memory, and cancellation.
2. Route matching inside each renderer — rejected because behavior would drift across platforms.
3. Mutable state on `ChatDefinition` — rejected because concurrent mounts would share conversation progress.
4. A general statechart dependency — rejected because explicit transition records satisfy the current finite workflow without another runtime.

## Consequences

- Known commands bypass model dispatch without bypassing the upstream controller.
- Each mount receives isolated conversation progress.
- Retry and regenerate remain deterministic; edited/truncated history is reconciled on its next dispatch.
- Same-id `ChatConfig` updates reach the upstream binding without resetting conversation progress.
- Route handlers cannot choose arbitrary target states; the machine owns transitions.
- Persistence, async routing, protocol transport, and action execution remain separate future concerns.