AutoForge/docs/calibration-rehearsal.md

182 lines
10 KiB
Markdown

# Verified simulated programming rehearsal
## Scope and explicit target
The isolated rehearsal appears within `/calibration`, beside the accepted
authoring editor. It is a **Simulation-only logical image rehearsal**, not a
wire protocol, firmware transfer, real driver, dynamics application or physical
programming capability. Opening the page, saving a proposal, changing display
units and rendering never open a target or dispatch a mutation.
First explicitly create/select a supported authoring configuration/workspace
and save a current Proposed head. Select the registered
`autoforge.simulation.calibration-rehearsal` provider and choose **Open fresh
isolated Simulation target**. Wrong provider/descriptor, PhysicalHardware,
RecordedReplay or a mismatched source rejects before factory creation.
The target's independent image is seeded once with the selected configuration's
source warm-idle scalar and complete fixed-axis torque table, at revision zero.
Thereafter the actual target owns reads and atomic commits.
Source configuration/profile revision/actual engine module/model/definition
remain explicit. No diagnostic session is fabricated; source metadata is not a
verified ECU identity or a write permission. Only `engine.warm-idle-target`
(rpm) and `engine.torque-curve` (fixed rpm axis, N*m cells) are supported,
with the accepted [authoring template](calibration-authoring.md).
## Independent original backup
Choose **Prepare original backup with two independent reads** before the first
mutation. Both complete actual reads must match exactly in target identity,
source, revision zero, keys, units, axes and every value. A wrong/partial/failed
read cannot publish a verified backup. An authoring baseline is never used as
a synthetic read response.
The immutable **Verified in-memory backup of supported simulation image**
covers exactly one scalar and all fixed-axis torque cells, not an entire ECU.
It retains original instance/source/revision/value evidence and remains the
original backup across multiple writes. There is no backup file, persistence
after close, crash durability, cryptographic attestation or physical authority.
## Preparation, confirmation and exact dispatch
Select the exact current saved Proposed head and prepare Apply. Preparation
reads the actual target before-image, validates source/head, rejects a no-op,
and displays a precise target-to-candidate diff. It does not write or approve.
Old source/head/preparation references are rejected, not automatically rebased.
Selected and current head IDs are shown separately for explicit feedback.
Confirmation creates a single-use local opaque approval bound to:
- Apply or Restore action;
- target provider/kind/instance/source/definition;
- original verified backup identity;
- actual before-image and expected image revision;
- exact full candidate, and workspace/saved head for Apply.
Authoring versions remain Baseline/Proposed. This confirmation is a deliberate
local rehearsal action, not a Tested/Approved calibration or hardware permit.
Before dispatch, Application revalidates source/head and a fresh full target
read against the approved before-image. A narrow authoring-head guard covers
synchronous dispatch admission; target CAS atomically checks the actual
instance/revision at commit, preventing a change after that read.
Only then is approval consumed and a mutation dispatched. Invalid requests,
stale source/image, no-op and capacity errors consume no approval or write.
Rehearsal-issued opaque operation IDs support exact active/completed mutation
replay. Repeating the same action/approval ID shares or returns its outcome
without another mutation; different inputs conflict. The session retains one
unused issued ID and bounded latest non-mutation command evidence, not an
unbounded preparation-ID history. Issuing another unused ID supersedes the old
one; expired/foreign IDs cannot authorize fresh commands. Completed dispatched
outcomes remain repeatable within that target's bounded audit.
## Full readback and RecoveryRequired
After dispatch, a new independent Read verifies target/source/definition,
expected next revision, both keys, exact units/axis and every changed and
unchanged value. Acknowledgement and readback are displayed separately.
Acknowledgement alone, including an echoed positive candidate, is not Applied
proof. A successful changed commit advances revision once; restore never
pretends the revision/time went backwards.
If a write may have committed but proof is unavailable, invalid or divergent,
the outcome and current state remain **RecoveryRequired**, with precise
evidence/error and no new Apply. Cancellation before dispatch writes zero;
cancellation after actual commit cannot be labeled safely unchanged. Close
invalidates publication, cancels/drains outside cleanup-required gates and
prevents late Applied/Restored evidence from becoming current.
No write is automatically resent and no restore is automatic. Choose the latest
unresolved dispatched operation and **Read-only reconcile**. A fresh complete
read classifies:
- **Unchanged**: exact approved before-image and revision;
- **CandidateMatching**: exact candidate, target identity and expected next revision;
- **Divergent**: valid evidence differs in any value or revision;
- **Unavailable**: missing/invalid current evidence.
Only exact complete evidence may yield VerifiedAppliedAfterReconciliation or
VerifiedRestoredAfterReconciliation, or verified unchanged. Divergence/unavailable
evidence remains RecoveryRequired. The operation preserves its original
failure, initial verification and initial readback alongside reconciliation;
lost acknowledgement is not erased. Cached observations and candidate values
never substitute for missing proof.
## Separately approved original Restore and close
Prepare Restore explicitly, using the original verified backup for the same
open target instance/source. Read fresh current values/revision, confirm a new
Restore approval, dispatch one guarded commit and verify full independent
readback. After scalar 650->1250 and 2000-rpm torque 360->350, Restore returns
650/360 and all unchanged cells/axes, with revision progressing 0->1->2->3.
It does not replace the authoring head, source export or dynamics model.
Failed/uncertain restore remains RecoveryRequired, not Restored.
Close destroys the isolated target. Its immutable backup/results may remain
visible as inactive evidence, but cannot authorize a new instance. Explicit
reopen seeds source values under a new instance/revision-zero identity and
clears old backup/approval/audit. Leaving the calibration page drains its
page-owned rehearsal; re-entry creates a fresh session.
Close completion belongs to the current admitted target lifetime, not merely
the last successfully published target. A new opening owner retires the old
completed/failed close task under the state gate before factory execution.
Close or page disposal during that pending factory invalidates/cancels the
owner and drains its late-created target cleanup before returning. Repeated
current Close calls share one completion/error; none returns a prior lifetime's
success or failure. No cleanup await holds the required state gate.
Closed state/completion publish together after drainage. Rejected/failed opens
retain inactive backup/approval evidence without granting new-target authority;
disposed sessions cannot publish or reopen, whereas completed ordinary Close
allows another explicit fresh instance.
## Explicit trusted comparison admission
After actual verified Apply/full readback, choose **Open explicit verified-image
comparison controls**, select THIS owner's exact Apply operation and the
Simulation dynamics/v2 provider, then Evaluate explicitly. Owning admission
requires idle Ready state, original two-read backup, current Proposed head,
matching target instance/revision/candidate/all unchanged cells and a fresh
full target read. Public records claiming success are insufficient.
RecoveryRequired/divergent/unavailable/closed/stale evidence rejects. An actual
VerifiedAppliedAfterReconciliation may qualify; no resend or Restore is implied.
Comparison is a separate [NEW-configuration projection](calibration-comparison.md),
not an alteration of rehearsal programming semantics or the original config.
Proof is historical as of its readback time, not perpetual external attestation.
Source/owner guards and a final fresh full read precede current publication.
## Bounded volatile audit and units
At most **32 dispatched mutation outcomes per target** are retained, including
successful, rejected-at-port and uncertain Apply/Restore attempts. A new 33rd
dispatch rejects before consuming approval or writing. Exact known mutation
repeats consume no slot. Preparation/reconciliation retain bounded current
evidence and update existing audit records, not another unbounded history.
Audit includes operation/action/approval, target/backup/source/head/revisions,
full before/expected/actual images, acknowledgement, verification/recovery,
original errors, initial evidence and timestamps. An unavailable completion
timestamp is explicitly null/error rather than a fabricated time or lost
already-dispatched audit outcome. Audit is local and volatile, not a disk format
or external security attestation.
Human torque display uses the existing Metric/Imperial converter. Programming,
backup and audit equality use exact canonical rpm/N*m and fixed source axes.
Unit changes cannot alter preparation, approval, before-image, saved authoring
values or dispatch commands.
## Verification status
Step-09 and corrected Step-10/10A are accepted. Real-port tests
exercise independent backup, exact scalar/table/CAS/Restore, malformed/stale
requests, real commit with lost acknowledgement/cancel/read failure, full
unchanged-cell checks, reconciliation, held cleanup and exact 32/33 capacity.
Step-10A adds controlled actual-factory return/disposal barriers for pending
reopen against Close/Dispose, including prior failed close and current failures.
This interleaving is test evidence, not a claim about human-timed native races.
Real rendered controls and live diagnostics/recording/replay coexistence are
also tested. Native normal success is distinct from controlled fault/race proof.
See [build/test evidence](build-and-test.md) and the
[Step-10 worker report](../prompts/Step-10-Report.md).