Skip to content

SPEC §23: the Event Feed Connector contract #614

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jeremy merged 13 commits into from
Aug 3, 2026
Merged

SPEC §23: the Event Feed Connector contract #614

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
4f0cc49
SPEC §23: the Event Feed Connector contract
jeremy Aug 3, 2026
04479b5
Address the #614 review: poll-error passthrough, poll-only reset curs…
jeremy Aug 3, 2026
34948f3
Address the #614 re-review: counter reset, present fallback, mint pas…
jeremy Aug 3, 2026
708f312
Address the #614 third round: dial lifecycle, state-generic terminals…
jeremy Aug 3, 2026
38f1150
Address the #614 fourth round: bounded cut, cancellable typed dial
jeremy Aug 3, 2026
41fedf6
Address the #614 fifth round: dequeued-frames bound, seam cancellation
jeremy Aug 3, 2026
d743061
Address the #614 sixth round: frame-violation disposition, byte-corre…
jeremy Aug 3, 2026
ba7dee5
Address the #614 seventh round: total srv1, in-read frame cap, archit…
jeremy Aug 3, 2026
eb55717
Address the #614 eighth round: pump-side reset, Draining carve-out, 1…
jeremy Aug 3, 2026
8a298ee
Address the #614 ninth round: staleness suspension, invalid-frame clo…
jeremy Aug 3, 2026
654959e
Address the #614 tenth round: evaluation-rule suspension, TS read-lim…
jeremy Aug 3, 2026
db2ef02
Address the #614 eleventh round: teardown cancels in-flight seam calls
jeremy Aug 3, 2026
7fb45af
Address the #614 twelfth round: Clock scope, interruptible writes, ca…
jeremy Aug 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,9 @@
All six SDKs (Go, TypeScript, Ruby, Swift, Kotlin, Python) share one architecture:
**Smithy spec -> OpenAPI -> generated services.** Every wire operation is generated. The
only hand-written runtime API methods are sanctioned composites calling generated wire
methods exclusively -- see SPEC.md §18 "Hand-Written Composite Methods".
methods exclusively -- see SPEC.md §18 "Hand-Written Composite Methods" -- plus one
sanctioned non-HTTP wire act: the SPEC.md §23 Event Feed connector's cable dial of the
URL a generated `CreateStreamTicket` call returned (Hard Rule 2 below).

---

Expand Down Expand Up @@ -65,7 +67,7 @@ When verifying API response shapes, check Go generated code in `go/pkg/generated
### Never Do These

1. **NEVER edit files under `*/generated/`** — they get overwritten by generators. Four files under `generated/` are not generator-emitted and are the ONLY exceptions: three hand-written base files, edited like any other infrastructure file — `python/src/basecamp/generated/services/_base.py`, `python/src/basecamp/generated/services/_async_base.py`, `ruby/lib/basecamp/generated/services/base_service.rb` — plus the empty package marker `python/src/basecamp/generated/__init__.py`. The `generated/services/__init__.py` next to the Python base files IS generated.
2. **NEVER add hand-written service methods that touch the wire** — all wire operations come from generators. The sole exception is a conformance-tested composite that only calls generated wire methods and satisfies SPEC.md §18 "Hand-Written Composite Methods"
2. **NEVER add hand-written service methods that touch the wire** — all wire operations come from generators. Two sanctioned exceptions: a conformance-tested composite that only calls generated wire methods and satisfies SPEC.md §18 "Hand-Written Composite Methods"; and the SPEC.md §23 Event Feed connector's cable dial — `CableTransport.dial(mint.url)`, connecting verbatim to the URL a generated `CreateStreamTicket` call returned. That dial is the connector's one non-HTTP wire act; every HTTP exchange it makes still flows through generated operations behind its `TicketMinter`/`PollSource` seams (§23 "Classification: Infrastructure, Not a Composite")
Comment thread
jeremy marked this conversation as resolved.
3. **NEVER skip running `make smithy-build` after Smithy changes** — keeps OpenAPI in sync
4. **NEVER construct API paths manually** — use the generated client methods
5. **NEVER bypass the SDK** — no raw `client.Get()`, string-concatenated URLs, or internal method calls
Expand Down
Loading
Loading