From eb22ff7517fac6ec9dd6833b417d881d8feb28f5 Mon Sep 17 00:00:00 2001
From: Jer Miller <jeremie.miller@gmail.com>
Date: Wed, 5 Aug 2026 15:46:36 -0600
Subject: [PATCH] docs(generate): owner media travels inline, and the cost
 lands on the caller

The alternative is a path handoff, which is what the speaker-analysis boundary
does for bulk audio -- and it puts an owner's frames at rest outside the journal
and outside retention, with a cleanup step a killed child never runs. Content
crossing this boundary is in flight or it is nowhere.

The cost is real and belongs in the contract rather than in a consumer's
surprise: a screen recording's frames are megabytes each going in, so a client
must write requests and read responses concurrently or it deadlocks both sides.
---
 docs/GENERATE.md | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/docs/GENERATE.md b/docs/GENERATE.md
index de67b171f..c992530ff 100644
--- a/docs/GENERATE.md
+++ b/docs/GENERATE.md
@@ -71,6 +71,15 @@ crate and the Python shim read that file. ⛔ **Neither language holds its own c
   what usage is recorded against. It is **not** a provider selector.
 - **`contents`** — non-empty array of parts. A `text` part carries `text`; an `image` part carries
   `mime_type` and base64 `data`. Unknown part types are refused.
+  🔴 **Owner media travels inline, over the pipe, and is never written to a temp file.** The obvious
+  alternative — hand the child a path — is what the speaker-analysis boundary does for bulk audio, and
+  it puts an owner's frames at rest outside the journal, outside retention, with a cleanup step that a
+  killed child never runs. ⛔ Inline is the covenant-correct choice and it is not negotiable for
+  convenience: **content crossing this boundary is in flight or it is nowhere.**
+  ⚠ It has a cost, and it lands on the caller: a screen recording's frames are megabytes each, so **a
+  client must write requests and read responses concurrently.** A client that writes a large request
+  while the child is blocked writing a response nobody is reading deadlocks both. See § the two
+  framings.
 - **`attempt_index`, `exclusive_admission`, `transport_retries`** — retry and admission hints. Each is
   meaningful to one lane and ignored by the others. ⚠ These are deliberately named for what they
   *do* rather than for the lane that honours them; a lane name in a field name is the provider leak
-- 
2.51.2