@lanefoundry/gatelane-sdk 0.0.0-canary-b3f6165

package/dist/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAyCH,6EAA6E;AAC7E,MAAM,OAAO,eAAe;IACjB,IAAI,GAAG,QAAQ,CAAC;IACR,OAAO,GAAG,IAAI,GAAG,EAAyB,CAAC;IAE5D,KAAK,CAAC,KAAK,CAAC,MAAqB;QAC/B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;QACpC,OAAO;YACL,EAAE,EAAE,MAAM,CAAC,EAAE;YACb,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,OAAO,EAAE,IAAI,CAAC,IAAI;SACnB,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,EAAU;QACnB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC;IACtC,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,MAAgE;QACzE,IAAI,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;QAC5C,IAAI,MAAM,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;YACrC,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,aAAa,CAAC,KAAK,MAAM,CAAC,WAAW,CAAC,CAAC;QACpF,CAAC;QACD,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC/B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvC,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,KAAK,CAAC,CAAC;QAC7D,CAAC;QACD,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC/B,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;QACnC,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;CACF;AAED,yEAAyE;AACzE,IAAI,aAAa,GAAmB,IAAI,eAAe,EAAE,CAAC;AAE1D,iGAAiG;AACjG,MAAM,UAAU,UAAU,CAAC,OAAuB;IAChD,MAAM,QAAQ,GAAG,aAAa,CAAC;IAC/B,aAAa,GAAG,OAAO,CAAC;IACxB,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,sCAAsC;AACtC,MAAM,UAAU,UAAU;IACxB,OAAO,aAAa,CAAC;AACvB,CAAC"}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@lanefoundry/gatelane-sdk",
+  "version": "0.0.0-canary-b3f6165",
+  "description": "Capture SDK + type-only shapes for the gatelane promotion gate.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lanefoundry/gatelane.git",
+    "directory": "packages/gatelane-sdk"
+  },
+  "homepage": "https://github.com/lanefoundry/gatelane/tree/main/packages/gatelane-sdk",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./gate": {
+      "types": "./dist/gate.d.ts",
+      "import": "./dist/gate.js"
+    },
+    "./dataset": {
+      "types": "./dist/dataset.d.ts",
+      "import": "./dist/dataset.js"
+    },
+    "./candidate": {
+      "types": "./dist/candidate.d.ts",
+      "import": "./dist/candidate.js"
+    },
+    "./promotion": {
+      "types": "./dist/promotion.d.ts",
+      "import": "./dist/promotion.js"
+    },
+    "./capture": {
+      "types": "./dist/capture.d.ts",
+      "import": "./dist/capture.js"
+    },
+    "./storage": {
+      "types": "./dist/storage.d.ts",
+      "import": "./dist/storage.js"
+    },
+    "./storage-fs": {
+      "types": "./dist/storage-fs.d.ts",
+      "import": "./dist/storage-fs.js"
+    },
+    "./storage-http": {
+      "types": "./dist/storage-http.d.ts",
+      "import": "./dist/storage-http.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.4",
+    "vitest": "^2.0.5"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  }
+}

package/src/candidate.ts

