Duende Builder feature guide

Restore Integrity Detection

How the local scheduler distinguishes verified recovery from partial browser state

Status: merged and Browser Proven on integrated main; Mike product-owner acceptance remains pending

Date: 2026-07-14

Baseline: RH Scheduler v9.346 on integrated current main a37b3bca0e4f0e1c565a38f491e6a6a0bf009289

Document owner: Kalen Howell Sr.

Audience: Mike, schedulers, product reviewers, developers, and maintainers

One-Minute Explanation

The scheduler stores orders, settings, schedules, and candidate history in one browser profile. A backup can replace that local scheduler state. Before F3, the restore helper could report success even when a browser write was dropped.

F3 first requires the exact duende-scheduler application marker so a foreign JSON envelope cannot replace scheduler storage. It then reads the complete restored rha_ namespace back and compares every key and raw string value with the backup. The product reloads only after an exact match. A missing, changed, unexpected, or unreadable key instead produces a persistent stop-work warning.

Recovery boundary: this feature detects an incomplete local restore. It does not repair the backup, roll back partial writes, certify the business correctness of the data, migrate real RH records, or create a production-grade transactional store.

What Changes For The Scheduler

Before

The restore loop suppressed individual storage errors and returned ok: true after attempting the writes. The page then reloaded. A scheduler could mistakenly continue from incomplete restored state.

After

  • A verified restore reports how many keys matched, then reloads.
  • A mismatch reports that restore integrity failed and keeps the page open.
  • The failure message tells the scheduler not to continue and to retain the source backup.
  • Candidate history is verified whenever rha_planCandidates is present.
  • Non-rha_ browser keys remain outside restore authority.
  • Failure results expose only counts and a stable code, never backup values.

Running scheduler showing the persistent restore-integrity warning after a controlled dropped write

What the screenshot proves: the real scheduler stayed on the Factory Defaults restore screen and raised a persistent warning after one fictional namespace write was deliberately dropped. The screenshot is framed above the factory roster and contains no imported customer or staff records.

Mike-Facing Workflow

  1. Open Default Settings, then Factory Defaults.
  2. Choose Restore from file and select a scheduler backup.
  3. Confirm that the backup will replace local scheduler state.
  4. On success, read the verified-key count and allow the page to reload.
  5. If the red integrity warning appears, stop using that browser state, retain the backup file, and retry only from a known-good copy.

Runtime And Authority

Runtime sequence showing restore writeback, exact namespace readback, verified reload, and value-free failure without reload

How to read this diagram: both outcomes use the same real restore path. Only an exact key-and-value match reaches success. The failure branch warns the user and deliberately stops before reload.

The pure compareRestoreNamespaces helper reports expected, verified, missing, changed, and unexpected counts. restoreBackupFromText normalizes the intended backup values to strings, performs the existing replacement, reads the namespace through DataStore, and requires the helper to return ok.

The restore already has write authority over local rha_ keys after the user confirms replacement. F3 does not expand that authority. It adds a truth gate before the UI may claim success.

Failure And Recovery Behavior

Condition Product behavior
Missing or wrong application marker Reject before browser-storage access or mutation
Exact namespace match Show verified count and reload
Missing restored key Persistent integrity warning; no reload
Changed restored value Persistent integrity warning; no reload
Unexpected stale rha_ key Persistent integrity warning; no reload
Readback unavailable Persistent integrity warning; no reload
Malformed, empty, foreign, or newer-schema backup Existing pre-restore rejection remains

A failed restore may leave a partial local namespace because browser storage does not provide a transaction here. The correct response is detection and an honest stop, not a false success claim. Automated repair and rollback remain explicit non-goals for this Phase 1 slice.

Verification Evidence

  • Focused Node tests prove exact success, order independence, pre-write rejection of missing or wrong application markers, dropped writes, changed readback, stale keys, candidate-history verification, unsafe backup rejection, unrelated-key preservation, and value-free results.
  • The synthetic recovery benchmark now requires the real runtime helper to fail closed under a dropped write.
  • Closeout PR #46 passed exact-head review and CI at 977c3833376e4f8e783932be6693e969091d23a4, then merged as 97c1a3d1086cc32f37a6afe1050b1134165018e6.
  • Real-browser proof used the visible file picker and confirmation dialog with fictional data. It proved verified reload on success and persistent warning without reload on failure.
  • Headless integrated proof on a37b3bca0e4f0e1c565a38f491e6a6a0bf009289 repeated the real file-input success and controlled incomplete-restore paths while preserving unrelated browser state.
  • The current-schedule and plan-release boundaries are unchanged. Restore does not approve, select, or release a plan.

See docs/agentic-engineering-framework/07-evidence/restore-integrity-detection-receipt-v9346.md for the compact engineering receipt.

The combined current-main result is recorded in docs/agentic-engineering-framework/07-evidence/wave-1-current-main-browser-receipt-v9346.md.

Deliberate Non-Goals

F3 does not provide cloud persistence, authentication, authorization, transactional rollback, automatic repair, business-data reconciliation, real RH migration rehearsal, production recovery certification, or plan release.

Owner Review

Mike can review this feature through a short non-technical demonstration: one successful fictional restore followed by one controlled failed restore. His acceptance determines product acceptance for the Phase 1 scenario; it does not block engineering from beginning the next approved feature lane.