@replayci/replay 0.1.9 → 0.1.10

package/dist/index.cjs

@@ -2370,7 +2370,10 @@ function normalizeInlineContract(input) {
     ...source.transitions != null ? { transitions: source.transitions } : {},
     ...source.gate != null ? { gate: source.gate } : {},
     ...source.evidence_class != null ? { evidence_class: source.evidence_class } : {},
-    ...source.commit_requirement != null ? { commit_requirement: source.commit_requirement } : {}
+    ...source.commit_requirement != null ? { commit_requirement: source.commit_requirement } : {},
+    ...typeof source.schema_derived === "boolean" ? { schema_derived: source.schema_derived } : {},
+    ...Array.isArray(source.schema_derived_exclude) ? { schema_derived_exclude: source.schema_derived_exclude } : {},
+    ...Array.isArray(source.binds) ? { binds: source.binds } : {}
   };
   validateSafeRegexes(contract);
   return contract;
@@ -2593,8 +2596,83 @@ function extractPath(obj, path) {
   return current;
 }
 
+// src/bindings.ts
+var MAX_BINDINGS = 256;
+function captureBindings(toolCall, contract, state, outputExtract) {
+  const bindings = new Map(state.bindings);
+  const captured = [];
+  const diagnostics = [];
+  if (!contract.binds || contract.binds.length === 0) {
+    return { bindings, captured, diagnostics };
+  }
+  if (state.killed) {
+    return { bindings, captured, diagnostics };
+  }
+  let parsedArgs;
+  try {
+    parsedArgs = JSON.parse(toolCall.arguments);
+  } catch {
+    parsedArgs = {};
+  }
+  for (const bind of contract.binds) {
+    const source = bind.source ?? "arguments";
+    const sourceObj = source === "output" ? outputExtract ?? {} : parsedArgs ?? {};
+    const value = extractPath(sourceObj, bind.path);
+    const overwritten = bindings.has(bind.name);
+    if (overwritten) {
+      const prev = bindings.get(bind.name);
+      diagnostics.push({
+        type: "binding_overwritten",
+        slot: bind.name,
+        detail: `Slot '${bind.name}' overwritten: ${JSON.stringify(prev.value)} \u2192 ${JSON.stringify(value)}`
+      });
+    }
+    if (bindings.size >= MAX_BINDINGS && !bindings.has(bind.name)) {
+      diagnostics.push({
+        type: "binding_cap_exceeded",
+        slot: bind.name,
+        detail: `Binding cap (${MAX_BINDINGS}) exceeded, slot '${bind.name}' not written`
+      });
+      continue;
+    }
+    bindings.set(bind.name, {
+      value,
+      source_tool: toolCall.name,
+      source_step: state.totalStepCount,
+      bound_at: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    captured.push({
+      slot: bind.name,
+      source,
+      path: bind.path,
+      value,
+      overwritten
+    });
+  }
+  return { bindings, captured, diagnostics };
+}
+function evaluateRef(refName, actualValue, tolerance, bindings) {
+  const bound = bindings.get(refName);
+  if (!bound) {
+    return { passed: false, reason: "binding_not_found" };
+  }
+  const expected = bound.value;
+  if (tolerance !== void 0 && typeof expected === "number" && typeof actualValue === "number") {
+    const denom = Math.max(Math.abs(expected), 1);
+    const relDiff = Math.abs(actualValue - expected) / denom;
+    if (relDiff <= tolerance) {
+      return { passed: true, reason: "ref_match", expected, actual: actualValue };
+    }
+    return { passed: false, reason: "ref_mismatch", expected, actual: actualValue };
+  }
+  if (JSON.stringify(actualValue) === JSON.stringify(expected)) {
+    return { passed: true, reason: "ref_match", expected, actual: actualValue };
+  }
+  return { passed: false, reason: "ref_mismatch", expected, actual: actualValue };
+}
+
 // src/argumentValues.ts
-function evaluateArgumentValueInvariants(parsedArguments, invariants) {
+function evaluateArgumentValueInvariants(parsedArguments, invariants, bindings) {
   const failures = [];
   for (const inv of invariants) {
     const value = extractPath(parsedArguments, inv.path);
@@ -2684,6 +2762,18 @@ function evaluateArgumentValueInvariants(parsedArguments, invariants) {
         });
       }
     }
+    if (inv.ref !== void 0 && bindings) {
+      const refResult = evaluateRef(inv.ref, value, inv.tolerance, bindings);
+      if (!refResult.passed) {
+        failures.push({
+          path: inv.path,
+          operator: refResult.reason,
+          expected: refResult.expected,
+          actual: refResult.actual ?? value,
+          detail: refResult.reason === "binding_not_found" ? `Binding '${inv.ref}' not found \u2014 producing tool has not been called` : `Ref mismatch on '${inv.ref}': expected ${JSON.stringify(refResult.expected)}, got ${JSON.stringify(refResult.actual)}`
+        });
+      }
+    }
   }
   return {
     passed: failures.length === 0,
@@ -3113,10 +3203,10 @@ function toString6(value) {
 }
 
 // src/replay.ts
-var import_node_crypto5 = __toESM(require("crypto"), 1);
+var import_node_crypto6 = __toESM(require("crypto"), 1);
 var import_node_fs3 = require("fs");
 var import_node_path3 = require("path");
-var import_contracts_core6 = require("@replayci/contracts-core");
+var import_contracts_core7 = require("@replayci/contracts-core");
 
 // src/redaction.ts
 var import_node_crypto2 = __toESM(require("crypto"), 1);
@@ -3664,7 +3754,12 @@ function createInitialState(sessionId, options) {
     totalBlockCount: 0,
     totalUnguardedCalls: 0,
     killed: false,
-    contractHash: null
+    contractHash: null,
+    bindings: /* @__PURE__ */ new Map(),
+    aggregates: /* @__PURE__ */ new Map(),
+    envelopes: /* @__PURE__ */ new Map(),
+    labels: new Set(options?.labels ?? []),
+    checkpointCount: 0
   };
 }
 function finalizeExecutedStep(state, step, contracts, compiledSession) {
@@ -3964,8 +4059,529 @@ function validateCrossStep(toolCalls, sessionState, contracts, ctx) {
   };
 }
 
-// src/messageValidation.ts
+// src/aggregates.ts
+var MAX_DISTINCT_VALUES = 1e4;
+function initializeAggregates(definitions) {
+  const map = /* @__PURE__ */ new Map();
+  for (const def of definitions) {
+    const state = {
+      name: def.name,
+      metric: def.metric,
+      currentValue: def.metric === "min" ? Infinity : 0
+    };
+    if (def.metric === "count_distinct") {
+      state.distinctValues = /* @__PURE__ */ new Set();
+    }
+    map.set(def.name, state);
+  }
+  return map;
+}
+function matchesTool(toolName, filter) {
+  if (filter === "*") return true;
+  if (typeof filter === "string") return filter === toolName;
+  return filter.includes(toolName);
+}
+function speculativeCheck(toolName, parsedArgs, aggregates, definitions) {
+  const failures = [];
+  for (const def of definitions) {
+    if (!matchesTool(toolName, def.tool)) continue;
+    const current = aggregates.get(def.name);
+    if (!current) continue;
+    const currentValue = current.currentValue;
+    if (def.metric === "count") {
+      const speculative2 = currentValue + 1;
+      if (def.lte !== void 0 && speculative2 > def.lte) {
+        failures.push({
+          aggregate: def.name,
+          reason: "aggregate_limit_exceeded",
+          detail: `${def.reason} (count ${speculative2} > lte ${def.lte})`,
+          current: currentValue,
+          speculative: speculative2,
+          bound: { lte: def.lte }
+        });
+      }
+      if (def.gte !== void 0 && speculative2 < def.gte) {
+      }
+      continue;
+    }
+    if (!def.path) {
+      failures.push({
+        aggregate: def.name,
+        reason: "aggregate_path_missing",
+        detail: `Aggregate '${def.name}' requires path but none configured`,
+        current: currentValue,
+        speculative: currentValue
+      });
+      continue;
+    }
+    const extracted = extractPath(parsedArgs, def.path);
+    if (extracted === void 0) {
+      failures.push({
+        aggregate: def.name,
+        reason: "aggregate_path_missing",
+        detail: `Tool '${toolName}' missing path '${def.path}' for aggregate '${def.name}'`,
+        current: currentValue,
+        speculative: currentValue
+      });
+      continue;
+    }
+    let speculative;
+    switch (def.metric) {
+      case "sum": {
+        if (typeof extracted !== "number") {
+          failures.push({
+            aggregate: def.name,
+            reason: "aggregate_type_error",
+            detail: `Aggregate '${def.name}' (sum) requires numeric value, got ${typeof extracted}`,
+            current: currentValue,
+            speculative: currentValue
+          });
+          continue;
+        }
+        speculative = currentValue + extracted;
+        break;
+      }
+      case "max": {
+        if (typeof extracted !== "number") {
+          failures.push({
+            aggregate: def.name,
+            reason: "aggregate_type_error",
+            detail: `Aggregate '${def.name}' (max) requires numeric value, got ${typeof extracted}`,
+            current: currentValue,
+            speculative: currentValue
+          });
+          continue;
+        }
+        speculative = Math.max(currentValue, extracted);
+        break;
+      }
+      case "min": {
+        if (typeof extracted !== "number") {
+          failures.push({
+            aggregate: def.name,
+            reason: "aggregate_type_error",
+            detail: `Aggregate '${def.name}' (min) requires numeric value, got ${typeof extracted}`,
+            current: currentValue,
+            speculative: currentValue
+          });
+          continue;
+        }
+        speculative = Math.min(currentValue, extracted);
+        break;
+      }
+      case "count_distinct": {
+        const key = JSON.stringify(extracted);
+        const existing = current.distinctValues ?? /* @__PURE__ */ new Set();
+        if (existing.has(key)) {
+          speculative = currentValue;
+        } else {
+          speculative = currentValue + 1;
+        }
+        break;
+      }
+      default:
+        continue;
+    }
+    if (def.lte !== void 0 && speculative > def.lte) {
+      failures.push({
+        aggregate: def.name,
+        reason: "aggregate_limit_exceeded",
+        detail: `${def.reason} (${def.metric} ${speculative} > lte ${def.lte})`,
+        current: currentValue,
+        speculative,
+        bound: { lte: def.lte }
+      });
+    }
+    if (def.gte !== void 0 && speculative < def.gte) {
+      failures.push({
+        aggregate: def.name,
+        reason: "aggregate_limit_exceeded",
+        detail: `${def.reason} (${def.metric} ${speculative} < gte ${def.gte})`,
+        current: currentValue,
+        speculative,
+        bound: { gte: def.gte }
+      });
+    }
+  }
+  return { passed: failures.length === 0, failures };
+}
+function commitAggregate(toolName, parsedArgs, aggregates, definitions) {
+  const updated = new Map(aggregates);
+  for (const def of definitions) {
+    if (!matchesTool(toolName, def.tool)) continue;
+    const current = updated.get(def.name);
+    if (!current) continue;
+    if (def.metric === "count") {
+      updated.set(def.name, { ...current, currentValue: current.currentValue + 1 });
+      continue;
+    }
+    if (!def.path) continue;
+    const extracted = extractPath(parsedArgs, def.path);
+    if (extracted === void 0) continue;
+    switch (def.metric) {
+      case "sum": {
+        if (typeof extracted !== "number") continue;
+        updated.set(def.name, { ...current, currentValue: current.currentValue + extracted });
+        break;
+      }
+      case "max": {
+        if (typeof extracted !== "number") continue;
+        updated.set(def.name, { ...current, currentValue: Math.max(current.currentValue, extracted) });
+        break;
+      }
+      case "min": {
+        if (typeof extracted !== "number") continue;
+        updated.set(def.name, { ...current, currentValue: Math.min(current.currentValue, extracted) });
+        break;
+      }
+      case "count_distinct": {
+        const key = JSON.stringify(extracted);
+        const existing = current.distinctValues ?? /* @__PURE__ */ new Set();
+        if (existing.has(key)) continue;
+        if (existing.size >= MAX_DISTINCT_VALUES) continue;
+        const newSet = new Set(existing);
+        newSet.add(key);
+        updated.set(def.name, { ...current, currentValue: current.currentValue + 1, distinctValues: newSet });
+        break;
+      }
+    }
+  }
+  return updated;
+}
+
+// src/envelopes.ts
+function initializeEnvelopes(definitions) {
+  const map = /* @__PURE__ */ new Map();
+  for (const def of definitions) {
+    map.set(def.name, {
+      name: def.name,
+      constraint: def.constraint,
+      established: false
+    });
+  }
+  return map;
+}
+function evaluateEnvelopes(toolName, parsedArgs, envelopes, definitions) {
+  const failures = [];
+  const captures = [];
+  for (const def of definitions) {
+    const current = envelopes.get(def.name);
+    if (!current) continue;
+    for (const stage of def.stages) {
+      if (stage.tool !== toolName) continue;
+      const extracted = extractPath(parsedArgs, stage.path);
+      if (stage.role === "constrained") {
+        if (!current.established) {
+          failures.push({
+            envelope: def.name,
+            reason: "envelope_not_established",
+            detail: `Envelope '${def.name}': constrained tool '${toolName}' called before reference value established`,
+            constraint: def.constraint
+          });
+          continue;
+        }
+        if (typeof extracted !== "number") {
+          failures.push({
+            envelope: def.name,
+            reason: "envelope_type_error",
+            detail: `Envelope '${def.name}': value at '${stage.path}' is ${typeof extracted}, expected number`,
+            constraint: def.constraint
+          });
+          continue;
+        }
+        const violation = checkConstraint(current, def, extracted);
+        if (violation) {
+          failures.push(violation);
+        }
+        captures.push({
+          envelope: def.name,
+          role: "constrained",
+          path: stage.path,
+          value: extracted
+        });
+      } else {
+        if (typeof extracted !== "number") {
+          failures.push({
+            envelope: def.name,
+            reason: "envelope_type_error",
+            detail: `Envelope '${def.name}': reference value at '${stage.path}' is ${typeof extracted}, expected number`,
+            constraint: def.constraint
+          });
+          continue;
+        }
+        captures.push({
+          envelope: def.name,
+          role: stage.role,
+          path: stage.path,
+          value: extracted
+        });
+      }
+    }
+  }
+  return { passed: failures.length === 0, failures, captures };
+}
+function commitEnvelope(captures, envelopes) {
+  if (captures.length === 0) return envelopes;
+  const updated = new Map(envelopes);
+  for (const cap of captures) {
+    const current = updated.get(cap.envelope);
+    if (!current) continue;
+    const next = { ...current };
+    switch (cap.role) {
+      case "ceiling":
+        next.ceiling = cap.value;
+        next.established = true;
+        break;
+      case "floor":
+        next.floor = cap.value;
+        next.established = true;
+        break;
+      case "anchor":
+        next.anchor = cap.value;
+        next.established = true;
+        break;
+      case "initial":
+        next.lastValue = cap.value;
+        next.established = true;
+        break;
+      case "constrained":
+        next.lastValue = cap.value;
+        break;
+    }
+    updated.set(cap.envelope, next);
+  }
+  return updated;
+}
+function checkConstraint(state, def, value) {
+  switch (def.constraint) {
+    case "lte_ceiling": {
+      if (state.ceiling === void 0) return null;
+      if (value <= state.ceiling) return null;
+      return {
+        envelope: def.name,
+        reason: "envelope_violation",
+        detail: `${def.reason} (${value} > ceiling ${state.ceiling})`,
+        constraint: def.constraint,
+        referenceValue: state.ceiling,
+        actualValue: value
+      };
+    }
+    case "gte_floor": {
+      if (state.floor === void 0) return null;
+      if (value >= state.floor) return null;
+      return {
+        envelope: def.name,
+        reason: "envelope_violation",
+        detail: `${def.reason} (${value} < floor ${state.floor})`,
+        constraint: def.constraint,
+        referenceValue: state.floor,
+        actualValue: value
+      };
+    }
+    case "within_band": {
+      if (state.anchor === void 0) return null;
+      const band = def.band ?? 0;
+      const denom = Math.max(Math.abs(state.anchor), 1);
+      const relDiff = Math.abs(value - state.anchor) / denom;
+      if (relDiff <= band) return null;
+      return {
+        envelope: def.name,
+        reason: "envelope_violation",
+        detail: `${def.reason} (${value} is ${(relDiff * 100).toFixed(1)}% from anchor ${state.anchor}, band ${(band * 100).toFixed(1)}%)`,
+        constraint: def.constraint,
+        referenceValue: state.anchor,
+        actualValue: value
+      };
+    }
+    case "monotonic_decrease": {
+      const ref = state.lastValue;
+      if (ref === void 0) return null;
+      if (value <= ref) return null;
+      return {
+        envelope: def.name,
+        reason: "envelope_violation",
+        detail: `${def.reason} (${value} > previous ${ref})`,
+        constraint: def.constraint,
+        referenceValue: ref,
+        actualValue: value
+      };
+    }
+    case "monotonic_increase": {
+      const ref = state.lastValue;
+      if (ref === void 0) return null;
+      if (value >= ref) return null;
+      return {
+        envelope: def.name,
+        reason: "envelope_violation",
+        detail: `${def.reason} (${value} < previous ${ref})`,
+        constraint: def.constraint,
+        referenceValue: ref,
+        actualValue: value
+      };
+    }
+    case "bounded": {
+      if (state.floor !== void 0 && value < state.floor) {
+        return {
+          envelope: def.name,
+          reason: "envelope_violation",
+          detail: `${def.reason} (${value} < floor ${state.floor})`,
+          constraint: def.constraint,
+          referenceValue: state.floor,
+          actualValue: value
+        };
+      }
+      if (state.ceiling !== void 0 && value > state.ceiling) {
+        return {
+          envelope: def.name,
+          reason: "envelope_violation",
+          detail: `${def.reason} (${value} > ceiling ${state.ceiling})`,
+          constraint: def.constraint,
+          referenceValue: state.ceiling,
+          actualValue: value
+        };
+      }
+      return null;
+    }
+    default:
+      return null;
+  }
+}
+
+// src/checkpoints.ts
+var import_node_crypto4 = __toESM(require("crypto"), 1);
 var import_contracts_core4 = require("@replayci/contracts-core");
+var MAX_CHECKPOINT_BUDGET = 10;
+function evaluateCheckpoints(toolCalls, checkpoints, contracts) {
+  if (checkpoints.length === 0) return null;
+  const contractByTool = new Map(contracts.map((c) => [c.tool, c]));
+  for (const tc of toolCalls) {
+    let parsedArgs;
+    try {
+      parsedArgs = JSON.parse(tc.arguments);
+    } catch {
+      parsedArgs = {};
+    }
+    for (const cp of checkpoints) {
+      if (cp.tool !== "*" && cp.tool !== tc.name) continue;
+      if (cp.when_side_effect) {
+        const contract = contractByTool.get(tc.name);
+        if (!contract?.side_effect || contract.side_effect !== cp.when_side_effect) {
+          if (cp.when === "always" || Array.isArray(cp.when) && cp.when.length === 0) {
+            continue;
+          }
+        } else {
+          return { checkpoint: cp, toolCall: tc, matchedConditions: [`when_side_effect:${cp.when_side_effect}`] };
+        }
+      }
+      if (cp.when === "always") {
+        return { checkpoint: cp, toolCall: tc, matchedConditions: ["always"] };
+      }
+      if (Array.isArray(cp.when) && cp.when.length > 0) {
+        const matched = [];
+        for (const cond of cp.when) {
+          if (evaluateCondition(parsedArgs, cond)) {
+            matched.push(cond.path);
+          }
+        }
+        const triggers = cp.match === "all" ? matched.length === cp.when.length : matched.length > 0;
+        if (triggers) {
+          return { checkpoint: cp, toolCall: tc, matchedConditions: matched };
+        }
+      }
+    }
+  }
+  return null;
+}
+function evaluateCondition(args, cond) {
+  const { exists, value } = (0, import_contracts_core4.getPathValue)(args, cond.path);
+  if (!exists) return false;
+  if (cond.gte !== void 0) {
+    if (typeof value !== "number" || value < cond.gte) return false;
+  }
+  if (cond.lte !== void 0) {
+    if (typeof value !== "number" || value > cond.lte) return false;
+  }
+  if (cond.equals !== void 0) {
+    if (value !== cond.equals) return false;
+  }
+  if (cond.one_of !== void 0) {
+    if (!cond.one_of.includes(value)) return false;
+  }
+  return true;
+}
+function buildApprovalRequest(checkpoint, toolCall, sessionId, matchedConditions) {
+  let parsedArgs;
+  try {
+    parsedArgs = JSON.parse(toolCall.arguments);
+  } catch {
+    parsedArgs = {};
+  }
+  const context = [];
+  for (const ctx of checkpoint.context) {
+    const { exists, value } = (0, import_contracts_core4.getPathValue)(parsedArgs, ctx.path);
+    context.push({ label: ctx.label, value: exists ? value : void 0 });
+  }
+  const reason = matchedConditions.includes("always") ? `Checkpoint '${checkpoint.name}': always requires approval for ${toolCall.name}` : matchedConditions.some((m) => m.startsWith("when_side_effect:")) ? `Checkpoint '${checkpoint.name}': tool ${toolCall.name} has ${matchedConditions[0]}` : `Checkpoint '${checkpoint.name}': conditions met [${matchedConditions.join(", ")}]`;
+  return {
+    checkpoint_id: import_node_crypto4.default.randomUUID(),
+    session_id: sessionId,
+    tool_name: toolCall.name,
+    arguments: parsedArgs,
+    context,
+    reason,
+    timeout_seconds: checkpoint.timeout_seconds,
+    requested_at: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+async function waitForApproval(request, onCheckpoint, timeoutSeconds, onTimeout, isKilled) {
+  return new Promise((resolve2) => {
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      resolve2({
+        checkpoint_id: request.checkpoint_id,
+        decision: isKilled() ? "deny" : onTimeout === "allow" ? "approve" : "deny",
+        decided_by: isKilled() ? "system:killed" : "system:timeout",
+        decided_at: (/* @__PURE__ */ new Date()).toISOString(),
+        reason: isKilled() ? "Session killed during checkpoint wait" : `Timeout after ${timeoutSeconds}s`
+      });
+    }, timeoutSeconds * 1e3);
+    onCheckpoint(request).then(
+      (response) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        if (isKilled()) {
+          resolve2({
+            checkpoint_id: request.checkpoint_id,
+            decision: "deny",
+            decided_by: "system:killed",
+            decided_at: (/* @__PURE__ */ new Date()).toISOString(),
+            reason: "Session killed during checkpoint wait"
+          });
+        } else {
+          resolve2(response);
+        }
+      },
+      (err) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve2({
+          checkpoint_id: request.checkpoint_id,
+          decision: "deny",
+          decided_by: "system:error",
+          decided_at: (/* @__PURE__ */ new Date()).toISOString(),
+          reason: `Checkpoint callback error: ${err instanceof Error ? err.message : String(err)}`
+        });
+      }
+    );
+  });
+}
+
+// src/messageValidation.ts
+var import_contracts_core5 = require("@replayci/contracts-core");
 function validateToolResultMessages(messages, contracts, provider) {
   const failures = [];
   const contractByTool = new Map(contracts.map((c) => [c.tool, c]));
@@ -3981,7 +4597,7 @@ function validateToolResultMessages(messages, contracts, provider) {
     } catch {
       continue;
     }
-    const invariantResult = (0, import_contracts_core4.evaluateInvariants)(parsed, outputInvariants, process.env);
+    const invariantResult = (0, import_contracts_core5.evaluateInvariants)(parsed, outputInvariants, process.env);
     for (const failure of invariantResult) {
       failures.push({
         toolName: result.toolName,
@@ -4245,6 +4861,29 @@ function narrowTools(requestedTools, sessionState, compiledSession, unmatchedPol
         continue;
       }
     }
+    if (compiledSession.labelGates && compiledSession.labelGates.length > 0 && sessionState.labels.size > 0) {
+      let labelBlocked = false;
+      for (const gate of compiledSession.labelGates) {
+        if (sessionState.labels.has(gate.when_label) && gate.deny_tools.includes(tool.name)) {
+          removed.push({
+            tool: tool.name,
+            reason: "label_gate",
+            detail: gate.reason
+          });
+          ctx?.trace.push({
+            stage: "narrow",
+            tool: tool.name,
+            verdict: "remove",
+            reason: "label_gate",
+            checked: { label: gate.when_label, gate_reason: gate.reason },
+            found: { active_labels: [...sessionState.labels] }
+          });
+          labelBlocked = true;
+          break;
+        }
+      }
+      if (labelBlocked) continue;
+    }
     ctx?.trace.push({
       stage: "narrow",
       tool: tool.name,
@@ -4255,7 +4894,8 @@ function narrowTools(requestedTools, sessionState, compiledSession, unmatchedPol
         phase_ok: true,
         preconditions_ok: true,
         not_forbidden: true,
-        policy_ok: true
+        policy_ok: true,
+        label_gates_ok: true
       },
       found: {}
     });
@@ -4285,12 +4925,12 @@ function getToolName(tool) {
 }
 
 // src/executionConstraints.ts
-var import_contracts_core5 = require("@replayci/contracts-core");
+var import_contracts_core6 = require("@replayci/contracts-core");
 function enforceExecutionConstraints(toolName, args, constraints) {
   if (constraints.length === 0) {
     return { passed: true, failures: [] };
   }
-  const failures = (0, import_contracts_core5.evaluateInvariants)(args, constraints, process.env);
+  const failures = (0, import_contracts_core6.evaluateInvariants)(args, constraints, process.env);
   const constraintFailures = failures.map((f) => ({
     path: f.path,
     operator: f.rule,
@@ -4342,7 +4982,7 @@ function buildWrappedToolsMap(tools, compiledSession) {
 }
 
 // src/runtimeClient.ts
-var import_node_crypto4 = __toESM(require("crypto"), 1);
+var import_node_crypto5 = __toESM(require("crypto"), 1);
 var CIRCUIT_BREAKER_FAILURE_LIMIT2 = 5;
 var CIRCUIT_BREAKER_MS2 = 10 * 6e4;
 var DEFAULT_TIMEOUT_MS2 = 3e4;
@@ -4733,7 +5373,7 @@ function normalizeUrl(url) {
   return url.endsWith("/") ? url.slice(0, -1) : url;
 }
 function generateIdempotencyKey() {
-  return `sdk_${import_node_crypto4.default.randomUUID().replace(/-/g, "")}`;
+  return `sdk_${import_node_crypto5.default.randomUUID().replace(/-/g, "")}`;
 }
 
 // src/replay.ts
@@ -4799,7 +5439,7 @@ function replay(client, opts = {}) {
   }
   let compiledSession = null;
   try {
-    compiledSession = (0, import_contracts_core6.compileSession)(contracts, sessionYaml, {
+    compiledSession = (0, import_contracts_core7.compileSession)(contracts, sessionYaml, {
       principal: opts.principal,
       tools: opts.tools ? new Map(Object.entries(opts.tools)) : void 0
     });
@@ -4889,13 +5529,13 @@ function replay(client, opts = {}) {
       compiledSession: compiledSession ? {
         schemaVersion: "1",
         hash: compiledSession.compiledHash,
-        body: (0, import_contracts_core6.serializeCompiledSession)(compiledSession)
+        body: (0, import_contracts_core7.serializeCompiledSession)(compiledSession)
       } : void 0,
       principal: opts.principal ?? null
     };
     if (workflowOpts && workflowId) {
       if (workflowOpts.type === "root" && compiledWorkflow) {
-        const serialized = (0, import_contracts_core6.serializeCompiledWorkflow)(compiledWorkflow);
+        const serialized = (0, import_contracts_core7.serializeCompiledWorkflow)(compiledWorkflow);
         sessionInitPayload.workflow = {
           workflowId,
           role: workflowOpts.role,
@@ -4936,7 +5576,7 @@ function replay(client, opts = {}) {
   }
   const initialTier = protectionLevel === "govern" && apiKey ? "strong" : "compat";
   const principalValue = opts.principal != null && typeof opts.principal === "object" && !Array.isArray(opts.principal) ? opts.principal : null;
-  let sessionState = createInitialState(sessionId, { tier: initialTier, agent, principal: principalValue });
+  let sessionState = createInitialState(sessionId, { tier: initialTier, agent, principal: principalValue, labels: opts.labels });
   if (compiledSession?.phases) {
     const initial = compiledSession.phases.find((p) => p.initial);
     if (initial) {
@@ -4944,6 +5584,12 @@ function replay(client, opts = {}) {
     }
   }
   sessionState = { ...sessionState, contractHash: compiledSession?.compiledHash ?? null };
+  if (compiledSession?.aggregates && compiledSession.aggregates.length > 0) {
+    sessionState = { ...sessionState, aggregates: initializeAggregates(compiledSession.aggregates) };
+  }
+  if (compiledSession?.envelopes && compiledSession.envelopes.length > 0) {
+    sessionState = { ...sessionState, envelopes: initializeEnvelopes(compiledSession.envelopes) };
+  }
   let killed = false;
   let killedAt = null;
   let restored = false;
@@ -5490,7 +6136,7 @@ function replay(client, opts = {}) {
             } catch {
               parsedArgs = {};
             }
-            const avResult = evaluateArgumentValueInvariants(parsedArgs, contract.argument_value_invariants);
+            const avResult = evaluateArgumentValueInvariants(parsedArgs, contract.argument_value_invariants, sessionState.bindings);
             if (!avResult.passed) {
               for (const f of avResult.failures) {
                 validation.failures.push({
@@ -5552,6 +6198,93 @@ function replay(client, opts = {}) {
           }
         }
         timing.argument_values_ms += Date.now() - argValuesStart;
+        if (compiledSession?.aggregates && compiledSession.aggregates.length > 0) {
+          const workingAggregates = new Map(sessionState.aggregates);
+          for (const tc of toolCalls) {
+            let parsedArgs;
+            try {
+              parsedArgs = JSON.parse(tc.arguments);
+            } catch {
+              parsedArgs = {};
+            }
+            const aggResult = speculativeCheck(tc.name, parsedArgs, workingAggregates, compiledSession.aggregates);
+            if (!aggResult.passed) {
+              for (const f of aggResult.failures) {
+                trace.push({
+                  stage: "aggregate",
+                  tool: tc.name,
+                  verdict: "block",
+                  reason: f.reason,
+                  checked: { aggregate: f.aggregate, bound_lte: f.bound?.lte ?? null, bound_gte: f.bound?.gte ?? null },
+                  found: { current: f.current, speculative: f.speculative }
+                });
+                validation.failures.push({
+                  path: `$.tool_calls.${tc.name}`,
+                  operator: f.reason,
+                  expected: "",
+                  found: String(f.speculative),
+                  message: f.detail,
+                  contract_file: ""
+                });
+              }
+            } else {
+              const committed = commitAggregate(tc.name, parsedArgs, workingAggregates, compiledSession.aggregates);
+              for (const [k, v] of committed) {
+                workingAggregates.set(k, v);
+              }
+            }
+          }
+        }
+        if (compiledSession?.envelopes && compiledSession.envelopes.length > 0) {
+          const workingEnvelopes = new Map(sessionState.envelopes);
+          for (const tc of toolCalls) {
+            let parsedArgs;
+            try {
+              parsedArgs = JSON.parse(tc.arguments);
+            } catch {
+              parsedArgs = {};
+            }
+            const envResult = evaluateEnvelopes(tc.name, parsedArgs, workingEnvelopes, compiledSession.envelopes);
+            if (!envResult.passed) {
+              for (const f of envResult.failures) {
+                trace.push({
+                  stage: "envelope",
+                  tool: tc.name,
+                  verdict: "block",
+                  reason: f.reason,
+                  checked: { envelope: f.envelope, constraint: f.constraint, reference: f.referenceValue ?? null },
+                  found: { value: f.actualValue ?? null }
+                });
+                validation.failures.push({
+                  path: `$.tool_calls.${tc.name}`,
+                  operator: f.reason,
+                  expected: "",
+                  found: String(f.actualValue ?? ""),
+                  message: f.detail,
+                  contract_file: ""
+                });
+              }
+            }
+            if (envResult.captures.length > 0) {
+              const committed = commitEnvelope(envResult.captures, workingEnvelopes);
+              for (const [k, v] of committed) {
+                workingEnvelopes.set(k, v);
+              }
+              for (const cap of envResult.captures) {
+                if (cap.role !== "constrained") {
+                  trace.push({
+                    stage: "envelope",
+                    tool: tc.name,
+                    verdict: "allow",
+                    reason: "ceiling_established",
+                    checked: { envelope: cap.envelope, role: cap.role, path: cap.path },
+                    found: { value: cap.value }
+                  });
+                }
+              }
+            }
+          }
+        }
         currentTraceStage = "policy";
         let policyVerdicts = null;
         const policyStart = Date.now();
@@ -5604,6 +6337,143 @@ function replay(client, opts = {}) {
           trace.push({ stage: "policy", tool: null, verdict: "skip", reason: "no_policy_configured", checked: {}, found: {} });
         }
         timing.policy_ms += Date.now() - policyStart;
+        currentTraceStage = "checkpoint";
+        if (compiledSession?.checkpoints && compiledSession.checkpoints.length > 0 && validation.failures.length === 0) {
+          const cpResult = evaluateCheckpoints(toolCalls, compiledSession.checkpoints, contracts);
+          if (cpResult) {
+            const { checkpoint: triggeredCp, toolCall: triggeredTc, matchedConditions } = cpResult;
+            if (mode === "shadow") {
+              trace.push({
+                stage: "checkpoint",
+                tool: triggeredTc.name,
+                verdict: "info",
+                reason: "checkpoint_would_trigger",
+                checked: { checkpoint: triggeredCp.name, conditions: matchedConditions },
+                found: { shadow: true }
+              });
+              emitDiagnostic2(diagnostics, {
+                type: "replay_checkpoint_shadow",
+                session_id: sessionId,
+                checkpoint: triggeredCp.name,
+                tool_name: triggeredTc.name
+              });
+            } else {
+              if (sessionState.checkpointCount >= MAX_CHECKPOINT_BUDGET) {
+                trace.push({
+                  stage: "checkpoint",
+                  tool: triggeredTc.name,
+                  verdict: "block",
+                  reason: "checkpoint_budget_exceeded",
+                  checked: { checkpoint: triggeredCp.name, budget: MAX_CHECKPOINT_BUDGET },
+                  found: { count: sessionState.checkpointCount }
+                });
+                validation.failures.push({
+                  path: `$.tool_calls.${triggeredTc.name}`,
+                  operator: "checkpoint_budget_exceeded",
+                  expected: `<= ${MAX_CHECKPOINT_BUDGET} checkpoints`,
+                  found: String(sessionState.checkpointCount),
+                  message: `Checkpoint budget exceeded: ${sessionState.checkpointCount} of ${MAX_CHECKPOINT_BUDGET}`,
+                  contract_file: ""
+                });
+              } else if (!opts.onCheckpoint) {
+                trace.push({
+                  stage: "checkpoint",
+                  tool: triggeredTc.name,
+                  verdict: "block",
+                  reason: "checkpoint_no_handler",
+                  checked: { checkpoint: triggeredCp.name },
+                  found: { has_handler: false }
+                });
+                validation.failures.push({
+                  path: `$.tool_calls.${triggeredTc.name}`,
+                  operator: "checkpoint_no_handler",
+                  expected: "onCheckpoint callback",
+                  found: "not provided",
+                  message: `Checkpoint '${triggeredCp.name}' triggered but no onCheckpoint handler provided`,
+                  contract_file: ""
+                });
+              } else {
+                trace.push({
+                  stage: "checkpoint",
+                  tool: triggeredTc.name,
+                  verdict: "paused",
+                  reason: "checkpoint_triggered",
+                  checked: { checkpoint: triggeredCp.name, conditions: matchedConditions },
+                  found: {}
+                });
+                emitDiagnostic2(diagnostics, {
+                  type: "replay_checkpoint_triggered",
+                  session_id: sessionId,
+                  checkpoint: triggeredCp.name,
+                  tool_name: triggeredTc.name
+                });
+                const approvalRequest = buildApprovalRequest(
+                  triggeredCp,
+                  triggeredTc,
+                  sessionId,
+                  matchedConditions
+                );
+                const approvalResponse = await waitForApproval(
+                  approvalRequest,
+                  opts.onCheckpoint,
+                  triggeredCp.timeout_seconds,
+                  triggeredCp.on_timeout,
+                  () => killed
+                );
+                sessionState = { ...sessionState, checkpointCount: sessionState.checkpointCount + 1 };
+                if (approvalResponse.decision === "approve") {
+                  trace.push({
+                    stage: "checkpoint",
+                    tool: triggeredTc.name,
+                    verdict: "allow",
+                    reason: "checkpoint_approved",
+                    checked: { checkpoint: triggeredCp.name, decided_by: approvalResponse.decided_by },
+                    found: { decision: "approve", latency_ms: Date.now() - new Date(approvalRequest.requested_at).getTime() }
+                  });
+                  emitDiagnostic2(diagnostics, {
+                    type: "replay_checkpoint_resolved",
+                    session_id: sessionId,
+                    checkpoint: triggeredCp.name,
+                    decision: "approve"
+                  });
+                } else {
+                  const isTimeout = approvalResponse.decided_by.startsWith("system:timeout");
+                  const blockReason = isTimeout ? "checkpoint_timeout" : "checkpoint_denied";
+                  trace.push({
+                    stage: "checkpoint",
+                    tool: triggeredTc.name,
+                    verdict: "block",
+                    reason: blockReason,
+                    checked: { checkpoint: triggeredCp.name, decided_by: approvalResponse.decided_by },
+                    found: {
+                      decision: "deny",
+                      ...approvalResponse.reason ? { reason: approvalResponse.reason } : {},
+                      latency_ms: Date.now() - new Date(approvalRequest.requested_at).getTime()
+                    }
+                  });
+                  emitDiagnostic2(diagnostics, {
+                    type: "replay_checkpoint_resolved",
+                    session_id: sessionId,
+                    checkpoint: triggeredCp.name,
+                    decision: isTimeout ? "timeout" : "deny"
+                  });
+                  validation.failures.push({
+                    path: `$.tool_calls.${triggeredTc.name}`,
+                    operator: blockReason,
+                    expected: "approve",
+                    found: approvalResponse.decision,
+                    message: `Checkpoint '${triggeredCp.name}' ${isTimeout ? "timed out" : "denied"}${approvalResponse.reason ? `: ${approvalResponse.reason}` : ""}`,
+                    contract_file: ""
+                  });
+                }
+              }
+            }
+          } else {
+            trace.push({ stage: "checkpoint", tool: null, verdict: "skip", reason: "no_checkpoint_triggered", checked: { checkpoint_count: compiledSession.checkpoints.length }, found: {} });
+          }
+        } else if (compiledSession?.checkpoints && compiledSession.checkpoints.length > 0 && validation.failures.length > 0) {
+          trace.push({ stage: "checkpoint", tool: null, verdict: "skip", reason: "skipped_due_to_validation_failures", checked: {}, found: { failure_count: validation.failures.length } });
+        }
         currentTraceStage = "gate";
         if (mode === "shadow") {
           const shadowGateStart = Date.now();
@@ -5660,6 +6530,34 @@ function replay(client, opts = {}) {
             } else {
               completedStep.phase = sessionState.currentPhase;
             }
+            for (const tc of toolCalls) {
+              const contract = contracts.find((c) => c.tool === tc.name);
+              if (contract?.binds && contract.binds.length > 0) {
+                const bindResult = captureBindings(tc, contract, sessionState);
+                sessionState = { ...sessionState, bindings: bindResult.bindings };
+              }
+              if (compiledSession?.aggregates && compiledSession.aggregates.length > 0) {
+                let parsedArgs;
+                try {
+                  parsedArgs = JSON.parse(tc.arguments);
+                } catch {
+                  parsedArgs = {};
+                }
+                sessionState = { ...sessionState, aggregates: commitAggregate(tc.name, parsedArgs, sessionState.aggregates, compiledSession.aggregates) };
+              }
+              if (compiledSession?.envelopes && compiledSession.envelopes.length > 0) {
+                let parsedArgs;
+                try {
+                  parsedArgs = JSON.parse(tc.arguments);
+                } catch {
+                  parsedArgs = {};
+                }
+                const envResult = evaluateEnvelopes(tc.name, parsedArgs, sessionState.envelopes, compiledSession.envelopes);
+                if (envResult.captures.length > 0) {
+                  sessionState = { ...sessionState, envelopes: commitEnvelope(envResult.captures, sessionState.envelopes) };
+                }
+              }
+            }
             const prevVersion = sessionState.stateVersion;
             sessionState = finalizeExecutedStep(sessionState, completedStep, contracts, compiledSession);
             syncStateToStore(prevVersion, sessionState);
@@ -5714,6 +6612,44 @@ function replay(client, opts = {}) {
           } else {
             completedStep.phase = sessionState.currentPhase;
           }
+          for (const tc of toolCalls) {
+            const contract = contracts.find((c) => c.tool === tc.name);
+            if (contract?.binds && contract.binds.length > 0) {
+              const bindResult = captureBindings(tc, contract, sessionState);
+              sessionState = { ...sessionState, bindings: bindResult.bindings };
+              for (const cap of bindResult.captured) {
+                trace.push({
+                  stage: "bind",
+                  tool: tc.name,
+                  verdict: "captured",
+                  reason: cap.overwritten ? "binding_overwritten" : "binding_captured",
+                  checked: { slot: cap.slot, source: cap.source, path: cap.path },
+                  found: { value: cap.value }
+                });
+              }
+            }
+            if (compiledSession?.aggregates && compiledSession.aggregates.length > 0) {
+              let parsedArgs;
+              try {
+                parsedArgs = JSON.parse(tc.arguments);
+              } catch {
+                parsedArgs = {};
+              }
+              sessionState = { ...sessionState, aggregates: commitAggregate(tc.name, parsedArgs, sessionState.aggregates, compiledSession.aggregates) };
+            }
+            if (compiledSession?.envelopes && compiledSession.envelopes.length > 0) {
+              let parsedArgs;
+              try {
+                parsedArgs = JSON.parse(tc.arguments);
+              } catch {
+                parsedArgs = {};
+              }
+              const envResult = evaluateEnvelopes(tc.name, parsedArgs, sessionState.envelopes, compiledSession.envelopes);
+              if (envResult.captures.length > 0) {
+                sessionState = { ...sessionState, envelopes: commitEnvelope(envResult.captures, sessionState.envelopes) };
+              }
+            }
+          }
           const prevVersionAllow = sessionState.stateVersion;
           sessionState = finalizeExecutedStep(sessionState, completedStep, contracts, compiledSession);
           sessionState = recordDecisionOutcome(sessionState, "allowed");
@@ -6005,6 +6941,22 @@ function replay(client, opts = {}) {
         });
       }
     },
+    addLabel(label) {
+      if (killed || restored) return;
+      if (sessionState.labels.has(label)) return;
+      if (sessionState.labels.size >= 64) {
+        emitDiagnostic2(diagnostics, {
+          type: "replay_label_cap",
+          session_id: sessionId,
+          label,
+          detail: "Label cap (64) reached, label not added"
+        });
+        return;
+      }
+      const newLabels = new Set(sessionState.labels);
+      newLabels.add(label);
+      sessionState = { ...sessionState, labels: newLabels };
+    },
     tools: wrapToolsWithDeferredReceipts(
       buildWrappedToolsMap(opts.tools, compiledSession)
     ),
@@ -6193,7 +7145,7 @@ function discoverSessionYaml(opts) {
   if (opts.sessionYamlPath) {
     const resolved = (0, import_node_path3.resolve)(opts.sessionYamlPath);
     const raw = (0, import_node_fs3.readFileSync)(resolved, "utf8");
-    return (0, import_contracts_core6.parseSessionYaml)(raw);
+    return (0, import_contracts_core7.parseSessionYaml)(raw);
   }
   if (opts.contractsDir) {
     const dir = (0, import_node_path3.resolve)(opts.contractsDir);
@@ -6201,7 +7153,7 @@ function discoverSessionYaml(opts) {
       const candidate = (0, import_node_path3.join)(dir, name);
       if ((0, import_node_fs3.existsSync)(candidate)) {
         const raw = (0, import_node_fs3.readFileSync)(candidate, "utf8");
-        return (0, import_contracts_core6.parseSessionYaml)(raw);
+        return (0, import_contracts_core7.parseSessionYaml)(raw);
       }
     }
   }
@@ -6225,11 +7177,11 @@ function discoverWorkflowYaml(opts, workflowOpts) {
     }
   }
   if (!raw) return null;
-  const parsed = (0, import_contracts_core6.parseWorkflowYaml)(raw);
-  return (0, import_contracts_core6.compileWorkflow)(parsed);
+  const parsed = (0, import_contracts_core7.parseWorkflowYaml)(raw);
+  return (0, import_contracts_core7.compileWorkflow)(parsed);
 }
 function generateWorkflowId() {
-  return `rw_${import_node_crypto5.default.randomUUID().replace(/-/g, "").slice(0, 24)}`;
+  return `rw_${import_node_crypto6.default.randomUUID().replace(/-/g, "").slice(0, 24)}`;
 }
 function validateConfig(contracts, opts) {
   const hasPolicyBlock = contracts.some((c) => c.policy != null);
@@ -6321,7 +7273,7 @@ function validateResponse2(response, toolCalls, contracts, requestToolNames, unm
     const outputInvariants = contract.assertions.output_invariants;
     if (outputInvariants.length > 0) {
       const normalizedResponse = buildNormalizedResponse(response, toolCalls);
-      const result = (0, import_contracts_core6.evaluateInvariants)(normalizedResponse, outputInvariants, process.env);
+      const result = (0, import_contracts_core7.evaluateInvariants)(normalizedResponse, outputInvariants, process.env);
       for (const failure of result) {
         failures.push({
           path: failure.path,
@@ -6334,7 +7286,7 @@ function validateResponse2(response, toolCalls, contracts, requestToolNames, unm
       }
     }
     if (contract.expected_tool_calls && contract.expected_tool_calls.length > 0) {
-      const result = (0, import_contracts_core6.evaluateExpectedToolCalls)(
+      const result = (0, import_contracts_core7.evaluateExpectedToolCalls)(
         toolCalls,
         contract.expected_tool_calls,
         contract.pass_threshold ?? 1,
@@ -6487,7 +7439,7 @@ function evaluateInputInvariants(request, contracts) {
   for (const contract of contracts) {
     if (!requestToolSet.has(contract.tool)) continue;
     if (contract.assertions.input_invariants.length === 0) continue;
-    const result = (0, import_contracts_core6.evaluateInvariants)(request, contract.assertions.input_invariants, process.env);
+    const result = (0, import_contracts_core7.evaluateInvariants)(request, contract.assertions.input_invariants, process.env);
     for (const failure of result) {
       failures.push({
         path: failure.path,
@@ -6811,6 +7763,8 @@ function createInactiveSession(client, sessionId, reason) {
     },
     widen() {
     },
+    addLabel() {
+    },
     tools: {},
     getWorkflowState: () => Promise.resolve(null),
     handoff: () => Promise.resolve(null)
@@ -6853,6 +7807,8 @@ function createBlockingInactiveSession(client, sessionId, detail, configError) {
     },
     widen() {
     },
+    addLabel() {
+    },
     tools: {},
     getWorkflowState: () => Promise.resolve(null),
     handoff: () => Promise.resolve(null)
@@ -6928,7 +7884,7 @@ function resolveApiKey2(opts) {
   return typeof envKey === "string" && envKey.length > 0 ? envKey : void 0;
 }
 function generateSessionId2() {
-  return `rs_${import_node_crypto5.default.randomUUID().replace(/-/g, "").slice(0, 24)}`;
+  return `rs_${import_node_crypto6.default.randomUUID().replace(/-/g, "").slice(0, 24)}`;
 }
 function stripHashPrefix(hash) {
   return hash.startsWith("sha256:") ? hash.slice(7) : hash;