73 lines
4.4 KiB
Markdown
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.
|