AutoForge/docs/calibration-authoring.md

147 lines
8.5 KiB
Markdown

# Synthetic calibration authoring
## Authoring only, not programming
The `/calibration` route creates **Synthetic configuration-derived baseline**
and **Proposed** revisions in process memory. It does not read an ECU, make a
verified original backup, test or approve a proposal, write to a module, apply
values to a model or change the source configuration. Restart loses all
authoring history; leaving the route loses its unsaved editor draft. Saved
authoring revisions survive route navigation only within the running app.
Steps 08 and 09 are accepted. The separate [Step-10 rehearsal](calibration-rehearsal.md)
can consume a saved current Proposed head only through explicit isolated target,
backup, approval and readback actions. Saving authoring values never dispatches
programming or rewrites their Baseline/Proposed status. Physical writes retain
their later independent authorization/evidence gates.
## Explicit source and bounded synthetic definition
First create/import a dynamics configuration through the existing explicit
simulation workflow. No configuration, profile or workspace is seeded by
opening authoring. Select an exact saved configuration fingerprint and choose
**Create synthetic authoring baseline**.
The versioned `autoforge.synthetic.engine-authoring` revision 1 template
supports `autoforge.synthetic.longitudinal` model version 1. Applicability
includes exact configuration fingerprint, profile identifier/revision,
the configuration's actual EngineModuleIdentifier, model identifier/version
and definition identifier/revision. The actual module is resolved through the
selected profile; it is never inferred from a role. Profile/module comparison
is case-insensitive per existing policy; fingerprints, model/definition IDs,
logical keys and units are exact. Supplied optional hardware/software/firmware/
calibration metadata is retained as metadata, not filled or promoted into proof.
| Logical value | Source units | Synthetic policy |
|---|---|---|
| `engine.warm-idle-target` | rpm | Finite scalar, inclusive `[Model.IdleSpeedRpm, Model.MaximumEngineSpeedRpm]` |
| `engine.torque-curve` | rpm axis; N*m cells | 2..32 fixed source rows; finite strictly increasing axis in `[0, MaximumEngineSpeedRpm]`; editable finite cells in inclusive `[1,1000]` N*m |
Only identity value scaling (1, offset 0) is supported. No raw binary layout,
addresses/offsets, adjustable axis, insertion/deletion, sorting, interpolation,
multidimensional maps or arbitrary firmware definition is provided. An otherwise
valid configuration outside this template is rejected, not truncated, clipped
or normalized. These are synthetic authoring constraints, not manufacturer-
safe operating limits or physical compatibility evidence.
For the warm example, baseline warm idle is 650 rpm with limits 650..5000 rpm.
The source torque rows are exactly `(650,240)`, `(1000,300)`, `(2000,360)`,
`(3200,350)`, `(4200,300)`, `(5000,180)` in rpm/N*m.
## Immutable linear versions and exact preconditions
The Application service retains **one** authoring workspace with at most
**32 saved revisions including baseline**. Baseline is revision 1, read-only.
Every valid changed save creates a unique Proposed revision with a monotonic
revision number, exact parent/current-head ID and copied workspace/source
identity. All definition, axis, value, history and diff collections are
defensively copied/read-only.
A save explicitly supplies the workspace ID, expected head ID, complete
applicability and complete candidate. Required keys, shape/count, unchanged
axis, source units, finite values and inclusive bounds are validated as a whole
before any head/history/version mutation. Invalid or mismatched requests return
typed visible errors with no partial save. Two requests based on the same head
cannot both commit changed proposals: the second is stale, with no merge,
branch or last-writer-wins fallback.
Content equal to the current head returns that same revision without consuming
capacity. Stale expected heads reject even if their proposed content is
unchanged. At 32 revisions, changed revision 33 rejects; an identical current-
head save remains a no-op. Changing back after a different proposal creates a
new Proposed revision, not a restored device or approved rollback.
Selecting a different configuration does not silently replace the workspace.
Replacement requires the explicit **I confirm replacement discards the current
in-memory history and unsaved draft** checkbox and replacement action, together
with the prior expected workspace/head. Invalid/stale replacement preserves the
old workspace/draft/history. A new workspace discards service-held old history;
there is no hidden unbounded multi-workspace repository or persistence.
## Editor, units and history
The editor captures its expected source/head and copied input strings. Another
editor's save rerenders a stale-head warning but does not silently rebase unsaved
fields. **Cancel draft / reload latest head** is the explicit recovery action.
Inspection of a saved revision does not change the editable head.
Torque presentation uses the existing shared N*m/lbf*ft converter. rpm remains
rpm. A draft pins its input unit selection until save/cancel; global preference
changes affect read-only presentation, not the meaning of unsaved fields or
saved canonical values. Inputs use round-trip numeric text; display precision
is presentation only. Unedited fields retain their exact original canonical
doubles, avoiding forward/inverse conversion drift. Edited torque converts
once to N*m before complete candidate validation. Canonical source values,
fixed axis and synthetic bounds remain visible.
Example: typing a torque edit while Metric is active and switching globally
to Imperial leaves that draft in N*m. Cancelling captures a new Imperial
draft in lbf*ft. An untouched subsequent save preserves exact source values
and does not create a proposal merely because displayed units changed.
## Explicit preview handoff
After explicit manual/local validation in `/runbooks`, return to `/calibration`
and choose **Copy current preview into this pinned draft**. Admission validates
that exact current preview, workspace/head, selected configuration and complete
canonical candidate. It preserves this draft's pinned units even if global
preferences changed. Unedited copied fields retain exact source doubles.
Invalid/stale/superseded/different-source input leaves the draft and saved
history unchanged with a visible error. Handoff never Saves, opens/reads/writes
a target or rebases. Choose Save separately to create the Proposed version.
Only the separate [verified comparison](calibration-comparison.md), after actual
rehearsal backup/approval/Apply/full readback, can explicitly project values to
a NEW immutable model configuration. Authoring Save itself is unchanged.
## Structured canonical diffs
Select two explicit saved versions from the same workspace/applicability and
choose **Compare explicit saved revisions**. Output includes only changed
scalars/cells, deterministic ordinal logical-key then numeric axis order,
logical ID, table axis coordinate/unit, original source unit, exact before/
after doubles and signed delta. No rounded-display comparison or tolerance
hides small changes. Comparisons against foreign/replaced version IDs reject.
Warm idle 650 -> 1250 produces one scalar entry: before 650, after 1250,
delta +600 rpm. Also changing the 2000-rpm torque cell 360 -> 350 produces
exactly two entries versus baseline, with table delta -10 N*m. Comparing that
third revision against its second-revision parent shows only the table change.
A changed-back Proposed revision may have an empty baseline diff without
changing its authoring-only status.
## Verification and isolation
`CalibrationAuthoringTests` constructs real profile/configuration-service
sources and asserts baseline values, exact parents/diffs, malformed values/
definitions/source tokens, immutable snapshots, deterministic competing-head
commits and the exact history bound. Actual rendered editor events cover
parse/validation failures, history/diff choice, stale editors, replacement and
unit-pinned drafts. A real live dynamics source, saved recording and validated
replay coexist while authoring adds zero transport/model/archive-Save calls,
with unchanged configuration export/fingerprint, raw archive bytes, source
trace/state and replay snapshot.
Native smoke uses the actual Windows Client and explicitly created warm source;
it is not controlled concurrent/head-capacity proof. Commands, counts, native
observations, limitations and preservation review are in the
[Step-09 worker report](../prompts/Step-09-Report.md).