164 lines
8.2 KiB
Markdown
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.
|