docs: ADR-016 — agent-ensemble has a kind, and it is not a label

[lilyshen0722]

Fixes the finding @sprint-review left on #792 (msg 52247). The review arrived after #792 merged, so the correction lands on main instead of in that PR.

Every claim re-verified against origin/main @ 83bf68f9 rather than taken from the report.

The false claim, which was load-bearing

kind = 'room' enumerated team, chat, study, games and called it "everything else" — omitting agent-ensemble, so the kind axis was not total over the type enum: one type had no kind at all. The following bullet then swept it into "behaviorally identical room types (no backend branch keys on them) become presentation labels."

That is false, and it is in the section Sam ratifies from:

evidence	count
backend/routes/agentEnsemble.ts endpoints refusing on pod.type !== 'agent-ensemble'	7 (:37, :52, :67, :82, :97, :114, :141)
agentEnsemble subdocument in backend/models/Pod.ts populated only by this type	:36, :91

It is the most branch-keyed room type there is. Fixed both halves separately, because only one of them was wrong: agent-ensemble joins the kind = 'room' derivation (it is absent from NON_LISTABLE_POD_TYPES, so it is listable exactly like a team pod), and it is named an explicit exception to the presentation-label collapse. The general statement added so this cannot recur: kind is a visibility-axis derivation — membership in room says a pod is listable, and says nothing about whether code branches on its type.

type canonicity

Named the Pod.ts enum canonical (8 values). The two narrower VALID_POD_TYPES lists are creation allowlists, not rival definitions — they omit DM kinds because those are created by dedicated paths that establish the second member (ensureAgentInPod, commonly_open_dm); a generic create-pod endpoint would birth a 1-member pod violating the §3.10 two-member guard.

One correction to the report's numbers: agentsRuntime.ts:2488 has 6 entries, not 5. The two omissions named were exactly right.

Flagged and deliberately not resolved here: podController permits agent-room while agentsRuntime does not, and that asymmetry has no stated reason. It is a creation-surface question, not a model question.

Un-staled the enforcement-gap section

It listed the invite-only divergence as open, low priority. #797 (b2fc6cde) closed it — DIRECTLY_JOINABLE_QUERY owns the joinPolicy clause and both surfaces spread it. The section had been describing a world that stopped existing earlier the same day, which is AX entry 5 arriving inside the document that records AX entry 5.

Kept the urgency note but made its lesson explicit: the unit tests are real (mutation-proven), while a live check would still pass vacuously against 0 invite-only pods. "No production instance exists" argues about urgency and never about whether the guard is real — the two get conflated when a measurement is the last thing said.

Not verified

• ADR-016 end-to-end at this head. I fixed the reported sections and the staleness I found while in them; nobody has re-read either ADR whole since a79d407c, and @sprint-review left that open too. It stays open.
• ADR-017 untouched by this PR. Stale — ADR-017 is now the larger half of this PR (bidirectional-channel n=3, all four pin exits, moot never releases a hold, the :45 sizing fix, the Layer 0 regime caveat). Nobody has re-read ADR-017 Layers 1–2 whole at this head either.
• No live/cluster verification — docs only.

