# Step-11 - Deterministic simulation runbook validation and preview ## STEP IDENTIFIER Step-11. Corrected Step-10/10A was accepted on 2026-10-31. This is the sole active implementation assignment. Local inference/knowledge is Step-12 and remains blocked until this deterministic boundary is accepted. ## STEP TITLE Validate one source-bound synthetic calibration runbook and preview its exact candidate/diff without saving, approving or executing anything. ## OBJECTIVE One user outcome: explicitly supply structured JSON, then inspect a valid, current-source proposal preview or a precise handled rejection. One primary new contract: a strict allowlisted schema/source/head/template boundary that future local inference must also use. This is manual JSON input and read-only preview, not an LLM, retrieval system, authoring Save, rehearsal approval/target operation or executable runbook. Read [STATE.md](STATE.md), [ROADMAP.md](ROADMAP.md), [authoring contracts](../docs/calibration-authoring.md), [rehearsal contracts](../docs/calibration-rehearsal.md) and [WORKER-QUALITY-GATE.md](WORKER-QUALITY-GATE.md). Establish the frozen matrix before coding, self-review after first green, write `prompts/Step-11-Report.md`, and STOP. ## ARCHITECTURAL CONTEXT Keep all nine projects, one Client, generic Components and existing Application feature boundaries. Application owns parsing/validation/preview against the read-only authoring snapshot; UI owns a route/input/error/preview. Core may hold small immutable data contracts if justified, not a new engine. Reuse [SyntheticEngineCalibration](../src/AutoForge.Core/Calibration/SyntheticEngineCalibration.cs) for complete scalar/table validation and [CalibrationAuthoringService](../src/AutoForge.Application/Features/Vehicles/Calibration/CalibrationAuthoringService.cs) for actual workspace/head/applicability. Reuse the existing pure exact diff helper rather than implementing another version/diff system. No new project/package/host, generic workflow/permission framework or schema change to profiles/configurations/archives. Source/tests stay under `src`, tests under `src/tests`. ## CURRENT IMPLEMENTATION STATE Accepted authoring provides exact applicability, immutable Baseline/Proposed heads, complete supported scalar/table values, synthetic constraints and exact diffs. Accepted rehearsal separately verifies/approves/commits/reads/restores an isolated Simulation image; it is not reachable through a runbook preview. Worker baseline: 179 unit + 263 integration passes (442 total, zero failed/ skipped), clean nine-project Release build and native rehearsal recheck. The orchestrator did not run those commands. No runbook validator, model runtime or inference/knowledge feature exists yet. Inspect Git/prior art and preserve dirty work, accepted behavior and all historical assignments/reports. This step does not implement app-level Git backup/persistence or change the accepted volatile domain snapshots. ## REQUIRED IMPLEMENTATION ### Frozen contract matrix | ID | Input/precondition | Required result | |---|---|---| | C-01 | Explicit actual authoring source/head, supported schema and unchanged full values | Valid read-only NoChanges preview with exact immutable source/head/values and empty diff; no implicit workspace/template/preview on route entry | | C-02 | Warm baseline 650 rpm; candidate 1250 plus 2000-rpm torque 360->350 | Exactly two canonical diff entries: scalar +600 rpm and axis-keyed table -10 N*m, with before/after/units; authoring/config/target untouched | | C-03 | Malformed/missing/duplicate/unknown/version/type/enum JSON fields | Typed visible schema rejection before preview publication; previous successful preview and all source state remain intact | | C-04 | Wrong operation, multiple/empty steps, physical/replay target, arbitrary SQL/script/frame/offset/approval fields | Allowlist rejects; no command/target access, automatic save/approval or inference of authority from rationale | | C-05 | Each wrong workspace/head/applicability component or case policy | Exact current-source/head rejection, no catalogue/role/latest-head fallback. Profile/module case variants retain existing policy; fingerprint/model/definition/key/unit are exact. | | C-06 | Invalid scalar/cell/axis/unit/key/shape, non-finite number, valid exact bounds/tiny change | Reuse full template rules; invalid rejects atomically, valid bounds and canonical differences remain exact without clipping/rounding/sorting | | C-07 | Source/head changes before validation or after a valid preview | Stale request rejects; existing preview becomes visibly stale against current source/head and never silently rebases or grants execution. Revalidate requires explicit correct input. | | C-08 | Maximum payload/rationale/identifier/depth and one-over inputs | UTF-8 input <=128 KiB, rationale <=2000 UTF-16 code units, step ID 1..128 trimmed code units and parser depth <=32; over/invalid input handled without replacing prior preview | | C-09 | Caller changes input collections, rerender/unit changes or invalid attempt after prior success | Immutable copied last-successful preview; bounded one preview, distinct input-error/old-preview labels; original canonical values/diff/source remain unchanged | | C-10 | Actual route with live diagnostics/replay/rehearsal present; full verification | Real validator/source/UI path and 442 regressions preserved; zero authoring Save/approval/target read-write/model/archive/network calls from preview; no model/physical execution | ### A. Exact small schema v1 and one allowlisted operation Define/document a strict schema-v1 input with these exact camelCase object fields: - Root: `schemaVersion`, `runbookIdentifier`, `targetKind`, `rationale`, `steps`. - Source is carried inside the step: `stepIdentifier`, `operation`, `source`, `values` are that step's exact fields. - Source: `workspaceIdentifier`, `expectedHeadIdentifier`, `profileIdentifier`, `profileRevision`, `configurationIdentifier`, `moduleIdentifier`, `modelIdentifier`, `modelVersion`, `definitionIdentifier`, `definitionRevision`. - Values: `scalars`, `tables`. - Scalar value: `logicalIdentifier`, `unit`, `value`. - Table value: `logicalIdentifier`, `unit`, `axisUnit`, `axis`, `cells`. All are required. `schemaVersion` is integer 1; `runbookIdentifier` is a lowercase GUID in N format; `targetKind` is the exact string `simulation`. `steps` is an array with exactly one step, whose exact operation is `proposeCalibration`. Step identifier is nonblank, trimmed and at most 128 UTF-16 code units; rationale is a string of at most 2000 such code units and is informational only (empty permitted). Profile/model/definition revision fields are positive JSON integers; source/ workspace/head identifiers are explicit nonblank trimmed strings and must match the actual source, not just syntactically resemble a fingerprint. Limit the original input to 128 KiB (131,072 bytes of UTF-8, not string.Length) and JSON parsing depth 32. Reject duplicate/unknown/missing properties at every schema object, wrong JSON kinds, comments/trailing data, unsupported versions, undefined target/operation tokens and invalid numbers through a typed handled error. Do not return a healthy default/no-op for malformed input. The values are exactly the existing supported warm-idle scalar and fixed-axis torque table, not arbitrary JSON, a partial patch or firmware payload. Keep finite inclusive bounds, logical IDs, fixed axis/count/source units and complete shape validation from the existing template. No shell, SQL, raw frame, offset, route/function name, provider write command, approval flag or execution switch is permitted. Rationale is rendered as safe text and is never interpreted as policy, instructions or a command. Do not install/run a model or retrieve context. Future Step-12 generated text will have to satisfy this same parser/validator, not a privileged alternative. ### B. Actual source/head validation and immutable exact preview Require an explicitly created current authoring workspace. Parse the supplied source token and compare every workspace/head/applicability component with that snapshot, following existing field-specific identity rules. Validate the complete candidate through its real SyntheticEngineCalibration definition. Both Baseline and Proposed current heads may be used as a preview source. Never resolve stale IDs to latest, infer a module from a role or create a missing profile/configuration/workspace during validation. Use consistent source/head at publication, reusing the existing narrow current- head guard if appropriate. All parsing/reference/template checks precede any last-successful-preview replacement. There is no authoring Save, approval or target command hidden inside this operation. Preview contains copied runbook/step/source/head identity, rationale, canonical candidate, exact current-head-to-candidate scalar/table diff and a truthful NoChanges/ChangesProposed indication. ChangesProposed is not a saved Proposed revision or a tested/approved/applied target state. No authorization token is generated by validation. Use exact canonical doubles and deterministic logical-ID/axis ordering. Preserve zero/tiny differences and actual before/after/delta/units; no display precision, conversion or tolerance can alter the input or diff. Return defensive/read-only snapshots; retain only one last successful preview, not unbounded history or a custom repository/branch/merge layer. The source can change after validation. Preview's captured identity/content remains immutable; separately compare it to the actual current workspace/head whenever status is shown and label mismatched/replaced previews **Stale**. Never silently rewrite the expected head, rerun validation on render or present an old diff as a current actionable plan. Explicit updated input/revalidation is required. A later executor would still need its own fresh checks and approval; none is implemented here. ### C. Real local UI with no execution path Add a clearly named `/runbooks` route and existing shared navigation. Provide manual JSON input, explicit Validate/Preview, last-successful preview/source/ canonical candidate/diff/status and visible error details. An explicit **Create input template from selected current source** action may copy that actual workspace/head/values into a draft to make entry practical. It must not automatically validate, save a proposal, open a target or create authoring data. Empty/unavailable source is a visible error; no seeded fallback. Identify draft input separately from the previous successful preview after an invalid attempt. Subscribe to authoring changes only to render source staleness, not to mutate/rebase the draft. Display global unit preferences only as optional read-only projection alongside canonical source values, using existing helpers. Unit changes and rerenders cannot validate/save a plan or change preview contents. Scope is preview only: no Execute/Apply/Approve/Save-to-authoring control or code path. Safe text/accessibility and existing routes remain intact. ## FILES OR PROJECTS EXPECTED TO CHANGE Focused Application runbook contracts/parser/validation/preview/DI, UI route/ navigation/template/error/preview, tests and directly related docs/README. Reuse existing calibration/template/diff contracts and narrow source/head guard. Core data additions only if necessary; no Simulation/Diagnostics programming/ model/transport or existing authoring-save behavior changes. No new dependency/project/host or model/retrieval/tool server. Only `prompts/Step-11-Report.md` under `prompts`. ## INTERFACE AND DEPENDENCY REQUIREMENTS Preserve all nine projects/references, one Client, independent Components, exact authoring/source/head/units/template limits and isolated rehearsal approval/CAS/ backup/readback/recovery. Profiles/configurations/archives/physics remain unchanged. No inference/cloud/network/upload, physical/replay target permission, source mutation, implicit save, command execution, broad catch or success-shaped rejection. The validator is not a general version-control or backup framework. Do not fix the separately disclosed recording refresh/navigation issue here. No package/system/workload install/update/repair/rollback, staging/commit/push or destructive Git; preserve dirty work and protected/history/orchestration files. ## TESTING REQUIREMENTS Map C-01..C-10 to named meaningful tests before handoff: - Real authoring/profile/configuration source, exact template/current-head and whole candidate; NoChanges and independent 650->1250/+600, 360->350/-10, multiple cells/reverse/tiny-difference canonical diff vectors. - Independent wrong JSON object/property/type/version/target/operation/source/ head/value/unit/axis/shape vectors; assert typed rejection and exact preserved last preview/source/head/history. Do not cite a test count as boundary proof. - Exact payload 131,072 bytes and one more using otherwise valid document whitespace; rationale length 2000/2001, step-ID boundaries and controlled excessive-depth/malformed JSON. UTF-8/UTF-16 limits are distinct. - Source-head change before validation rejects; change/replacement after success marks prior result stale without modifying it or the input. Defensive-copy and one-preview-retention assertions; no validation triggered by renders. - Actual rendered template/validate/error/stale/diff controls, safe rationale text, original/canonical versus display units, and zero unassigned side effects. Use real existing live/recording/replay/rehearsal instances plus counted ports around feature invocation; verification reads outside that invocation are not validator calls. Do not mock away the validator/authoring source. Run focused cases, then sequentially: - `dotnet build .\src\AutoForge.slnx --configuration Release --no-restore` - `dotnet test .\src\AutoForge.slnx --configuration Release --no-build` Preserve 442 baseline cases (179 unit, 263 integration) plus meaningful new coverage. Map required UI-only assertion changes without deleting safety/source checks. Build all nine projects/native Client. Install/restore nothing absent a genuine chosen-command missing dependency. Native smoke: explicit source creation through existing UI, input template, valid exact preview, malformed/wrong-target/head/invalid-value rejection with previous preview retained, source change/stale status and explicit revalidation. Verify original source/history/target/replay are not changed by preview and that global units/old routes still work. No model, knowledge or physical target. Native normal UI is not controlled concurrency/limit proof. Clean only exact task-owned artifacts/profiles and preserve unrelated user data/preferences. ## DOCUMENTATION REQUIREMENTS Update README/index/architecture/build guide and runbook-schema/preview usage: exact fields/limits/allowlist, source/head/template rules, immutable diff/stale semantics, manual input/no model/no save/no execution/no authorization scope and actual verification. Step-10/10A is accepted; Step-11 stays pending manual review. Local inference/knowledge and later executor integration are future, not implemented capabilities or implicit mutation authority. ## ACCEPTANCE CRITERIA | ID | Criterion | Evidence | |---|---|---| | AC-01 | C-03..C-06/C-08 strict bounded schema/allowlist/types/source/head/full template validation | Independent input vectors, exact limits and typed atomic negative assertions | | AC-02 | C-01/C-02/C-07/C-09 immutable precise preview/diff/no-op, current-versus-stale status and bounded retained result | Exact source/value/delta/tiny-change/defensive-copy/staleness tests | | AC-03 | C-10 actual local UI/service path with no execution/save/approval/model/network effects | Rendered/native actions, real-source/target/coexistence counters and unchanged state | | AC-04 | All 442 regressions/new coverage, complete nine-project Release build and required native smoke pass | Exact commands/exits/warnings/per-project counts and native/control distinction | | AC-05 | Matrix/self-review/docs/history/protection/manual gate describe actual implementation and limits | Own post-green producer/consumer review, named evidence and `prompts/Step-11-Report.md` | ## OUT-OF-SCOPE WORK LLM/model/runtime/server install or integration, knowledge retrieval/vector/RAG, runbook execution/tool invocation, authoring Save/target programming/approval, app-level Git/plan persistence, multiple operations/step orchestration, new units/ templates/schema changes to other features, physical/AI hardware authority, new project/package/host and unrelated cleanup. No future assignment, agents, automatic handoff, orchestration/shared-gate edit, staging, commit or push. ## REPORTING REQUIREMENTS Save `prompts/Step-11-Report.md` wholly inside exactly one plain triple-backtick fence, no language tag/outside text/nested fences. Include identifier/title/status, functions/files/interfaces, C-01..C-10/AC-01..AC-05 mapping with named executed evidence, exact schema/limits/negative/source/head/preview/diff/stale/no-side- effect results, commands/exits/warnings/per-project counts, native versus controlled coverage, docs/README, own post-green source-path self-review, limitations/deviations/blockers and preservation review. COMPLETE requires all assigned checks; otherwise report INCOMPLETE/BLOCKED with the precise unmet criterion. Save and STOP; do not begin Step-12.