Calibration service (SDK 1.0, et.tune.v1)

The optional ET_SERVICE_TUNE table is an et_tune_service, layout-compatible with et_read_service. Negotiate version 1.0. tune.read is needed to negotiate; every operation is independently checked against the worker session's granted capabilities at both ends. Existing C ABI 1.0/1.1 prefixes are unchanged. Use epictuner/tune.h from C, or epictuner/sdk/tune.hpp from C++20.

All requests and callbacks run on the worker dispatcher. Inputs are copied before return, replies are borrowed until callback return. Limits, cancellation, acknowledgement and terminal-callback semantics are those in READ.md. Cancelling before dispatch prevents local changes. An already accepted commit is authoritative; cancellation is never a rollback. A transport timeout never means it is safe to retry a write: refresh first.

Request mapping

Initialize with Reads::make(operation, projectGeneration). Unused fields must remain at their defaults. count is 1..32 for catalog/snapshot pages. A revision is a monotonically advancing 32-bit host token, returned in reply schema. Project generations are the same as the project/read service. Revision changes are conservative: manual edits, AutoTune, project/save and connection changes invalidate an old preview. Never derive a revision by adding to it.

PROPOSE and DISCARD require tune.propose; APPLY/UNDO/REDO require tune.apply. CATALOG/SNAPSHOT/STATUS require tune.read. Handles are scoped to worker session and project generation. There are at most eight outstanding proposals per worker; DISCARD unused previews. Refreshing a revision retires older previews. Restart, project replacement and disconnect invalidate proposals without replaying them.

A proposal is UTF-8 TSV, with a nonempty label of at most 128 characters on its first line, followed by 1..64 lines field<TAB>index<TAB>expected<TAB>requested. The entire payload is at most 4096 bytes. Field names and labels cannot contain embedded tab/newline/NUL. Use the supplied encoder rather than locale-dependent number formatting:

const auto body = et::sdk::Tune::proposal("Fuel correction", {
    {"fuel", 0, oldValue, newValue}
});
auto request = et::sdk::Reads::make(ET_TUNE_PROPOSE, generation);
request.id = et::sdk::string(definitionHash);
request.schema = baseRevision;
request.text = et::sdk::string(body);
tune.request(request, previewCallback);

Preview/result items use id = field, sequence = element index, timestamp = expected old value, value = normalized stored value. This mapping is specific to tune operations; timestamp is not a time for a tune item.

Snapshot JSON includes id, units, digits, bounds and whether each bound exists, shape, enum value/label pairs, readOnly, and native field type. Table/curve metadata also includes kind, title, axisLabels, backing x/y/z field IDs and read-only axes. Read their backing fields separately to obtain axis values. String/PC-variable and protected/read-only axis writes are rejected; this numeric service never exposes raw page pointers. Unsupported metadata exceeding 4096 bytes returns a limit error rather than truncating a definition.

Correctness and ECU outcomes

The host validates every element on an isolated copy using ProjectManager's storage/scaling rules. It rejects malformed numbers, bounds, dimensions, duplicate cells, old-value conflicts, protected axes and overlapping/scaling changes whose final stored values disagree with the proposed normalization. It serializes and reads back the candidate before publishing the live state once. The normal host write queue receives changed spans after local acceptance. There are no partial local commits on validation failure; undo reverses the complete accepted group.

LOCAL_ACCEPTED is distinct from RAM_UNVERIFIED, RAM_VERIFIED, RAM_FAILED, OFFLINE, and FLASH_PENDING. In connected mode the comms thread drains the normal write queue and reads ECU pages to verify the exact accepted snapshot. STATUS reports the result only while the project/revision still matches. A failed or mismatched readback retains the local tune and directs the user to the normal synchronization flow. It does not replay or silently roll back physical writes. Whole-page readback briefly pauses polling on the communications thread.

Firmware updates, tune synchronization and packet-proxy ownership block edits. Disconnected operation is rejected unless the project is explicitly offline. Only verified Serial/TcpBridge/Mock local project connections are supported; remote sessions are rejected. Burn is a separate confirmation tied to the current session, generation and revision. The existing Burn flow reports its result; opening a panel, reconnecting, proposing, applying or restoring state never burns.

See PREFABS.md and the two calibration examples. The fuel demo accepts offline/Mock proposals only and has no Burn capability.