types.ts

/**
 * Public type surface for the `src/lib/` package internals.
 *
 * --- API verification notes (Phase 0, against pinned versions) ---
 *
 * - `@mastra/core` 1.29.1: `createTool`'s `execute` is `(inputData, context)` —
 *   two positional args, not the single `({ context })` shape that earlier docs
 *   describe. All examples and tools in this package use the two-arg form.
 *
 * - `@tigrisdata/agent-kit` 0.1.3:
 *   * `createForks` does NOT accept a `ttl` option. The original plan's "TTL on
 *     every fork" rule is therefore not enforceable from this package. We omit
 *     `ttl` from `ImmutableSessionOptions`. Cleanup is the caller's responsibility
 *     via `session.teardown()` (typically in a `finally` block in the orchestrator).
 *   * `createForks` returns `{ baseBucket, snapshotId, forks: Fork[] }`. We carry
 *     `snapshotId` through as `parentCheckpointId` on `ForkContext` — no separate
 *     `checkpoint` call is needed at start time.
 *   * `Fork.credentials` is optional in agent-kit. We always pass
 *     `credentials: { role: 'Editor' }` by default and treat missing post-call
 *     credentials as a hard error (see `session.ts`).
 *   * `restore` returns `{ bucket }` only — no credentials. Not exposed in this
 *     package's public API.
 *   * `promote` and `quarantine` are NOT exported by agent-kit yet. Inlined here.
 *     When agent-kit absorbs them, the implementations in `promote.ts` and
 *     `quarantine.ts` become thin re-exports.
 */

import type { TigrisAgentKitConfig, Fork, Forks } from "@tigrisdata/agent-kit";

export type { TigrisAgentKitConfig } from "@tigrisdata/agent-kit";

export interface ForkContext {
  /** The fork's bucket name. Tools should write artifacts here. */
  bucket: string;
  /** Scoped access key for the fork. Tools should use this, not orchestrator credentials. */
  accessKeyId: string;
  /** Scoped secret. */
  secretAccessKey: string;
  /** The source bucket the fork was created from. */
  parentBucket: string;
  /** Snapshot the fork was created at. Useful for diff-style validators or copy-forward promote. */
  parentCheckpointId?: string;
}

export interface ValidationResult {
  passed: boolean;
  reason?: string;
  details?: Record<string, unknown>;
}

export type Validator = (fork: ForkContext) => Promise<ValidationResult>;

export type PromoteStrategy =
  | "pointer-swap"
  | "copy-forward"
  | {
      strategy: "custom";
      promote: (fork: ForkContext, source: string) => Promise<void>;
    };

export interface ImmutableSessionOptions {
  /** Production bucket to fork from. */
  source: string;
  /** Optional pre-promote validator. If omitted, `validate()` returns `{ passed: true }`. */
  validate?: Validator;
  /** Promote strategy. Default `'pointer-swap'`. */
  promote?: PromoteStrategy;
  /** Scoped fork-credential role. Default `'Editor'`. */
  credentials?: { role: "Editor" | "ReadOnly" };
  /**
   * Forwarded to agent-kit and storage for endpoint and root-credential overrides.
   * Falls back to env vars when omitted.
   */
  config?: TigrisAgentKitConfig;
}

export interface QuarantineRecord {
  bucket: string;
  reason: string;
  quarantinedAt: Date;
  parentBucket: string;
  parentCheckpointId?: string;
}

/** Internal session state; not exported from package root. */
export interface SessionState {
  forks: Forks;
  fork: Fork;
  parentBucket: string;
  parentCheckpointId?: string;
  validator?: Validator;
  promoteStrategy: PromoteStrategy;
  config?: TigrisAgentKitConfig;
}

/** Thrown when a promote strategy is reached that hasn't been implemented yet. */
export class NotImplementedError extends Error {
  constructor(strategy: string) {
    super(`Promote strategy '${strategy}' is not implemented in this version of immutable-agent's src/lib`);
    this.name = "NotImplementedError";
  }
}