AutoForge/prompts/Step-02A.md

15 KiB

Step-02A - Explicit profile timestamps and optional evidence constraints

STEP IDENTIFIER

Step-02A, corrective assignment for Step-02. Step-02 is NOT ACCEPTED. This is the sole active assignment. Step-03 is blocked and not assigned.

STEP TITLE

Correct ambient-dependent timestamp parsing and over-restrictive optional module evidence applicability, preserving the existing profile feature.

OBJECTIVE

Fix two specific source/contract defects, add meaningful regressions, verify the real Application/UI/native path, and align related documentation. Preserve all other Step-02 behavior and the accepted single-shell/RCL/VSA architecture.

You are the WORKER. Execute only this correction, write prompts/Step-02A-Report.md, and STOP for manual orchestrator review.

ARCHITECTURAL CONTEXT

Read STATE.md, ROADMAP.md, original Step-02, its report, the schema guide and ADR-0003.

Keep the seven-project modular monolith: Client -> UI -> Components, with Application feature slices depending on reusable Core contracts. Client remains the only application executable; no backend, mediator, new host or new assembly. All application/test projects stay under src, tests under src/tests. Only docs, src, prompts are top-level project directories.

The orchestrator found the issues by inspecting source/contracts and official .NET documentation, without running application builds/tests. Reproduce the issues yourself; do not treat static findings as already executed regressions.

CURRENT IMPLEMENTATION STATE

Step-02 introduced:

  • Immutable Core vehicle/profile/module/capability/evidence types in src/AutoForge.Core/Vehicles/VehicleProfile.cs.
  • Application feature at Features/Vehicles/Profiles: strict schema-v1 import/export, an in-memory revision catalog, exact selection and real DI.
  • UI /vehicle-profiles with explicit JSON import, revision selection, metadata/provenance inspection and export; no auto-selection or target changes.
  • Three synthetic fixtures and expanded tests. The worker reports 59 unit and 34 integration cases passed (93 total, zero failed/skipped), full solution and direct native Release builds with zero warnings/errors, and native profile smoke. These reported runs remain valid evidence of their covered cases, not proof that the two missing cases work.

Step-01/Step-01A remain accepted. There is no simulation, diagnostic transport, calibration data/editor, physical operation, persistent database/file store or AI. Preserve previous assignments/reports and any concurrent work. Reinspect Git and instructions before editing; do not assume the worktree is clean.

REQUIRED IMPLEMENTATION

R-01 - Require complete, explicit-offset timestamp input

Location: VehicleProfileJsonCodec.cs, NullableDate, line 478.

Current code uses DateTimeOffset.TryParse with InvariantCulture and RoundtripKind. The official TryParse documentation states that a missing date defaults to the current day, a missing offset defaults to the local zone, and RoundtripKind has no effect for DateTimeOffset. This accepts forms outside the explicit timestamp contract and can invent metadata from the execution environment.

Correct both publishedAt and retrievedAt:

  1. Keep explicit JSON null as unknown.
  2. Accept a documented, strict ISO-8601 subset containing the complete calendar date, time including seconds and an explicit Z or signed HH:mm UTC offset. Support the existing exporter's round-trip format, including its fractional seconds and numeric offsets. Preserve supplied instant/offset/precision semantically; do not invent or silently reinterpret missing parts.
  3. Reject time-only, date-only, offset-free date/time, culture-style/slash dates, missing-year forms, whitespace-padded input, malformed dates and invalid offsets. Do not replace missing pieces with today, local time, UTC or defaults.
  4. Surface VehicleProfileInterchangeException with the precise offending publication/retrieval JSON path and actionable format guidance. Invalid input must fail before catalog registration.
  5. Use a simple verified .NET implementation. Merely switching culture, DateTimeStyles.None/AssumeUniversal, or relying on a permissive helper does not satisfy strictness. Verify the actual lexical and offset behavior.

Do not change the schema version merely to fix behavior that violated the stated v1 contract. Record the newly explicit supported timestamp subset in schema docs. Do not alter the system date, time zone or machine settings to test this.

R-02 - Distinguish an absent identity constraint from an asserted null match

Location: VehicleProfile.cs, module applicability validation at line 367 and SameOptional at line 408.

