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

4.4 KiB

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, architecture and build/test guidance. Step-02A's worker report records correction regressions and native verification; manual orchestrator acceptance of Step-02 remains pending.