rdbms-playground/docs/adr/0037-execution-time-mode-side-channel.md

# ADR-0037: Execution-time mode side-channel (the three-way submission mode)

## Status

Proposed (design agreed with the user 2026-05-27; pending `/runda` +
implementation). Redeems the follow-up **deferred by ADR-0033
Amendment 3**, which named this very ADR and its motivating consumer.

## Context

ADR-0033 Amendment 3 ("Execution-time mode is side-channel — deferred
to its own ADR") recorded a requirement and deferred it:

> every command should — at **execution time** — know which of three
> modes it ran under: `simple`, `advanced`, or `advanced-one-shot`
> (the `:` escape from Simple mode, ADR-0003), so execution can adjust
> **output** without changing **identity** (e.g. a Simple-mode
> `create table` echoing the generated SQL when run in Advanced mode,
> while staying silent in Simple mode).

That echo is the **DSL → SQL teaching bridge** (ADR-0030 §10), specified
as its own Phase-5 ADR (ADR-0038). ADR-0038 is the motivating — and, at
time of writing, only — consumer of this side-channel. This ADR
establishes the channel; ADR-0038 consumes it.

### What exists today

- The persistent input mode `Mode` (`src/mode.rs`) is **two-way**:
  `Simple` / `Advanced`. Its doc comment is explicit that the one-shot
  `:` escape "is handled at submission time in `app::App::submit`, **not
  as additional state here**."
- The one-shot `:` is therefore a **transient, per-submission**
  property, collapsed to an effective mode at submit time. It is not
  persistent state and was deliberately kept out of `Mode`.
- The only mode information that survives past submission is a
  **rendering** side-channel: `OutputLine.mode_at_submission: Mode`
  (the `[simple]`/`[advanced]` echo-line tag in `ui.rs`). It is two-way
  and exists purely to label the input-echo line.
- Neither `Action::ExecuteDsl` nor the database worker
  (ADR-0010) carries any mode. Execution is mode-agnostic.

### Why the gap blocks the echo

The teaching echo (ADR-0038) renders the equivalent SQL **beneath the
`[ok]` summary**. That summary is built in the App's outcome handler
(`App::update`, the `Dsl*Succeeded` arms) from the **worker's result
event** — not at dispatch time. At that point:

- The typed `Command` is available (the success events already carry it).
- The submission mode is **not** available. `self.mode` is the *current*
  persistent mode, which is unreliable for this purpose: it can change
  between submission and outcome, and for a `:` one-shot it never
  reflected the effective mode of that single line at all.

So the echo needs the **effective submission mode delivered to
execution/outcome**. And several echo forms (ADR-0038 — auto-resolved
index / relationship names, generated `shortid` values, lossy-conversion
counts) are only knowable **after the worker has run**, so the echo's
data is fundamentally worker-produced. The natural place to gate and
build mode-dependent output is therefore the execution path, with the
mode threaded to it — exactly the side-channel Amendment 3 anticipated.

## Decision

Introduce a **three-way effective submission mode**, computed at submit
time and threaded through the `Action` → worker interface, available at
**execution time** to adjust **output only**. Command identity, dispatch,
and execution semantics are **unchanged** (ADR-0033 Amendment 3: identity
is intrinsic to the mode-rooted grammar path, not a flag).

### 1. A new per-submission enum, distinct from persistent `Mode`

```rust
/// The effective mode of a single submitted line, resolved at submit
/// time. Distinct from the persistent input `Mode` (which stays
/// two-way) because the one-shot `:` escape is a transient per-line
/// property, never persistent state (ADR-0003; `mode.rs`).
pub enum SubmissionMode {
    Simple,
    Advanced,
    AdvancedOneShot,
}
```

**This refines Amendment 3's framing.** Amendment 3 sketched "widening
`Mode` to the three-way distinction." On implementation review, a
**separate enum** is cleaner: `Mode` models *persistent input state*,
and `mode.rs` deliberately keeps the one-shot out of it. Folding a
transient `AdvancedOneShot` into the persistent `Mode` would contradict
that design note and let a non-persistable value leak into persistent-
mode call sites. `SubmissionMode` carries the three-way distinction on
the per-submission channel where it belongs; `Mode` stays two-way and
untouched. The *requirement* Amendment 3 recorded is met; only the
**shape** is refined. (Flagged for `/runda`/user challenge — it is an
internal architecture choice with no user-facing effect.)

The effective mode is resolved at submit time from the persistent
`Mode` plus whether the `:` sigil was used:

- persistent `Simple`, no `:` → `Simple`
- persistent `Simple`, `:` prefix → `AdvancedOneShot`
- persistent `Advanced` → `Advanced` (the `:` is a no-op there)

### 2. Threaded through `Action::ExecuteDsl` to the worker

`Action::ExecuteDsl` gains a `submission_mode: SubmissionMode` field;
the worker request mirrors it. Execution thus knows, per command, the
effective mode it ran under. The value is **output-only**: no executor
branches its *effect* on it (that would be a behavioural mode dependency,
which ADR-0033 Amendment 3 forbids — identity and effect are intrinsic).

### 3. The worker produces mode-dependent output; the App renders it

For the first consumer (ADR-0038): when the command is a **DSL-form**
command (`Command::CreateTable`/`Insert`/… — *not* the `Sql*` variants)
and `submission_mode` is `Advanced` or `AdvancedOneShot`, the worker
builds the teaching echo (equivalent SQL + any category-3 expansion
data — ADR-0038) and returns it on the result event. In `Simple` mode,
or for a command typed as SQL, no echo is produced. The App renders the
returned echo as de-emphasised `OutputLine`(s) beneath `[ok]`.

Co-locating echo construction with execution is deliberate: the echo's
harder forms (resolved auto-names, generated `shortid`s, conversion
counts) are facts the worker already computes. Gating on the threaded
mode means the work happens **only when an echo will be shown**.

**Non-interactive re-execution does not echo.** `replay` (ADR-0034)
re-runs recorded commands through the dispatch pipeline in advanced mode
(ADR-0033 Amendment 3) — but a per-line teaching echo there would bury
the replay summary in noise. So replayed lines (and any future
programmatic re-execution) dispatch with a `SubmissionMode` that
**suppresses** mode-dependent output: command *identity* still parses in
advanced mode (Amendment 3, unchanged), but no echo fires. The mechanism
— a fourth non-echoing context, or an `interactive: bool` alongside the
mode — is a build choice; the contract fixed here is *replay is silent*.

### 4. Scope of this ADR

This ADR establishes the channel and the resolution rule **only**. The
echo renderer, its catalogue, and the `Value → SQL-literal` machinery
are ADR-0038. The advanced-mode `ALTER COLUMN` gap-fill the echo relies
on is the ADR-0035 amendment. No echo behaviour is specified here beyond
the gating contract in §3.

## Alternatives considered

- **Widen `Mode` to three-way (Amendment 3's literal sketch).** Avoids a
  new type but conflates transient per-submission state with persistent
  input state, against `mode.rs`'s explicit design note. Rejected for
  §1's separate enum.
- **App-side gating, worker always returns echo data.** Keep the worker
  mode-agnostic; have it return echo data on *every* result, and let the
  App decide whether to render from `mode_at_submission` + command shape.
  Rejected: it computes the echo unconditionally (including in Simple
  mode, where it is never shown), does not generalise to other mode-
  dependent output, and re-opens exactly the "the echo is purely render-
  side" framing the user has twice ruled against — the settled direction
  is execution-time mode awareness, per Amendment 3.

## Consequences

- Additive and small: a new enum, one field on `Action::ExecuteDsl` and
  the worker request, and the submit-time resolution rule. No change to
  parsing, dispatch, command identity, or any executor's effect.
- The persistent `Mode` enum and `OutputLine.mode_at_submission` are
  unchanged. (ADR-0038 may enrich the render tag separately; not required
  here.)
- Future mode-dependent **output** has a home. Anything touching command
  *identity* or *effect* does not belong here (Amendment 3).
- Tests: submit-time resolution for all three cases (incl. `:` one-shot
  and the Advanced-mode `:`-is-a-no-op case); the field survives the
  `Action` → worker round-trip; a Simple-mode DSL command yields no echo
  request while an Advanced / one-shot one does (the gating contract).

## See also

- ADR-0033 Amendment 3 — deferred this side-channel; defines the
  intrinsic command-identity model this ADR must not disturb.
- ADR-0030 §10 — the DSL → SQL teaching bridge (the motivating consumer).
- ADR-0038 — the teaching echo; the consumer built on this channel.
- ADR-0003 — input modes and the one-shot `:` escape.
- ADR-0010 — the database worker thread this mode is threaded to.