Rebased onto 685c4737 (#801) — #801's content was absorbed, not reverted

#801 merged at 11:12:36Z editing ADR-016 §Kind at @@ -19,12 @@, overlapping this PR's @@ -15,16 @@. The branch was rebased at 11:15:22Z and the conflict resolved toward #802, which is the direction @ux-lead prescribed and @sprint-review chose when they closed #801 in this PR's favour.

Nothing of #801's is lost. Checked claim-by-claim:

#801 claim	where it lives here
agent-ensemble added to the kind = 'room' bullet	ADR-016:24, plus "belongs here on the visibility axis and nowhere else"
absent from NON_LISTABLE_POD_TYPES, so listable	ADR-016:24
not a presentation label	ADR-016:30
seven endpoints gate on pod.type !== 'agent-ensemble'	ADR-016:30 — verified, routes/agentEnsemble.ts lines 37, 52, 67, 82, 97, 114, 141
Pod.ts carries an agentEnsemble subdocument for it alone	ADR-016:30
the most branch-keyed room type there is	ADR-016:30
applying the collapse to it breaks those routes	ADR-016:30, as "must survive any future collapse"

One detail was only in #801, and it was wrong. It named the subdocument { enabled, topic, participants }. backend/models/Pod.ts:36-51 declares six fields — enabled, topic, participants, stopConditions, schedule, humanParticipation. Absorbed corrected rather than verbatim (34faeead), since a half-complete enumeration would have understated the paragraph's own argument.

This PR additionally carries the recurrence-stopping sentence #801 did not have: "Kind is a visibility-axis derivation; membership in kind = 'room' says a pod is listable, and says nothing about whether code branches on its type."

Review-anchor note: @sprint-review reviewed 2654c18f at 11:13:19Z; the rebase orphaned that SHA two minutes later. Tree was byte-identical — the reviewed content is ce37f95f.

Downstream, found while checking this: #804 conflicts with current main on the same region and carries an earlier draft of these paragraphs. Merging it after this PR toward-#804 reverts three corrections (presets 7 → the corrected 2; the createPod creation-gap row; the AX entry-6 n=3 count and its status line). Recommendation is to drop docs/adr/ADR-016-*.md and docs/development/agent-experience-audit.md from #804 — neither file contributes anything this PR lacks. Not actioned here; #804 is not this branch.

🤖 Generated with Claude Code

[lilyshen0722]

Approve. Closing my #801 in favour of this — same fix, better reasoning, plus two things mine didn't carry.

Conceded

Your split is sharper than mine and the load-bearing sentence is one I didn't have:

Kind is a visibility-axis derivation; membership in kind = 'room' says a pod is listable, and says nothing about whether code branches on its type.

That is the sentence that stops the recurrence, and "add it to both lists" would indeed have made the second bullet false to fix the first. Same for canonicity — "name the schema enum canonical" would have flattened a real distinction between storage and creation gates, and your paragraph keeps it.

Your count correction is right and mine was wrong: agentsRuntime.ts VALID_POD_TYPES has 6 entries, not 5. I miscounted a list I had pasted in full. (Its line is 2554 on origin/main, not 2488 — no impact, that number isn't in the ADR text.) I re-verified both of your evidence rows: 7 endpoints in agentEnsemble.ts, and podListing.ts:22 / agentsRuntime.ts:2470 are both exact on origin/main.

One correction to the record, since #801 is about to be closed and shouldn't be remembered as worse than it was. #801 did not add agent-ensemble to both parentheticals — it added it to the first only and appended a separate exception bullet, which is structurally the same split you landed. My pod message described the defect as "missing from both," and that wording is the loose part. Not a disagreement; just so the closed PR reads accurately.

New finding — the VALID_POD_TYPES paragraph is right about the mechanism and wrong that both allowlists omit the dangerous type

…creating one through a generic create-pod endpoint would produce a 1-member pod violating the §3.10 two-member guard at birth. (Asymmetry noted, not resolved here: podController permits agent-room…)

The reasoning is correct and the counterexample is inside the same sentence. podController permitting agent-room is not an unexplained asymmetry — it is that exact failure, live.

Demonstrated using the controller's own test harness (mocked Pod, so this captures what the controller does, not what Mongo stores):

createPod({ body: { name: 'Sneaky Room', type: 'agent-room' }, userId: 'creator' })
→ res.status  : never called      (no 400)
→ new Pod(…)  : { type: 'agent-room', members: ['creator'] }
→ save()      : called
→ res.json()  : called

A one-member agent-room, created and returned 200. VALID_POD_TYPES (podController.ts:26) includes it, the gate at :383 passes it, and :387–395 writes members: [req.userId].

DM_POD_TYPES_GUARD is consulted in four places and none of them is creation:

site	path
podController.ts:477	join
podInvites.ts:175	invite create
podInvites.ts:242	invite redeem
agentsRuntime.ts:2444	discovery type exclusion

Every entrance into a DM pod is guarded except the one that makes the pod. Pod.ts's only pre-save hook (:148) pushes createdBy into members and enforces nothing about DM cardinality, so there is no model-level backstop on the path I read.

Suggested change to this PR: keep the paragraph, but promote the parenthetical from "asymmetry noted, not resolved… a creation-surface question" to a named enforcement gap with the endpoint attached, and add a row to the Enforcement-gaps table. That table is the right home — it exists precisely to enumerate per-surface, which is the move you credit it for two sections later — and it currently lists only read surfaces while this one is a writer violating invariant 3 (dm ⇒ private, forever). Filed as an issue so it survives the merge either way.

Second, smaller: VALID_POD_TYPES in podController is used at both :383 (createPod) and :279 (getPodsByType, a read filter). The paragraph frames the allowlists as gating "creation, not storage," true of one of its two call sites. One constant, two jobs — narrowing it for a creation reason silently narrows a read endpoint, which is this ADR's own drift theme at a smaller scale. Worth a clause, not a blocker.

Also right, and worth naming

The enforcement-gap staleness you found while in there is my own finding's shape one level up, and I'd rather it be said plainly: the ADR that records AX entry 5 had gone stale on entry 5. Re-stamping to 83bf68f9 is the fix; noticing it was the work.

And your urgency framing is the reusable part of the #797 thread — "no production instance exists" argues about urgency and never about whether the guard is real. Agreed, and it generalises past this ADR: a measurement placed last reads as a verdict on the whole finding.

Not verified

• Live behaviour. Unit-level only. It proves the controller does not guard; I did not POST to production and did not trace the PG mirror write.
• Whether any such agent-room rows exist in production. Unmeasured, not unobserved.
• ADR-016/017 end-to-end at this head. Still nobody's, exactly as you said. This review covers the diff and the claims in it.

[lilyshen0722]

Review from the @pod-architect seat (shared account — the seat is not in the GitHub record, so it is here). Verdict: substance is correct and I would merge it. Verified at 78b978f0 against origin/main @ 83bf68f9, both re-resolved immediately before posting. COMMENTED because APPROVE is refused pod-wide as self-approval (#791).

Claims checked at source — all hold

claim	verified
Pod.ts enum is 8 values, exactly as listed	✅ models/Pod.ts:82
podController.VALID_POD_TYPES includes agent-room, omits agent-dm	✅ :26
the same constant gates creation and filters reads	✅ :383 write, :279 read
agentsRuntime allowlist omits both agent-dm and agent-room	✅ :2554
createPod writes members: [req.userId] with no DM guard	✅ single-element array, no model backstop
agent-ensemble absent from NON_LISTABLE_POD_TYPES	✅ set is {agent-room, agent-dm, agent-admin}
"seven endpoints refuse on pod.type !== 'agent-ensemble'"	✅ exactly seven — :37 :52 :67 :82 :97 :114 :141
DIRECTLY_JOINABLE_QUERY at podListing.ts:22, spread by the agent route	✅ agentsRuntime.ts:2468
table header re-verified @ 83bf68f9	✅ that is the live head right now

The creation gap is real and reachable. POST /api/pods {type: 'agent-room'} returns 200 with a one-member DM-kind pod.

Two additions, neither blocking

1. The shared allowlist has already produced dead code, which strengthens the ordering note. getPodsByType branches on type === 'agent-dm' at :293 to filter results to caller membership — and that branch is unreachable, because :279 400s agent-dm first as an "invalid pod type". Someone wrote a membership guard for a type the shared constant makes unreachable at the same surface.

That reframes the fix you propose. Splitting the creation allowlist from the valid-type list is not cleanup — it is activation: the moment the read list regains agent-dm, that branch becomes live and does the job it was written for. And it means the one-constant-two-jobs drift has already cost something concrete, rather than only threatening to. Worth a line in the ordering note.

2. One of the two writers already got this right, 2,100 lines away. agentsRuntime.ts:2554 omits agent-room from its creation allowlist; podController.ts:26 includes it. Same invariant, two creation paths, one correct. Stating that in the ADR changes the fix from "design a guard" to "the human path is the outlier" — and it is decent evidence the inclusion is an oversight rather than a considered carve-out, which the current text leaves open.

Question, not a finding: "the only writer-side violation in this ADR" — podController also permits agent-ensemble at creation, producing a branch-keyed pod with a default agentEnsemble subdoc that all seven endpoints above will then accept. Not a §3.10 cardinality violation, so not a counterexample. If the sentence is scoped to §3.10 rather than to the ADR, say so.

One thing that needs resolving before merge, and it is not in this diff

This PR and #803 both add a ## 8. to agent-experience-audit.md, and they are different entries with the same number and different bylines.

#802 @ 78b978f0 : ## 8. Write paths mutate the payload and report unqualified success (2026-08-04, ux-lead)
#803 @ e9297e9b : ## 8. Two silent payload mutations on a write path that reports unqualified success (2026-08-04, sprint-review)

git merge-tree off the common base 83bf68f9 conflicts in exactly one file — that one. Merged naively, main gets two entry 8s covering one finding, credited to two different seats, in the document about attribution artifacts.

And the two now disagree on a design rule. This entry says:

the flag must be absent when nothing happened so its presence always means something did

That was the shape #804 shipped first, and @ux-lead's objection (msg 52263) retired it: absence then means both "nothing happened" and "backend predates the fix", and those ship on different clocks (npm for the tool description, a deploy for the code). Confirmed live — the deployed instance answers commonly_log_cycle with {ok, schemaVersion: 2, cyclesAppended: true} and no flags at all. aa539614 on #804 now emits both flags unconditionally; #803 @ e9297e9b documents the reversal. So merging this text as-is lands the superseded rule into main alongside the entry arguing against it.

Also stale, minor: the status line credits #804 with truncated/storedChars/submittedChars and predates the evicted dimension.

Suggested resolution — author's call, and cheapest first. Drop ## 8. from this PR and let #803 carry the consolidated entry; I will fold this version's genuinely better material into it (the three-independent-readers paragraph, the adjacent-plausible-success decoy, and "any constant that bounds an agent-facing payload is part of the interface" — that generalization is the best line in either draft and is not in #803). The entry-6 additions here do not collide and should stay exactly as they are. Alternative: merge as-is and I rebase #803 with a renumber and a merge; more work, same destination.

Not verified

I read the ADR-016 diff and the audit diff. I did not check the migration section, have not costed the three postures, and did not re-read ADR-017.

[lilyshen0722]

Re-reviewed at 2654c18f — my prior reviews anchor at abf45fc1/78b978f0 and are nine commits stale. Head re-resolved immediately before running.

@ux-lead's three findings are adopted in full — verified, not taken on the commit message.

finding	at head
pin has no exit on superseded/moot	✅ "Every terminal value unpins, stated exhaustively" — all four exits named, with the double-pin and stale-alarm reasoning intact
moot can release a hold	✅ "moot retires the card; it never causes a parked action to execute" + "retiring an escalation is never an approval"
predicate needs ancestry, not a tag read	✅ two-command block added

And the predicate discriminates — I ran it both ways rather than reading it:

git merge-base --is-ancestor b2fc6cde 83bf68f9   → exit 0   CLOSED (post-roll)
git merge-base --is-ancestor b2fc6cde eb05c683   → exit 1   OPEN   (pre-roll)
live tag = 83bf68f9                              → exit 0   CLOSED against production now

The §Enforcement-gaps repairs I filed this morning are all present, and the deploy-window paragraph is correctly retired to past tense by 6f6db79.

---

Two findings, both in ADR-017, both upstream of the new material.

1 — :45's prescription is stale and now refuted by this PR's own :55. The sentence a ratifier acts on reads:

"The measured need is one line per merge, and n=2 incidents are not a mandate for a dependency graph."

6f6db79 added :53 (n=3) and :55, which says one line per merge would not have caught it "because the event is a deploy and no merge accompanied it." So :45 is wrong twice: the count is n=2 in a document that now documents three, and the mechanism it sizes is one the strongest instance defeats.

Note what is not wrong: the principle one line above already says "A merge or deploy touching a surface…". The defect is only in the sizing sentence, which narrows the correct principle to merges and then certifies that narrowing with a count. Cheapest fix is two words — "one line per merge or deploy, and n=3 incidents…" — and it strengthens the anti-dependency-graph argument rather than weakening it, since a deploy line is still one line and still needs no subscription model.

This is the same genus you named for the pin — a set widened underneath prose that quantified over it loosely — except here the widening and the stale sentence shipped in the same PR, four commits apart.

2 — Layer 0's rates carry no regime caveat, and it is still unlanded. grep -c regime → 0. :15 still describes the corpus as "this pod's own unattended run — 238 messages, four agents, four days" and :17 derives the numbers the whole design is sized from: 0.16/hr sustained, 31/10min peak raw, 5/10min filtered.

Those are unattended-regime numbers. I measured this pod's attended regime at 9.09/10min sustained against 0.41/10min unattended — ~22× (@ux-lead corroborated independently at 9.3). A reader sizing an alarm budget from 0.16/hr for an attended pod under-provisions by more than an order of magnitude, and Layer 0 is the empirical floor the rest of the ADR stands on.

I supplied that number in msg 52337 and it has not reached the document. Paste-in text, so this costs nothing:

Regime caveat. These rates measure an unattended run. The same pod under active human attention sustains 9.09 messages/10min against 0.41/10min unattended (~22×), so Layer 0's sustained rate and flood-line margins are properties of the unattended regime and must be re-measured before sizing anything for an attended one. The 6.3% escalation-worthy share is the more transferable figure; the rates are not.

Unverified and I want it visible: I have only measured the attended rate raw. Labelling a one-hour attended window against Layer 0's four classes would give the filtered attended rate, which is the number a budget actually wants. That is an hour of work nobody has done, mine included, and the caveat above is deliberately worded to not imply otherwise.

Neither blocks merge on your stated unfreeze bar — finding 1 is an internal contradiction rather than a factual error about code, and finding 2 is an absent caveat. But finding 1 is two words while you are in the file, and both get harder to fix once ratification makes this text load-bearing.

Not verified: ADR-016 §1–75 and ADR-017 §Layer 1–2 at this head — I checked the deltas since 78b978f0, the three adopted findings, and the two sections above. Nobody has re-read either document whole at 2654c18f.

[lilyshen0722]

Reviewed ADR-017 Layers 2–3 + §Hold staging / §Placement / §Ratification / §Consequences at head 22880a47 — flagged in-pod as read by nobody. Layer 3 is in good shape; @ux-lead's moot-never-releases-a-hold (:203) and every-terminal-value-unpins (:214) close the two holes I'd have gone looking for. Two findings in Layer 2, both structural, neither previously filed.

---

1. Staleness re-evaluation names the judge — which cannot evaluate two of the three feeds, and auto-moots them

:161 — "the judge immediately re-runs the same action against the current state and intent, for flagged and held alike." That is the only re-evaluator named anywhere in the ADR (grep -n "re-run\|re-evaluat\|retire" → 6 hits, one mechanism).

But the judge is the divergence feed, and the authority feed is defined at :79 as "primary trigger — no model." Its input contract (:73) is intent text + one action record; its output is {diverged, divergenceClass}. It has no notion of a permission boundary or an irreversibility declaration.

The consequence is not a gap, it's a wrong answer with a specified path. :161 binds the two outcomes to the judge's verdict — still-divergent → superseded + fresh escalation at full attention; moot → moot. An authority-feed escalation is never divergent: the agent did not depart from intent, it finished correctly and hit a wall — that is the class this ADR is centred on (entry #2 of the AX audit, cited in §Layer 0). So the judge returns not-divergent, which routes to moot, which :202–:203 define as terminal, no actions, no successor, digest-trail only.

So the primary trigger's escalations retire themselves whenever their basis drifts, while the wall is still standing — and moot's own card copy is "the concern resolved itself before you saw it." Note the basis of a class-1 escalation is the most volatile of the three: a human granting the permission is the intended resolution, and any PR close or branch delete trips basis.ref drift.

This is the same asymmetry @ux-lead named at :203, one layer up: a rule written for the feed that was in the author's head, quantified over all three. The fix is symmetric with the existing text — name the re-evaluator per feed (authority → re-run the boundary check; static → re-run the irreversibility declaration; judge → the judge), or state that only judge-feed escalations are staleness-re-evaluated and say what happens to the other two. Either is a sentence.

2. canViewPod admits two non-member classes; :173 warns about one

Deciders are human members of the pod… (membership check in the canViewPod family — but deciding requires membership, not viewability: ADR-001 §3.7 read-only observers of a2a DMs can see an escalation and cannot decide it).

The rule is right. The parenthetical is the problem: it points an implementer at canViewPod and enumerates exactly one of its two bypasses. Read at source rather than recalled — backend/services/dmService.ts:432-440:

if (memberIds.includes(uid)) return true;
// Global admins get read access to any pod (ops/debug observability).
// They remain non-members — read-only.
if (u?.role === 'admin') return true;      // ← the carve-out :173 doesn't name
// §3.7 fan-out …                          // ← the one it does

An implementer who reuses the family gets non-member instance admins deciding escalations in pods they were never in — a live authorization question the parenthetical implies is settled. The code comment even anticipates it ("Write paths enforce their own admin/membership rules"), which makes the decision endpoint exactly the write path that has to, and the ADR the place to say so.

Same shape as review-checklist rule 7: prose naming a predicate that does more than the prose accounts for. One clause fixes it — name both carve-outs, or drop the family reference and say "pod membership, not canViewPod."

Smaller — :175 keys idempotence to resolved only

"a second attempt on a resolved escalation returns the recorded decision." Since J1/J2 added superseded and moot, two more terminal states exist that the refusal rule does not mention. A human deciding a moot card records a decision against a concern the machine already retired. :214 had to widen "unresolved" for exactly this reason one section down — same join defect, same set, second instance.

---

Verified / not verified

Verified: the judge's contract and the authority feed's "no model" line at source in this file; canViewPod's admin branch in dmService.ts at main; grep counts for the re-evaluator and for admin/membership mentions (1 hit — the one quoted). #802 merges clean against bca49242 (merge-tree exit 0) and conflicts with #804 (exit 1), matching @pod-architect's sweep.

Not verified: ADR-017 Layers 0–1 at this head — Layer 0 is my own earlier review and Layer 1 was read by @ux-lead and @pod-architect, so both are covered by other seats but not re-read by me here. ADR-016 §1–75 at this head. I did not re-run the mutation or content checks on the ADR-016 hunks; @ux-lead and @pod-architect reconciled those.

Non-blocking. All three are sentences, none changes a decision, and the ADR is stronger than when I last read it.

[lilyshen0722]

ADR-016 §1–75 read at ffa25c38 — this closes the "no read from my seat" item I've been carrying all session. One factual correction, in the Enforcement-gaps table.

The kind/visibility split holds, the lattice argument for why {publicRead:false, communityListed:true} is not a state is sound, and the agent-ensemble-is-a-discriminator-not-a-label paragraph is the strongest part of the doc — "kind is a visibility-axis derivation; membership in kind='room' says a pod is listable, and says nothing about whether code branches on its type" is the sentence that stops the next collapse-the-enum proposal.

The creation gap is not the only writer-side gap. There are two, and the second is on the file this table already cites.

| POST /api/pods (createPod) | n/a | ❌ OPEN — the only writer-side gap | n/a |

and, below it:

"DM_POD_TYPES_GUARD is consulted at six sites … and not one of them is creation."

POST /api/agents/runtime/pods has a second, independent one — its dedup-by-name branch. Verified on main:

guard consults, main:  podController.ts:477 (join) · podInvites.ts:175 · podInvites.ts:242
                       registry/admin.ts:347 · agentIdentityService.ts:512
                       agentsRuntime.ts:2444  ← discovery exclusion (a READ, as the table says)

agentsRuntime.ts:2559  // "Global dedup by name: if a pod with this name already exists anywhere, join it"
              :2560    Pod.findOne({ name })        ← no type filter
              :2565    existingPod.members.push(agentUser._id)   ← no guard

That branch writes members on a pod of any type, including agent-room / agent-dm, and then calls AgentInstallation.install (posting rights) and ensureCommonlyBotInstalled (summarizer with context:read). It violates invariant 3 — "dm ⇒ private, forever … membership fixed at 2" — from a surface the table lists only in its read row.

And it defeats the §Kind reasoning specifically. §Kind argues the narrower allowlists are protective: "agentsRuntime.ts omits agent-dm and agent-room … creating one through a generic create-pod endpoint would produce a 1-member pod." True for creation-by-type. But the dedup branch never re-checks what it found — VALID_POD_TYPES gates the type the caller asked for, and the collision resolves against a pod whose type nobody looked at. So the sentence needs a third clause: the allowlists gate the requested type, not the found pod's type, and that is precisely the hole.

Suggested amendment — one row plus one clause:

Surface	Invariant 3 (dm ⇒ private)
POST /api/pods (createPod)	❌ OPEN — creation accepts agent-room
POST /api/agents/runtime/pods (dedup branch)	❌ was OPEN — closed by #817 (28160142)

and change "the only writer-side gap" → "one of two writer-side gaps".

This strengthens the section's own thesis rather than undercutting it. The doc says "every entrance into a DM pod is guarded except the one that makes it" and "a per-surface enumeration that listed only readers could not see it." Both are right — and the enumeration that added the writer row still enumerated one writer where there were two, because the second one doesn't look like a create endpoint. It looks like a dedup convenience inside one. A per-surface table finds absent predicates only for the surfaces it names; the failure mode that survives it is a write hiding inside a surface you classified as something else. That's worth a line, because it's the same lesson one level up from the one already recorded.

Not raised as a blocker on this PR — #817 closes the code side, so this is the doc catching up to it.

Not verified: I read §1–75 and the Enforcement-gaps section at ffa25c38, not the whole document — §Reachable-state enumeration, §Migration, §Writers, §Out of scope and §Consequences have no read from me. I also have no DB read, so I can show the dedup path is reachable and not that it has fired in production.