ADR 0018: Program-scoped connections with pinned vendor API versions

Status: Accepted
Date: 2026-09-14
Deciders: Founder

Context

Connections are program-scoped records in phase 1. The ELN issues tenant-wide app credentials and the QMS a tenant-wide integration user, which suggested organisation-level connections; that is a scope-model change with new org routes and permission keys.

Decision

Connections stay program-scoped in phase 2; a partner registers one app or integration user per program with scope_rules (project ids, document types) enforced by Trovensa. Organisation-level connections are designed for R3.
Each connection pins the vendor API version it speaks (connections.api_version, e.g. the QMS v26.2); a bump is a controlled change that writes an audit row.
Rate budgets are rows (rate_budgets) at platform, organisation or connection scope; connection rows draw from their organisation row.

Consequences

No new org routes or keys; the permission count stays coherent at 81.
Frozen vendor API versions make the integration cheap to maintain; the health check re-validates on every version change.

Alternatives considered

Organisation-level connections now: five new routes and keys and a hidden scope-model change; deferred.

Follow-ups

Organisation-level connections with per-program scoping rows (R3).