@@ -0,0 +1,76 @@
+/**
+ * Candidate types — any component swap in the agent's context that can be attacked.
+ *
+ * gatelane's gate treats all 10 as first-class. The GateReport
+ * carries the SHA of every candidate.
+ *
+ * @see docs/prd.md §5.3 — Candidate types table
+ */
+export type CandidateRef = {
+  /** Discriminator + identifier. Format: `<type>:<id>[@<version>]`. */
+  readonly ref: string;
+  /** SHA captured in the GateReport. */
+  readonly sha: string;
+  /** Optional human-readable label for reports. */
+  readonly label?: string;
+};
+
+export type CandidateType =
+  | 'model'
+  | 'prompt'
+  | 'skill'
+  | 'config'
+  | 'tool'
+  | 'eval'
+  | 'kb'
+  | 'memory'
+  | 'dispatcher'
+  | 'guardrail';
+
+/** Parse a candidate ref string like `tool:mcp-server-foo@1.2.0` into type + id + version. */
+export function parseCandidateRef(ref: string): {
+  type: CandidateType;
+  id: string;
+  version?: string;
+} {
+  const colonIdx = ref.indexOf(':');
+  if (colonIdx < 0) {
+    throw new Error(`invalid candidate ref: ${ref} (expected <type>:<id>[@<version>])`);
+  }
+  const type = ref.slice(0, colonIdx) as CandidateType;
+  const rest = ref.slice(colonIdx + 1);
+  const valid: CandidateType[] = [
+    'model',
+    'prompt',
+    'skill',
+    'config',
+    'tool',
+    'eval',
+    'kb',
+    'memory',
+    'dispatcher',
+    'guardrail',
+  ];
+  if (!valid.includes(type)) {
+    throw new Error(
+      `invalid candidate type: ${type} (expected one of ${valid.join(', ')})`,
+    );
+  }
+  const atIdx = rest.lastIndexOf('@');
+  if (atIdx < 0) {
+    return { type, id: rest };
+  }
+  return { type, id: rest.slice(0, atIdx), version: rest.slice(atIdx + 1) };
+}
+
+/** Compute a placeholder SHA for a candidate ref. Stub: SHA-256 of the ref string. */
+export async function shaOfCandidateRef(ref: string): Promise<string> {
+  // v0.0.0-dev stub: deterministic placeholder so reports are reproducible.
+  // Real implementation in W2 will hash the actual artifact content.
+  const data = new TextEncoder().encode(ref);
+  const digest = await crypto.subtle.digest('SHA-256', data);
+  const hex = Array.from(new Uint8Array(digest))
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('');
+  return `sha256:${hex}`;
+}

package/src/capture.ts

@@ -0,0 +1,153 @@
+/**
+ * Capture SDK — one-line instrumentation for agent calls.
+ *
+ * Wraps an LLM/tool/judge call so gatelane can observe (and later replay) it.
+ * Records go through the active StorageAdapter (in-memory by default; HTTP via
+ * HttpStorage for production; filesystem via FilesystemStorage for local dev).
+ *
+ * @example
+ * ```ts
+ * import { capture, setStorage, HttpStorage } from "@lanefoundry/gatelane-sdk";
+ *
+ * // One-time setup: point capture at the production Worker.
+ * setStorage(new HttpStorage({
+ *   endpoint: process.env.GATELANE_ENDPOINT!,
+ *   token: process.env.GATELANE_CAPTURE_TOKEN!,
+ * }));
+ *
+ * // Now every call site uses the same wrapper.
+ * const response = await capture({
+ *   prompt: [{ role: "user", content: userInput }],
+ *   model: "gpt-4o",
+ *   metadata: { traceId: "...", agentVersion: "..." },
+ * }, async () => openai.chat.completions.create({ ... }));
+ * ```
+ *
+ * @see docs/prd.md §5.6 — SDK & API surface
+ */
+
+import { getStorage } from './storage.js';
+
+import type { DatasetSourceKind } from './dataset.js';
+
+export type CaptureMetadata = {
+  readonly traceId?: string;
+  readonly agentVersion?: string;
+  readonly dataset?: string;
+  readonly source_kind?: DatasetSourceKind;
+  /** Free-form metadata. */
+  readonly [key: string]: unknown;
+};
+
+export type CaptureInput = {
+  readonly prompt: ReadonlyArray<{ role: string; content: string }>;
+  readonly model?: string;
+  readonly metadata?: CaptureMetadata;
+};
+
+/** What the capture SDK stores per call. */
+export type CapturedCall = {
+  readonly id: string;
+  readonly input: CaptureInput;
+  readonly output: unknown;
+  readonly started_at: string;
+  readonly completed_at: string;
+  readonly cost_usd: number;
+  readonly latency_ms: number;
+  /** Span kind: gate.replay, gate.compare, gate.promote, scan.attack, scan.judge. */
+  readonly span_kind?: string;
+};
+
+/** A single step in a multi-turn agent trace (user/assistant/tool). */
+export type Turn = {
+  readonly role: 'system' | 'user' | 'assistant' | 'tool';
+  readonly content: string | null;
+  readonly tool_call_id?: string;
+  readonly name?: string;
+  readonly tool_calls?: ReadonlyArray<{ id: string; name: string; arguments: string }>;
+  readonly status?: 'ok' | 'error' | 'timeout';
+  readonly error?: { type: string; message: string; stack?: string };
+  readonly span_kind?: string;
+  readonly span_id?: string;
+  readonly parent_span_id?: string;
+  readonly model?: string;
+  readonly started_at?: string;
+  readonly completed_at?: string;
+  readonly cost_usd?: number;
+  readonly latency_ms?: number;
+  readonly tokens_in?: number;
+  readonly tokens_out?: number;
+};
+
+export type CaptureOptions = {
+  readonly span_kind?: string;
+  /** If true, observe without writing. Used for SDK validation in prod. */
+  readonly dry_run?: boolean;
+};
+
+/**
+ * Wrap an LLM/tool/judge call so gatelane captures it.
+ *
+ * Production behavior: writes the record to the active StorageAdapter (HTTP → Worker → R2/D1).
+ * Tests: in-memory adapter keeps everything in process.
+ * Local dev without Worker: filesystem adapter.
+ */
+export async function capture<T>(
+  input: CaptureInput,
+  call: () => Promise<T>,
+  options: CaptureOptions = {},
+): Promise<T> {
+  const started_at = new Date().toISOString();
+  const start = performance.now();
+  const output = await call();
+  const latency_ms = performance.now() - start;
+  const completed_at = new Date().toISOString();
+
+  if (options.dry_run) {
+    return output;
+  }
+
+  const record: CapturedCall = {
+    id: crypto.randomUUID(),
+    input,
+    output,
+    started_at,
+    completed_at,
+    cost_usd: 0, // placeholder; real impl reads from model registry
+    latency_ms,
+    ...(options.span_kind !== undefined ? { span_kind: options.span_kind } : {}),
+  };
+
+  // Fire-and-await: a capture write failure must not break the user's call.
+  // The Worker is the source of truth; SDK surfaces the error to stderr but
+  // does NOT throw, so a flaky network does not turn into a broken agent.
+  try {
+    await getStorage().write(record);
+  } catch (err) {
+    process.stderr.write(
+      `[gatelane] capture write failed (record id=${record.id}): ${err instanceof Error ? err.message : String(err)}\n`,
+    );
+  }
+
+  return output;
+}
+
+/**
+ * Wrap an existing agent function so every call is captured.
+ * Sugar over {@link capture} for the common case.
+ */
+export function withCapture<TArgs extends unknown[], TReturn>(
+  fn: (...args: TArgs) => Promise<TReturn>,
+  options: { span_kind?: string } = {},
+): (...args: TArgs) => Promise<TReturn> {
+  return async (...args: TArgs): Promise<TReturn> => {
+    return capture(
+      {
+        prompt: [],
+        metadata: { args: args.length },
+      },
+      () => fn(...args),
+      options,
+    );
+  };
+}

