147 lines
8.5 KiB
Markdown
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).
|