Skip to content

ADR 0003 - Canonical ID Strategy and Evidence Storage

Date: 2026-02-06 Status: Accepted

Context

Discovery outputs must be normalized into canonical entities and relationships. IDs must be stable enough to support repeatable UI navigation and future diffing. Evidence references must scale as data grows and align with AWS-hosted SaaS constraints.

Decision

1) Canonical ID strategy - Use stable, deterministic IDs per workspace based on: workspace_id + provider_system + native_type + native_id. - Canonical IDs are derived via a stable hash function and remain consistent across runs. - IDs are unique within a workspace and not shared across workspaces, even within the same tenant.

2) Evidence storage - Store evidence payloads in object storage (AWS S3) and persist references in the database. - The canonical model stores evidence_ref as a pointer to the object location and metadata (bucket, key, checksum, size).

Consequences

  • Enables stable Access Explorer navigation and makes it easier to compare runs.
  • Avoids large evidence blobs in the relational database while keeping metadata queryable.
  • Requires an S3 bucket and KMS policy for encryption at rest.

Alternatives considered

  • Per-run IDs (rejected: unstable UX and poor diffability).
  • Store evidence in DB blobs (rejected: scale and cost concerns).