package/src/dataset.ts

@@ -0,0 +1,85 @@
+/**
+ * Frozen dataset — content-addressed, immutable, versioned.
+ *
+ * A dataset is the input to a gate run. Three sources:
+ * - `scan` — curated attacks from garak / PyRIT / Promptfoo / DeepTeam
+ * - `prod` — frozen production slice from capture SDK
+ * - `compliance` — curated cases mapped to NIST / AI Basic Act / EU AI Act
+ *
+ * @see docs/prd.md §5.2 — Three dataset sources
+ */
+
+export type DatasetSourceKind = 'scan' | 'prod' | 'compliance';
+
+export type FrozenDataset = {
+  /** Content hash of the dataset. */
+  readonly content_hash: string;
+  /** Schema version. */
+  readonly version: string;
+  /** Where this dataset came from. */
+  readonly source_kind: DatasetSourceKind;
+  /** Free-form reference to the upstream source (e.g. "garak@0.14.0+owasp-agentic-v1"). */
+  readonly source_ref: string;
+  /** Optional slice filter (time range, user cohort, etc.). */
+  readonly slice_filter?: Record<string, unknown>;
+  /** When the dataset was frozen. ISO 8601 timestamp. */
+  readonly frozen_at: string;
+  /** Number of items in the dataset. */
+  readonly item_count: number;
+  /** Items themselves (lazy-loaded). */
+  readonly items?: ReadonlyArray<DatasetItem>;
+};
+
+import type { Turn } from './capture.js';
+
+export type DatasetItem = {
+  readonly id: string;
+  /** For red-team: the attack payload. For prod: the captured user input. For compliance: the test case. */
+  readonly input: unknown;
+  /** Optional expected outcome (for compliance / eval datasets). */
+  readonly expected?: unknown;
+  /** Full multi-turn agent trace from the original capture, when available.
+   *  Includes tool calls, tool results, and intermediate assistant turns. */
+  readonly turns?: ReadonlyArray<Turn>;
+  /** Metadata from the original capture (model, cost, latency, etc.). */
+  readonly metadata?: Record<string, unknown>;
+  /** OWASP Agentic Top 10 mapping, if known. */
+  readonly mapped_asi?: 'ASI01' | 'ASI02' | 'ASI03' | 'ASI04' | 'ASI05' | 'ASI06' | 'ASI07' | 'ASI08' | 'ASI09' | 'ASI10';
+  /** MITRE ATLAS technique ID, if known. */
+  readonly mapped_atlas?: string;
+};
+
+/** Compute a placeholder content hash from item count + source ref. Stub. */
+export async function hashDataset(
+  source_kind: DatasetSourceKind,
+  source_ref: string,
+  item_count: number,
+): Promise<string> {
+  const data = new TextEncoder().encode(`${source_kind}|${source_ref}|${item_count}`);
+  const digest = await crypto.subtle.digest('SHA-256', data);
+  const hex = Array.from(new Uint8Array(digest))
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('');
+  return `sha256:${hex}`;
+}
+
+/** Build a stub FrozenDataset. Items optional. */
+export async function freezeDataset(args: {
+  source_kind: DatasetSourceKind;
+  source_ref: string;
+  slice_filter?: Record<string, unknown>;
+  items?: ReadonlyArray<DatasetItem>;
+}): Promise<FrozenDataset> {
+  const item_count = args.items?.length ?? 0;
+  const content_hash = await hashDataset(args.source_kind, args.source_ref, item_count);
+  return {
+    content_hash,
+    version: '0.0.0-dev',
+    source_kind: args.source_kind,
+    source_ref: args.source_ref,
+    ...(args.slice_filter !== undefined ? { slice_filter: args.slice_filter } : {}),
+    frozen_at: new Date().toISOString(),
+    item_count,
+    ...(args.items !== undefined ? { items: args.items } : {}),
+  };
+}

