Skip to content

docs: rewrite the README top-down around use cases - #275

Open
lan17 wants to merge 2 commits into
mainfrom
docs/readme-top-down
Open

lan17 wants to merge 2 commits into
mainfrom
docs/readme-top-down

Conversation

@lan17

@lan17 lan17 commented Nov 12, 2026 •

Copy link
Copy Markdown
Owner

Problem

The README opened with a feature list and a language table, and the one example showed only process-local caching. A reader had to go to docs/ to learn the point of DialCache: caching organized into use cases, each with its own runtime configuration, metrics and invalidation. Discussed with the maintainer; no issue.

Change

Rewrite README.md top-down. Docs change type; no design record, no behavior changes.

  • Pitch first. What DialCache is, then what each registered use case gets: configuration (layers, TTLs, ramps, changed at runtime), metrics (labeled by use case and layer) and invalidation (one call per keyType and id). Safety defaults in one paragraph.
  • One example. Registers GetUser with Redis configured but ramped to 0, reads inside enable(), then invalidates after a write. The text after it shows the metric lines the example produces, the runtime override ({ "ramp": { "remote": 10 } }) that starts Redis serving without a deploy, and what the invalidation call fences, including that local layers are not fenced.
  • Safe to roll out. Off by default, fail-open, coalescing, stale-on-error and shadow validation as one-line items.
  • Languages, install, read path, documentation map, development. Kept, in that order; the status column replaces the dash notes in the language table; coverage and Scorecard badges moved to Development.
  • Short sentences in the style of ASD-STE100 throughout.

Published anchors (changing-policy-at-runtime, enabled-scope, cache-layers, reference) stay in place. The source audit re-keys the README; the new Example, Safe to roll out and Languages sections get contract dispositions (C01/C05/C16/C18/C32/W01, C01/C13/C17/C27/C40/C47 and B01), and the Go parity ledger re-pins the dispositions digest. The README now has eight sections instead of seven, so the section count quoted in formal/guides/course/13-catalogs-and-ledgers.md moves from 216 to 217 (the quint CI lane checks that quote).

Choices a reviewer may want to reverse: the example keeps a 60 s local TTL next to the invalidateRemote call, and the note says local hits are not fenced; the pitch keeps its second paragraph (off by default on the first screen) although the simplicity review lane suggested deleting it; the former Usage and Runtime control sections are folded into the example and its notes.

Validation

Head: a79cdc5fe065b2ac84a83619d5ce7358fc0dc8bb

  • node formal/tools/validation.mjs audit (the full make audit lane: source audit, semantic coverage, feature coverage, Go parity, fixture fingerprints, Quint style caps, course citations, generated views) at a79cdc5: passed

  • node formal/tools/check-source-audit.mjs at a79cdc5: passed

  • node formal/tools/check-go-parity.mjs at a79cdc5: passed

  • corepack pnpm run docs:check at a79cdc5: passed (ports: 4, imports: 12, formalLinks: { pages: 56 })

  • corepack pnpm vitest run test/formal-source-audit.test.ts (typescript/) at a79cdc5: 23 passed

  • review-loop, report mode (correctness, simplicity, contracts, holistic) at 2042a62: 3 medium findings fixed in fff12cb (invalidation note no longer promises a source read on the next call and names the futureBufferMs argument; fail-open bullet distinguishes provider errors from invalid fields); 1 low finding (delete the pitch's second paragraph) not applied; see Change.

Not run: none required for a Docs change beyond PR CI.

Follow-ups

None filed. Worth a separate look: the README.md row of the source index in formal/guides/CONTRACTS.md lists neither the contracts assigned here (C13, C27, C32, C40, C47) nor C31, which the previous README already carried.

@codecov-commenter

codecov-commenter commented Nov 12, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.80%. Comparing base (995c629) to head (a79cdc5).

Additional details and impacted files
@@           Coverage Diff           @@
##             main     #275   +/-   ##
=======================================
  Coverage   94.79%   94.80%           
=======================================
  Files          84       84           
  Lines       13199    13199           
  Branches      805      805           
=======================================
+ Hits        12512    12513    +1     
+ Misses        621      620    -1     
  Partials       66       66           
Flag Coverage Δ
go 94.06% <ø> (+0.04%) ⬆️
python 93.60% <ø> (ø)
rust 94.78% <ø> (ø)
typescript 97.21% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@lan17
lan17 force-pushed the docs/readme-top-down branch 2 times, most recently from 1686988 to fff12cb Compare November 12, 2026 06:03

lan17 commented Nov 12, 2026

Copy link
Copy Markdown
Owner Author

Agent: review-loop (report mode; lanes: correctness, simplicity, contracts, holistic two-stage) on 2042a62; fixes landed in fff12cb.

Fixed (medium)

  • Invalidation note promised "the next read goes to the source". Coalesced callers can inherit a Redis observation made before the invalidation, and the example used the zero default futureBufferMs without saying so (docs/invalidation.md, "Choosing futureBufferMs" and "Independent fence checks"). Now: the example passes a named application-owned buffer; the note states the boundary as the watermark on the next Redis read and names the local-hit and in-flight exceptions, with a link. (correctness, contracts, holistic; stage two tightened the in-flight wording to the invalidation, not the source write.)
  • "Fail-open" bullet said a configuration error runs the loader. Provider errors run the loader uncached; an invalid field disables only its layer or feature while valid layers continue (docs/configuration.md "Provider behavior", docs/api.md "Validation and snapshots"). Reworded. (contracts, holistic)

Open question for the maintainer (low)

  • simplicity: delete the pitch's second paragraph because "Safe to roll out" repeats it. Left in place; listed under Open questions in the description.

Noted, not changed

  • formal/guides/CONTRACTS.md source-index row for README.md does not list the contracts assigned here (nor C31, which the old README already carried). Listed under Follow-ups.

Local checks at fff12cb: source audit, Go parity, docs:check and the formal-source-audit vitest pass. PR CI pending.

— Levicus Connecto 🤖

@lan17
lan17 force-pushed the docs/readme-top-down branch from fff12cb to 594e6b7 Compare November 12, 2026 06:17
@lan17
lan17 marked this pull request as ready for review November 12, 2026 06:30
Lead with what DialCache is and what each registered use case gets:
runtime configuration, metrics and invalidation. Follow with one
TypeScript example that shows all three, the rollout safety properties,
the language table, install, the read path and the documentation map.

Re-key the README in the source audit and assign contracts to the new
Example, Safe to roll out and Languages sections; re-pin the audit
dispositions digest in the Go parity ledger; update the section count
quoted in the catalogs lesson of the course.
@lan17
lan17 force-pushed the docs/readme-top-down branch from 594e6b7 to 8fe72f5 Compare November 12, 2026 06:32

This branch has not been deployed

No deployments
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.

2 participants