Skip to content

README.md

Latest commit

 

History

History
96 lines (69 loc) · 3.42 KB

README.md

File metadata and controls

96 lines (69 loc) · 3.42 KB
Raw

JoyRide Documentation

Documentation map for LUMI's typed execution cache.

JoyRide docs follow the layered structure used by mature cache systems (Turbo task cache, Nx computation cache, Bazel action cache, Redis operations manuals): Concepts → How it works → Reference → Operations.

Reading paths by role

Role Start here Then read
Executive / PM Brief Philosophy §P1–P3
Architect / reviewer Philosophy Whitepaper · Caching model
Contributor CONTRIBUTING.md Caching model · API
Operator / support OPERATORS.md Troubleshooting
Auditor / security Whitepaper §13 Philosophy §9 · Contract

Document catalog

Concepts (why)

Document Description
Brief One-page executive summary — problem, solution, guarantees
Philosophy Design principles, rejected alternatives, industry lineage
Glossary Canonical terminology (cache vs memory vocabulary)

How it works (what happens)

Document Description
Caching model Inputs → hash → hit/miss flow (Turbo/Nx-style)
Whitepaper Full technical specification with appendices

Reference (API and vocabulary)

Document Description
API reference Frozen public surface, lookup/store matrix
Contributing guide Hot path workflow, tests, PR checklist
Package README Quick start, module map
LICENSE MIT — Copyright CardSorting
JoyRideReasonCodes.ts Stable JOYRIDE_REASON vocabulary (source of truth)
JoyRideContract.ts Export/import contract (source of truth)

Operations (run and debug)

Document Description
Troubleshooting Symptom → cause → action runbook
OPERATORS.md Config, diagnostics, disable
RELEASE-NOTES.md GA changelog
LUMI_INTEGRATION.md LUMI monorepo embedding

Documentation conventions

Following patterns from Turbo, Nx, and Redis docs:

  1. Cache, not memory — operational vocabulary only; no anthropomorphic terms
  2. Inputs define reuse — document what goes into keys and validation fingerprints
  3. Explicit hit/miss/stale — never imply boolean cache semantics
  4. Fail-closed defaults — document what is refused before what is allowed
  5. No UI assumption — observability through logs, snapshots, and tests
  6. Contract-tested claims — guarantees in docs map to test suites

Status

Metric Value
API status GA — modern-only, frozen exports
Test suites 179+ unit tests (npm run test:unit -- --grep "JoyRide")
Public entrypoint @core/joyride
Implementation src/core/joyride/
License MIT — CardSorting

Quick links

# Run JoyRide tests
npm run test:unit -- --grep "JoyRide"

# Disable JoyRide instantly
JOYRIDE_MODE=disabled code .

# Diagnostics-only (observe without skipping)
JOYRIDE_MODE=diagnostics-only code .