17 KiB
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, ROADMAP.md,
authoring contracts,
rehearsal contracts and
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
for complete scalar/table validation and
CalibrationAuthoringService
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,valuesare 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-restoredotnet 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.