File the event-feed api-gap entry and record the cross-team decisions

[jeremy]

Files the obligation COORDINATION.md's lifecycle step 1 creates for BC3's account-wide event feed (BC3 #9646/#9659, unmerged eventstream+accountid branch), now that the pre-merge review cycle with the BC3 authors has settled the contract questions. Exactly three files; no spec surface (SPEC.md/Smithy/openapi untouched), so it rides beside the spec train legitimately.

What this records

spec/api-gaps/event-feed.md (new): the registry entry, revised against BC3 branch head 8be5c67de5 (a branch-head verification record, never the provenance pin — the pin never references unmerged history). The "Settled pre-merge" block records the decisions:

• the poll response body envelope {"events", "position", "next"} is the contract; headers are echoes; PollEvents becomes an ordinary generated operation
• the filter digest is published as a versioned srv1 contract — bare 16-hex on the wire; srv1-<digest> is the SDK-side checkpoint-lineage namespace
• the 409 body names both position_digest and filters_digest
• the disconnect-reason matrix is four rows, including remote/reconnect:true (revocation is not wire-distinguishable; a failing re-mint is the designed detection path)
• stream tickets are stateless replayable bearers (mint safe-to-retry; statelessness re-confirmed at BC3's merge-time gate)
• raw filter bounds, page cap, wrong-account 400, presence-bearing visible_to_clients, guarantor identification
• entry-boundary semantics are position-relative, never wall-clock: since=now permanently excludes an in-flight lower id that commits after entry (deterministic regression on the branch). The entry states the SDK connector's drain-before-save consequence in its scoped form — a save-ordering invariant against a defined observation point, with no global at-least-once claim; post-snapshot stragglers are the feed's documented best-effort case.

COORDINATION.md: cross-team item 4 in the established shape, plus the Division-of-labor line fixed to match Lifecycle step 3 (the SDK authors the Smithy + regeneration PRs; BC3 reviews) — resolving the self-contradiction the BC3 reply pointed out.

spec/api-gaps/README.md: the one registry row. The pin blockquote is untouched.

What stays gated

Fixture freezing and Layer-1 absorption wait on BC3's merge-time gate (rebase both PRs, re-CI, fresh exact-head reviews, re-confirmed ticket statelessness, regenerated transcripts). Layer-2 work proceeds against the recorded decisions, marked provisional wherever it pins BC3-derived wire literals or semantics.

Verification

• make validate-api-gaps → 32 entries clean.
• make check on this branch composed with Unbreak doc-constants-check: grant SPEC.md's two as-of pin citations #605 → full run (see below).
• git diff --stat = exactly the three files above.

Note: the first CI run inherited main's doc-constants-check breakage (cross-merge conflict between #601 and #590, fixed by #605). Rebased onto post-#605 main; the full make check passes locally on exactly this composition (REAL_EXIT=0).

[Copilot]

Pull request overview

This is a documentation-only PR that files the API-gap registry obligation created by COORDINATION.md's lifecycle for BC3's account-wide event feed (unmerged eventstream+accountid branch, BC3 #9646/#9659) and records the cross-team contract decisions reached during the pre-merge review. It touches no spec surface (Smithy/OpenAPI/SPEC.md untouched) and no generated code — it only adds registry/coordination prose, so it rides beside the spec train legitimately.

Changes:

• Adds spec/api-gaps/event-feed.md: a new registry entry (no-json-contract, high demand) capturing the settled pre-merge contract (body-envelope authority, srv1 filter digest, enriched 409, four-row disconnect matrix, stateless replayable tickets, position-relative entry semantics) and the two-layer absorption plan.
• Updates COORDINATION.md: adds cross-team item 4 and corrects the Division-of-labor line to match Lifecycle step 3 (SDK authors Smithy + regeneration PRs; BC3 reviews).
• Adds the registry row to spec/api-gaps/README.md (pin blockquote untouched).

I verified the new entry's frontmatter against spec/api-gaps/schema.json, confirmed all five required body sections required by scripts/validate-api-gaps.rb are present, checked that the referenced SPEC sections (§5 47→48, §14/§15/§16/§18/§22) and the existing ListEvents operation are accurate, and confirmed the new SHAs are non-pin values that won't trip doc-constants-check. The one issue found is a markdown formatting defect (a whole sentence wrapped in an inline-code span). The substance of the PR is cross-team coordination decisions about an external unmerged BC3 branch that cannot be independently verified from this repository.

Tip

If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
spec/api-gaps/event-feed.md	New registry entry recording the pre-merge event-feed contract decisions and two-layer absorption plan (one malformed inline-code span noted).
COORDINATION.md	Adds cross-team item 4 and aligns the Division-of-labor line with Lifecycle step 3.
spec/api-gaps/README.md	Adds the event-feed row to the registry table.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

Suppressed comments (1)

spec/api-gaps/event-feed.md:167

• The backtick placement here wraps the entire clause "go/pkg/basecamp/eventfeed wiring follows the bookmarks.go precedent" in a single inline-code span, so the explanatory prose renders as code and bookmarks.go is not distinguished as a path. Scope the code span to just the path(s), as the other bullets in this list do.

     (`go/pkg/basecamp/eventfeed wiring follows the bookmarks.go precedent`)

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[jeremy]

Merging on green: the substantive review coverage is at 9d0d093 (Copilot: no new comments; its one suppressed item duplicated the already-filed thread). The sole finding — inline-code span scoping at event-feed.md:167 — is fixed in 5665152 exactly per the reviewer's suggested wording, and the thread is resolved with the fix commit. Copilot errored on both review attempts of the fix commit (re-requested once per the usual playbook), so the one-line diff rides the prior review plus fully green CI. Post-merge findings welcome as a follow-up.