Skip to content

ADR 0002: Visibility Policy Contract

Status

Accepted

Context

The handbook defines multiple visibility policies used across customer lifecycle and applet visibility flows:

  • sa_wide
  • assigned_plus_unassigned
  • assigned_only

These policy names are reused across contexts, but their enforcement semantics can drift if not recorded as a stable contract.

Decision

Treat visibility policies as a governed contract with fixed semantics:

  • sa_wide: any actor inside the scoped Service Account can view.
  • assigned_plus_unassigned: directly assigned actors can view, and unassigned records inside scope remain visible.
  • assigned_only: only directly assigned actors can view.

Apply policy evaluation consistently in this order:

  1. Service Account scope eligibility
  2. Assignment state eligibility
  3. Workflow-specific additional constraints

Any new policy addition or semantic change requires a new ADR.

Consequences

  • Teams can reason about visibility outcomes consistently across customer, applet, and related domains.
  • Cross-workflow documentation can reference a single policy contract rather than redefining semantics.
  • Policy changes become explicit architectural events with reviewable rationale.
  • Implementation gaps can be identified as "contract not enforced here yet" instead of silent behavioral divergence.