registrystack / registrystack/registry-stack
Casework docs: reconciliation interval is stated inconsistently and its effect on reads is not explained
- Dominant language
- Rust
- Stars
- 2
- Forks
- 0
- Avg merge
- 2h 57m
- Merged PRs (30d)
- 128
Description
## Use Case
A developer runs Casework beside a BREG source, either through `caseworkctl dev` or from their own launcher, and needs to know how quickly Casework repairs events it never received.
## What we hit
- `products/casework/DEV-SOURCES.md` says Casework reconciles active source requests "on startup and every minute", while `caseworkctl dev` renders `reconciliationIntervalMilliseconds: 5000`. The operate guide gives the runtime default (60000, range 1000 to 3600000). A reader of the dev guide gets the wrong number for the dev session and the right one for any runtime they write themselves, without being told they differ.
- Neither page says what the interval means for callers: while an event is missed, reads of an item whose source binding moved are refused until the next pass (#1075). Choosing the interval is choosing that window.
- A launcher that supervises Casework itself (because it owns the host and Casework process, next to a `bregctl dev` session) has to hand-write the runtime. Nothing ships the values `caseworkctl dev` uses, so two writers drift. One such launcher kept the 60 s default while `caseworkctl dev` used 5 s, and its missed-event proofs failed on that difference alone.
## Proposed Behavior
1. Fix `DEV-SOURCES.md` to state the interval the dev session actually renders, and link the runtime default.
2. In `RUNTIME-CONFIG.md` and the operate guide, say that the interval bounds how long a missed source event leaves affected items unreadable, with the recommended development value.
3. Decide whether `caseworkctl` should offer a supported way to obtain its development runtime values for an external supervisor (for example a rendered example runtime in `caseworkctl dev start --format json` output, or a documented "development defaults" block), or state that external launchers own those choices.
## Boundaries
- Documentation first; point 3 is a decision, not a commitment to a new command.
Contributor guide
Research direction
Read products/casework/DEV-SOURCES.md and RUNTIME-CONFIG.md, then locate the operate guide and the caseworkctl dev rendering. Align the documented development and runtime intervals, explain the unreadable-read window, and resolve or document how external supervisors obtain or own development values. Done when the three documentation areas agree and the external-launcher decision is explicit.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- cli, documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 72/100