feat: per-channel initial-state opt-out for reactive-only channels (R-040, D-025) - #9
Merged
Conversation
…nnels Design intake for suppressing the L1 floor on channels with no initial state (error/notification topics), where a synthetic on-subscribe draw can corrupt a stateful client. Resolved via design dialog: topicOverrides.initialState:false, handler-wins-with-warning, four spec-load warnings; allocates D-025/R-040 with the implementation PR.
…s key sweep (R-040)
…ked on refresh (R-040)
…e topics views; pin residue + doctor tolerance (R-040)
…e intake (R-040 tested)
…tatus + guide (R-040) - Resolve topicOverrides.initialState onto toClient Channel records only; a fromClient row can no longer show initialState:false, which previously contradicted the initial-state-on-from-client warning. - Same scope narrowing in mergeRegistries' cross-service check. - Pin the new behavior with a registry test on a dual-direction address. - contracts.md §1: note the toClient-only scope in the field comment. - AGENTS.md: refresh the Status & next count (38 of 40) and mention the R-040/D-025 initial-state opt-out. - wiring-your-service.md §7: add the EQ5 breadcrumb bullet the intake required.
…; toClient-scoping doc sweep (R-040)
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
1 participant
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.
What
topicOverrides.<address>.initialState: falsein services.yaml declares a reactive-only channel (error/notification topics): the L1 floor never materializes initial state there, on any leg (concrete subscribe, eager startup,seedInstances,resetrepublish), while the instance ledger, L2/L3 emissions, wildcard retained replay, and the explicit example surfaces stay untouched.Fixes the class of bug where a stateful client's state machine is corrupted by a synthetic schema-valid example arriving on a topic that should be silent until something real happens (a real broker delivers nothing on subscribe to a non-retained topic).
Design decisions (docs/archive/intake/2026-08-01-initial-state-optout.md, D-025)
initialStatevocabulary: the flag ridestopicOverrides(F14 keying) and mirrors the L3initialStatehook by name; resolved ontoChannel.initialState(toClient records only).initialStatehandler on a flagged channel still runs; the compose root warn-logs the contradiction and re-checks afterPOST /v1/specs/refresh.spec-loadwarnings —override-dangling-key,initial-state-on-from-client,initial-state-non-boolean,initial-state-cross-service. The cross-service warning names the trueregistry.matchwinner: a same-address fromClient record can win, in which case the floor never runs there and every initialState declaration is dead — the warning says which case applies.GET /v1/topicscarriesinitialState: falseonly when suppressed (survives?schema=false); the CLI topics views mark[no initial state].reset(contracts §2/§5 caveats + test); the flag is boot-time-only; the F21 cache-key invariant is commented at the cache site.Doc system
R-040
tested(7 arrow-tagged test files), D-025 appended, contracts §1/§2/§5/§6 + design §7a amended, wiring guide §7 added, intake item resolved and archived. A two-axis review pass (standards + spec-vs-intake) is folded in: the cross-service warning winner fix and the toClient-scoping doc sweep (D-025/R-040 statements, model comment, plan Deviations) landed as the head commit.Testing
Full gate set at head: check-docs, lint, typecheck all exit 0;
bun test454 pass / 0 fail (exit 0). New coverage: registry resolution + all four warnings (incl. dual-direction, same-service-disagreement, and fromClient-match-winner cases), engine gate on all legs, handler-wins, compose contradiction warn-log incl. refresh re-check, /v1/topics field presence/absence on the wire, retained-residue-across-reset, doctor tolerance.