agent-inspect 6.20.0 → 6.22.0

package/packages/core/dist/checks.cjs

@@ -64,6 +64,17 @@ function formatProgrammaticDiagnostic(code, detail) {
 }
 
 // packages/core/src/outcomes/types.ts
+var OBSERVED_OUTCOME_METHODS = [
+  "dom",
+  "accessibility",
+  "snapshot",
+  "network",
+  "storage",
+  "filesystem",
+  "database",
+  "queue",
+  "custom"
+];
 var OUTCOME_ATTRIBUTE_STATUS_KEY = "outcomeStatus";
 var OUTCOME_ATTRIBUTE_EXPECTATION_KEY = "expectation";
 var OUTCOME_ATTRIBUTE_METHOD_KEY = "method";
@@ -85,11 +96,11 @@ function parseMethod(value) {
 }
 function fromPersistedOutcome(event) {
   if (event.kind !== "OUTCOME") return void 0;
-  const attrs = event.attributes ?? {};
-  const statusRaw = attrs[OUTCOME_ATTRIBUTE_STATUS_KEY];
+  const attrs2 = event.attributes ?? {};
+  const statusRaw = attrs2[OUTCOME_ATTRIBUTE_STATUS_KEY];
   if (!isOutcomeStatus(statusRaw)) return void 0;
-  const expectation = typeof attrs[OUTCOME_ATTRIBUTE_EXPECTATION_KEY] === "string" ? attrs[OUTCOME_ATTRIBUTE_EXPECTATION_KEY] : event.name;
-  const observedAtRaw = attrs[OUTCOME_ATTRIBUTE_OBSERVED_AT_KEY];
+  const expectation = typeof attrs2[OUTCOME_ATTRIBUTE_EXPECTATION_KEY] === "string" ? attrs2[OUTCOME_ATTRIBUTE_EXPECTATION_KEY] : event.name;
+  const observedAtRaw = attrs2[OUTCOME_ATTRIBUTE_OBSERVED_AT_KEY];
   const observedAt = typeof observedAtRaw === "string" ? Date.parse(observedAtRaw) : typeof observedAtRaw === "number" && Number.isFinite(observedAtRaw) ? observedAtRaw : Date.parse(event.timestamp);
   return {
     outcomeId: event.eventId,
@@ -98,9 +109,9 @@ function fromPersistedOutcome(event) {
     name: event.name,
     expectation,
     status: statusRaw,
-    ...parseMethod(attrs[OUTCOME_ATTRIBUTE_METHOD_KEY]) !== void 0 ? { method: parseMethod(attrs[OUTCOME_ATTRIBUTE_METHOD_KEY]) } : {},
+    ...parseMethod(attrs2[OUTCOME_ATTRIBUTE_METHOD_KEY]) !== void 0 ? { method: parseMethod(attrs2[OUTCOME_ATTRIBUTE_METHOD_KEY]) } : {},
     ...event.outputSummary !== void 0 ? { actual: event.outputSummary } : {},
-    ...attrs.evidence !== void 0 ? { evidence: attrs.evidence } : {},
+    ...attrs2.evidence !== void 0 ? { evidence: attrs2.evidence } : {},
     observedAt: Number.isFinite(observedAt) ? observedAt : Date.parse(event.timestamp)
   };
 }
@@ -466,10 +477,10 @@ function projectLogicalEvents(events) {
   };
 }
 function resolveCanonicalToolName(event) {
-  const attrs = event.attributes;
-  const direct = pickString(attrs, ["toolName", "tool"]);
+  const attrs2 = event.attributes;
+  const direct = pickString(attrs2, ["toolName", "tool"]);
   if (direct) return direct;
-  const metadata = attrs?.metadata;
+  const metadata = attrs2?.metadata;
   if (isRecord(metadata)) {
     const nested = pickString(metadata, ["toolName", "tool"]);
     if (nested) return nested;
@@ -511,10 +522,10 @@ function pickNumber(record, keys) {
   return void 0;
 }
 function eventMetadata(event) {
-  const attrs = isRecord2(event.attributes) ? event.attributes : void 0;
-  const nested = attrs !== void 0 && isRecord2(attrs.metadata) ? attrs.metadata : void 0;
+  const attrs2 = isRecord2(event.attributes) ? event.attributes : void 0;
+  const nested = attrs2 !== void 0 && isRecord2(attrs2.metadata) ? attrs2.metadata : void 0;
   return {
-    ...attrs ?? {},
+    ...attrs2 ?? {},
     ...nested ?? {}
   };
 }
@@ -807,6 +818,208 @@ function deriveFailureFacts(logicalEvents) {
   };
 }
 
+// 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("operationId", record.operationId);
+  assignString("attemptId", record.attemptId);
+  assignString("fallbackOf", record.fallbackOf);
+  assignString("idempotencyKey", record.idempotencyKey);
+  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;
+  }
+  const attemptNumber = finitePositiveInt(record.attemptNumber);
+  if (attemptNumber !== void 0) {
+    out.attemptNumber = attemptNumber;
+    found = true;
+  }
+  return found ? out : void 0;
+}
+
+// packages/core/src/checks/relationship-facts.ts
+function attrs(event) {
+  return event.attributes && typeof event.attributes === "object" ? event.attributes : {};
+}
+function stringAttr(record, key) {
+  const value = record[key];
+  return typeof value === "string" && value.trim() !== "" ? value.trim() : void 0;
+}
+function deriveRelationshipFacts(events) {
+  const relationships = [];
+  const diagnostics = [];
+  const byId = new Map(events.map((event) => [event.eventId, event]));
+  const seen = /* @__PURE__ */ new Set();
+  const push = (edge) => {
+    const key = `${edge.type}:${edge.fromEventId}:${edge.toEventId ?? ""}:${edge.externalRef ?? ""}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    relationships.push(edge);
+  };
+  for (const event of events) {
+    if (event.parentId) {
+      push({
+        type: "parent-child",
+        fromEventId: event.parentId,
+        toEventId: event.eventId,
+        confidence: byId.has(event.parentId) ? "explicit" : "unknown",
+        basis: ["persisted.parentId"]
+      });
+      if (!byId.has(event.parentId)) {
+        diagnostics.push({
+          code: "AI_RELATIONSHIP_PARENT_MISSING",
+          message: `parentId ${event.parentId} is not present in the event set.`,
+          eventId: event.eventId
+        });
+      }
+    }
+    const bag = attrs(event);
+    const meta = extractSessionWorkflowMetadata(bag) ?? {};
+    const nested = bag.metadata && typeof bag.metadata === "object" ? extractSessionWorkflowMetadata(bag.metadata) : void 0;
+    const workflow = { ...meta, ...nested };
+    if (workflow.retryOf) {
+      const target = events.find((candidate) => candidate.runId === workflow.retryOf);
+      push({
+        type: "retry-of",
+        fromEventId: event.eventId,
+        ...target ? { toEventId: target.eventId } : {},
+        externalRef: workflow.retryOf,
+        confidence: target ? "explicit" : "correlated",
+        basis: ["attributes.retryOf"]
+      });
+    }
+    const attemptOf = stringAttr(bag, "attemptOf") ?? stringAttr(bag, "operationId");
+    if (attemptOf && workflow.attempt !== void 0) {
+      push({
+        type: "attempt-of",
+        fromEventId: event.eventId,
+        externalRef: attemptOf,
+        confidence: "explicit",
+        basis: workflow.attempt !== void 0 ? ["attributes.attempt", "attributes.operationId"] : ["attributes.operationId"]
+      });
+    }
+    const fallbackOf = stringAttr(bag, "fallbackOf");
+    if (fallbackOf) {
+      push({
+        type: "fallback-of",
+        fromEventId: event.eventId,
+        externalRef: fallbackOf,
+        confidence: "explicit",
+        basis: ["attributes.fallbackOf"]
+      });
+    }
+    const remediationOf = stringAttr(bag, "remediationOf");
+    if (remediationOf) {
+      push({
+        type: "remediation-of",
+        fromEventId: event.eventId,
+        externalRef: remediationOf,
+        confidence: "explicit",
+        basis: ["attributes.remediationOf"]
+      });
+    }
+    const evidenceFor = stringAttr(bag, "evidenceFor");
+    if (evidenceFor) {
+      push({
+        type: "evidence-for",
+        fromEventId: event.eventId,
+        ...byId.has(evidenceFor) ? { toEventId: evidenceFor } : { externalRef: evidenceFor },
+        confidence: byId.has(evidenceFor) ? "explicit" : "correlated",
+        basis: ["attributes.evidenceFor"]
+      });
+    }
+    const acceptedBy = stringAttr(bag, "acceptedBy");
+    if (acceptedBy) {
+      push({
+        type: "accepted-by",
+        fromEventId: event.eventId,
+        ...byId.has(acceptedBy) ? { toEventId: acceptedBy } : { externalRef: acceptedBy },
+        confidence: byId.has(acceptedBy) ? "explicit" : "correlated",
+        basis: ["attributes.acceptedBy"]
+      });
+    }
+    const supersedes = stringAttr(bag, "supersedes");
+    if (supersedes) {
+      push({
+        type: "supersedes",
+        fromEventId: event.eventId,
+        ...byId.has(supersedes) ? { toEventId: supersedes } : { externalRef: supersedes },
+        confidence: byId.has(supersedes) ? "explicit" : "correlated",
+        basis: ["attributes.supersedes"]
+      });
+    }
+    const sourceLineage = stringAttr(bag, "sourceLineage") ?? stringAttr(bag, "sourceEventId");
+    if (sourceLineage) {
+      push({
+        type: "source-lineage",
+        fromEventId: event.eventId,
+        externalRef: sourceLineage,
+        confidence: "explicit",
+        basis: ["attributes.sourceLineage"]
+      });
+    }
+    const unsupported = stringAttr(bag, "relationshipType");
+    if (unsupported && unsupported !== "parent-child" && ![
+      "source-lineage",
+      "attempt-of",
+      "retry-of",
+      "fallback-of",
+      "remediation-of",
+      "evidence-for",
+      "accepted-by",
+      "supersedes"
+    ].includes(unsupported)) {
+      diagnostics.push({
+        code: "AI_RELATIONSHIP_UNSUPPORTED_TYPE",
+        message: `Unsupported relationshipType ${unsupported} was reported without flattening.`,
+        eventId: event.eventId
+      });
+    }
+  }
+  return {
+    relationships: Object.freeze(relationships),
+    diagnostics: Object.freeze(diagnostics)
+  };
+}
+
 // packages/core/src/checks/trace-facts.ts
 function summarizeSemanticParity(events) {
   const projection = projectLogicalEvents(events);
@@ -893,6 +1106,7 @@ function buildTraceFacts(input) {
     toolsByName.set(name, Object.freeze([...list]));
   }
   const derived = deriveFailureFacts(projection.logicalEvents);
+  const relationship = deriveRelationshipFacts(events);
   const summary = summarizeSemanticParity(events);
   return {
     rawEvents: Object.freeze([...events]),
@@ -906,7 +1120,203 @@ function buildTraceFacts(input) {
       failureRoleCounts: derived.failureRoleCounts
     },
     failureFacts: derived.failureFacts,
-    failuresByRole: derived.failuresByRole
+    failuresByRole: derived.failuresByRole,
+    relationships: relationship.relationships,
+    relationshipDiagnostics: relationship.diagnostics
+  };
+}
+
+// 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 attrs2 = event.attributes;
+    if (!attrs2 || typeof attrs2 !== "object") continue;
+    const direct = extractSessionWorkflowMetadata(attrs2);
+    const nested = attrs2.metadata && typeof attrs2.metadata === "object" ? extractSessionWorkflowMetadata(attrs2.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: []
   };
 }
 
@@ -933,12 +1343,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 ?? [];
@@ -1086,9 +1625,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;
@@ -1195,9 +1796,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(" "));
   }
@@ -1209,15 +1812,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,
@@ -1241,13 +1854,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);
@@ -1267,7 +1925,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",
@@ -1294,13 +1956,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({
@@ -1335,6 +2005,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).");
   }
@@ -1386,6 +2062,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(
@@ -1486,7 +2174,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,
@@ -1519,14 +2207,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) {
@@ -1558,7 +2246,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}.`
           )
@@ -1572,7 +2260,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}.`)
         ]
       };
     }
@@ -1584,7 +2272,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",
@@ -1596,7 +2284,7 @@ function resolveSelectedRun(input, runId) {
   }
   return {
     diagnostics: [
-      diagnostic(
+      diagnostic2(
         "AI_CHECK_RUN_SELECTION_REQUIRED",
         formatProgrammaticDiagnostic("AI_TRACE_CONTRACT_RUN_SELECTION_REQUIRED")
       )
@@ -1609,7 +2297,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;
     }
@@ -1620,7 +2308,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)
         );
       }
     }
@@ -1696,7 +2384,7 @@ function classifyRuleExecution(findings, threw) {
   }
   return "pass";
 }
-function stringAttr(event, keys) {
+function stringAttr2(event, keys) {
   for (const key of keys) {
     const value = event.attributes?.[key];
     if (typeof value === "string" && value.trim() !== "") return value;
@@ -1774,15 +2462,15 @@ function semanticEvents(context) {
 }
 function llmModel(event) {
   const keys = ["model", "modelId", "responseModelId", "modelName", "model_name"];
-  return stringAttr(event, keys) ?? metadataStringAttr(event, keys) ?? stripPrefix(event.name, ["llm:", "generation:", "transcription:", "speech:"]);
+  return stringAttr2(event, keys) ?? metadataStringAttr(event, keys) ?? stripPrefix(event.name, ["llm:", "generation:", "transcription:", "speech:"]);
 }
 function llmProvider(event) {
   const keys = ["provider", "providerName", "provider_name"];
-  return stringAttr(event, keys) ?? metadataStringAttr(event, keys);
+  return stringAttr2(event, keys) ?? metadataStringAttr(event, keys);
 }
 function llmFinishReason(event) {
   const keys = ["finishReason", "rawFinishReason", "finish_reason"];
-  return stringAttr(event, keys) ?? metadataStringAttr(event, keys);
+  return stringAttr2(event, keys) ?? metadataStringAttr(event, keys);
 }
 function retryCount(event) {
   return numericAttr(event, ["retryCount", "retryAttempt", "retry_attempt", "attempt"]);
@@ -1924,7 +2612,7 @@ function parentMarkedUnresolved(event) {
   ]) === true) {
     return true;
   }
-  const resolution = stringAttr(event, [
+  const resolution = stringAttr2(event, [
     "parentResolution",
     "relationshipResolution",
     "relationshipStatus"
@@ -1932,13 +2620,13 @@ function parentMarkedUnresolved(event) {
   return resolution === "unresolved" || resolution === "missing-parent";
 }
 function signalName(event, attributeKeys, prefixes) {
-  return stringAttr(event, attributeKeys) ?? stripPrefix(event.name, prefixes);
+  return stringAttr2(event, attributeKeys) ?? stripPrefix(event.name, prefixes);
 }
 function guardrailEvents(context) {
   return finishedEvents(context).filter((event) => {
     const name = event.name.toLowerCase();
     if (name.startsWith("guardrail:") || name.includes(".guardrail.")) return true;
-    return stringAttr(event, ["guardrailName", "guardrail", "guardrailId"]) !== void 0;
+    return stringAttr2(event, ["guardrailName", "guardrail", "guardrailId"]) !== void 0;
   });
 }
 function retryValue(event) {
@@ -3307,7 +3995,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."
         )
@@ -3338,7 +4026,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,
@@ -3397,6 +4085,7 @@ exports.createToolOrderingRule = createToolOrderingRule;
 exports.createToolUsageRule = createToolUsageRule;
 exports.defineTraceContract = defineTraceContract;
 exports.deriveFailureFacts = deriveFailureFacts;
+exports.deriveRelationshipFacts = deriveRelationshipFacts;
 exports.evaluateTraceContract = evaluateTraceContract;
 exports.evaluateTraceContractRead = evaluateTraceContractRead;
 exports.explainTraceContract = explainTraceContract;
@@ -3404,7 +4093,9 @@ exports.formatProgrammaticDiagnostic = formatProgrammaticDiagnostic;
 exports.lintTraceContract = lintTraceContract;
 exports.projectLogicalEvents = projectLogicalEvents;
 exports.resolveCanonicalToolName = resolveCanonicalToolName;
+exports.resolveTraceContractScope = resolveTraceContractScope;
 exports.runTraceChecks = runTraceChecks;
 exports.summarizeSemanticParity = summarizeSemanticParity;
+exports.workflowMetadataForRun = workflowMetadataForRun;
 //# sourceMappingURL=checks.cjs.map
 //# sourceMappingURL=checks.cjs.map