AutoForge/docs/adr-0003-profile-interchang...

73 lines
4.4 KiB
Markdown

# ADR-0003: Strict versioned vehicle-profile metadata interchange
- Date: 2026-10-28
- Status: implemented and worker-verified for Step-02/Step-02A; manual orchestrator acceptance pending
- Scope: vehicle profile metadata model and in-memory JSON interchange
## Context
Step-02 needs a data-driven representation of vehicles, arbitrary module
inventories, operation declarations, unknown facts and provenance. The first
profile slice must remain useful without a database, online service or real
vehicle definition. Silent defaults or permissive JSON mapping could discard
identity/evidence or bind a profile to an unintended revision.
## Decision
1. Core owns immutable vehicle identity, profile revision, module instances,
extensible role/operation identifiers, capability declaration states and
evidence applicability. Profile revision identifies an immutable saved
configuration; schema version identifies the JSON format.
2. The Application feature owns schema-v1 JSON import/export and an in-memory
exact `(profileIdentifier, revision)` catalog. The catalog uses
ordinal case-insensitive identity comparison, rejects duplicates, and never
chooses a latest/closest configuration.
3. Schema v1 requires all defined properties, representing unknown optional facts
with explicit JSON `null`. Reject malformed/unsupported versions, ambiguous
duplicate properties, unknown properties, invalid enums, duplicates and
dangling/conflicting evidence. Incompatible future schemas require an explicit
later version and migration rather than silent downgrade.
4. Provenance applicability is scoped to a vehicle and optionally a model year,
exact profile revision, module instance and module identity values. Null
confidence is unknown; numeric confidence is finite `[0,1]`. A null optional
module identity applicability field is no constraint; each supplied non-null
constraint must match a known target module identity. A supplied constraint
against a mismatched or unknown target is rejected, and no identity is inferred
or filled. Module-scoped evidence may omit all four version-specific constraints.
Classification preserves supplied evidence only and does not independently
verify it or authorize work.
5. Synthetic fixtures remain source-controlled test inputs. The Client catalog is
in-memory per process; the existing UI imports explicitly and requires explicit
selection before displaying or exporting a profile.
6. This is metadata-only. No diagnostic service, simulation, calibration data,
firmware image, operation executor, persistent user-file storage, AI or
hardware authorization is part of this decision.
7. `publishedAt` and `retrievedAt` accept explicit null or only a complete
`YYYY-MM-DDTHH:mm:ss[.fraction](Z|+HH:mm|-HH:mm)` timestamp: uppercase `T`/`Z`,
required seconds, optional 1-7 digit fractional seconds and an explicit valid
whole-minute offset in `-14:00..+14:00`. Parsing never supplies local-zone or
current-date defaults. Invalid input fails with the exact JSON property path
before catalog registration.
## Consequences
- Immutable constructor validation is shared by direct domain construction and
JSON deserialization. Arrays/collections are snapshotted and not exposed.
- Optional evidence identity constraints remain absent when null; known module
identifiers are neither required to be null nor copied into evidence. Supplied
constraints cannot match an unknown target or change classification/authority.
- Timestamp parsing is lexically restricted and calendar-validated before creating
`DateTimeOffset`, so an import cannot inherit machine-local time or today's date.
- The strict v1 policy may reject forward-extended documents until a later schema
version is deliberately implemented; this is preferable to losing unknown
identity or capability data.
- The catalog currently loses imported data on process exit. Persistence needs a
separate approved design and is not implied by JSON export.
- “Supported” and `VERIFIED` remain labels on metadata, not proof of an
implemented operation, vehicle compatibility, authorization or physical access.
See [schema-v1 profile documentation](vehicle-profile-schema-v1.md),
[architecture](architecture.md) and [build/test guidance](build-and-test.md).
Step-02A's worker report records correction regressions and native verification;
manual orchestrator acceptance of Step-02 remains pending.