The helper currently returns right is null whenever the evidence identity is null. It therefore rejects evidence that specifies a matching module but omits an optional hardware/software/firmware/calibration constraint whenever the module has that identity. The schema describes those context fields as optional.

Concrete baseline vector: keep the module's known hardware identity and all matching vehicle/profile/module context, but set only the evidence's hardware applicability to explicit null. No hardware constraint was supplied; the otherwise compatible profile must not be rejected for that omission.

Required behavior:

  • A null optional evidence identity means no constraint was supplied for that field. It does not assert that the corresponding module identity must be null.
  • A module-scoped record with no version-specific identity constraints is valid when its vehicle/profile/module context is valid.
  • Validate every supplied non-null constraint. Preserve rejection of mismatched known values and supplied constraints against unknown target module values. Do not convert an unknown target into a verified match or fill its identity.
  • Preserve rejection of dangling/wrong module IDs, wrong vehicle/profile/revision, conflicting known model years and invalid evidence references. Version-specific context without a module instance remains invalid.
  • Apply consistent rules across module and capability evidence references, direct constructors and JSON/service import. Preserve immutable originals, classifications, limitations, unknowns and lack of operational authorization.

Use the smallest clear shared validation change. Do not duplicate alternative matching logic in the codec/UI or weaken known-constraint checks to pass tests. Document precisely the absence-versus-supplied-constraint semantics.

FILES OR PROJECTS EXPECTED TO CHANGE

  • Correct the two existing Core/Application validation paths.
  • Extend the existing domain/codec unit tests and real profile composition/UI integration tests. Add focused fixture variants only if necessary; preserve the original synthetic baseline/variant/alternate inputs where possible.
  • Update schema/build guidance, relevant ADR text, documentation index if needed, and root README for actual corrective status and verification.
  • UI changes only if needed to expose the corrected service failures/results; no new page/host/engine or scope expansion.
  • Create only prompts/Step-02A-Report.md under prompts.

Do not modify assignments, ROADMAP, STATE, previous reports or protected Copilot instructions. Do not create override instruction files, initialize Git, stage, commit, push, discard unrelated changes or perform destructive cleanup.

INTERFACE AND DEPENDENCY REQUIREMENTS

Preserve existing public feature contracts and seven-project reference graph. Keep validation in Core/Application; UI remains presentation. Preserve typed errors, catalog atomicity, exact revision selection, no target substitution and all prior metadata-only/safety boundaries. No new package, major tool installation, workload update/restore/repair/rollback or external service is expected or authorized. Ordinary package restore is distinct from workload-changing commands.

TESTING REQUIREMENTS

Reproduction and unit regressions

First add focused tests that demonstrate each issue against the current code, execute them and record the actual pre-fix failures. Then implement the correction and rerun them. Do not fabricate before/after results.

For both timestamp fields:

  • Invalid: time-only, date-only, full time without offset, missing-year, culture-style date, whitespace-padded, malformed calendar and invalid-offset input. Assert explicit interchange failure and the correct property path.
  • Valid: null; UTC Z; positive/negative numeric offsets; non-fractional and exporter-produced fractional values. Assert the exact expected date/time, offset and round-trip semantics, not just successful parsing.
  • Ensure no format can depend on current day or local zone. Do not change global clock/time-zone settings. Keep the tests deterministic.

For evidence:

  • Module-only matching context with all four optional identity constraints null.
  • Each optional constraint independently null while the module's corresponding value is known, plus mixed supplied/absent matching constraints.
  • Supplied non-null constraints matching the module succeed.
  • Supplied constraints conflicting with a known value or targeting an unknown value fail; wrong/dangling module, vehicle/profile/revision and evidence references continue to fail.
  • Assert identities/classification/unknowns are preserved, not inferred or promoted.

Real DI and UI integration

Import/select/export/reimport through the real profile feature:

  1. Invalid timestamp rejects atomically with the expected interchange path and unchanged catalog/current explicit selection. Do not let a duplicate-key error mask whether the timestamp was validated.
  2. A profile containing valid partial/module-only evidence context imports and round-trips with the absent fields still null.
  3. Invalid supplied identity constraints still reject atomically.
  4. Actual routed UI displays the timestamp/scope errors and accepts the corrected positive case via the same real service; no fake feature/component under test.

