276 lines
17 KiB
Markdown
276 lines
17 KiB
Markdown
# 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.
|