discord_bot/specs/SPEC-001-responder-envelope.md

# SPEC-001 — Responder + response envelope

Characterization of the current (v2) responder contract in
`fjerkroa_bot/ai_responder.py`. The model answers with a JSON
envelope: `answer`, `answer_needed`, `channel`, `staff`, `picture`,
`picture_edit`, `hack`. FDB-005 will replace the transport of this
contract (structured outputs); the *behavioral* requirements below
survive that change unless marked otherwise.

### ENV-01 — Model answer reaches the user (coverage: feature)

When the model envelope carries a non-empty `answer` and
`answer_needed` is true, `AIResponder.send()` returns an `AIResponse`
with that answer text and `answer_needed == True`. This is the core
loop: user talks, bot answers.

### ENV-02 — Suppressed answer stays silent (coverage: feature)

When the model envelope sets `answer_needed` to false (and the
message is not direct, mentions nobody, and no staff note is set),
the returned `AIResponse` has `answer_needed == False`. The bot may
observe without butting in.

### ENV-03 — Staff note forces delivery (coverage: feature)

When the envelope carries a non-null `staff` text and a non-null
`answer`, the returned response preserves the staff text and has
`answer_needed == True`. Staff alerts must never be silently
dropped.

### ENV-04 — Direct messages are always answered (coverage: feature)

When the incoming `AIMessage` is marked `direct` and the model
returns a non-null answer, `answer_needed` is forced to `True`
regardless of the model's own `answer_needed`. A user addressing the
bot directly gets a reply.

### ENV-05 — Short-path rules skip the model (coverage: feature)

When a configured `short-path` `[channel-regex, user-regex]` pair
matches the message, `send()` appends the message to history, trims
history to the limit, persists it, and returns an empty response
(answer `None`, `answer_needed False`) **without calling the model**.
Cheap archival of noisy channels.

### ENV-06 — Malformed model output is repaired (coverage: withdrawn — successor ENV-18)

Withdrawn 2026-07-13 with FDB-005: strict structured outputs make the
repair model obsolete. Malformed output now counts as a failed
attempt — see ENV-18.

### ENV-07 — History is trimmed to the limit (coverage: feature)

After a completed exchange, `len(history) <= history-limit` holds.
Trimming happens both before the model call and after appending the
new question/answer pair.

### ENV-08 — Markdown links are unwrapped (coverage: feature)

In the final answer text, `[label](url)` becomes `url` and
`@[label](url)` becomes `label`. Discord renders raw URLs; markdown
link syntax from the model reads as noise.

### ENV-09 — Missing channel falls back to the message channel (coverage: feature)

When the envelope `channel` is null/none/empty, the response channel
is the channel the message came from.

### ENV-10 — System prompt template substitution (coverage: test)

`message()` substitutes `{date}` (YYYY-MM-DD), `{time}`, `{memory}`
(the assembled memory block — legacy memory string while the
structured memory is inactive, see MEM-10) in the system prompt;
`{news}` is replaced with the news file content when the configured
file exists and stays literal when it does not.

### ENV-11 — Per-channel history shrink prefers busy channels (coverage: test)

`shrink_history_by_one()` removes the oldest entry whose channel has
more than `history-per-channel` (default 3) entries; when no channel
exceeds the cap, the oldest entry overall is removed.

### ENV-12 — Exhausted retries raise, attempts are spaced (coverage: test)

When the model returns no usable answer three times in a row,
`send()` raises `RuntimeError`. Consecutive attempts are separated by
an exponential-backoff sleep — failures never hammer the API
back-to-back (D1).

### ENV-13 — Reaction-clear events are recorded (coverage: test)

`on_reaction_clear(message, reactions)` — the discord.py signature —
records the clearing in the channel's memory. (D7: the previous
handler declared `(reaction, user)` and crashed on dispatch.)

### ENV-14 — update_memory persists its argument (coverage: withdrawn — successor SPEC-002)

Withdrawn 2026-07-13 with FDB-007: the per-answer memory rewrite
(`update_memory`/`memoize`) is deleted; structured memory (MEM-01+)
replaces it. The D12 defect died with the code.

### ENV-15 — retry-model is used after a rate limit (coverage: test)

After a rate-limited attempt, the next `chat()` attempt uses the
configured `retry-model` instead of `model`; a successful attempt
switches back. (D2: the fallback was assigned to a local and never
took effect.)

### ENV-16 — Model calls are never served from a disk cache (coverage: test)

`openai_chat`/`openai_image` call the client every time. The pickle
response cache (`openai_chat.dat`) is a test-era artifact and must
not exist in the production path (D3/D4).

### ENV-17 — IGDB tool execution runs in a worker thread (coverage: test)

`_execute_igdb_function` executes the synchronous IGDB library off
the event loop (worker thread), returning identical results. The
event loop keeps serving Discord events during lookups (D5).

### ENV-18 — Malformed or refused output is a failed attempt (coverage: test)

Model output is requested as schema-validated JSON (strict structured
outputs). Output that still fails to parse, or a model refusal,
counts as a failed attempt (backoff + retry per ENV-12) — there is no
repair model, no `fix()` path, no relaxed-JSON fallback. Replaces
ENV-06.

### ENV-19 — The envelope schema is pinned (coverage: test)

Every chat call carries `response_format` = strict JSON schema named
`envelope` with exactly the fields `answer`, `answer_needed`,
`channel`, `staff`, `picture`, `picture_edit`, `hack` — all required,
`additionalProperties: false`, nullable where the protocol allows
null. Tool-followup calls carry the same format.