TenantAtlas/specs/350-operator-resolution-guidance-framework-v1/contracts/adapter-contract.md

Adapter Contract

Status: Draft for Spec 350
Scope: Runtime adapters that wrap existing guidance-producing truth

Purpose

Each adapter translates one current repo-real guidance family into one or more ResolutionCase objects without inventing a new workflow system.

Adapters are not source-of-truth owners. They are normalizers over existing truth.

Required Responsibilities

Each adapter must:

1. accept already-scoped repo-backed input
2. determine the dominant issue case
3. derive one primary action
4. attach source refs and evidence refs where applicable
5. attach technical details as secondary disclosure only
6. preserve existing action safety requirements

Each adapter must not:

1. persist new state
2. create new domain lifecycle or workflow state
3. perform remote calls during render
4. invent actions that do not exist safely in the repo

Suggested Adapter Inputs

Adapter	Expected input truth
ReviewPackOutputResolutionAdapter	EnvironmentReview, ReviewPack, EvidenceSnapshot, existing output-readiness guidance
standalone evidence-basis adapter	not justified in v1 because evidence-basis truth is already part of review-output guidance
ProviderReadinessResolutionAdapter	existing provider surface summary, required-permissions guidance, verification truth
OperationFollowUpResolutionAdapter	existing OperationRun, OperationUxPresenter, operator explanation, proof links

Output Rule

Each adapter returns either:

• one dominant ResolutionCase, or
• a small ordered list of cases where the consumer surface can legitimately display more than one case without creating a warning wall

Default bias: one dominant case.

Consumer Rule

Consumer surfaces may:

• render one case card
• render a bounded list
• merge case metadata into an existing first-viewport decision block

Consumer surfaces may not:

• rebuild the adapter logic locally
• fork the primary-action logic without documenting why
• elevate technical details above the dominant case

V1 Required Adapters

• ReviewPackOutputResolutionAdapter

Optional Same-Slice Adapters

• ProviderReadinessResolutionAdapter
• OperationFollowUpResolutionAdapter

These adapters are allowed only when a concrete in-scope consumer can adopt them without a broader surface redesign.

Optional Later Adapters

• FindingRequiresTriageResolutionAdapter
• AcceptedRiskReviewResolutionAdapter
• standalone evidence-basis adapter after a non-review consumer proves it is necessary

Those optional adapters are out of current guaranteed scope unless the implementation proves they can be added without widening the feature.