docs(runtime): freeze T3 delivery→EventFabric cutover design (RIG-3107) - #905
Merged
trunk-io[bot] merged 4 commits intoSep 6, 2026
Merged
Conversation
Design record for T3 PR4: migrate ONLY the delivery work-queue consumer from the in-process comms bus to the NATS JetStream EventFabric (durable, at-least-once, cross-instance). The bus survives for the client gRPC stream and presence; the client-edge migration is T5. Five load-bearing decisions, ratified by Matt (2026-09-05) after a design-critic red-team pass: - OQ-1 ack timing → ack-on-receive (DL-327): the cursor sweep closes the hold-to-fire window exactly as the in-process bus does today. - OQ-2 concurrency → callback-direct under c.mu + per-session gates (DL-328), with scan-vs-hold and bounded-callback/AckWait folded as invariants. - OQ-3 part 1 RLS scope → split (DL-329): system-role sweeps, tenant-scoped per-event processing, tenant-stamped heldEntry; fail-closed on a forged ref. - OQ-3 part 2 recovery → reconnect-hook + periodic floor tick (DL-330). The red-team falsified the draft's mapping (scanMissedMentions routes only mentions; NATS auto-reconnect never fires a re-subscribe trigger), which would have left a publish-failed plain deliver to an always-live agent silently undelivered until its next session restart. - OQ-4 cross-instance → single-instance transitional constraint (DL-331) until parent-T4 durable session bindings land. Also freezes the double-publish-not-a-Global-Constraint-violation interpretation (DL-332) so the T5 bus-retirement inherits it explicitly. Ledger-impact: appends DL-327..332 to docs/designs/DECISIONS.md. Co-authored-by: Matt Wilkinson <matt@rigel.build>
|
😎 Merged successfully - details. |
|
Compass engineering docs preview: https://compass-managed-rig-3107-del.compass-eng-docs.pages.dev Deployed from Changed pages: |
'/home/mattw/.agents/skills/review' pass on #905 returned 2 high, 5 medium, 4 low; all dispositioned (fixed or ruled), gates green. - F1 (high): T2 now names the three bus/afterResubscribe test files it edits in-commit and folds the overrun-branch test deletion into T2, so the package compiles; recovery-trigger (T5) ordered to land in T2's PR. - F2 (high): the ratified reconnect trigger had no seam on the frozen 3-method EventFabric. Surfaced to Matt as an API-shape fork; ruled Option A (add EventFabric.OnReconnect). Stamped + DL-333 appended. - F3/F4/F5/F6/F7/F8/F9/F10 (med/low): swept stale draft phrasing, flipped Status to Active (this is the freeze PR), narrowed T6 (DL rows already landed), regrounded the concurrency citation to nats.go@v1.53.1 + a new fabric serial-callback contract obligation, disambiguated bare cross-record T5 refs, de-hedged T5 Produces, widened two undershooting citation ranges, normalized the `- - ` option bullets. - F11 (low): DL-329 kept in Transport with the cutover's sibling rows. Co-authored-by: Matt Wilkinson <matt@rigel.build>
Round 2 '/home/mattw/.agents/skills/review' on #905 returned 0 high, 2 medium, 3 low; all fixed (both mediums were defects the round-1 folds introduced), gates green. - M1 (med): the round-1 F1 fold named THREE bus/afterResubscribe test files, but package delivery is one compilation unit and eleven test files reference c.bus.*/events.Bus/c.afterResubscribe — incl. the shared newTestConsumer in helpers_test.go and the publishCtxResponse signature in trace_test.go. Replaced the fixed count with the true set stated as a criterion; synced the Tasks checklist mirror. - M2 (med): the round-1 F5/F8 rewrite of T5 dropped its Test-cycle bullet, losing the DL-330 plain-deliver recovery regression test and the start-time-scan test (the checklist still promised them). Restored the bullet with the two orphaned obligations plus an OnReconnect chained-log test. - L1 (low): DL-332's ledger twin still carried the stale "until T5" / "T3->T5" referent F7 corrected in the record; matched it to the record. - L2 (low): rewrapped three reflow-ragged paragraphs. - L3 (low): unified the DL range to DL-327..333 in T6 body + checklist. Co-authored-by: Matt Wilkinson <matt@rigel.build>
Round 3 '/home/mattw/.agents/skills/review' on #905 returned all-clear (0 high / 0 medium / 1 low) — every round-2 fix verified landed and complete, ~40 citations re-grounded exact, whole-record integrity clean. Fold the one low. - L (low): the M1 fix said helpers_test.go and trace_test.go both "name the events.Bus type directly". Exact for trace_test.go (type is in the publishCtxResponse signature) but helpers_test.go names it in a doc comment and CONSTRUCTS one via events.NewBus[...](), passing it to NewConsumer. Reworded to distinguish the two — the eleven-file set and the same-commit-breakage obligation were already exact. Co-authored-by: Matt Wilkinson <matt@rigel.build>
rigel-mintaka
marked this pull request as ready for review
September 6, 2026 00:08
mattwilkinsonn
approved these changes
Sep 6, 2026
trunk-io
Bot
deleted the
compass-managed/rig-3107-delivery-cutover-design
branch
September 6, 2026 04:10
This was referenced Sep 6, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Design record for T3 PR4: migrate ONLY the delivery work-queue consumer
from the in-process comms bus to the NATS JetStream EventFabric (durable,
at-least-once, cross-instance). The bus survives for the client gRPC stream
and presence; the client-edge migration is a separate later effort.
Five load-bearing decisions, ratified by Matt (2026-09-05) after a
design-critic red-team pass:
hold-to-fire window exactly as the in-process bus does today.
with scan-vs-hold and bounded-callback/AckWait folded as invariants.
per-event processing, tenant-stamped heldEntry; fail-closed on a forged ref.
red-team falsified the draft's mapping (scanMissedMentions routes only
mentions; NATS auto-reconnect never fires a re-subscribe trigger), which
would have left a publish-failed plain deliver to an always-live agent
silently undelivered until its next session restart.
until parent-T4 durable session bindings land.
Also freezes the double-publish-not-a-Global-Constraint-violation
interpretation (DL-332) so the eventual bus-retirement inherits it explicitly.
Ledger-impact: appends DL-327..333 to docs/designs/DECISIONS.md.
Co-authored-by: Matt Wilkinson matt@rigel.build