import type {
  ClaimRuntimeStepReceiptInput,
  CompleteRuntimeStepReceiptInput,
  FailRuntimeStepReceiptInput,
  GetRuntimeStepReceiptInput,
  ReleaseRuntimeStepReceiptInput,
  RuntimeStepReceipt,
  SkipRuntimeStepReceiptInput,
} from './ctx-types';
import type { PlayRunLedgerEvent } from './run-ledger';

export type MapRowOutcomeStatus = 'completed' | 'failed';

export type MapRowOutcome = {
  key: string;
  /**
   * Original row position within this dataset invocation. The deterministic
   * key is the primary identity; inputIndex is a same-run repair identity for
   * completion writes after the start phase has already stamped `_run_id`.
   */
  inputIndex?: number | null;
  data: Record<string, unknown>;
  cellMetaPatch?: Record<string, unknown>;
  /**
   * Terminal row status for this write. Defaults to completed. Failed rows keep
   * partial data, persist `_error`, and are returned as pending on the next run.
   */
  status?: MapRowOutcomeStatus;
  /** Row-level error message persisted when `status` is failed. */
  error?: string | null;
};

/**
 * Runner-facing Interface for hot-path durable writes.
 *
 * Runtime API and Play Harness Worker Adapters can satisfy this seam while
 * keeping their transport/SQL details private to their Implementations.
 */
export interface PlayDurabilityStore {
  appendRunEvents(input: {
    runId: string;
    events: readonly PlayRunLedgerEvent[];
  }): Promise<void>;

  getRuntimeStepReceipt(
    input: GetRuntimeStepReceiptInput,
  ): Promise<RuntimeStepReceipt | null>;
  claimRuntimeStepReceipt(
    input: ClaimRuntimeStepReceiptInput,
  ): Promise<RuntimeStepReceipt | null>;
  completeRuntimeStepReceipt(
    input: CompleteRuntimeStepReceiptInput,
  ): Promise<RuntimeStepReceipt | null>;
  releaseRuntimeStepReceipt(
    input: ReleaseRuntimeStepReceiptInput,
  ): Promise<RuntimeStepReceipt | null>;
  failRuntimeStepReceipt(
    input: FailRuntimeStepReceiptInput,
  ): Promise<RuntimeStepReceipt | null>;
  skipRuntimeStepReceipt(
    input: SkipRuntimeStepReceiptInput,
  ): Promise<RuntimeStepReceipt | null>;

  prepareMapRows(input: {
    tableNamespace: string;
    rows: readonly Record<string, unknown>[];
    outputFields: readonly string[];
  }): Promise<{
    pendingRows: Record<string, unknown>[];
    completedRows: Record<string, unknown>[];
  }>;

  completeMapRows(input: {
    tableNamespace: string;
    rows: readonly MapRowOutcome[];
    outputFields: readonly string[];
  }): Promise<{ updated: number }>;
}