docs(eventing): an executive summary of the phases and architecture

[mrsabath]

Phase / scope

Phase	None — a summary of Phases 0-4 that cites them rather than changing any of them
What this changes	One new document, plus one reading-order entry in the agentdocs index. No code, no manifests, no tests.
Why a separate directory	agentdocs/ is explicitly "long-form design and build records … written to be read by whoever picks this up next". This is for the other audience — someone deciding whether to fund, demo, or depend on the component — and mixing an exec-audience page into the implementer set would make the index say something false about what it holds.
Phases it does not touch	All of them. Disjoint from any open eventing work.

Adds eventing/docs/EXECUTIVE_SUMMARY.md. The agentdocs set is twelve documents and
~10.6k lines, and there was no entry point for a reader who will not open the code.

What it says

Six sections: what the component is; the five phases at a glance; what each phase
decided and why; what is built as opposed to designed; the KubeCon commitment with
its gaps; and an assessment with the decisions still outstanding.

Every figure is quoted from the document that measured it, with that document named
inline, so a reader can check it rather than take it on trust. Nothing is restated as
though this page were the source.

Two statuses called out deliberately

Both are easy to misread from the phase documents alone, and both would be
embarrassing to get wrong in front of someone evaluating this:

• Phase 3's multi mode routes, but does not yet authorize. It gives each tenant
  its own store and topics; it does not check that a reader is the owner. The summary
  says not to enable or demo it until owner-scoped reads and transcript auth land.
• Signing is implemented but unproven in deployment. The crypto is checked against
  the RFC's own vectors, but the signed path has never run end to end on a cluster, and
  🐛 eventing: response-signature enforcement is advisory — rejected events still end batches and overwrite verified answers #885 means enforcement is currently advisory.

On the KubeCon section

§5 reflects the beat-by-beat status in KUBECON_NA_2026.md, with the open-issue state
re-checked against the tracker on 2026-10-09. Worth noting for whoever picks up the
talk work: #888, #889 and #891 have closed since that document was assessed on
2026-10-05, so its "all still open" list now overstates the remaining work. #885 and
#887 are still open. I have not edited that document here — it is a living file with
its own lifecycle and a separate owner's call on how to re-cut the MVP.

Per the same document's own rule, §5 and §4 are marked as expiring; §§1-3 do not.

Checks

• All five relative links out of the summary resolve, and the new index link resolves
  back into it (verified in-tree).
• Every quoted figure matched against its source document.
• No markdown or link checker in CI, so there is nothing for this to break.

[aslom]

Docs-only, and the right document to be missing: twelve agentdocs/ files at ~10,626 lines (I counted them at d71dd99a) with no entry point for a reader who will not open the code. The structure is good, the ASCII flow is the clearest one-screen summary of the component in the repo, and the decision to cite figures inline rather than restate them is what makes this maintainable.

I spot-checked every quoted figure against the document named inline. Almost all of them hold exactly:

• wake latency 1.0–5.0 s / 2.2–4.3 s, scale-to-zero 30–31 s, image pull 5.1 s cold / 454 ms–2.45 s warm, Ed25519 222 ms / 227 ms, group of 100 in 1m02s with 0 failed — all IMPLEMENTATION_REPORT1.md §3, verbatim
• Gap A's group.initial.rebalance.delay.ms=3000, Gap B's resume-by-path fix, Gap C's 24 h retention.ms under 7-day offset retention — all DESIGN_PHASE1.md §16 (and §16 is where the gaps live, despite the heading reading "Demo flow")
• all eight Q&E questions resolved, Q&E-2 and Q&E-8 characterised correctly
• the 300 s sha256(token) cache, failures-not-cached, 401/403, empty-list-denies-everyone — DESIGN_PHASE2.md §2.3–§2.4 and §5
• the §3.6 Tier A boundary quote is exact, including the instruction to say the second sentence out loud
• 12 → ~300 pod ceiling, claude 2.1.270's 75 s PreToolUse block, --permission-prompt-tool not existing, plan mode never attempting the call
• all five relative links out of the summary resolve, and the new index link resolves back

Approving — this is a net improvement to the doc set as it stands, and nothing below blocks it.
Two items are worth a follow-up before the page gets pointed at widely, both small and both textual:

The multi-mode framing is the one IMPLEMENTATION_REPORT3.md §5 explicitly asks you not to use. The summary says it "routes but does not yet authorize". IR3 says multi consumes no responses at all until T6, and then names the misreading: "This is a more useful warning than 'not yet isolated', which implies a working-but-unisolated mode." Given this PR calls that status out deliberately, it is worth landing it the way the source wants.

The 429/300 s observation is cited to the wrong document. It is KUBECON_NA_2026.md §2.3, not IMPLEMENTATION_REPORT1.md §7. IR1 §7 records a different accident. A reader who follows the citation — which this document invites them to do — finds nothing, and that is expensive for the one figure attached to "the best idea in the component".

Three smaller notes inline: the ~900 test figure is the one number with no named source, and KUBECON_NA_2026.md §2 specifically says not to quote it bare; §4 points at open issues in §5 that §5 does not list; and the Phase 4 measurement is on a CLI version the repo no longer pins.

None of this is a factual error about the system — the findings are about citation and framing. That is worth getting right here precisely because the document's value is that a reader can check it, but it is follow-up work, not a reason to hold the merge. Worth noting the PR body's issue check is also more current than KUBECON_NA_2026.md §2.5, which still lists #885–#889 as "all still open"; leaving that document alone was the right call, but its staleness is now visible through this page.

[mrsabath]

All seven addressed in f5b8c61. Thanks for spot-checking every figure against its named source — that is the one thing this document needs done to it, and it caught the two that mattered.

	Finding	Fix
high	multi framed as working-but-unisolated	Carried IMPLEMENTATION_REPORT3.md §5's own wording; rewrote the §6 condition, which understated the blocker for the reason you gave
high	429/300 s cited to IMPLEMENTATION_REPORT1.md §7	Now KUBECON_NA_2026.md §2.3
medium	Unreachable from the component front door	Added to eventing/README.md's table — plus the Phase 2-4, IR3 and KubeCon rows it was missing anyway
medium	Bare ~900 with no named source	Now 904 collected / 896 CI with its citation, narrowed back to #885 and #888
low	Dangling "open issues in §5"	Names #885, with the EB_REQUIRE_RESPONSE_SIGNATURE default
low	Phase 4 CLI version	Notes it is not reconfirmed on the pinned 2.1.278
low	Phase 3 row undercounted	Now "steps 1–4, plus T5, T13 and T22"

Two notes on judgement calls:

The README table grew more than the one row you asked for. Adding the summary while leaving out the documents it cites would have made that table misleading in a new way, so Phases 2-4, IMPLEMENTATION_REPORT3.md and KUBECON_NA_2026.md are in as well. Happy to split that into its own PR if you would rather keep this one to the summary.

KUBECON_NA_2026.md §2.5 is still stale — #888, #889 and #891 have closed since its 2026-10-05 assessment, so "all still open" now overstates the remaining work, and the MVP is effectively down to #885 then #896. Still think that is the owner's call to re-cut rather than something to fold in here, but it is now visible through a page that points at it, which is a reason to do it sooner than later.