Add a disposable projection-replay recovery walkthrough #676

Activity

1. woksin

   self-assigned this

   on Nov 2, 2026
2. cratis-direct

   added the

   Bug

   issue type on Nov 2, 2026
3. woksin commented on Nov 2, 2026

   

   woksin

   on Nov 2, 2026

   CollaboratorAuthor

   More actions

   Implementation design (rev 1)

   Base: f3234f8 (main, 2026-11-02)
   Status: proposed
   Size / release intent: M · minor
   Reviewed: independent Claude reviewer — dedicated learning gap and released replay API confirmed

   Problem and root cause

   The catalog's diagnosis exercise intentionally excludes replay. Chronicle19.115.3 already exposes projection Replay methods returning JobId; a separate rebuilding walkthrough is absent.

   Approach

   Add a small separate OperationsRecovery application using deterministic facts and one side-effect-free projection. Demonstrate explicit replay request, bounded completion observation, and rebuilt-state verification. Leave diagnosis-only behavior intact.

   Steps

   1. Drift-check catalog/solution/diagnosis infrastructure and verify selected Chronicle release APIs.
   2. Add separate application/spec project and disposable local-store setup, with a guard against arbitrary administrative targets.
   3. Seed known facts, establish projected output, request replay and observe the returned JobId through supported published APIs until completion or bounded timeout.
   4. Assert rebuilt output, expose useful failure diagnostics, and document cleanup.
   5. Register catalog/solution/CI and link operating guidance without editing Chronicle#4021.

   Files to touch

   New Chronicle/OperationsRecovery/ application, specs, README and local configuration; Samples.slnx, samples.json, relevant CI project registration.

   Public API, compatibility, migration

   No product API change. Use existing consumer projection APIs, not invented observer methods or internal kernel contracts.

   Performance

   Tiny deterministic fixture; bounded polling and container deadlines. Do not busy-loop or assume receiving JobId means completion.

   Specs to add (red first)

   Verify known seed/projection result, replay JobId observation, eventual rebuilt state, timeout diagnostics and rejection of non-sample targets. Keep in-process and real-server evidence distinct.

   Gate (exact commands from the repo's CI)

   dotnet restore Samples.slnx
   dotnet build Samples.slnx --configuration Debug --no-restore
   bash .github/scripts/run-specs.sh --project <registered-spec-project> --configuration Debug --no-build --no-restore --
   dotnet restore Samples.slnx -p:Configuration=Release
   dotnet build Samples.slnx --configuration Release --no-restore -p:CratisProxiesOutputPath=
   corepack enable
   yarn install
   yarn samples:validate

   Register and substitute the new spec project. Add one bounded real-kernel replay acceptance in the appropriate CI lane; none was run for this proposal.

   Done when

   • Separate catalog sample shows explicit replay, completed job and verified rebuilt data.
   • Disposable-only safeguards, deadlines, cleanup and error guidance are documented and tested.
   • Required builds/specs and actual replay acceptance pass.

   Risks and open questions

   Confirm completion-observation API against the selected published package before implementation; do not invent polling methods.

   Out of scope

   Partition retry, erasure, clearing quarantine, external effects, arbitrary production targets, and changing the existing diagnosis sample's contract.