type ArgsCodec<D extends DefinitionData = DefinitionData> = Schema.Codec<ReadArgs<D>, Annotation["args"]>

export interface DefinitionLift<D extends DefinitionData = DefinitionData> {
  readonly rules?: ReadonlyArray<LiftRule>
  readonly recognize?: (site: LiftSite<D>) => Result.Result<ReadArgs<D>, LiftRecognitionError>
}

export interface ImplementOptions<Read, D extends DefinitionData = DefinitionData> {
  /** Explanations owned by this implementation, collected by extension(). */
  readonly diagnosticEntries?: ReadonlyArray<DiagnosticEntry>
  /** IR analyses that belong to this annotation (diagnostics only). */
  readonly analyze?: Analysis | ReadonlyArray<Analysis>
  /** A free generator over the IR: new generated files, never a rewrite of source (spec 0020 §6). */
  readonly write?: Generator
  /** Source→IR. Omitted: the default declarative `Extension` node (spec 0020 §2.3), added by the framework. */
  readonly read?: (args: Read, at: ReadContext) => Contribution
  /** A framework guard run before the duplicate check (e.g. `Http.Group`'s declaration-kind check). */
  readonly before?: (annotation: { readonly name: string }, declaration: Declaration) => Diagnostic | undefined
  /** Duplicate-annotation diagnostic for `cardinality: "one"`; defaults to `EFFX2402`. */
  readonly duplicate?: (subject: string, annotation: string) => Diagnostic
  /** Diagnostic for an operation-target annotation on a declaration that is not an operation. */
  readonly notOperation?: (annotation: { readonly name: string }, declaration: Declaration) => Diagnostic
  /**
   * What malformed arguments contribute. Default `"report"`: the `EFFX1102` diagnostic. `"ignore"`: nothing,
   * for an assertion annotation whose arguments another interpreter already decodes and reports
   * (`@Errors`/`@Requirements` are decoded and reported by the operation they sit on).
   */
  readonly malformed?: "report" | "ignore"
  /**
   * The definition-owned compiler lift seam (spec 0019 §5, S1). Omitted: the framework's default
   * recognizer lowers the site's term by `definition.plan` and decodes with the definition's own codec.
   */
  readonly lift?: DefinitionLift<D>
}

export interface Implementation<D extends DefinitionData = DefinitionData> {
  readonly definition: D
  readonly diagnosticEntries?: ReadonlyArray<DiagnosticEntry>
  readonly interpreter: Interpreter
  readonly analyses: ReadonlyArray<Analysis>
  readonly generators: ReadonlyArray<Generator>
  /**
   * The erased definition-owned lift hook (spec 0019 §5, S1). Erased because `Implementation<D>` must
   * stay assignable to `Implementation` for `extension()`; the site carries the definition itself and the
   * result is validated by the definition's own decode, so the type-level erasure never changes what a
   * recognizer receives or returns.
   */
  readonly lift?: LiftImplementation
}

export interface LiftDefinitionEntry {
  readonly definition: DefinitionData
  readonly rules: ReadonlyArray<LiftRule>
  readonly recognize: LiftRecognition | undefined
}

export interface LiftImplementation {
  readonly rules: ReadonlyArray<LiftRule>
  readonly recognize: LiftRecognition | undefined
}

type LiftRecognition = (site: LiftSite<DefinitionData>) => Result.Result<unknown, LiftRecognitionError>

type LiftRecognitionError = typeof LiftRecognitionErrorSchema.Type

declare const LiftRecognitionErrorSchema: Schema.TaggedStruct<"Unsupported", { readonly construct: Schema.String }>

export interface LiftRegistry {
  /** Entries by annotation name, in implementation order; the first implementation of a name wins. */
  readonly definitions: ReadonlyMap<string, LiftDefinitionEntry>
  /** Definition-owned rule data, in implementation order, behind the input's own rules. */
  readonly rules: ReadonlyArray<LiftRule>
  /** The derived lowered-args codec of each definition, derived ONCE per registry (never per endpoint). */
  readonly codecs: ReadonlyMap<string, ArgsCodec>
}

export interface LiftSite<D extends DefinitionData = DefinitionData> {
  readonly definition: D
  readonly schema: ArgsCodec<D>
  /** The term the frontend lowered for the annotation's argument list. */
  readonly value: Term
  /** `<group>.<endpoint key>`, as users write the site. */
  readonly subject: string
  /** Source range of the `.annotate` step. */
  readonly range: SourceRange
  readonly names: Readonly<Record<string, SymbolRef>>
  readonly emptyInput: SchemaRef | undefined
  readonly project: ProjectResolution
}

type ReadArgs<D> = D extends { readonly Args?: infer Input }
  ? Resolved<ReadParameters<Exclude<Input, undefined>>>
  : never

export interface ReadContext {
  /** The lowered annotation `args` were decoded from; its `definition` is the definition's own export. */
  readonly annotation: Annotation
  readonly declaration: Declaration
  readonly ctx: InterpretContext
}

type Resolved<T> = T extends JsonValue
  ? T // marker-free JSON (also: the recursive `JsonValue` itself must not be mapped over)
  : T extends SchemaMarker
    ? typeof SchemaArg.Type
    : T extends RootSymbolMarker
      ? typeof RootSymbol.Type
      : T extends SymbolMarker
        ? typeof SymbolArg.Type
        : T extends CapabilityMarker
          ? typeof capabilityValue.Type
          : T extends ReadonlyArray<unknown>
            ? { readonly [I in keyof T]: Resolved<T[I]> }
            : T extends object
              ? { readonly [K in keyof T]: Resolved<T[K]> }
              : T

declare const argsSchemaOf: (plan: ArgsPlan) => Schema.Top

declare const dataOf: <D extends DefinitionData>(
  definition: D,
  ir: ApplicationIR,
  operationId: StableId.StableId
) => Option.Option<ReadArgs<D>>

declare const decodeSchemaOf: <D extends DefinitionData>(definition: D) => ArgsCodec<D>

declare const decoderOf: <D extends DefinitionData>(
  definition: D
) => (annotation: Annotation, declaration: Declaration) => Result.Result<ReadArgs<D>, Diagnostic>

declare const definitionDiagnostics: (extensions: ReadonlyArray<Extension>) => ReadonlyArray<Diagnostic>

declare const definitionProblemDiagnostics: (definition: DefinitionData) => ReadonlyArray<Diagnostic>

declare const definitionsOf: (extensions: ReadonlyArray<Extension>) => ReadonlyMap<string, DefinitionEntry>

declare const extension: (
  name: string,
  implementations: ReadonlyArray<Implementation>,
  rest?: Partial<Pick<Extension, "analyses" | "generators" | "expand" | "diagnosticEntries">>
) => Extension

declare const implement: <D extends DefinitionData>(
  definition: D,
  options?: ImplementOptions<ReadArgs<D>, D>
) => Implementation<D>

declare const liftRegistryOf: (extensions: ReadonlyArray<Extension>) => LiftRegistry

declare const schemaOfPlan: (plan: Plan) => Schema.Top