import type { EmailStatusExtractorConfig } from './email-status';
import type { DeeplineGetterValueMap } from './extractor-targets';
import type { PlayDataset, SerializedPlayDataset } from '../plays/dataset';

export type ToolResultExecutionMetadata = {
  idempotent: true;
  cached: boolean;
  source: 'live' | 'checkpoint' | 'cache' | 'in_flight';
  cacheKey?: string;
  receiptRole?: 'owner' | 'follower';
  receiptKey?: string;
  attachedToReceiptKey?: string;
};

export type ToolResultTargetMetadata = {
  value: unknown;
  path: string;
};

export type ToolResultListMetadata = {
  path: string;
  count: number | null;
  keys: Record<string, string>;
};

export type ToolResultExtractorDescriptor = {
  paths: readonly string[];
  transforms?: readonly string[];
  enum?: readonly string[];
  overrides?: readonly ToolResultExtractorOverride[];
  emailStatus?: EmailStatusExtractorConfig;
};

export type ToolResultExtractorOverride = {
  paths: readonly string[];
  equals?: string | number | boolean | null;
  value: string | number | boolean | null;
};

export type ToolResultMetadata = {
  toolId: string;
  execution: ToolResultExecutionMetadata;
  targets: Record<string, ToolResultTargetMetadata>;
  lists: Record<string, ToolResultListMetadata>;
  /** Original declarations preserve semantic accessor names across replay. */
  listExtractorPaths?: readonly string[];
  extractors?: Record<string, ToolResultExtractorDescriptor>;
};

export type ToolResultTargetAccessor<T = unknown> = ToolResultTargetMetadata & {
  get(): T | null;
};

export type ToolResultListAccessor<
  T = Record<string, unknown>,
  TKey extends string = string,
> = Omit<ToolResultListMetadata, 'keys'> & {
  keys: Partial<Record<TKey, string>> & Record<string, string>;
  get(): PlayDataset<T>;
};

export type ToolResultMetadataInput = {
  toolId: string;
  extractors?: Record<string, ToolResultExtractorDescriptor>;
  targetGetters?: Record<string, readonly string[]>;
  listExtractorPaths?: readonly string[];
  listIdentityGetters?: Record<string, readonly string[]>;
};

export type ToolResultEnvelope<
  TData = unknown,
  TMeta = Record<string, unknown>,
> = {
  data: TData;
  meta?: TMeta;
};

export type SerializedToolExecuteResultV1 = {
  __kind: 'deepline.tool_execute_result.v1';
  status: string;
  job_id?: string;
  /** Deepline-owned execution/result metadata. */
  meta?: Record<string, unknown>;
  toolResponse: {
    /**
     * Raw provider/tool data with declared row-list payloads clipped to bounded
     * previews. Use list getters for row-shaped data.
     */
    raw: unknown;
    meta?: Record<string, unknown>;
  };
  listDatasets?: Record<string, SerializedPlayDataset<Record<string, unknown>>>;
  /** Full declared list rows used to rehydrate list Dataset Handles. */
  listRows?: Record<string, Array<Record<string, unknown>>>;
  /** Computed scalar/object getters preserved before raw list previews are clipped. */
  targetValues?: Record<string, ToolResultTargetMetadata>;
  metadata: ToolResultMetadataInput;
  execution: ToolResultExecutionMetadata;
};

/**
 * Canonical receipt form. Provider data is stored once as `rawV2`; the legacy
 * raw/meta view is recreated from the payload-free projection descriptor.
 */
export type SerializedToolExecuteResultV2 = Omit<
  SerializedToolExecuteResultV1,
  '__kind' | 'toolResponse'
> & {
  __kind: 'deepline.tool_execute_result.v2';
  toolResponse: {
    rawV2: unknown;
    view: 'data' | 'rawV2';
    /** Deepline-owned additions not already represented in `rawV2.meta`. */
    responseMeta?: Record<string, unknown>;
  };
};

export type SerializedToolExecuteResult =
  | SerializedToolExecuteResultV1
  | SerializedToolExecuteResultV2;

export type ToolResponseEnvelope<
  TData = unknown,
  TMeta = Record<string, unknown>,
> = {
  raw: TData;
  /** Complete parsed and scrubbed provider response, materialized from raw-v2. */
  rawV2?: unknown;
  /** Durable descriptor for deriving the legacy raw view from `rawV2`. */
  view?: 'data' | 'rawV2';
  meta?: TMeta;
};

export type ToolExecuteResultBase<
  TResult = unknown,
  TMeta = Record<string, unknown>,
> = {
  status: string;
  job_id?: string;
  /** Deepline-owned execution/result metadata. */
  meta?: Record<string, unknown>;
  toolResponse: ToolResponseEnvelope<TResult, TMeta>;
  extractedValues: Record<string, ToolResultTargetAccessor>;
  extractedLists: Record<string, ToolResultListAccessor>;
  /** Convenience alias for play code. Serialized output uses toolResponse. */
  toolOutput: ToolResponseEnvelope<TResult, TMeta>;
  _metadata: {
    toolId: string;
    execution: ToolResultExecutionMetadata;
    targets: Record<string, { value: unknown; path: string }>;
    extractors?: Record<string, ToolResultExtractorDescriptor>;
    lists: Record<
      string,
      {
        path: string;
        count: number | null;
        keys: Record<string, string>;
      }
    >;
    /** Original declarations preserve semantic accessor names across replay. */
    listExtractorPaths?: readonly string[];
  };
};

export type ToolExecuteResultAccessors<
  TExtracted extends Record<string, unknown> = Partial<DeeplineGetterValueMap>,
  TLists extends Record<string, Record<string, unknown>> = Record<
    string,
    Record<string, unknown>
  >,
> = {
  extractedValues: {
    [K in keyof TExtracted]: ToolResultTargetAccessor<TExtracted[K]>;
  };
  extractedLists: {
    [K in keyof TLists]: ToolResultListAccessor<TLists[K]>;
  };
};

/**
 * Canonical result returned by Deepline tool execution.
 *
 * The top-level object is Deepline-owned execution metadata and semantic
 * extraction state. The canonical provider response lives under
 * `toolResponse.rawV2`; `toolResponse.raw` remains the legacy compatibility
 * projection. Response metadata lives under `toolResponse.meta`. Semantic single-value
 * getters live under `extractedValues.<name>.get()`, and list getters live
 * under `extractedLists.<name>.get()`.
 *
 * Use extractors first when a tool contract exposes them. Use list getters for
 * row-shaped data. Drop to `toolResponse.raw` only for provider-specific scalar
 * fields or bounded debugging context; persisted rows may clip declared lists to
 * previews.
 *
 * @sdkReference runtime 200
 */
export type ToolExecuteResult<
  TResult = unknown,
  TMeta = Record<string, unknown>,
  TExtracted extends Record<string, unknown> = Partial<DeeplineGetterValueMap>,
  TLists extends Record<string, Record<string, unknown>> = Record<
    string,
    Record<string, unknown>
  >,
> = ToolExecuteResultBase<TResult, TMeta> &
  ToolExecuteResultAccessors<TExtracted, TLists>;