docs: the export ledger's three watermarks, and a page for stella doctor#718
Merged
Conversation
…ctor` Closes #631. Closes #690. #631 — `enterprise_telemetry/export_ledger.rs` (the path in the issue is stale; the module moved) documented its lifecycle but never stated the three-watermark contract as such. Adds a `# The three watermarks` section naming each floor, what advances it, and what breaks if it moves early or late. The audit declined this on the grounds that the WHY can only be inferred. Nothing here is inferred: every claim is read off the SQL that enforces it. `enrolled_after_execution_id` and `compacted_through_execution_id` are the two `execution_id >` floors in `mark_enterprise_export_pending`'s eligibility check; `after_execution_id` is the keyset cursor in `pending_enterprise_export_page`. Why there are three falls out of their failure modes rather than out of anyone's intent: the two durable floors fail permanently and silently (a silent gap, a back-export, or a double-count once the row holding the nonce is reclaimed), while the cursor's failures are absorbed in both directions by nonce stability plus the spool's dedup — which is exactly why persisting it would be a downgrade, not a safeguard. Two consequences worth having in writing, both derived and neither previously stated: compaction carries a precondition (an execution still unfinished when a cutoff passes its id is refused forever), and the compaction floor gates re-admission only — pending rows survive compaction and still drain. #690 — `stella doctor` shipped with no docs-site page, so `--repair`, which rewrites a user's `store.db`, was discoverable only via `--help`. Adds `commands/doctor.mdx` and registers it in `index.mdx` (23 → 24 rows) and `meta.json`. Covers the single `store integrity` check and its binary verdict, the exit-code contract, and precisely what `--repair` does on disk: that it acts only on a corruption verdict and leaves an inconclusive one untouched, that the db and both sidecars are renamed (never deleted) under one timestamp, that the salvage is a separate copy, and that uncheckpointed WAL pages do not reach it. Verified: `RUSTDOCFLAGS="-D warnings" cargo doc -p stella-store` clean, clippy/fmt/file-size/doc-citations/no-scratch pass, `next build` renders /docs/commands/doctor with the index row and sidebar links wired.
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Sorry @macanderson, you have reached your weekly rate limit of 500000 diff characters.
Please try again later or upgrade to continue using Sourcery
Contributor
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
macanderson
marked this pull request as ready for review
July 26, 2026 18:38
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
1 participant
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.
Closes #631. Closes #690.
Two docs issues from the #622 audit backlog.
#631 — the three-watermark contract
The issue's path is stale: the module moved to
stella-store/src/enterprise_telemetry/export_ledger.rs, and it does now have module docs describing the lifecycle. What it never had is the three-watermark contract stated as such — which is the part the issue actually asks for.The audit declined this on principle, reasoning that the WHY of a three-watermark scheme can only be inferred and that inventing a rationale risks documenting an intent the authors do not hold. That concern is respected here: nothing in this section is inferred from intent. Every claim is read off the SQL that enforces it.
The three are the three monotone
execution_id >floors that govern the module:enrolled_after_execution_idbegin_enterprise_enrollment, oncecompacted_through_execution_idcompact_enterprise_export_ledger, monotonicallyafter_execution_idWhy there are three falls out of their failure modes, not out of anyone's design philosophy. The two durable floors fail permanently and silently — a silent gap, an unconsented back-export, or a double-count once the row holding the nonce has been reclaimed. The cursor's failures are absorbed in both directions by nonce stability plus the spool's dedup on event id. That asymmetry is the whole answer to "why not one watermark", and it is why persisting the cursor would be a downgrade rather than a safeguard.
Two consequences that were not written down anywhere, both derived from the queries:
pending_enterprise_export_pagedoes not consult it and compaction never deletes pending rows, so an already-admitted execution still drains normally.I'd particularly welcome a check on those two, since they're the claims that go furthest beyond restating a doc comment.
#690 —
stella doctoron the docs siteThe code shipped in #685; the page did not.
--repairrewrites a user'sstore.db, and it was discoverable only via--help.Adds
website/content/docs/commands/doctor.mdx, plus theindex.mdxrow (23 → 24) and themeta.jsonsidebar entry.A few things the page states carefully, after reading the source rather than the issue:
store integrity), not a suite, and its verdict is binary — there is no warn state.--repairis the only flag.--output-formatdoes not apply, because doctor dispatches beforeConfig::loadso a broken store stays diagnosable without a working model config.--repairacts only on a corruption verdict; an inconclusive check leaves the store untouched. The db and both-wal/-shmsidecars are renamed under one timestamp (never deleted, undoable withmv), the salvage is a separate copy, and uncheckpointed WAL pages do not reach it — the one genuine sharp edge, called out in a warning callout.Verification
RUSTDOCFLAGS="-D warnings" cargo doc -p stella-store --no-deps— clean (intra-doc links resolve).cargo clippy -p stella-store --all-targets -- -D warnings,cargo fmt --check— clean.check-file-size.sh,check-doc-citations.sh,check-no-scratch.sh— pass.next build— 89 pages;/docs/commands/doctorrenders, and the index-table row and sidebar prev/next links are wired.No lockfile was committed: the website tracks none, so the
package-lock.jsonfrom my localnpm installwas removed rather than introduced as an unrelated change.Docs-only — no behavior change in either crate.