AutoForge/docs/runbooks-v1.md

164 lines
8.2 KiB
Markdown

# 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](calibration-authoring.md)
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 N*m produce
exactly two diff entries: scalar +600 rpm and table -10 N*m. 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](build-and-test.md) and the
[Step-11 worker report](../prompts/Step-11-Report.md).
Corrected Step-10/10A and Step-11 are accepted. The separate optional
[local-generation path](local-runbook-generation.md) 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](../prompts/Step-12A-Execution-Report.md).
Step-13 adds a separate explicit [pinned draft handoff and verified comparison](calibration-comparison.md).
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.