Types

interface ExecuteRequest {
  /** Action shape, e.g. 'PAYMENT_TRANSFER', 'HOTEL_RESERVATION', 'DATA_EXPORT'. */
  archetype: string;

  /** Archetype-specific constraints. Validated against the archetype's schema. */
  constraints: Record<string, unknown>;

  /** Optional payment-flow mode (production only). */
  payment_mode?: 'QUOTE_ONLY' | 'RESERVE_IF_AVAILABLE' | 'IMMEDIATE_CHARGE' | 'IMMEDIATE_CHARGE_WITH_CHALLENGE';

  /** Opaque delegation token bounding agent authority. */
  delegation_token?: string;

  /** Soft deadline for the gateway pipeline (ms). */
  deadline_ms?: number;
}

interface ExecuteResponse {
  /** Always true for sandbox-issued responses. */
  sandbox: true;

  /** Terminal state of the pipeline. */
  kind: 'executed' | 'held' | 'needs_challenge' | 'pending_settlement' | 'failed' | 'blocked';

  transaction_id: string;
  receipt_id: string;
  receipt_url: string;          // https://executionprotocol.dev/r/<sig>
  receipt_url_short: string;    // https://executionprotocol.dev/r/<short>

  message: string;
  correlation_id: string;

  /** Archetype-specific metadata. */
  details?: Record<string, unknown>;

  /** The full v2.2 receipt — embedded for offline verification. */
  receipt: Receipt;
}

interface Receipt {
  version: { spec: 'ep-receipt/2026-04-27' };
  receiptId: string;
  transactionId: string;
  agentId: string;
  sessionId: string;
  /** ISO-8601 — NOT in the signed bytes (deterministic re-signing under clock skew). */
  created: string;
  /** Hash chain. Index 0 is __genesis__; subsequent indices are pipeline stages. */
  entries: ReceiptEntry[];
  signature: Signature;
  amendmentOf: string | null;
  eventType: 'ORIGINAL' | 'AMENDMENT_SCHEDULE_CHANGED' | 'AMENDMENT_PRICE_ADJUSTED' | 'AMENDMENT_CANCELLED' | 'AMENDMENT_REFUNDED' | 'AMENDMENT_PARTIAL_REFUND' | 'AMENDMENT_PROVIDER_CONFIRMATION' | 'AMENDMENT_BLOCKED' | 'AMENDMENT_INTERVENTION_REQUIRED';
  paymentStatus: 'charged' | 'not_charged' | 'pending_provider_confirmation';
  money: MoneyEnvelope;
  idempotencyKey: string;
  replicaId: string;
  chainId: string;
  regulatoryFramework: string[];
  metadata: Record<string, unknown>;
}

interface ReceiptEntry {
  entryId: string;
  index: number;
  /** '__genesis__' or one of: token_validation, schema, boundary, completeness,
      math, execute, commit_auth_split, receipt. */
  stepName: string;
  input: unknown;
  output: unknown;
  startTime: string;
  endTime: string;
  latencyMs: number;
  cost: number | null;
  error: string | null;
  /** SHA-256 of the canonical entry bytes (RFC 8785 JCS), excluding `hash` itself. */
  hash: string;
  /** Previous entry's hash. Genesis uses 64 hex zeros. */
  previousHash: string;
  metadata: Record<string, unknown>;
}

interface Signature {
  /** Key id; resolves via /.well-known/jwks.json. */
  kid: string;
  /** Always 'ES256' (RFC 7518). */
  alg: 'ES256';
  /** Base64url of R||S (64 bytes for P-256). */
  value: string;
}

interface MoneyEnvelope {
  /** ISO 4217 currency of the original offer. */
  offerCurrency: string;
  /** Decimal string. Never a float. */
  offerAmount: string;
  chargeCurrency: string;
  chargeAmount: string;
  fxRate?: string;
  fxRateAt?: string;
}

interface ErrorObject {
  type: string;
  code: string;       // EP_-prefixed gateway error code
  message: string;
  field?: string;
  remediation: string[];
  request_id: string;
  docs: string;
}