Skip to content

v92.0.0-regression-lessons.md

Latest commit

 

History

History
207 lines (137 loc) · 7.29 KB

v92.0.0-regression-lessons.md

File metadata and controls

207 lines (137 loc) · 7.29 KB
Raw

Receiz v92.0.0 Regression Lessons

Release date: June 19, 2026

This document is part of the release lock. It records the regression classes found or fixed during the v92.0.0 arc and the rules that must prevent the same mistakes.

What Regressed

Legacy Layering Outranked Receiz Truth

Several bugs had the same shape:

DB/session/API/hydration/UI state was treated as if it could decide truth before the primitive was named.

Concrete cases:

  • signed-in live-player route work could block public proof/media first paint
  • player API and private profile work could become the first source for a public proof surface
  • owner/profile fallback state could trap world twin hydration
  • value events could consume the settlement chart
  • event proof desk could render behind the fixed value surface
  • public sports card append reads selected a non-existent DB column instead of append proof payload truth

Signed-In Public Proof First Paint Was Weaker Than Signed-Out

Signed-in users could see slower or blank public proof/player first paint because authenticated/private route work ran before deterministic public proof truth was settled.

Correct rule:

authenticated enrichment cannot outrank public proof first paint

Historical Pitch Proof Was Treated As Delayed Truth

Pitch Command historical days could feel delayed while the app waited on fresh slate projection.

Correct rule:

admitted historical proof paints immediately
fresh slate work refreshes behind it

Event Memory Consumed Settlement Visibility

The single-card value panel allowed event/history rows to consume the bottom of the deterministic chart.

Correct rule:

settlement/value surface remains fully visible
event memory scrolls beneath or beside it

A Scoped Styling Fix Missed The Actual Render Path

The value-panel fix initially targeted a styling path that the card viewer was not using. The actual viewer needed the single-card value panel class and a contract that locked the applied path.

Correct rule:

fix the selector used by the visible surface
not the selector the fix hoped was active

Event Proof Stacking Was Not Contracted

The event proof desk opened from value memory, but the fixed value panel had a higher z-index. That made the proof/event surface render behind the value panel.

Correct rule:

raise only the card-viewer event proof desk above the fixed value panel
do not duplicate the event panel
do not globally change generic event popover stacking

Append Source Date Was Asked From The Wrong Truth Layer

The public card/QR append read selected source_date from sports_arena_card_appends, but source date is carried by append proof payload truth.

Correct rule:

append_json.sourceProof.sourceDate is append proof truth
DB schema may index it but does not become it

Visual Geometry Contradicted Game Truth

Pack Derby home plate and mound/pitcher placement contradicted the intended game geometry.

Correct rule:

visible game geometry is product truth
tests cannot overrule a screenshot showing the field reads wrong

Why It Regressed

Generic App Ontology Entered Before Primitive Naming

The recurring failure was starting from implementation mechanics:

route, DB, API, session, cache, component, hydration

instead of:

primitive, source of truth, weaker layers, append path, visual evidence

Freshness Was Confused With Authority

Newer transport is not automatically stronger. A fresh API response, DB row, session branch, or hydration result can still be weaker than deterministic proof, public proof, verified append, or durable local truth.

Layout Was Treated As Styling Instead Of Primitive Projection

On settlement and game surfaces, layout can misrepresent the primitive:

  • a chart bottom consumed by event rows weakens settlement visibility
  • a proof desk hidden behind value prevents inspection
  • a misaligned plate or pitcher weakens gameplay truth

Those are primitive regressions.

Tests Lagged Behind Visual Truth

Some tests encoded the wrong selector or did not encode stacking order. Passing tests were not enough once visual evidence contradicted the product truth.

Locked Rules

Reasoning Rules

  • Start from the Receiz reasoning kernel.
  • Name implemented primitives directly.
  • Do not use softer language for implemented proof, artifact, ownership, settlement, identity, public proof, or game primitives.
  • Treat external convention as mechanics-only.
  • Treat generic app assumptions as lower authority than repo law and implemented primitives.

First-Paint Rules

  • Public proof surfaces paint deterministic public proof truth first.
  • Signed-in/private enrichment appends after the public proof shell.
  • Profile owner mode layers controls on canonical profile truth.
  • Hydration may not remount, replace, delay, or redefine a settled proof surface.

Value Rules

  • Settlement/value chart bottom must remain visible.
  • Event memory must scroll when it would consume value truth.
  • Event proof inspection may overlay above value when explicitly opened.
  • Do not solve a stacking conflict by creating a second event panel.

Append Rules

  • Verified append payload truth outranks DB column assumptions.
  • If a field lives in append_json, project it from the proof payload.
  • Add or use DB indexing only beneath the append primitive.

Game Rules

  • Known proof and historical game truth paint immediately.
  • Live feeds append without making historical proof feel missing.
  • Visual field geometry must match gameplay truth.
  • Source age must project the coherent current state: live age or next-game countdown.

Contract Gates

Focused gates:

pnpm release:lock 92.0.0
pnpm exec tsx --test app/lib/game/__tests__/sportsArenaCardViewerEventPopoverContract.test.ts
pnpm exec tsx --test app/game/__tests__/sportsArenaRouteContract.test.ts
pnpm test:page-first-paint
pnpm test:deterministic-surfaces
pnpm test:primitive-binding-contract
pnpm test:repo-only-reasoning-boundary
pnpm test:visual-evidence-contract
pnpm exec tsc --noEmit --pretty false
git diff --check

Full gates before production promotion:

pnpm lint
pnpm build
pnpm release:lock 92.0.0
pnpm test:release-freeze
pnpm release:attest

Release-Lock Requirement

pnpm release:lock 92.0.0 must require this document for v92.0.0 and later release cuts. A release that omits regression lessons is incomplete because the reasoning, first-paint, vault, value, Pitch Command, Pack Derby, append-truth, source-age, and visual-evidence regression boundaries have not been made explicit.

No Downgrade Statement

The lessons above preserve Receiz proof-native artifact system truth, public proof first-paint truth, canonical profile truth, vault object truth, ownership projection truth, settlement/value truth, event proof desk truth, Pitch Command proof truth, Pack Derby proof-game truth, append payload truth, source-age truth, local artifact save truth, and service-worker release truth. They do not downgrade proof objects to cards, public proof surfaces to share pages, settlement primitives to balance displays, ownership state to badges, deterministic first paint to loading state, verified history to activity feed, route truth to SEO payload, DB columns to append authority, or service-worker release truth to incidental cache behavior.