agent-inspect 6.20.0 → 6.21.0

package/packages/core/dist/{chunk-G47KQB42.mjs → chunk-43SHIPZM.mjs}

@@ -1,6 +1,61 @@
-import { extractOutcomesFromPersistedEvents, outcomesMatchingStatus } from './chunk-3XS5O4JI.mjs';
+import { OBSERVED_OUTCOME_METHODS, extractOutcomesFromPersistedEvents, outcomesMatchingStatus } from './chunk-R4SSYU6D.mjs';
 import { formatProgrammaticDiagnostic } from './chunk-FWK3Q3OJ.mjs';
 
+// packages/core/src/sessions/metadata.ts
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim() !== "";
+}
+function finitePositiveInt(value) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 1) {
+    return void 0;
+  }
+  return Math.trunc(value);
+}
+function extractSessionWorkflowMetadata(record) {
+  if (!record) return void 0;
+  const out = {};
+  let found = false;
+  const assignString = (key, value) => {
+    if (isNonEmptyString(value)) {
+      out[key] = value.trim();
+      found = true;
+    }
+  };
+  assignString("sessionId", record.sessionId);
+  assignString("conversationId", record.conversationId);
+  assignString("groupId", record.groupId);
+  assignString("parentGroupId", record.parentGroupId);
+  assignString("retryOf", record.retryOf);
+  assignString("retryReason", record.retryReason);
+  assignString("handoffFrom", record.handoffFrom);
+  assignString("handoffTo", record.handoffTo);
+  assignString("subAgentId", record.subAgentId);
+  assignString("subAgentName", record.subAgentName);
+  assignString("jobId", record.jobId);
+  assignString("queueName", record.queueName);
+  assignString("workflowName", record.workflowName);
+  assignString("workflowStep", record.workflowStep);
+  assignString("toolCallId", record.toolCallId);
+  assignString("mcpToolCallId", record.mcpToolCallId);
+  assignString("linkedStepId", record.linkedStepId);
+  assignString("correlationId", record.correlationId);
+  assignString("requestId", record.requestId);
+  assignString("decisionId", record.decisionId);
+  const attempt = finitePositiveInt(record.attempt);
+  if (attempt !== void 0) {
+    out.attempt = attempt;
+    found = true;
+  }
+  return found ? out : void 0;
+}
+function sessionKeyForRun(meta, options) {
+  if (meta?.sessionId) return meta.sessionId;
+  if (options?.correlateByGroupId && meta?.groupId) {
+    return `group:${meta.groupId}`;
+  }
+  return void 0;
+}
+
 // packages/core/src/checks/logical-events.ts
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -722,6 +777,200 @@ function buildTraceFacts(input) {
   };
 }
 
