Event-feed conformance families, their gates, and the §23 G-SD repair

[jeremy]

PR 2 of the Event Feed Connector program (#606 filed the registry entry; #614 merged the SPEC §23 contract). This lands the conformance surface the §23 contract is tested against — and the small SPEC §23 repair that closes the G-SD gate reopened by #614's two post-merge findings.

The tier-2 scenario family — conformance/event-feed/

A 22-fixture scenario suite against its own schema (the oauth/oauth-token parallel-family precedent), covering:

• the four acceptance behaviors — fresh-ticket reconnect, confirmation gating, deadline teardown, terminal rejection (01–05)
• reason-level disconnect dispatch: protocol-fatal terminal vs unauthorized fresh-ticket retry vs remote re-mint (06, 07, 17)
• checkpoint-after-handoff and the 410-accepted/resumed path (12, 16)
• present-class entry sequencing against §23's bounded ownership cut: the buffered-lower-id delivery-before-save proof, the post-snapshot straggler boundary (19, 20)
• the semantic-signal handler contract with exact handler-invocation records: overflow and gap, each through no-handler-terminal, accepted, and Terminate dispositions — the invocation records are what make handler-Terminate distinguishable from the no-handler default (21–25)
• continuation security: hostile cross-origin next, hostile 410 resume, and a validated same-origin next answering 302 with a foreign Location — each invalid_continuation with zero requests to the foreign origin (26, 27, 30)
• checkpoint-store failure semantics: load-failure terminal with zero wire attempts (distinct from Missing), save-failure continuing with the observer signal and a subsequent save attempt (28, 29)

The README carries the PROVISIONAL(8be5c67de5) posture: a fixture→server-behavior dependency table (wire literals and semantic rows, each naming its pinning fixtures), the PR-T true-up checklist for BC3's merge-time gate, per-action strictness semantics, the per-SDK consumers table, and the fifteen-mutation kill matrix for the PR-3 reference implementation. Counts are seam calls, never wire attempts.

The digest family — conformance/event-feed-digest/

BC3's published srv1 five-vector table — every digest independently recomputed from the published canonicalization and matching byte-for-byte — plus checkpoint flat-key cases covering origin canonicalization. The srv1 algorithm is total over client-validated inputs; catalog membership is server-owned.

Gates

event-feed-fixtures-check and event-feed-digest-fixtures-check, each metaschema-validating its schema then validating every fixture, wired into .PHONY and as conformance: prerequisites so make check carries them.

Red-first evidence (both captured with REAL_EXIT discipline):

• A deliberately invalid fixture (finally.state terminal without connectCount) fails the gate: RED_REAL_EXIT=2, the fixture named in the output; removed, gate green again.
• A synthetic 409 body missing error is rejected by the schema (NEG_REAL_EXIT=1, 'error' is a required property) — the negative proof for the enriched-409 contract below.

Deliberately no §19/§21/Appendix-D rows for these parallel families — they follow the oauth-family precedent (inventory in the family README + §23's Verification subsection; fixture-schema gates ride the conformance row). The tier-1 event-feed-poll.json takes its rows when it lands with the generated layer.

The SPEC §23 repair (a stated exception to conformance-only — this is the G-SD closure)

#614's final review landed 69 seconds after its merge with two real findings, both bound to this PR (its two threads were left open deliberately and resolve here):

1. CheckpointStore becomes tri-state: load(key) → Loaded(position) | Missing | Failed(error), save(key, position) → Saved | Failed(error). The merged (position, ok)/void shapes could not express the failures §23 dispatches on — checkpoint_load (terminal, zero wire attempts; collapsing Failed to Missing would silently skip history) and checkpoint_save_failed (observer signal, feed continues, no save circuit-breaker).
2. Redirect suppression on the poll seam: prevalidating a continuation does not validate its redirects — the HTTP stacks auto-follow (Go strips Authorization cross-origin but still egresses), which falsified the zero-foreign-egress guarantee. The seam disables auto-follow for PollEvents (or per-hop validates every resolved Location under §8's hop-anchored rule); a failing Location is invalid_continuation with zero egress. Fixture 30 pins it; the kill basis (outcome divergence + the sentinel-listener harness obligation) is stated honestly in the README.

Plus three review-hardening pins that keep the fixtures deterministic: semantic-signal dispatch timing (first consumer-context opportunity; "before the next save" as the outer bound), in-memory position authority within a run (the store is write-through durability only — a failed save never regresses the live cursor; transition 24 and the Cursor comment reconciled), and the terminal table's invalid_continuation row covering failing redirect Locations.

Verification

• Full make check green (REAL_EXIT=0) on the pre-rebase sealed head and re-run green on exactly this rebased head. The run also confirmed check-fixture-coverage/validate-api-gaps are untouched by the new directories.
• The schema went through a freeze gate before fixture authoring: metaschema validation plus a four-lens adversarial review (25 findings, all fixed — including making unauthorized-poll responses, dial outcomes, and observer assertions expressible), then a four-lens assembly review of the committed tree (8 findings, all fixed), then the 409 required-trio repair with its negative proof.
• All 22 fixtures batch-validate against the frozen schema in one run (REAL_EXIT=0); the committed schema is byte-identical to the frozen lineage copy.
• Spec-train census at open: no other open PR touches SPEC.md/COORDINATION.md/Makefile/openapi.json/smithy/api-gaps/conformance.

Merging this closes the reopened G-SD gate and unblocks PR 3 (the Go reference connector, which must go green on all 22 fixtures with each of the fifteen mutants shown red). Fixture freezing still waits on BC3's merge-time gate (8be5c67de5 is a verification record, never the provenance pin); PR-4's reserved fixtures (08–11, 13–15, 18, and the authorization block) land after it.

---

Summary by cubic

Adds event‑feed conformance suites and digest vectors, wires their gates into make check, repairs SPEC §23 around checkpoint failures and continuation safety, and runs the new gates in PR CI.

• New Features

  • conformance/event-feed/: 22 schema‑validated fixtures for acceptance flows, reason‑based disconnects, present‑class entry sequencing, semantic signal handlers, hostile next/resume/redirects, and checkpoint‑store failures.
  • conformance/event-feed-digest/: srv1 digest vectors (independently recomputed) plus checkpoint flat‑key cases.
  • Gates event-feed-fixtures-check and event-feed-digest-fixtures-check added and made conformance prerequisites so make check validates schemas and all fixtures.
  • PR CI now runs event-feed-fixtures-check and event-feed-digest directly so fixture validation is enforced on every PR.

• Bug Fixes

  • SPEC §23: CheckpointStore is tri‑state (load → Loaded|Missing|Failed; save → Saved|Failed) to support checkpoint_load and checkpoint_save_failed.
  • Poll seam suppresses automatic redirect following; cross‑origin continuations/redirects now fail with invalid_continuation and zero egress.
  • New poll seam kind redirect_refused(location_origin): 3xx with a failing Location maps to invalid_continuation (never poll_failed), with origin redacted.
  • Added .gitleaks.toml to allowlist srv1-[0-9a-f]{16} checkpoint filter keys, avoiding false positives in gitleaks on digest fixtures.

^{Written for commit 2fdcc73. Summary will update on new commits.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3b5ab21377

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

This is PR 2 of the Event Feed Connector program. It lands the tier-2 conformance surface that the SPEC §23 connector contract (merged in #614) is tested against, plus a small §23 repair that closes two post-merge findings. It's spec/conformance-data only — no runtime SDK code — so it rides beside the "spec train" legitimately.

Changes:

• Adds conformance/event-feed/ — a 1530-line JSON Schema, a README, and 22 strictly-ordered scenario fixtures covering the four §23 acceptance behaviors, disconnect dispatch, present-class entry sequencing, the semantic-signal handler contract, continuation security, and checkpoint-store failure semantics.
• Adds conformance/event-feed-digest/ — the published BC3 srv1 five-vector table plus checkpoint flat-key cases, with digests independently recomputed and cross-matching the SPEC §23 vector table.
• Wires two new gates (event-feed-fixtures-check, event-feed-digest-fixtures-check) into .PHONY, the conformance: target, and help, so make check carries them; and applies the SPEC §23 repair (tri-state CheckpointStore, in-memory-authoritative cursor, redirect suppression on the poll seam, and semantic-signal dispatch timing).

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 29 out of 29 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
SPEC.md	§23 repair: CheckpointStore becomes tri-state, cursor is in-memory authoritative, redirect suppression on the poll seam, semantic-signal dispatch timing; terminal/table rows updated for redirect Location.
Makefile	Adds the two new fixture-check targets and wires them into .PHONY, the conformance: prerequisite chain, and help — matching the oauth-token precedent.
conformance/event-feed/schema.json	The tier-2 scenario contract: step/seam directives, mint/poll/frame variants, handler-invocation and default-terminal conditionals, finally-state invariants.
conformance/event-feed/README.md	PROVISIONAL posture, strictness semantics, fixture inventory, fixture→server-behavior dependency table, PR-T true-up checklist, and the fifteen-mutation kill matrix.
conformance/event-feed/fixtures/*.json (22 files: 01–07, 12, 16, 17, 19–30)	Scenario scripts proving each §23 behavior; verified against the schema, with correct 9-key push vs 8-key poll event usage and dependency-table/mutation-matrix cross-references.
conformance/event-feed-digest/schema.json	Draft-07 schema for srv1 digest vectors and checkpoint flat-key cases.
conformance/event-feed-digest/README.md	Documents the recomputed-digest claim and the schema-boundary convention.
conformance/event-feed-digest/fixtures/srv1-vectors.json	Five srv1 vectors + three flat-key cases; digests and filter_keys are internally consistent and match SPEC §23's vector table.

I did not find concrete, objective defects to comment on: the schema's allOf/oneOf conditionals are internally consistent, all 22 fixtures conform, the README inventory/dependency/mutation tables match the actual fixtures, the digest fixtures cross-match the SPEC §23 vector table and the filter_key↔digest relationships, and the terminalReason/stateName enums match the SPEC taxonomy with no stale CheckpointStore signature references remaining.

That said, this change modifies a normative spec contract (the tri-state CheckpointStore and redirect-suppression seam behavior) that the forthcoming reference implementation (PR 3) and all six SDKs must honor, it depends on cross-team BC3 provenance that is explicitly PROVISIONAL until BC3's merge-time gate, and it commits cryptographic digest values whose byte-correctness cannot be verified by automated review (only by each SDK's runtime tests). These factors warrant final human sign-off.

---

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

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2cce169db0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

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

Suppressed comments (1)

conformance/event-feed-digest/schema.json:2

• Minor consistency nit: this new schema declares JSON Schema draft-07, but every other conformance schema in the repo — including this PR's sibling conformance/event-feed/schema.json, and the oauth/oauth-token families this README cites as its precedent — uses draft 2020-12. None of the keywords here ($ref, const, type arrays, pattern) behave differently between the drafts, and the $ref has no siblings, so switching to 2020-12 is safe and keeps the sibling families aligned. Optional, but recommended for consistency.

  "$schema": "http://json-schema.org/draft-07/schema#",

[github-actions]

Sensitive Change Detection (shadow mode)

This PR modifies control-plane files:

• .github/workflows/test.yml

Shadow mode — this check is informational only. When activated, changes to these paths will require approval from a maintainer.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2fdcc737b7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

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

Suppressed comments (1)

conformance/event-feed-digest/schema.json:2

• This new digest schema declares JSON Schema draft-07, but every other conformance schema in the repo — including the sibling conformance/event-feed/schema.json added in this same PR, plus conformance/oauth/schema.json, conformance/oauth-token/schema.json, conformance/schema.json, and conformance/tests.schema.json — uses draft 2020-12. The body here uses only features valid in both drafts (const, pattern, type arrays, $ref by JSON pointer), so switching to 2020-12 for consistency is safe and keeps --check-metaschema uniform across the families. This is optional but avoids a surprising per-family draft divergence for future editors.

  "$schema": "http://json-schema.org/draft-07/schema#",

[Copilot]

Pull request overview

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