281 lines
15 KiB
Markdown
281 lines
15 KiB
Markdown
# 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](STATE.md), [ROADMAP.md](ROADMAP.md), original
|
|
[Step-02](Step-02.md), its [report](Step-02-Report.md), the
|
|
[schema guide](../docs/vehicle-profile-schema-v1.md) and
|
|
[ADR-0003](../docs/adr-0003-profile-interchange-v1.md).
|
|
|
|
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](../src/AutoForge.Application/Features/Vehicles/Profiles/VehicleProfileJsonCodec.cs),
|
|
`NullableDate`, line 478.
|
|
|
|
Current code uses DateTimeOffset.TryParse with InvariantCulture and RoundtripKind.
|
|
The [official TryParse documentation](https://learn.microsoft.com/en-us/dotnet/api/system.datetimeoffset.tryparse?view=net-10.0)
|
|
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](../src/AutoForge.Core/Vehicles/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.
|