Skip to content

chore: hygiene sweep — backplane projector cleanup, test alignment, council fixes#96

Merged
joaomdsg merged 18 commits into
mainfrom
chore/hygiene-sweep
Jun 9, 2026
Merged

chore: hygiene sweep — backplane projector cleanup, test alignment, council fixes#96
joaomdsg merged 18 commits into
mainfrom
chore/hygiene-sweep

Conversation

@joaomdsg

@joaomdsg joaomdsg commented Jun 9, 2026

Copy link
Copy Markdown
Member

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 catalogue honesty: metrics.go documented a status label on
    via.action.total / via.render.total that no call site emits, and listed 7
    of 24 emitted via.* names. Catalogue now reconciles exactly with the emit
    sites.
  • write-only ls.snapRev: written at 4 sites, read nowhere, with a comment
    claiming it backed the snapshot CAS (it didn't). Removed, shrinking the shared
    logState.
  • vianats sanitize doc/impl mismatch (underscore-escaping invariant) + a
    characterization test locking it.
  • marshalEvent errors now carry a via: origin prefix (TDD).

Structure & organization

  • Renamed the confusingly-named applog* family to stateappevents_* (it's the
    projector runtime behind StateAppEvents, not application logging).
  • Split the 373-line projector source into 7 focused files
    (projector/coldstart/gap/fold/snapshot/canary/compact), each a single concern.
  • Aligned every test file with its source file (one concept per file + its
    test); redistributed the projector test cluster to match.
  • Anchored the projector's single-writer / lock-discipline contract in one
    logState doc-block.

Test hygiene

  • Converted all raw t.Fatal/t.Errorf in vianats and the projector cluster
    to testify.
  • Renamed all vianats + projector-cluster test funcs to the mandated
    Test+Subject_behavior format.

Notes

  • An internal/projector package was considered and rejected: every projector
    function is an *App method woven into App state, so a boundary would force a
    wide speculative interface for no isolation gain. The shared-logState
    coupling is intrinsic to a single-writer fold state machine.
  • HYGIENE.md records every step (including surveyed-and-rejected candidates and
    the council's deferred/rejected items).

Verification: gofmt clean, go vet ./... clean, go test -race ./... green
across via, vianats, viashowcase, and all plugins.

joaomdsg added 18 commits June 8, 2026 17:10
…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.
@joaomdsg
joaomdsg merged commit fba6b07 into main Jun 9, 2026
4 checks passed
@joaomdsg
joaomdsg deleted the chore/hygiene-sweep branch June 9, 2026 08:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant