chore: hygiene sweep — backplane projector cleanup, test alignment, council fixes#96
Merged
Conversation
…ctor startProjector mixed a ~50-line inline snapshot cold-start switch with the reconnect/fold goroutine. Extract the cold-start into coldStartFrom(ls, key), so the goroutine reads as tail -> fold -> fan out. Behavior preserved on every branch (halt cases still return the snapshot's covered offset).
…aping
The sanitize doc claimed the passthrough set was [A-Za-z0-9_-], but '_' is the
escape delimiter and is itself escaped to _5f_ — otherwise key "a_b" collides
with the encoding of "a.b" (a_2e_b). Fix the comment to [A-Za-z0-9-], explain
why '_' is escaped, and add a characterization case ("a_b" -> "a_5f_b") that
pins the invariant against a future switch "simplification".
All 6 vianats test functions used freeform names; rename to the mandated Test + Subject + _ + camelCase-behavior form so each reads as a behavioral claim. Pure rename, no behavior change.
embedded_test.go (and its startEmbeddedJetStream helper) and sanitize_internal_test.go used raw t.Fatalf/t.Errorf, which CONVENTIONS forbids. Convert to require/assert (require for preconditions, assert for behavioral claims) and check the previously-discarded second Publish error. Test-only.
marshalEvent is StateAppEvents.Append's documented error surface but returned bare json.Marshal/keystore/encrypt errors, against the CONVENTIONS origin-prefix rule. Wrap all failure paths once via a named-return defer (via: marshal event:, %v not %w). ErrClosed from the backplane bypasses marshalEvent so errors.Is still matches.
…churn Tick-6 survey found no substantive hygiene item; record the surveyed-and- rejected candidates (best-effort reconcile error swallowing, reconcile near-duplication, deferred request-context wiring) so a future sweep does not re-litigate them.
applog.go read like application logging (it collides with log.go, the slog adapter) but is actually the per-key projector runtime behind the public StateAppEvents handle. git mv the whole applog* family to bind to the public concept and unify with the existing stateappevents_runtime_test.go: applog.go -> stateappevents_projector.go applogsnap.go -> stateappevents_snapshot.go applogmigrate.go -> stateappevents_migrate.go applog*_internal_test.go -> stateappevents_<concern>_internal_test.go Pure rename (package unchanged); update two live cross-reference comments in vianats to the new filename.
Each _test.go should correspond to a same-named source file (one
concept/responsibility per file + its test). Merged same-package scenario test
files (goimports reconciled imports; no duplicate-declaration risk as they
already shared the package) and renamed drifted ones. Internal (package via) vs
external (package via_test) tests kept as separate files sharing the base name.
Key moves:
marshalevent_internal_test.go -> stateappevents_internal_test.go
ctxr_test.go -> ctx_test.go
eventupcaster_internal_test.go -> eventenvelope_internal_test.go
queue_order_test.go -> action_test.go
8 projector scenario tests -> stateappevents_projector_internal_test.go
stateappevents_runtime_test.go -> stateappevents_projector_test.go
sse_{brotli,liveness}_test.go -> sse_test.go
sse_recover_test.go -> recover_test.go
backplane_{crosspod,*,reconcile,wire}_test.go -> backplane_test.go
sess_{adopt,change}_internal_test.go -> sess_internal_test.go
vianats conformance/embedded/epoch -> vianats_test.go
vianats sanitize_internal_test.go -> vianats_internal_test.go
picocss/maplibre/echarts/vt/showcase test renames
Left legit standalone tests (benchmarks, integration/e2e, helpers, Go examples,
cross-cutting protocol tests like shape/patch/csp_push/h-render) as-is. gofmt
clean; go vet + go test -race green across all modules.
stateappevents_projector.go did four jobs in 373 lines. Split into focused
files (package unchanged; functions share the logState struct, not control flow,
so this is a clean file split, not a leaky abstraction):
stateappevents_projector.go lifecycle: logState, registerLog, startProjector,
shuttingDown, logProjection
stateappevents_coldstart.go cold-start snapshot seeding: coldStartFrom,
seedFromSnapshot, haltUnbridgeable, haltErasure
stateappevents_gap.go gap classification: applyRecord, classifyGap, gapClass
stateappevents_fold.go the fold: projectRecord
Tests untouched this commit (redistribution follows); go vet + go test -race green.
…tests Carve two more concerns out of snapshot.go so each has its own file and matching test (consistent with the projector split): stateappevents_canary.go emitFoldDigest (cross-pod fold-divergence canary) stateappevents_compact.go maybeCompact (snapshot-FIRST/compact-SECOND reclaim) Redistribute the 1262-line merged projector test (42 funcs) to mirror the sources, with shared doubles/helpers in one stateappevents_helpers_test.go: canary_internal_test.go FoldDigest* (4) compact_internal_test.go Compact*/AutoCompacts/SnapshotOnly (6) coldstart_internal_test.go FreshProjectorColdStarts (1) gap_internal_test.go gap classification + reseed/halt (13) fold_internal_test.go epoch reset, foldVerify, determinism, fuzz (6) projector_internal_test.go lifecycle: rehydrate/shutdown (4) snapshot_internal_test.go += SnapshotWriteNeverRegresses (8 total) Every source file now has a matching test; all land at/under the ~300-line guideline (helpers_test.go excepted as test infra). Same 42 test funcs, none lost/duplicated; gofmt + go vet + go test -race green.
The catalogue documented a 'status' label on via.action.total / via.render.total that no call site emits (action.go emits method, render.go emits route), and listed 7 of the 24 emitted via.* names. Rewrite it to the full grouped set and drop the phantom labels. Doc-only; documented names now reconcile exactly with the emit sites.
ls.snapRev was written (seedFromSnapshot, setSnapRev x3) but read nowhere; its comment claimed it backed the snapshot CAS, but writeSnapshot CASes against a freshly-read curRev. Delete the field, setSnapRev, seedFromSnapshot's now-unused rev param, and the dead rev-resync LoadSnapshot on the CAS-conflict path. No reads existed, so no observable behavior change; shrinks the shared logState.
12 raw t.Fatal/t.Fatalf sites across the projector test cluster violated CONVENTIONS. Append/CAS guards -> require.NoError; hang/timeout/child-output failures -> require.FailNow. Test-only, no raw t.Fatal remain.
The 4 TestColdStart* funcs (testing coldStartFrom) lived in snapshot_internal_test.go, breaking the 1:1 test<->source mapping. Move them to coldstart_internal_test.go and relocate their shared helper writeContrivedSnapshot (used only by coldstart + migrate) to helpers_test.go. Test-only.
52 cluster test/fuzz funcs used freeform names instead of the mandated Test + Subject + _ + camelCase-behavior format. Rename all, grouped by subject. Pure rename (test funcs have no internal callers); count unchanged, green.
…gState The source split scattered the single-writer / ls.mu / I-O-outside-the-lock invariant across projector/gap/fold/compact as partial restatements. State it once authoritatively on the logState type and reduce the three scattered restatements to back-pointers. Doc-only.
The merged projector test file held 35 funcs (34 Test + 1 Fuzz), not 42 — the 42 conflated it with snapshot's pre-existing 7. Reword to accurate numbers.
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
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.
Code structure & hygiene sweep focused on the StateAppEvents backplane projector
(introduced in #95), plus a council-charted defect pass. No public API changes;
all work is refactors, file/test reorganization, doc accuracy, and two real
defect fixes.
Defect fixes
metrics.godocumented astatuslabel onvia.action.total/via.render.totalthat no call site emits, and listed 7of 24 emitted
via.*names. Catalogue now reconciles exactly with the emitsites.
ls.snapRev: written at 4 sites, read nowhere, with a commentclaiming it backed the snapshot CAS (it didn't). Removed, shrinking the shared
logState.vianatssanitizedoc/impl mismatch (underscore-escaping invariant) + acharacterization test locking it.
marshalEventerrors now carry avia:origin prefix (TDD).Structure & organization
applog*family tostateappevents_*(it's theprojector runtime behind
StateAppEvents, not application logging).(projector/coldstart/gap/fold/snapshot/canary/compact), each a single concern.
test); redistributed the projector test cluster to match.
logStatedoc-block.Test hygiene
t.Fatal/t.Errorfinvianatsand the projector clusterto testify.
vianats+ projector-cluster test funcs to the mandatedTest+Subject_behaviorformat.Notes
internal/projectorpackage was considered and rejected: every projectorfunction is an
*Appmethod woven into App state, so a boundary would force awide speculative interface for no isolation gain. The shared-
logStatecoupling is intrinsic to a single-writer fold state machine.
HYGIENE.mdrecords every step (including surveyed-and-rejected candidates andthe council's deferred/rejected items).
Verification:
gofmtclean,go vet ./...clean,go test -race ./...greenacross via, vianats, viashowcase, and all plugins.