AutoForge/docs/runbooks-v1.md

8.2 KiB

Manual runbook schema v1 and read-only preview

Preview only

Open /runbooks from shared navigation. Supply manual structured JSON, then choose Validate / Preview explicitly. Entry, rendering and unit changes do not create a workspace, template or preview. There is no LLM/model/runtime, retrieval/network/upload, authoring Save, approval, target read/write or runbook execution. Validation produces no authorization token or saved authoring revision. Rationale is informational text, never instructions or policy.

First explicitly create a synthetic configuration-derived authoring workspace through the existing simulation/calibration UI. Create input template from current authoring source copies that actual immutable workspace/head and complete canonical values into an input draft. It does not validate or save. Missing source gives a visible error, not a seeded/default/live fallback. Both current Baseline and current Proposed authoring heads can be preview sources.

Exact object fields

All fields below are required, exact camelCase. Every schema object rejects missing, duplicate or unknown properties, including escaped duplicate names. Comments, trailing commas/data, incorrect JSON kinds and unsupported tokens are handled typed errors. No SQL/script/frame/offset/approval/execution property is allowed at any schema level.

Root

Field Contract
schemaVersion JSON Int32 integer exactly 1, not string/fraction/exponent syntax
runbookIdentifier Lowercase GUID in N format, exactly 32 characters
targetKind Exact string simulation; this is not target access/permission
rationale String, empty permitted, at most 2000 UTF-16 code units
steps Array with exactly one step

Step

Field Contract
stepIdentifier Explicit nonblank trimmed string, 1..128 UTF-16 code units
operation Exact proposeCalibration, read-only preview only
source Complete source object below
values Complete scalar/table value object below, not a partial patch

Source

Exactly:

  • workspaceIdentifier, expectedHeadIdentifier
  • profileIdentifier, profileRevision
  • configurationIdentifier, moduleIdentifier
  • modelIdentifier, modelVersion
  • definitionIdentifier, definitionRevision

Revision/version fields are positive JSON Int32 integers. Other source fields are explicit nonblank trimmed strings and must match the actual current authoring workspace/head/applicability. Profile/module comparison retains existing ordinal case-insensitive policy. Configuration fingerprint, model/ definition identifiers, workspace/head identities, logical keys and units are exact. No module role, catalogue, live feed or latest-head resolution can fill or replace a supplied source field.

Values

The values object contains exactly scalars and tables arrays. Each scalar object contains exactly logicalIdentifier, unit, value. Each table object contains exactly logicalIdentifier, unit, axisUnit, axis, cells; axis/cells are arrays of finite JSON numbers.

The existing full synthetic authoring template validates the complete candidate:

  • Exactly one engine.warm-idle-target scalar in source rpm, finite and in the inclusive selected model IdleSpeedRpm..MaximumEngineSpeedRpm range.
  • Exactly one engine.torque-curve table, source N*m cells and fixed source rpm axis copied exactly from the selected configuration. All 2..32 rows, units and counts must match. Every cell is finite in inclusive [1,1000].
  • No axis edit/reordering/sorting/insertion/deletion, clipping, interpolation, arbitrary key or display-unit conversion is performed.

JSON is always canonical source units even when global display is Imperial. For the warm example, 650->1250 rpm and 2000-rpm torque 360->350 Nm produce exactly two diff entries: scalar +600 rpm and table -10 Nm. Unchanged cells/ axes are omitted. Read-only display conversion can show lbf*ft alongside the canonical candidate but never changes JSON, bounds or diff.

Exact bounds and handled errors

Limit Maximum
Original complete input, UTF-8 encoding 131072 bytes (128 KiB)
JSON parser nesting depth 32
Rationale 2000 UTF-16 code units
Step identifier 128 trimmed UTF-16 code units, minimum 1

Input size is not string.Length. Supplementary Unicode uses two UTF-16 code units per character and its actual UTF-8 byte size for the independent payload bound. Otherwise valid JSON with whitespace at exactly 131072 bytes is accepted; one extra byte is rejected. Non-finite/invalid-number, invalid encoding, malformed syntax and depth-overflow inputs never produce a healthy default.

Errors expose a typed failure, JSON/source/value path and readable reason: InvalidJson, LimitExceeded, UnsupportedSchema, SchemaViolation, OperationNotAllowed, SourceUnavailable, StaleSource or InvalidValues. The UI identifies rejected draft input separately from the preserved previous successful preview. An invalid attempt does not replace valid source/head/ history/candidate/diff state.

Immutable result and current versus Stale

The last successful preview contains copied preview/runbook/step/source/head identity, rationale, captured head kind/revision/content, complete canonical candidate, deterministic exact logical-ID/axis-ordered diff and:

  • NoChanges: exact captured head content and empty diff;
  • ChangesProposed: changed preview, not a saved Proposed revision or a Tested/Approved/Applied result.

Parsing, allowlist, source/reference and full template validation all precede publication under the actual authoring current-head guard. Only one successful result is retained in process memory; there is no runbook repository, history, Git backup, disk persistence, branch or merge layer. Snapshots/collections are defensive/read-only. Canonical double comparisons have no display tolerance, so a tiny representable change still yields its exact signed delta.

When shown, source freshness is compared separately with the actual current workspace/head/applicability and captured content. A changed/replaced source labels the immutable old preview Stale, without rewriting it or the draft, running validation on render or granting current execution authority. Supply explicit updated input and revalidate to obtain a new current preview. A new template is only a draft and does not clear staleness by itself.

The page owns its unsaved input/error state; source and global-unit notifications only rerender. Leaving the route loses that draft, while the bounded last-successful preview remains in the running app and is labeled separately on re-entry. Restart loses the preview. A future executor would need independent fresh checks/approval; no executor is implemented here.

Verification and next boundary

Tests use actual authoring/profile/configuration services, independent exact value/diff vectors, all schema/source/value/limit boundaries, defensive copies, source staleness, actual rendered controls and safely escaped rationale. Real live diagnostics/recording/replay/approved-rehearsal instances coexist around feature invocation with zero unassigned calls or mutations. Native normal UI evidence is separate from headless boundary/coexistence proof. See build/test evidence and the Step-11 worker report.

Corrected Step-10/10A and Step-11 are accepted. The separate optional local-generation path passes original model content through this same strict validator, adding captured-source, expected-prior-preview and cancellation admission atomically at publication. Manual Validate behavior/limits remain unchanged. Step-12A actual local-model native verification passes with current cloud-disabled proof, exact original output and pending lifecycle evidence; Step-12/12A is accepted. See the execution report. Step-13 adds a separate explicit pinned draft handoff and verified comparison. It checks the actual current preview/workspace/head and copies canonical values only. Save, backup, approval, Apply, readback and evaluation remain separate commands. Validation/rendering still grants no target or execution authority; a general runbook executor remains unimplemented.