TenantAtlas/specs/095-graph-contracts-registry-completeness/research.md

Phase 0 — Research: Graph Contracts Registry Completeness

Decisions

Decision: Scope of enforcement

• Decision: Enforce “registry-backed paths” only for the four specified Graph resources and the five known call sites.
• Rationale: Keeps the change bounded and reviewable while addressing the concrete governance gap.
• Alternatives considered:
  • Enforce across the entire codebase (rejected: scope explosion and higher regression risk).

Decision: Acceptance evidence

• Decision: Pest tests passing are sufficient acceptance evidence.
• Rationale: Reproducible in CI/local without requiring a live tenant or delegated auth.
• Alternatives considered:
  • Require drift-check command output (rejected: can require tenant setup and auth).

Decision: Handling additional discoveries

• Decision: Do not expand scope beyond the four specified resources.
• Rationale: Prevents “scope creep by implementation”. Additional gaps can be handled via a follow-up spec.
• Alternatives considered:
  • Expand to additional resources found during implementation (rejected: unbounded).

Best Practices / Patterns (Repo-specific)

• Contract registry: Graph endpoint resources are centrally declared in config/graph_contracts.php and should be considered the source of truth.
• Graph client: All Graph calls route through GraphClientInterface.
• Governance goal: Feature code should avoid ad-hoc endpoint strings for governed resources.

Testing Strategy

• Registry completeness test: Assert the four resources are registered and the template subresource is representable.
• Regression guard: Assert the five in-scope files do not contain hardcoded endpoint substrings for the governed resources.

Notes

• This feature makes no changes to RBAC, UI, database schema, or operations observability.

Follow-ups (out of scope)

• None identified yet.