Duende Builder feature guide

Candidate History Browser

How a scheduler revisits optimizer evidence without changing the current schedule or releasing a plan

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

Each successful optimizer run creates a local PlanCandidate: a saved, review-only record of what the optimizer produced. Before PR #32 merged on 2026-07-13, the scheduler showed the latest candidate and exposed older IDs mainly through a comparison selector. A scheduler could not browse a clear history and reopen one earlier result on its own.

F1 adds a newest-first candidate history to Order Optimizer. The scheduler can open an earlier candidate, read its timestamp, evidence fingerprints, scheduled-row count, warnings, and explicit candidate — not released label, then return to the latest candidate. Reloading preserves the same history.

Authority boundary: browsing is read-only. It does not rerun the optimizer, replace the current schedule, make a candidate current, approve or release a plan, or send work to the floor.

Business Problem And Practical Value

Before F1 (Historical)

A scheduler reviewing several optimizer runs could see only the latest candidate in detail. Earlier candidates appeared as IDs in a comparison control, so revisiting one result required indirect comparison or another optimizer run. That weakened review continuity: the evidence existed, but it was not easy to reopen and read.

After

  • Saved candidates appear newest-first in one visible history.
  • Each item shows its creation time, scheduled-row count, and warning count.
  • Opening an item shows that candidate's input, configuration, and output fingerprints plus its warning summary.
  • A Return to latest control restores the normal view without changing storage.
  • Malformed, unsupported, or duplicate-ID history stops safely with backup-recovery guidance. A valid but stale nextSequence also stops a new capture before it can duplicate an existing candidate ID.
  • Values restored from a backup render as text rather than executable markup.

The practical value is continuity. Mike or the scheduler can revisit what an earlier optimizer run produced without recreating it and without risking a change to the schedule currently used elsewhere in the prototype.

People And Workflow

The primary user is the scheduler reviewing optimizer alternatives in the same browser profile. The input is the existing local candidate record. The output is an evidence summary for review; the feature makes no operating decision.

Activity view showing a scheduler opening saved candidate evidence, receiving safe recovery guidance for unreadable history, and stopping before approval or release

How to read this view: Blue steps are implemented review behavior. Amber is the safe failure path. Gray marks the authority boundary where F1 stops.

Mike-Facing Demonstration

  1. Open Order Optimizer with three fictional saved candidates.
  2. Confirm that the newest ID appears first and is labeled latest.
  3. Open an earlier candidate and read its ID, time, fingerprints, row count, warnings, and nonrelease label.
  4. Return to the latest candidate.
  5. Reload and confirm that the same three candidates remain.
  6. Show malformed-history guidance in an isolated fictional browser profile.
  7. Confirm that candidate-history and current-schedule hashes do not change while browsing.

Feature Behavior

Normal States

State Visible behavior
No history A benign message asks the scheduler to run the optimizer
One candidate The latest evidence and one history item appear; comparison is absent
Several candidates History is newest-first; latest is labeled; prior items can be opened
Earlier candidate open Its evidence replaces the detail card and Return to latest appears
Reload The saved history is read again; the latest candidate is the default view

Failure And Trust States

  • Invalid JSON produces Candidate history is unavailable and recommends a known-good backup.
  • An unsupported store or candidate record produces the same stop-safe posture.
  • Repeated candidate IDs are rejected before any evidence value renders or a new candidate can be captured. The guidance does not echo the repeated ID or other stored values.
  • If nextSequence would generate an ID that already exists, capture fails before the storage write. The product does not guess a replacement ID or silently repair restored history.
  • A read/render failure says that candidate history and the current schedule were not changed because browsing has no write authority.
  • A capture failure is narrower: candidate-store bytes are preserved and the guard does not write the schedule. In a full optimizer run, however, the legacy schedule is saved before candidate capture begins.
  • Candidate IDs, timestamps, fingerprints, warning types, and warning messages are HTML-encoded before insertion into the page.
  • A selected candidate ID lives only in page memory. It is not a current-plan pointer and disappears on reload.

Deliberate Non-Goals

F1 does not render the full historical schedule, compare work changes, choose the better candidate, delete or retain history, synchronize browsers, identify users, create an audit trail, approve or release a plan, or change optimizer output.

System Context And Runtime

Candidate history is stored under rha_planCandidates in the same browser profile as the single-file scheduler. The current legacy schedule remains separate under rha_scheduled. F1 reads both authority boundaries correctly: it reads the candidate store and never writes either record while browsing.

Sequence view separating read-only browsing from candidate-capture failure after the optimizer may already have saved the legacy schedule

How to read this view: The normal branch reads stored evidence and renders it. The failure branch returns guidance instead of partial content. The note across both stores is the load-bearing rule: browsing has no write authority.

Runtime Steps

  1. nav('order-optimizer') calls renderPlanCandidateDetail.
  2. readPlanCandidateStore reads and parses the schema-versioned candidate record, then rejects repeated string candidate IDs before returning it.
  3. capturePlanCandidate derives the next ID and rejects it when that exact ID already exists, before candidate creation or candidate-store persistence. The surrounding optimizer has already assigned and saved scheduled before it calls this function.
  4. The renderer validates that every displayed candidate is schema version 1, has a string ID, and remains candidate-not-released.
  5. The stored list is reversed for newest-first display without changing the stored array.
  6. selectPlanCandidate keeps the chosen ID in window memory and rerenders.
  7. escapePlanCandidateHtml encodes every restored string before display.
  8. selectLatestPlanCandidate clears the in-memory ID; reload naturally does the same.

Technical Implementation Map

