AutoForge/docs/calibration-rehearsal.md

9.2 KiB

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.

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.

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 is accepted; Step-10 remains pending manual review. 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 and the Step-10 worker report.