package/src/gate.ts

@@ -0,0 +1,162 @@
+/**
+ * Gate runner registry — the SDK defines the shape, the engine plugs in the impl.
+ *
+ * The default export is a stub that produces a deterministic mock. Production
+ * installs the engine package and calls {@link setGateRunner} once at process
+ * startup; subsequent {@link runGate} calls delegate to the engine.
+ *
+ * Decoupling: SDK doesn't depend on engine (engine depends on SDK). Test code
+ * can install a fake runner for deterministic gate outputs.
+ *
+ * @see docs/prd.md §5.1 — The gate
+ */
+
+import { shaOfCandidateRef } from './candidate.js';
+import type { FrozenDataset } from './dataset.js';
+import {
+  DEFAULT_POLICY,
+  type GateDecision,
+  type GatePolicy,
+  type GateReport,
+} from './promotion.js';
+
+export type GateRunArgs = {
+  readonly candidates: ReadonlyArray<string>;
+  readonly dataset: FrozenDataset;
+  readonly judges: ReadonlyArray<string>;
+  readonly baseline?: string;
+  readonly policy?: GatePolicy;
+  readonly approver?: string;
+};
+
+/** Lightweight replay row shape (mirrors engine's ReplayRow without importing it). */
+export type GateReplayRow = {
+  readonly item_id: string;
+  readonly candidate_ref: string;
+  readonly response: {
+    readonly content: string;
+    readonly cost_usd: number;
+    readonly latency_ms: number;
+    readonly tokens_in?: number;
+    readonly tokens_out?: number;
+    readonly finish_reason?: string;
+  };
+};
+
+/** Lightweight judge verdict shape (mirrors engine's JudgeVerdict). */
+export type GateJudgeVerdict = {
+  readonly candidate_ref: string;
+  readonly judge_ref: string;
+  readonly item_id: string;
+  readonly outcome: 'pass' | 'fail';
+  readonly score: number;
+  readonly reasoning?: string;
+  readonly cost_usd: number;
+  readonly latency_ms: number;
+};
+
+/** Lightweight per-candidate metric shape (mirrors engine's CandidateMetric). */
+export type GateCandidateMetric = {
+  readonly mean_score: number;
+  readonly pass_rate: number;
+  readonly n_items: number;
+  readonly total_cost_usd: number;
+  readonly mean_latency_ms: number;
+  readonly aggregate_delta: number;
+  readonly cost_delta: number;
+  readonly latency_delta: number;
+};
+
+export type GateRunResult = {
+  readonly report: GateReport;
+  readonly decision: GateDecision;
+  /** Per-item replay outputs for every (candidate, item) pair. */
+  readonly replay_rows?: ReadonlyArray<GateReplayRow>;
+  /** Per-item judge verdicts with scores and reasoning. */
+  readonly verdicts?: ReadonlyArray<GateJudgeVerdict>;
+  /** Per-candidate aggregate metrics (mean_score, pass_rate, cost, latency, deltas). */
+  readonly candidate_metrics?: Readonly<Record<string, GateCandidateMetric>>;
+};
+
+/** Runner interface. The engine implements this and registers it. */
+export type GateRunner = (args: GateRunArgs) => Promise<GateRunResult>;
+
+let registeredRunner: GateRunner | null = null;
+
+/** Install the real engine runner. Idempotent; subsequent calls overwrite. */
+export function setGateRunner(runner: GateRunner): void {
+  registeredRunner = runner;
+}
+
+/** Reset to the stub runner. Tests use this. */
+export function resetGateRunner(): void {
+  registeredRunner = null;
+}
+
+/**
+ * Run the gate. If an engine runner is installed, delegates to it.
+ * Otherwise produces a deterministic mock report (W1 behavior).
+ */
+export async function runGate(args: GateRunArgs): Promise<GateRunResult> {
+  if (registeredRunner !== null) {
+    return registeredRunner(args);
+  }
+  return stubRunGate(args);
+}
+
+/** v0.0.0-dev stub — kept for SDK consumers that don't load the engine yet. */
+export async function stubRunGate(args: GateRunArgs): Promise<GateRunResult> {
+  const policy = args.policy ?? DEFAULT_POLICY;
+  const baseline = args.baseline ?? 'model:baseline';
+  const runId = crypto.randomUUID();
+  const reportId = crypto.randomUUID();
+
+  const candidate_shas: Record<string, string> = {};
+  for (const ref of args.candidates) {
+    candidate_shas[ref] = await shaOfCandidateRef(ref);
+  }
+  const judge_shas: Record<string, string> = {};
+  for (const judge of args.judges) {
+    judge_shas[judge] = await shaOfCandidateRef(judge);
+  }
+
+  const report: GateReport = {
+    id: reportId,
+    gate_run_id: runId,
+    dataset_content_hash: args.dataset.content_hash,
+    dataset_version: args.dataset.version,
+    candidate_shas,
+    judge_shas,
+    scorer_code_sha: await shaOfCandidateRef('gatelane-sdk:scorer:v0.0.0-dev'),
+    baseline_metrics: { primary_score: 0.7 },
+    candidate_metrics: Object.fromEntries(
+      args.candidates.map((ref) => [
+        ref,
+        { aggregate_delta: 0.05, cost_delta: 0.02, latency_delta: 0.03 },
+      ]),
+    ),
+    judge_matrix: {
+      candidates: args.candidates,
+      judges: args.judges,
+      winners_by_judge: Object.fromEntries(
+        args.candidates.map((ref) => [ref, args.judges.length]),
+      ),
+      consensus_winners: args.candidates,
+    },
+    policy,
+    ...(args.approver !== undefined ? { approver: args.approver } : {}),
+    timestamp: new Date().toISOString(),
+    signature: 'stub:unsigned',
+  };
+
+  const winner = args.candidates[0] ?? baseline;
+  const decision: GateDecision = policy.approval_required
+    ? { action: 'hold_for_review', reason: 'approval_required' }
+    : {
+        action: 'pass',
+        winner,
+        reason: `stub: all candidates passed policy (min_delta=${policy.min_delta})`,
+      };
+
+  return { report, decision, replay_rows: [], verdicts: [], candidate_metrics: {} };
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+/**
+ * @lanefoundry/gatelane-sdk — promotion gate SDK.
+ *
+ * Public API for v0.0.1-dev. Engine wires up across W1–W6 per docs/roadmap.md.
+ *
+ * @see docs/prd.md §5.6 — SDK & API surface
+ */
+
+export * from './capture.js';
+export * from './candidate.js';
+export * from './dataset.js';
+export * from './gate.js';
+export * from './promotion.js';
+export * from './storage.js';
+export * from './storage-fs.js';
+export * from './storage-http.js';

package/src/promotion.ts

@@ -0,0 +1,98 @@
+/**
+ * Gate policy, report, and decision — the signed artifacts produced by a gate run.
+ *
+ * @see docs/prd.md §5.1 — The gate
+ */
+
+export type GatePolicy = {
+  /** Minimum aggregate delta over baseline required to pass. */
+  readonly min_delta: number;
+  /** Minimum fraction of judges that must agree on the winning candidate (e.g., 0.67 = 2 of 3). */
+  readonly judge_stability_threshold: number;
+  /** Maximum cost increase over baseline permitted for a pass decision. */
+  readonly cost_ceiling: number;
+  /** Maximum latency increase over baseline permitted for a pass decision. */
+  readonly latency_ceiling: number;
+  /** Whether human approval is required before the gate decision is executed. */
+  readonly approval_required: boolean;
+  /** Trigger condition under which a deployed canary is automatically blocked. */
+  readonly auto_block_rule?: {
+    /** Metric drop threshold (e.g., 0.05 = 5% drop). */
+    readonly metric_drop: number;
+    /** Window to observe canary before passing to 100% (e.g., "24h"). */
+    readonly window: string;
+  };
+};
+
+/** @deprecated Use GatePolicy instead. */
+export type PromotionPolicy = GatePolicy;
+
+export type JudgeStabilityMatrix = {
+  readonly candidates: ReadonlyArray<string>;
+  readonly judges: ReadonlyArray<string>;
+  /** winners_by_judge[candidate] = count of judges that picked this candidate as winner. */
+  readonly winners_by_judge: Record<string, number>;
+  /** Candidates that won under at least judge_stability_threshold × judges.length judges. */
+  readonly consensus_winners: ReadonlyArray<string>;
+};
+
+export type GateReport = {
+  readonly id: string;
+  readonly gate_run_id: string;
+  readonly dataset_content_hash: string;
+  readonly dataset_version: string;
+  /** SHA per candidate, keyed by candidate ref. */
+  readonly candidate_shas: Record<string, string>;
+  /** SHA per judge, keyed by judge ref. */
+  readonly judge_shas: Record<string, string>;
+  /** SHA of the scorer / evaluator code. */
+  readonly scorer_code_sha: string;
+  /** Baseline metrics: per-metric. */
+  readonly baseline_metrics: Record<string, number>;
+  /** Per-candidate metrics: aggregate delta + cost + latency. */
+  readonly candidate_metrics: Record<string, {
+    aggregate_delta: number;
+    cost_delta: number;
+    latency_delta: number;
+  }>;
+  /** Which judge picked which candidate as winner. */
+  readonly judge_matrix: JudgeStabilityMatrix;
+  /** Policy that was applied to this gate run. */
+  readonly policy: GatePolicy;
+  /** Who approved the decision (when approval_required = true). */
+  readonly approver?: string;
+  /** ISO 8601 timestamp of report signing. */
+  readonly timestamp: string;
+  /** Signature. Stub in v0.0.0-dev. */
+  readonly signature: string;
+};
+
+/** @deprecated Use GateReport instead. */
+export type PromotionReport = GateReport;
+
+export type GateDecision =
+  | {
+      readonly action: 'pass';
+      readonly winner: string;
+      readonly reason: string;
+    }
+  | {
+      readonly action: 'block';
+      readonly reason: string;
+    }
+  | {
+      readonly action: 'hold_for_review';
+      readonly reason: string;
+    };
+
+/** @deprecated Use GateDecision instead. */
+export type PromotionDecision = GateDecision;
+
+/** Default gate policy. */
+export const DEFAULT_POLICY: GatePolicy = {
+  min_delta: 0.02,
+  judge_stability_threshold: 0.67,
+  cost_ceiling: 0.1,
+  latency_ceiling: 0.2,
+  approval_required: false,
+};