Product concept Implementation Practical meaning
Local evidence record readPlanCandidateStore Parse the existing schema-versioned candidate collection
Collision-safe capture capturePlanCandidate Reject a stale counter before it can write a repeated ID
Safe display escapePlanCandidateHtml Treat restored strings as untrusted text
History and detail renderPlanCandidateDetail Render newest-first history, evidence, warnings, and recovery states
Open prior selectPlanCandidate Change only the page's review focus
Return to latest selectLatestPlanCandidate Clear the temporary review focus
Contract proof plan-candidate-history.test.mjs Prove order, states, reload, no writes, recovery, and encoding

The implementation remains in src/prototype/rh_adhesives_scheduler_0346.html, the accepted single-file baseline. F1 does not introduce a new persistence format or architectural migration.

Data, Privacy, Security, And Operations

Candidate history is local to one browser profile. It can disappear if browser data is cleared and is not shared across users or devices. The existing rha_ backup envelope includes the candidate record, but backup inclusion is not cloud durability or product-owner acceptance.

The guide and screenshot use fictional IDs, products, warnings, and schedule rows. No customer records, staff names, credentials, tokens, local machine paths, or raw browser-storage payloads are committed.

The hostile-string browser scenario included markup-like candidate IDs, timestamps, fingerprints, and warnings. The real rendered panel contained zero injected img, script, or svg elements, and no attack flag executed.

Decisions, Risks, And Safe Next Steps

Decisions Preserved

  • A candidate remains evidence, not an approved or released plan.
  • Browsing changes only the reader's view, never persisted plan state.
  • Invalid or duplicate-ID history fails visibly rather than being silently ignored or rendered ambiguously.
  • A stale counter fails closed; F1 does not silently choose a different ID or mutate restored history to make capture continue.
  • Candidate evidence and the legacy schedule do not share a transaction. The optimizer saves the schedule first, so a later capture failure can leave a new schedule without matching candidate evidence. Whether those writes must become atomic is a follow-on authority decision.
  • The latest candidate is the default after reload.
  • F1 reuses the current local store instead of adding another copy of history.

Known Limits And Risks

  • Browser-local history is not multi-user or durable server history.
  • Fingerprints show whether evidence differs; they do not explain which work changed. F2 provides that separate explanation.
  • A malformed record requires recovery from a known-good backup; F1 does not repair it.
  • Saved optimizer evidence does not prove feasibility, approval, release, or production execution.

Next Gate

Mike can observe the seven-step fictional-data demonstration and record APPROVE, REVISE, or DEFER. An APPROVE decision would satisfy the outstanding product-owner gate. Until then, report F1 as merged and Browser Proven rather than product-owner accepted.

Verification

  • PR #32 merged F1 with green validation at exact head 996af8f9a060ee042d8306fe5c33427f6164ff36.
  • Closeout PR #47 passed exact-head review and CI at 0fa4374eb90a9a85a1e19c3c5bb3097ecc6ed419, then merged as a618d8ce995fbcea4c5c8685374fe1feb94e96da.
  • Integrated current main a37b3bca0e4f0e1c565a38f491e6a6a0bf009289 passed the 289-test repository gate. The F1 closeout suite passed 28 focused candidate and restore checks.
  • The real v9.346 scheduler was served on loopback in headed Chromium at a 1440 by 1100 viewport with fictional data only.
  • Candidate history and current schedule retained byte-identical SHA-256 hashes while opening prior evidence, returning to latest, and reloading.
  • Malformed history remained unchanged while visible recovery guidance appeared. Restored markup-like strings remained inert text.
  • Headless real-Chromium scenarios fetched and hashed the exact served source. Already-duplicated history and a stale counter collision each produced value-free guidance, and direct capture stopped without changing candidate-store bytes. The seeded schedule SHA-256 also stayed unchanged because this proof did not invoke the optimizer workflow. The fetched and executed source SHA-256 was cdc43392c4cc2d74891b28330d782be647c587af35c9f8397fa5c183b90823ca.
  • A headless current-main scenario fetched and executed the integrated prototype at SHA-256 3c2e077e60fb05c6890586140bca861faff68754f86bf723bdb1f7a0c3e8b8b7, browsed three candidates, repeated the review after reload, and retained exact candidate, schedule, and unrelated-sentinel bytes.
  • Scheduler syntax, six configured feature guides, every PlantUML source, and repository Markdown lint also passed.

Real scheduler candidate panel showing fictional prior-candidate evidence, newest-first history, a Return to latest control, and the nonrelease label

Screenshot metadata: captured 2026-07-14 from the earlier closeout baseline f6d2b38232da46b82f9bd8af55b4243d8091693b, viewport 1440 by 1100, scenario F1 prior-candidate review, fictional data, privacy-safe. The panel is the real running scheduler, not a reconstructed mockup.

See docs/agentic-engineering-framework/07-evidence/candidate-history-browser-receipt-v9346.md for the sanitized command and result receipt.

Glossary And Source Trail

  • PlanCandidate: local evidence captured from one optimizer run.
  • Fingerprint: a deterministic short identifier for a stored input, configuration, or output value.
  • Current schedule: the separate legacy rha_scheduled result used by existing scheduler output views.
  • Browser Proven: automated checks and the named real-browser workflow passed; product-owner acceptance remains pending.
  • Released plan: an authoritative plan sent to operations. F1 does not create one.

Primary sources:

  • docs/requirements/features/2026-07-12-plan-candidate-history-brief.md
  • src/prototype/rh_adhesives_scheduler_0346.html
  • tests/scheduler/plan-candidate-history.test.mjs
  • tests/scheduler/plan-candidate-traceability.test.mjs
  • tests/scheduler/plan-candidate-comparison.test.mjs
  • tests/scheduler/backup-restore.test.mjs
  • PR #32, closeout PR #47, the F1 receipt linked above, and docs/agentic-engineering-framework/07-evidence/wave-1-current-main-browser-receipt-v9346.md