Use robust data mutation helpers or assert that test mutations really changed the intended JSON path. Existing successful string replacements are not proof that the specific invalid vector was exercised.

Build, regression and native evidence

Preserve all 93 current cases/invariants, add the missing regressions, and run focused checks while implementing. Then run, sequentially, the complete Release solution build and both suites using the existing SDK/runner:

  • dotnet build .\src\AutoForge.slnx --configuration Release --no-restore
  • dotnet test .\src\AutoForge.slnx --configuration Release --no-build
  • Direct Windows Client build when needed for native target verification, using the existing net10.0-windows10.0.26100.0 target; no framework override on portable projects. Restore packages only when needed.

Record exact commands/exit outcomes, target/configuration, warnings and per-project discovered/passed/failed/skipped counts. Do not run competing build/test processes against the same outputs or skip required cases to report success.

Launch the actual native Client and verify a valid explicit timestamp/partial evidence profile imports/selects/exports, an invalid timestamp shows its specific error, and a conflicting supplied constraint fails without catalog/selection replacement. Verify original fixture import and target metadata routes still work. Record observations separately from headless tests; report any exact environment blocker and unexecuted check honestly.

DOCUMENTATION REQUIREMENTS

Update the root README and directly related schema/ADR/testing documentation with:

  • The exact accepted timestamp grammar and explicit null/offset rules.
  • Absence versus supplied optional evidence constraints, preserved mismatch/ unknown-target handling and the fact that validation never grants authority.
  • Step-02/Step-02A worker verification versus pending orchestrator acceptance, actual test/native evidence and limitations.
  • Existing one-shell/two-RCL/VSA architecture and native startup/build instructions.

Keep Markdown LF convention and historical reports intact. Do not rewrite the original 93-test evidence as though it covered these new cases.

ACCEPTANCE CRITERIA

ID Criterion Required evidence
AC-01 Both timestamp properties accept only the documented complete, explicit-offset grammar or null; no ambient defaults Positive/negative vectors, exact date/offset assertions and implementation paths
AC-02 Partial/module-only optional evidence context works without mutating unknowns or weakening supplied-constraint validation Direct constructor matrix covering all four fields and positive/negative identity cases
AC-03 Domain, JSON/service and actual UI paths consistently implement the corrected rules, preserving atomic failed import/explicit selection Real DI/rendered integration assertions and exact failure paths
AC-04 Original fixtures, metadata statuses/provenance, exact revisions, target isolation, all 93 prior cases and architecture remain intact Regression mapping, source/project/Git review and per-project results
AC-05 Focused new tests demonstrate actual pre-fix failures and pass after correction; complete solution/native verification succeeds Before/after commands/results, sequential Release build/test evidence and native observations
AC-06 README/schema/ADR/test guidance accurately describe the corrected v1 contract and corrective lifecycle Changed documentation list and exact policy summary
AC-07 No unrelated feature, package/workload action, orchestration/protected-file edit or automatic handoff introduced; report complete and worker stops Preservation/scope evidence and prompts/Step-02A-Report.md

Map every criterion to PASSED, FAILED, NOT EXECUTED or BLOCKED with concrete evidence. COMPLETE requires all required correction/regression/native checks. Do not begin Step-03; acceptance belongs to the orchestrator.

OUT-OF-SCOPE WORK

New vehicle features, simulation/diagnostic engines or protocols, transport/ hardware/provider integration, calibration values/programming, persistence, research/AI, new shells/RCLs, mediator/generic repository refactors, broad model redesign and unrelated UI cleanup. All physical safety/prohibited-operation restrictions remain unchanged.

REPORTING REQUIREMENTS

Create prompts/Step-02A-Report.md entirely inside exactly one plain triple-backtick code fence, without language tag or outside content. Use no nested fences. Use the same copy-window format for the final chat report.

Include step/title and COMPLETE/INCOMPLETE/BLOCKED status; functionality and architectural changes; files created/modified; R-01/R-02 root causes and fixes; unit/integration tests and before/after evidence; exact build/test commands and results with per-project counts; native observations; AC-01 through AC-07 mapping; documentation and README changes; limitations/outstanding issues; deviations; recommendations; and protected/scope/Git preservation review.

Save the report and STOP. Do not change assignments/roadmap/state, create or begin Step-03, invoke another agent, automate handoff, stage, commit or push.