+// packages/core/src/checks/contract-scope.ts
+function diagnostic(code, message, ruleId) {
+  return {
+    code,
+    message,
+    severity: "error",
+    ...ruleId !== void 0 ? { ruleId } : {}
+  };
+}
+function isNonEmptyString2(value) {
+  return typeof value === "string" && value.trim() !== "";
+}
+function scopeEntries(scope) {
+  const out = [];
+  if (isNonEmptyString2(scope.runId)) out.push(["runId", scope.runId.trim()]);
+  if (isNonEmptyString2(scope.subAgentId)) out.push(["subAgentId", scope.subAgentId.trim()]);
+  if (isNonEmptyString2(scope.groupId)) out.push(["groupId", scope.groupId.trim()]);
+  if (isNonEmptyString2(scope.workflowStep)) {
+    out.push(["workflowStep", scope.workflowStep.trim()]);
+  }
+  if (isNonEmptyString2(scope.rootEventId)) {
+    out.push(["rootEventId", scope.rootEventId.trim()]);
+  }
+  return out;
+}
+function mergeWorkflowMeta(into, from) {
+  if (!from) return;
+  for (const [key, value] of Object.entries(from)) {
+    if (value === void 0) continue;
+    if (into[key] === void 0) {
+      into[key] = value;
+    }
+  }
+}
+function workflowMetadataForRun(events, runId) {
+  const preferred = {};
+  const fallback = {};
+  for (const event of events) {
+    if (event.runId !== runId) continue;
+    const attrs = event.attributes;
+    if (!attrs || typeof attrs !== "object") continue;
+    const direct = extractSessionWorkflowMetadata(attrs);
+    const nested = attrs.metadata && typeof attrs.metadata === "object" ? extractSessionWorkflowMetadata(attrs.metadata) : void 0;
+    const bag = {};
+    mergeWorkflowMeta(bag, direct);
+    mergeWorkflowMeta(bag, nested);
+    if (event.kind === "RUN") {
+      mergeWorkflowMeta(preferred, bag);
+    } else {
+      mergeWorkflowMeta(fallback, bag);
+    }
+  }
+  mergeWorkflowMeta(preferred, fallback);
+  return preferred;
+}
+function flattenNodes(nodes) {
+  return nodes.flatMap((node) => [node, ...flattenNodes(node.children)]);
+}
+function collectSubtreeEventIds(run, rootEventId) {
+  const nodes = flattenNodes(run.children);
+  const byId = new Map(nodes.map((node) => [node.event.eventId, node]));
+  const root = byId.get(rootEventId);
+  if (!root) return void 0;
+  const ids = /* @__PURE__ */ new Set();
+  const visit = (node) => {
+    ids.add(node.event.eventId);
+    for (const child of node.children) visit(child);
+  };
+  visit(root);
+  return ids;
+}
+function filterTree(nodes, keep) {
+  const out = [];
+  for (const node of nodes) {
+    if (!keep.has(node.event.eventId)) continue;
+    out.push({
+      ...node,
+      children: filterTree(node.children, keep)
+    });
+  }
+  return out;
+}
+function projectInput(input, run, eventIds) {
+  const runEvents = input.read.events.filter((event) => event.runId === run.runId);
+  const projectedEvents = eventIds === void 0 ? runEvents : runEvents.filter((event) => eventIds.has(event.eventId) || event.kind === "RUN");
+  const projectedChildren = eventIds === void 0 ? run.children : filterTree(run.children, eventIds);
+  const projectedRun = {
+    ...run,
+    children: projectedChildren,
+    metadata: {
+      ...run.metadata,
+      totalEvents: flattenNodes(projectedChildren).length
+    }
+  };
+  return {
+    evidenceEventCount: projectedEvents.length,
+    input: {
+      ...input,
+      selectedRun: projectedRun,
+      read: {
+        ...input.read,
+        runs: [projectedRun],
+        events: projectedEvents
+      }
+    }
+  };
+}
+function resolveTraceContractScope(input, scope) {
+  if (scope === void 0) {
+    return { diagnostics: [] };
+  }
+  const entries = scopeEntries(scope);
+  if (entries.length === 0) {
+    return {
+      diagnostics: [
+        diagnostic(
+          "AI_CHECK_INVALID_CONFIG",
+          "TraceContract scope requires at least one explicit selector (runId, subAgentId, groupId, workflowStep, or rootEventId).",
+          "contract.scope.empty"
+        )
+      ]
+    };
+  }
+  const matchedSelectors = Object.fromEntries(entries);
+  const actorKeys = entries.filter(([key]) => key !== "rootEventId");
+  const rootEventId = matchedSelectors.rootEventId;
+  let candidates = [...input.read.runs];
+  if (matchedSelectors.runId) {
+    candidates = candidates.filter((run2) => run2.runId === matchedSelectors.runId);
+  }
+  for (const [key, value] of actorKeys) {
+    if (key === "runId") continue;
+    candidates = candidates.filter((run2) => {
+      const meta = workflowMetadataForRun(input.read.events, run2.runId);
+      const actual = meta[key];
+      return actual === value;
+    });
+  }
+  if (rootEventId && actorKeys.length === 0) {
+    candidates = candidates.filter(
+      (run2) => flattenNodes(run2.children).some((node) => node.event.eventId === rootEventId)
+    );
+  }
+  if (candidates.length === 0) {
+    return {
+      diagnostics: [
+        diagnostic(
+          "AI_CHECK_RUN_SELECTION_REQUIRED",
+          `TraceContract scope matched zero actors for ${JSON.stringify(matchedSelectors)}. Missing actor metadata does not fall back to the whole session.`,
+          "contract.scope.zero-match"
+        )
+      ]
+    };
+  }
+  if (candidates.length > 1) {
+    return {
+      diagnostics: [
+        diagnostic(
+          "AI_CHECK_RUN_SELECTION_REQUIRED",
+          `TraceContract scope matched ${candidates.length} actors for ${JSON.stringify(matchedSelectors)} (runIds: ${candidates.map((run2) => run2.runId).sort().join(", ")}). Singular actor selectors must resolve to exactly one run.`,
+          "contract.scope.ambiguous"
+        )
+      ]
+    };
+  }
+  const run = candidates[0];
+  let eventIds;
+  if (rootEventId) {
+    eventIds = collectSubtreeEventIds(run, rootEventId);
+    if (eventIds === void 0) {
+      return {
+        diagnostics: [
+          diagnostic(
+            "AI_CHECK_INVALID_ARGUMENTS",
+            `TraceContract scope rootEventId ${rootEventId} was not found in run ${run.runId}.`,
+            "contract.scope.root-missing"
+          )
+        ]
+      };
+    }
+  }
+  const projected = projectInput(input, run, eventIds);
+  return {
+    resolved: {
+      runId: run.runId,
+      ...rootEventId !== void 0 ? { rootEventId } : {},
+      matchedSelectors,
+      evidenceEventCount: projected.evidenceEventCount,
+      input: projected.input
+    },
+    diagnostics: []
+  };
+}
+
 // packages/core/src/safety/sensitive-key.ts
 function keyHasExplicitSeparator(value) {
   return /[_\-.]/.test(value);
@@ -878,7 +1127,7 @@ var DEFAULT_SECRET_PATTERNS = [
 function compareStrings(a, b) {
   return (a ?? "").localeCompare(b ?? "");
 }
-function diagnostic(code, message, ruleId) {
+function diagnostic2(code, message, ruleId) {
   return {
     code,
     message,
@@ -911,14 +1160,14 @@ function errorResult(input, diagnostics, selectedRun, ruleExecutions = []) {
     ruleExecutions: [...ruleExecutions]
   };
 }
-function flattenNodes(nodes) {
-  return nodes.flatMap((node) => [node, ...flattenNodes(node.children)]);
+function flattenNodes2(nodes) {
+  return nodes.flatMap((node) => [node, ...flattenNodes2(node.children)]);
 }
 function buildFacts(input, selectedRun) {
   const scopedRuns = selectedRun ? [selectedRun] : input.read.runs;
   const scopedRunIds = new Set(scopedRuns.map((run) => run.runId));
   const scopedEvents = selectedRun === void 0 ? input.read.events : input.read.events.filter((event) => scopedRunIds.has(event.runId));
-  const nodes = flattenNodes(scopedRuns.flatMap((run) => run.children));
+  const nodes = flattenNodes2(scopedRuns.flatMap((run) => run.children));
   const nodesByEventId = /* @__PURE__ */ new Map();
   const childrenByParentId = /* @__PURE__ */ new Map();
   for (const node of nodes) {
@@ -950,7 +1199,7 @@ function resolveSelectedRun(input, runId) {
     if (runId && input.selectedRun.runId !== runId) {
       return {
         diagnostics: [
-          diagnostic(
+          diagnostic2(
             "AI_CHECK_INVALID_ARGUMENTS",
             `Selected run ${input.selectedRun.runId} does not match requested run ${runId}.`
           )
@@ -964,7 +1213,7 @@ function resolveSelectedRun(input, runId) {
     if (!run) {
       return {
         diagnostics: [
-          diagnostic("AI_CHECK_RUN_SELECTION_REQUIRED", `Run not found: ${runId}.`)
+          diagnostic2("AI_CHECK_RUN_SELECTION_REQUIRED", `Run not found: ${runId}.`)
         ]
       };
     }
@@ -976,7 +1225,7 @@ function resolveSelectedRun(input, runId) {
   if (input.read.runs.length === 0) {
     return {
       diagnostics: [
-        diagnostic(
+        diagnostic2(
           "AI_CHECK_RUN_SELECTION_REQUIRED",
           formatProgrammaticDiagnostic(
             "AI_TRACE_CONTRACT_RUN_SELECTION_REQUIRED",
@@ -988,7 +1237,7 @@ function resolveSelectedRun(input, runId) {
   }
   return {
     diagnostics: [
-      diagnostic(
+      diagnostic2(
         "AI_CHECK_RUN_SELECTION_REQUIRED",
         formatProgrammaticDiagnostic("AI_TRACE_CONTRACT_RUN_SELECTION_REQUIRED")
       )
@@ -1001,7 +1250,7 @@ function selectRules(rules, selectedIds) {
   for (const rule of rules) {
     if (byId.has(rule.id)) {
       diagnostics.push(
-        diagnostic("AI_CHECK_INVALID_CONFIG", `Duplicate trace check rule id: ${rule.id}.`, rule.id)
+        diagnostic2("AI_CHECK_INVALID_CONFIG", `Duplicate trace check rule id: ${rule.id}.`, rule.id)
       );
       continue;
     }
@@ -1012,7 +1261,7 @@ function selectRules(rules, selectedIds) {
     for (const id of selected) {
       if (!byId.has(id)) {
         diagnostics.push(
-          diagnostic("AI_CHECK_INVALID_CONFIG", `Unknown trace check rule id: ${id}.`, id)
+          diagnostic2("AI_CHECK_INVALID_CONFIG", `Unknown trace check rule id: ${id}.`, id)
         );
       }
     }
@@ -2699,7 +2948,7 @@ function runTraceChecks(input, options = {}) {
     return errorResult(
       input,
       [
-        diagnostic(
+        diagnostic2(
           "AI_CHECK_NO_RULES_EVALUATED",
           "No trace check rules were evaluated. Configure at least one rule, contract, or CLI check option."
         )
@@ -2730,7 +2979,7 @@ function runTraceChecks(input, options = {}) {
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       diagnostics.push(
-        diagnostic("AI_CHECK_INTERNAL_ERROR", `Rule ${rule.id} failed: ${message}`, rule.id)
+        diagnostic2("AI_CHECK_INTERNAL_ERROR", `Rule ${rule.id} failed: ${message}`, rule.id)
       );
       ruleExecutions.push({
         ruleId: rule.id,
@@ -2783,12 +3032,141 @@ function cloneBody(body) {
     ...body.run ? { run: { ...body.run } } : {},
     ...body.tools ? { tools: { ...body.tools } } : {},
     ...body.llm ? { llm: { ...body.llm } } : {},
-    ...body.observations ? { observations: { ...body.observations } } : {}
+    ...body.observations ? {
+      observations: {
+        ...body.observations,
+        ...body.observations.requireProvenance ? { requireProvenance: { ...body.observations.requireProvenance } } : {}
+      }
+    } : {}
   };
 }
 function bodyHasRules(body) {
   return body.run !== void 0 || body.tools !== void 0 || body.llm !== void 0 || body.observations !== void 0;
 }
+var MAX_EVIDENCE_EVENT_IDS = 16;
+var METHOD_VOCABULARY = new Set(OBSERVED_OUTCOME_METHODS);
+function parseEvidenceEventIds(evidence) {
+  if (evidence === void 0 || evidence === null) {
+    return { status: "missing" };
+  }
+  if (typeof evidence === "string") {
+    const trimmed = evidence.trim();
+    if (trimmed === "") {
+      return { status: "invalid", reason: "empty evidence string" };
+    }
+    return { status: "ok", eventIds: [trimmed] };
+  }
+  if (typeof evidence !== "object" || Array.isArray(evidence)) {
+    return {
+      status: "invalid",
+      reason: "evidence must be a string event id or { eventId } / { eventIds }"
+    };
+  }
+  const record = evidence;
+  if (typeof record.eventId === "string") {
+    const trimmed = record.eventId.trim();
+    if (trimmed === "") {
+      return { status: "invalid", reason: "empty evidence.eventId" };
+    }
+    return { status: "ok", eventIds: [trimmed] };
+  }
+  if (Array.isArray(record.eventIds)) {
+    if (record.eventIds.length === 0) {
+      return { status: "invalid", reason: "empty evidence.eventIds" };
+    }
+    if (record.eventIds.length > MAX_EVIDENCE_EVENT_IDS) {
+      return {
+        status: "invalid",
+        reason: `evidence.eventIds exceeds bound of ${MAX_EVIDENCE_EVENT_IDS}`
+      };
+    }
+    const eventIds = [];
+    for (const item of record.eventIds) {
+      if (typeof item !== "string" || item.trim() === "") {
+        return { status: "invalid", reason: "evidence.eventIds contains a non-string id" };
+      }
+      eventIds.push(item.trim());
+    }
+    return { status: "ok", eventIds };
+  }
+  return {
+    status: "invalid",
+    reason: "evidence must include eventId or eventIds"
+  };
+}
+function provenanceFindingsForOutcome(outcome, requireProvenance, knownEventIds) {
+  const findings = [];
+  const evidenceBase = [
+    {
+      runId: outcome.runId,
+      eventId: outcome.outcomeId,
+      kind: "OUTCOME",
+      name: outcome.name,
+      path: `outcome.${outcome.name}`
+    }
+  ];
+  if (requireProvenance.method) {
+    if (outcome.method === void 0 || outcome.method.trim() === "") {
+      findings.push(
+        contractFailFinding(
+          "contract.observation.provenance.method",
+          `Observation ${outcome.name} is missing a structural method.`,
+          evidenceBase,
+          { method: true },
+          { name: outcome.name, method: outcome.method ?? null }
+        )
+      );
+    } else if (!METHOD_VOCABULARY.has(outcome.method)) {
+      findings.push(
+        contractFailFinding(
+          "contract.observation.provenance.method",
+          `Observation ${outcome.name} method ${outcome.method} is outside the bounded ObservedOutcomeMethod vocabulary.`,
+          evidenceBase,
+          { methodVocabulary: [...OBSERVED_OUTCOME_METHODS] },
+          { name: outcome.name, method: outcome.method }
+        )
+      );
+    }
+  }
+  if (requireProvenance.evidence || requireProvenance.sameRunEventReference) {
+    const parsed = parseEvidenceEventIds(outcome.evidence);
+    if (parsed.status === "missing") {
+      findings.push(
+        contractFailFinding(
+          "contract.observation.provenance.evidence",
+          `Observation ${outcome.name} is missing bounded evidence references.`,
+          evidenceBase,
+          { evidence: true },
+          { name: outcome.name, evidence: null }
+        )
+      );
+    } else if (parsed.status === "invalid") {
+      findings.push(
+        contractFailFinding(
+          "contract.observation.provenance.evidence",
+          `Observation ${outcome.name} evidence is not a bounded event reference (${parsed.reason}).`,
+          evidenceBase,
+          { evidence: true },
+          { name: outcome.name, reason: parsed.reason }
+        )
+      );
+    } else if (requireProvenance.sameRunEventReference) {
+      const missing = parsed.eventIds.filter((eventId) => !knownEventIds.has(eventId));
+      if (missing.length > 0) {
+        findings.push(
+          contractFailFinding(
+            "contract.observation.provenance.same-run",
+            `Observation ${outcome.name} references event ids missing from the same run: ${missing.join(", ")}.`,
+            evidenceBase,
+            { sameRunEventReference: true, eventIds: parsed.eventIds },
+            { name: outcome.name, missing }
+          )
+        );
+      }
+    }
+  }
+  return findings;
+}
 function contractToRules(contract) {
   const rules = [];
   const allowedStatuses = contract.run?.allowedStatuses ?? [];
@@ -2936,9 +3314,71 @@ function contractToRules(contract) {
         })
       );
     }
+    const requireProvenance = contract.observations.requireProvenance;
+    if (requireProvenance && (requireProvenance.method || requireProvenance.evidence || requireProvenance.sameRunEventReference)) {
+      rules.push({
+        id: "contract.observation.provenance",
+        category: "run",
+        defaultSeverity: "error",
+        evaluate(context) {
+          const outcomes = extractOutcomesFromPersistedEvents(context.events);
+          const knownEventIds = new Set(context.events.map((event) => event.eventId));
+          const targets = required.length > 0 ? outcomes.filter((outcome) => required.includes(outcome.name)) : outcomes;
+          return targets.flatMap(
+            (outcome) => provenanceFindingsForOutcome(outcome, requireProvenance, knownEventIds)
+          );
+        }
+      });
+    }
   }
   return rules;
 }
+function validateScopeShape(scope) {
+  if (scope === void 0) return [];
+  const hasSelector = typeof scope.runId === "string" && scope.runId.trim() !== "" || typeof scope.subAgentId === "string" && scope.subAgentId.trim() !== "" || typeof scope.groupId === "string" && scope.groupId.trim() !== "" || typeof scope.workflowStep === "string" && scope.workflowStep.trim() !== "" || typeof scope.rootEventId === "string" && scope.rootEventId.trim() !== "";
+  if (!hasSelector) {
+    return [
+      {
+        code: "contract.scope.empty",
+        severity: "error",
+        message: "scope requires at least one explicit selector (runId, subAgentId, groupId, workflowStep, or rootEventId).",
+        path: "scope"
+      }
+    ];
+  }
+  return [];
+}
+function validateProvenanceShape(observations) {
+  const diagnostics = [];
+  const provenance = observations?.requireProvenance;
+  if (!provenance) return diagnostics;
+  const enabled = provenance.method === true || provenance.evidence === true || provenance.sameRunEventReference === true;
+  if (!enabled) {
+    diagnostics.push({
+      code: "contract.observation.provenance.empty",
+      severity: "warning",
+      message: "observations.requireProvenance is set but no flags are enabled.",
+      path: "observations.requireProvenance"
+    });
+  }
+  if (provenance.sameRunEventReference === true && provenance.evidence !== true) {
+    diagnostics.push({
+      code: "contract.observation.provenance.same-run-without-evidence",
+      severity: "info",
+      message: "sameRunEventReference implies evidence checking; set requireProvenance.evidence: true for clarity.",
+      path: "observations.requireProvenance.sameRunEventReference"
+    });
+  }
+  if (enabled && (observations?.required?.length ?? 0) === 0) {
+    diagnostics.push({
+      code: "contract.observation.provenance.without-required",
+      severity: "warning",
+      message: "requireProvenance without observations.required applies to every observed outcome in scope.",
+      path: "observations.requireProvenance"
+    });
+  }
+  return diagnostics;
+}
 function validateAlternativesShape(alternatives) {
   const diagnostics = [];
   if (alternatives === void 0) return diagnostics;
@@ -3045,9 +3485,11 @@ function evaluateBody(input, body, options = {}) {
   });
 }
 function defineTraceContract(input) {
-  const shapeErrors = validateAlternativesShape(input.alternatives).filter(
-    (item) => item.severity === "error"
-  );
+  const shapeErrors = [
+    ...validateAlternativesShape(input.alternatives),
+    ...validateScopeShape(input.scope),
+    ...validateProvenanceShape(input.observations)
+  ].filter((item) => item.severity === "error");
   if (shapeErrors.length > 0) {
     throw new TypeError(shapeErrors.map((item) => item.message).join(" "));
   }
@@ -3059,15 +3501,25 @@ function defineTraceContract(input) {
       contract: cloneBody(branch.contract)
     }))
   } : void 0;
+  const scope = input.scope ? {
+    ...input.scope.runId !== void 0 ? { runId: input.scope.runId } : {},
+    ...input.scope.subAgentId !== void 0 ? { subAgentId: input.scope.subAgentId } : {},
+    ...input.scope.groupId !== void 0 ? { groupId: input.scope.groupId } : {},
+    ...input.scope.workflowStep !== void 0 ? { workflowStep: input.scope.workflowStep } : {},
+    ...input.scope.rootEventId !== void 0 ? { rootEventId: input.scope.rootEventId } : {}
+  } : void 0;
   return {
     ...body,
+    ...scope ? { scope } : {},
     ...alternatives ? { alternatives } : {}
   };
 }
 function evaluateTraceContract(input, contract, options = {}) {
-  const shapeErrors = validateAlternativesShape(contract.alternatives).filter(
-    (item) => item.severity === "error"
-  );
+  const shapeErrors = [
+    ...validateAlternativesShape(contract.alternatives),
+    ...validateScopeShape(contract.scope),
+    ...validateProvenanceShape(contract.observations)
+  ].filter((item) => item.severity === "error");
   if (shapeErrors.length > 0) {
     return {
       ok: false,
@@ -3091,13 +3543,58 @@ function evaluateTraceContract(input, contract, options = {}) {
       ruleExecutions: []
     };
   }
-  const base = evaluateBody(input, contract, options);
+  const scoped = resolveTraceContractScope(input, contract.scope);
+  if (scoped.diagnostics.length > 0) {
+    return {
+      ok: false,
+      status: "error",
+      format: input.read.format,
+      ...options.runId !== void 0 ? { runId: options.runId } : {},
+      ...scoped.resolved?.runId !== void 0 ? { runId: scoped.resolved.runId } : {},
+      summary: {
+        passed: 0,
+        failed: 0,
+        warnings: 0,
+        errors: scoped.diagnostics.length,
+        rulesEvaluated: 0
+      },
+      findings: [],
+      diagnostics: scoped.diagnostics,
+      ruleExecutions: []
+    };
+  }
+  const effectiveInput = scoped.resolved?.input ?? input;
+  const effectiveRunId = scoped.resolved?.runId ?? options.runId;
+  const base = evaluateBody(effectiveInput, contract, {
+    ...effectiveRunId !== void 0 ? { runId: effectiveRunId } : {}
+  });
+  const scopeFinding = scoped.resolved ? {
+    ruleId: "contract.scope.selected",
+    severity: "info",
+    status: "pass",
+    message: `Selected actor ${scoped.resolved.runId} with ${scoped.resolved.evidenceEventCount} evidence event(s).`,
+    expected: scoped.resolved.matchedSelectors,
+    actual: {
+      runId: scoped.resolved.runId,
+      evidenceEventCount: scoped.resolved.evidenceEventCount,
+      ...scoped.resolved.rootEventId !== void 0 ? { rootEventId: scoped.resolved.rootEventId } : {}
+    },
+    evidence: [
+      {
+        runId: scoped.resolved.runId,
+        kind: "RUN",
+        path: "scope"
+      }
+    ]
+  } : void 0;
   const branches = contract.alternatives?.anyOf ?? [];
   if (branches.length === 0) {
-    return base;
+    return scopeFinding ? mergeContractResults(effectiveInput, [base], [scopeFinding]) : base;
   }
   const branchEvaluations = branches.map((branch) => {
-    const result = evaluateBody(input, branch.contract, options);
+    const result = evaluateBody(effectiveInput, branch.contract, {
+      ...effectiveRunId !== void 0 ? { runId: effectiveRunId } : {}
+    });
     return { branch, result };
   });
   const satisfied = branchEvaluations.filter((item) => item.result.ok && item.result.status === "pass").map((item) => item.branch.id);
@@ -3117,7 +3614,11 @@ function evaluateTraceContract(input, contract, options = {}) {
       },
       evidence: []
     };
-    return mergeContractResults(input, [base], [passFinding]);
+    return mergeContractResults(
+      effectiveInput,
+      [base],
+      [...scopeFinding ? [scopeFinding] : [], passFinding]
+    );
   }
   const noneFinding = {
     ruleId: "contract.alternatives.none-satisfied",
@@ -3144,13 +3645,21 @@ function evaluateTraceContract(input, contract, options = {}) {
       ruleId: `contract.alternatives.${item.branch.id}.${finding.ruleId}`
     }))
   );
-  return mergeContractResults(input, [base], [noneFinding, ...prefixedBranchFindings]);
+  return mergeContractResults(
+    effectiveInput,
+    [base],
+    [...scopeFinding ? [scopeFinding] : [], noneFinding, ...prefixedBranchFindings]
+  );
 }
 function evaluateTraceContractRead(read, contract, options = {}) {
   return evaluateTraceContract({ read }, contract, options);
 }
 function lintTraceContract(contract) {
-  const diagnostics = validateAlternativesShape(contract.alternatives);
+  const diagnostics = [
+    ...validateAlternativesShape(contract.alternatives),
+    ...validateScopeShape(contract.scope),
+    ...validateProvenanceShape(contract.observations)
+  ];
   const branches = contract.alternatives?.anyOf ?? [];
   if (branches.length === 1) {
     diagnostics.push({
@@ -3185,6 +3694,12 @@ function lintTraceContract(contract) {
 }
 function explainTraceContract(contract) {
   const lines = [];
+  if (contract.scope) {
+    const parts = Object.entries(contract.scope).filter(([, value]) => typeof value === "string" && value.trim() !== "").map(([key, value]) => `${key}=${value}`);
+    if (parts.length > 0) {
+      lines.push(`Scope: select actor by [${parts.join(", ")}] before evaluation.`);
+    }
+  }
   if (contract.run?.requireCompleted !== false) {
     lines.push("Base: run must complete (no running events).");
   }
@@ -3236,6 +3751,18 @@ function explainTraceContract(contract) {
   if (contract.observations?.failOn?.length) {
     lines.push(`Base: fail on observations [${contract.observations.failOn.join(", ")}].`);
   }
+  if (contract.observations?.requireProvenance) {
+    const flags = [
+      contract.observations.requireProvenance.method ? "method" : void 0,
+      contract.observations.requireProvenance.evidence ? "evidence" : void 0,
+      contract.observations.requireProvenance.sameRunEventReference ? "sameRunEventReference" : void 0
+    ].filter((item) => item !== void 0);
+    if (flags.length > 0) {
+      lines.push(
+        `Base: require structural observation provenance [${flags.join(", ")}] (not semantic truth).`
+      );
+    }
+  }
   const branches = contract.alternatives?.anyOf ?? [];
   if (branches.length > 0) {
     lines.push(
@@ -3252,6 +3779,6 @@ function explainTraceContract(contract) {
   return lines;
 }
 
-export { buildTraceFacts, createBaselineRegressionRule, createDecisionRule, createGuardrailRule, createLlmUsageRule, createMaxStepDurationRule, createObservedOutcomeRule, createRequireCompletedRule, createRetrievalRule, createRunDepthRule, createRunDurationRule, createRunEventCountRule, createRunStatusRule, createSafetyOversizedAttributeRule, createSafetyRawContentRule, createSafetyRedactionRule, createSafetySecretPatternRule, createStallDetectionRule, createStructureCycleRule, createStructureIncompleteRule, createStructureOrphanRule, createStructureParallelWidthRule, createStructureRelationshipRule, createToolFailureRule, createToolOrderingRule, createToolUsageRule, defineTraceContract, deriveFailureFacts, evaluateTraceContract, evaluateTraceContractRead, explainTraceContract, lintTraceContract, projectLogicalEvents, resolveCanonicalToolName, runTraceChecks, summarizeSemanticParity };
-//# sourceMappingURL=chunk-G47KQB42.mjs.map
-//# sourceMappingURL=chunk-G47KQB42.mjs.map
+export { buildTraceFacts, createBaselineRegressionRule, createDecisionRule, createGuardrailRule, createLlmUsageRule, createMaxStepDurationRule, createObservedOutcomeRule, createRequireCompletedRule, createRetrievalRule, createRunDepthRule, createRunDurationRule, createRunEventCountRule, createRunStatusRule, createSafetyOversizedAttributeRule, createSafetyRawContentRule, createSafetyRedactionRule, createSafetySecretPatternRule, createStallDetectionRule, createStructureCycleRule, createStructureIncompleteRule, createStructureOrphanRule, createStructureParallelWidthRule, createStructureRelationshipRule, createToolFailureRule, createToolOrderingRule, createToolUsageRule, defineTraceContract, deriveFailureFacts, evaluateTraceContract, evaluateTraceContractRead, explainTraceContract, extractSessionWorkflowMetadata, lintTraceContract, projectLogicalEvents, resolveCanonicalToolName, resolveTraceContractScope, runTraceChecks, sessionKeyForRun, summarizeSemanticParity, workflowMetadataForRun };
+//# sourceMappingURL=chunk-43SHIPZM.mjs.map
+//# sourceMappingURL=chunk-43SHIPZM.mjs.map