registrystack / registrystack/registry-stack

Casework docs: reconciliation interval is stated inconsistently and its effect on reads is not explained

Open
#1,081 0 comments 0 reactions 0 assignees View on GitHub
area:casework area:docs criticality:p3 documentation needs-jeremi-decision
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.