type AccessUse = AccessContractData

export interface ContractMetadata {
  readonly annotator: SymbolRef | undefined
  readonly operationId: string
  readonly summary: string | undefined
  readonly description: string | undefined
  readonly tags: ReadonlyArray<string> | undefined
}

export interface MetadataUse {
  readonly annotator: SymbolRef | undefined
  readonly operationId: string | undefined
  readonly summary: string | undefined
  readonly description: string | undefined
  readonly tags: ReadonlyArray<string> | undefined
}

type Method = "GET" | "POST" | "PUT" | "PATCH" | "DELETE"

export interface MiddlewareUse {
  readonly ref: SymbolRef
  readonly security: boolean
}

export interface Outcome {
  /** `<group>.<key>`, as users write it. */
  readonly subject: string
  /** Present exactly when `causes` is empty. */
  readonly recognized: Recognized | undefined
  readonly causes: ReadonlyArray<Cause>
  readonly refactors: ReadonlyArray<Refactor>
  readonly codeReferences: ReadonlyArray<CodeReference>
}

export interface ProblemsUse {
  readonly registry: SymbolRef
  readonly identifier: string
  readonly codes: ReadonlyArray<string>
}

export interface Recognized {
  readonly subject: string
  readonly key: string
  readonly method: Method
  readonly path: string
  readonly params: SchemaUse | undefined
  readonly query: SchemaUse | undefined
  readonly headers: SchemaUse | undefined
  readonly payload: SchemaUse | undefined
  readonly mediaType: string | undefined
  readonly success: SchemaUse
  readonly status: number | undefined
  readonly responseHeaders: SchemaRef | undefined
  readonly conditional: boolean
  /** The registered success wrapper the endpoint is written through (its header refactor is planned once). */
  readonly wrapper: SymbolRef | undefined
  readonly middleware: ReadonlyArray<MiddlewareUse>
  readonly metadata: ContractMetadata
  readonly problems: ProblemsUse | undefined
  readonly access: AccessUse | undefined
  /**
   * The definition annotations the `.annotate` steps produced, in step order (spec 0019 §5, S1). Atomicity
   * is the engine's: a recognized endpoint carries them only when every cause was cleared.
   */
  readonly annotations: ReadonlyArray<Annotation>
}

export interface SchemaUse {
  readonly ref: SchemaRef
  /** Every static field key (params, operation input). */
  readonly allKeys: ReadonlyArray<string> | undefined
  /** The required static field keys (headers). */
  readonly requiredKeys: ReadonlyArray<string> | undefined
  /** Wrapped by `Http.headers`. */
  readonly headers: boolean
}