AutoForge/docs/calibration-authoring.md

7.5 KiB

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. Step-08 is accepted; Step-09 remains pending manual orchestrator review. Step-10 verified simulated programming is separate and unimplemented. 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 Nm/lbfft 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 Nm. Cancelling captures a new Imperial draft in lbfft. An untouched subsequent save preserves exact source values and does not create a proposal merely because displayed units changed.

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.