ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
platform-dev
TenantAtlas/specs/350-operator-resolution-guidance-framework-v1/contracts/adapter-contract.md
ahmido 4cf2712f92 feat: operator resolution guidance framework v1 (spec 350) (#421) 
Implemented the first version of the operator resolution guidance framework. Added new foundation classes (ResolutionCase, ResolutionAction) and a ReviewPackOutputResolutionAdapter. Updated the Customer Review Workspace and Environment Review Resource to use the new adapter. Added extensive test coverage for the framework and UI integrations.

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #421
2026-06-03 15:35:25 +00:00

2.6 KiB
Raw Permalink Blame History

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.