engineering-behavior-observatory 0.2.1

package/dist/src/structural-observations.js

@@ -0,0 +1,671 @@
+import { createHash } from "node:crypto";
+import { createAgentSdkBehaviorEvidence } from "./behavior-assertions.js";
+import { createRetainedBehaviorEvidence } from "./retained-evidence.js";
+import {} from "./agent-sdk-normalizer.js";
+import { canonicalizeMetadata, digestMetadata, validateArtifact } from "./artifacts.js";
+import {} from "./normalization-integrity.js";
+export const STRUCTURAL_EXTRACTOR_VERSION = "1.0.0";
+export { CLAUDE_AGENT_SDK_NORMALIZATION_ADAPTER_VERSION } from "./agent-sdk-normalizer.js";
+export const STRUCTURAL_EXTRACTOR_REGISTRY = [
+    registry("model-request-count", ["family:model-request"], "Distinct source-native inference requests observed in the attempt."),
+    registry("tool-operation-count", ["family:tool"], "Distinct logical tool operations, deduplicated by source-native operation identity."),
+    registry("tool-native-record-count", ["family:tool"], "Native records carrying mapped or explicitly unprojectable tool evidence."),
+    registry("unidentified-tool-native-record-count", ["family:tool"], "Native tool-family records without a resolvable source-native operation identity."),
+    registry("tool-error-count", ["family:tool"], "Distinct logical tool operations with an explicit native failure result."),
+    registry("repeated-tool-operation-count", ["family:tool"], "Distinct logical tool operations beyond the first with the same explicit tool identity and input digest."),
+    registry("failure-followed-by-same-tool-count", ["family:tool", "evidence:nativeOrder"], "Failed logical tool operations followed by a distinct operation of the same tool in the same native-order domain."),
+    registry("failure-followed-by-alternate-tool-count", ["family:tool", "evidence:nativeOrder"], "Failed logical tool operations followed by a distinct operation of another tool in the same native-order domain."),
+    registry("validation-after-last-mutation", ["family:artifact", "family:validation", "evidence:nativeOrder"], "Whether an explicitly identified validation occurs after the last explicitly identified mutation in one native-order domain."),
+    registry("compaction-boundary-record-count", ["family:context"], "Native records that explicitly identify a compaction boundary."),
+    registry("input-token-count", ["family:runtime"], "Native-reported input-token total without combining cumulative snapshots or telemetry sources."),
+    registry("output-token-count", ["family:runtime"], "Native-reported output-token total without combining cumulative snapshots or telemetry sources."),
+    registry("cache-read-input-token-count", ["family:runtime"], "Native-reported cache-read input-token total."),
+    registry("cache-creation-input-token-count", ["family:runtime"], "Native-reported cache-creation input-token total."),
+    registry("total-token-count", ["family:runtime"], "Native-reported total-token total; component categories are not added to reconstruct it."),
+    registry("total-cost-usd", ["family:runtime"], "Native-reported attempt cost in US dollars; subscription utilization is not inferred."),
+    registry("attempt-latency-ms", ["family:outcome"], "Native-reported end-to-end attempt duration in milliseconds."),
+];
+export async function createAgentSdkStructuralObservationSet(bundleRoot) {
+    const { capture, dataset, resolver, coverage } = await createAgentSdkBehaviorEvidence(bundleRoot);
+    const result = createStructuralObservationSet(dataset, coverage, capture);
+    await validateStructuralObservationSet(result, resolver);
+    return result;
+}
+export async function createRetainedStructuralObservationSet(bundleRoot) {
+    const { outcomeCapture, dataset, resolver, coverage } = await createRetainedBehaviorEvidence(bundleRoot);
+    const result = createStructuralObservationSet(dataset, coverage, outcomeCapture);
+    await validateStructuralObservationSet(result, resolver);
+    return result;
+}
+export function createStructuralObservationSet(dataset, coverage, nativeCapture) {
+    if (coverage.runId !== dataset.runId || coverage.attemptId !== dataset.attemptId
+        || canonicalizeMetadata(coverage.adapter) !== canonicalizeMetadata(dataset.adapter)) {
+        throw new Error("Structural observation coverage does not match the normalized dataset.");
+    }
+    const assessmentMode = importAssessmentMode(dataset, nativeCapture);
+    const observations = [
+        ...importOutcomes(dataset, nativeCapture, assessmentMode),
+        ...extractStructuralFacts(dataset),
+    ];
+    return {
+        schemaVersion: "ebo.structural-observation-set/v1",
+        runId: dataset.runId,
+        attemptId: dataset.attemptId,
+        assessmentMode,
+        extractorVersion: STRUCTURAL_EXTRACTOR_VERSION,
+        normalization: {
+            datasetDigest: `sha256:${digestMetadata(dataset).value}`,
+            adapter: structuredClone(dataset.adapter),
+            capabilityProfile: structuredClone(dataset.capabilityProfile),
+            coverage: structuredClone(coverage),
+        },
+        observations,
+    };
+}
+export async function validateStructuralObservationSet(report, resolver) {
+    const errors = validateArtifact("structural observations", report);
+    if (errors.length > 0)
+        throw new Error(errors.map(({ field, message }) => `${field}: ${message}`).join("\n"));
+    const ids = new Set();
+    for (const observation of report.observations) {
+        if (ids.has(observation.id))
+            throw new Error(`Duplicate structural observation ID "${observation.id}".`);
+        ids.add(observation.id);
+        if (observation.runId !== report.runId || observation.attemptId !== report.attemptId) {
+            throw new Error(`Structural observation "${observation.id}" belongs to another run or attempt.`);
+        }
+        if (observation.denominator.id !== report.attemptId) {
+            throw new Error(`Structural observation "${observation.id}" has the wrong attempt denominator.`);
+        }
+        if (observation.sourceRecordCount !== observation.citations.length) {
+            throw new Error(`Structural observation "${observation.id}" source-record count does not match its citations.`);
+        }
+        for (const citation of observation.citations) {
+            const resolution = await resolver.resolve(citation);
+            if (typeof resolution !== "object" || resolution.runId !== report.runId || resolution.attemptId !== report.attemptId) {
+                throw new Error(`Structural observation "${observation.id}" has an unresolved native citation.`);
+            }
+        }
+    }
+}
+function extractStructuralFacts(dataset) {
+    const operations = toolOperations(dataset.events);
+    const unprojectedToolEvidence = dataset.events.filter((event) => typeof event.attributes.unprojectedToolBlockCount === "number" && event.attributes.unprojectedToolBlockCount > 0);
+    const ambiguousTools = uniqueEvents([
+        ...dataset.events.filter((event) => event.family === "tool" && operationId(event, dataset.events) === undefined),
+        ...ambiguousActorScopedToolEvents(dataset.events),
+        ...unprojectedToolEvidence,
+    ]);
+    const ambiguousToolFailures = ambiguousTools.filter(explicitToolFailure);
+    const toolEvidence = uniqueEvents([...dataset.events.filter(({ family }) => family === "tool"), ...unprojectedToolEvidence]);
+    const toolCitations = citations(toolEvidence);
+    const unprojectedToolReason = unprojectedToolEvidence.length === 0 ? undefined
+        : `${unprojectedToolEvidence.length} native record(s) contain unprojectable tool blocks.`;
+    const modelEvents = dataset.events.filter(({ family }) => family === "model-request");
+    const requests = logicalRequestCount(modelEvents);
+    const failed = operations.filter(({ failed }) => failed);
+    const ambiguousToolStarts = ambiguousTools.filter(isToolStart);
+    const repeated = repeatedOperations(operations, ambiguousToolStarts);
+    const followed = followedOperations(operations, ambiguousToolStarts);
+    const compactions = dataset.events.filter(isCompactionBoundary);
+    return [
+        countOrUnavailable(dataset, registration("model-request-count"), requests.count, citations(modelEvents), requests.reason, "requests", modelEvents),
+        countOrUnavailable(dataset, registration("tool-operation-count"), operations.length, toolCitations, unprojectedToolReason, "identified-logical-tool-operations", toolEvidence),
+        countOrUnavailable(dataset, registration("tool-native-record-count"), toolCitations.length, toolCitations, undefined, "native-records", toolEvidence),
+        countOrUnavailable(dataset, registration("unidentified-tool-native-record-count"), citations(ambiguousTools).length, citations(ambiguousTools), undefined, "native-records", ambiguousTools),
+        countOrUnavailable(dataset, registration("tool-error-count"), failed.length, citations(failed.flatMap(({ events }) => events)), unprojectedToolReason
+            ?? (ambiguousToolFailures.length > 0 ? "Tool failure totals are unavailable because a failure record has ambiguous operation identity." : undefined), "logical-tool-operations", failed.flatMap(({ events }) => events)),
+        countOrUnavailable(dataset, registration("repeated-tool-operation-count"), repeated.count, repeated.citations, unprojectedToolReason ?? repeated.reason, "logical-tool-operations", repeated.events),
+        countOrUnavailable(dataset, registration("failure-followed-by-same-tool-count"), followed.same, followed.citations, unprojectedToolReason ?? followed.reason, "failed-logical-tool-operations", followed.events),
+        countOrUnavailable(dataset, registration("failure-followed-by-alternate-tool-count"), followed.alternate, followed.citations, unprojectedToolReason ?? followed.reason, "failed-logical-tool-operations", followed.events),
+        validationAfterMutation(dataset),
+        countOrUnavailable(dataset, registration("compaction-boundary-record-count"), compactions.length, citations(compactions), undefined, "native-records", compactions),
+        resourceObservation(dataset, "input-token-count", ["inputTokens"], "tokens"),
+        resourceObservation(dataset, "output-token-count", ["outputTokens"], "tokens"),
+        resourceObservation(dataset, "cache-read-input-token-count", ["cacheReadInputTokens", "cachedInputTokens"], "tokens"),
+        resourceObservation(dataset, "cache-creation-input-token-count", ["cacheCreationInputTokens", "cacheWriteInputTokens"], "tokens"),
+        resourceObservation(dataset, "total-token-count", ["totalTokens"], "tokens"),
+        resourceObservation(dataset, "total-cost-usd", ["totalCostUsd"], "usd"),
+        resourceObservation(dataset, "attempt-latency-ms", ["durationMs"], "milliseconds"),
+    ];
+}
+function importOutcomes(dataset, capture, assessmentMode) {
+    const terminal = dataset.events.find((event) => event.family === "outcome" && event.source.nativeType === "terminal-record");
+    const retainedTerminal = capture?.records.find(({ record }) => record.kind === "manifest");
+    const retainedState = asRecord(retainedTerminal?.record.document);
+    const retainedWorkspace = capture?.records.find(({ record }) => record.kind === "workspace"
+        && asRecord(record.document)?.id === retainedState?.workspaceArtifactId);
+    const terminalWorkspaceIds = new Set(terminal?.content.status === "known"
+        ? terminal.content.value.flatMap(({ nativeReference, role }) => role === "final-workspace" ? [nativeReference.artifactId] : [])
+        : []);
+    const workspace = dataset.events.filter((event) => event.family === "artifact"
+        && event.scope.kind === "workspace" && typeof event.scope.id === "string" && terminalWorkspaceIds.has(event.scope.id)
+        && event.content.status === "known" && event.content.value.some(({ nativeReference, role }) => role === "workspace-outcome" && terminalWorkspaceIds.has(nativeReference.artifactId)));
+    const captureReports = capture?.records.filter(({ record }) => record.kind === "capture-report") ?? [];
+    const captureReferences = captureReports.length > 0
+        ? captureReports.map(({ reference }) => reference)
+        : capture?.records.map(({ reference }) => reference) ?? [];
+    const assessmentEvents = dataset.events.filter((event) => event.source.nativeType === "assessment-mode");
+    const assessmentReferences = capture?.records.filter(({ record }) => record.kind === "assessment-mode").map(({ reference }) => reference) ?? [];
+    const verifierReferences = capture?.records.filter(({ record }) => record.kind === "verifier").map(({ reference }) => reference) ?? [];
+    const base = [
+        assessmentMode === "unknown"
+            ? unavailable(dataset, outcomeRegistry("assessment-mode", "Assessment mode retained by the run manifest."), "Assessment mode evidence is missing.", [])
+            : directObservation(dataset, "assessment-mode", "Assessment mode retained by the run manifest.", assessmentMode, "mode", assessmentEvents, assessmentEvents.length === 0 ? assessmentReferences.length > 0 ? assessmentReferences : verifierReferences : []),
+        terminal === undefined || typeof terminal.attributes.state !== "string"
+            ? retainedTerminal !== undefined && typeof retainedState?.state === "string"
+                ? directObservation(dataset, "terminal-state", "Terminal state retained by the run manifest.", retainedState.state, "state", [], [retainedTerminal.reference])
+                : unavailable(dataset, outcomeRegistry("terminal-state", "Terminal state retained by the run manifest."), "Terminal outcome evidence is missing.", [])
+            : directObservation(dataset, "terminal-state", "Terminal state retained by the run manifest.", String(terminal.attributes.state), "state", [terminal]),
+        capture === undefined
+            ? unavailable(dataset, outcomeRegistry("capture-qualification", "Structural capture qualification used to admit normalization."), "Capture qualification evidence was not supplied.", [])
+            : directObservation(dataset, "capture-qualification", "Structural capture qualification used to admit normalization.", capture.qualification, "qualification", [], captureReferences),
+        workspace.length === 0 && retainedWorkspace !== undefined && retainedTerminal !== undefined
+            ? directObservation(dataset, "workspace-outcome-count", "Retained final workspace outcomes referenced by the attempt.", 1, "workspace-outcomes", [], [retainedWorkspace.reference, retainedTerminal.reference])
+            : workspace.length === 0
+                ? unavailable(dataset, outcomeRegistry("workspace-outcome-count", "Retained final workspace outcomes referenced by the attempt."), terminalWorkspaceIds.size === 0 ? "Terminal outcome does not reference a final workspace artifact." : "Terminal-referenced workspace outcome evidence is missing.", terminal === undefined ? [] : citations([terminal]), terminal === undefined ? [] : [terminal])
+                : directObservation(dataset, "workspace-outcome-count", "Retained final workspace outcomes referenced by the attempt.", new Set(workspace.map(({ scope }) => scope.id)).size, "workspace-outcomes", [...workspace, ...(terminal === undefined ? [] : [terminal])]),
+    ];
+    if (assessmentMode !== "verified" || capture === undefined)
+        return base;
+    const assertions = capture.records.flatMap(({ record, reference }) => {
+        if (record.kind !== "verifier")
+            return [];
+        const document = asRecord(record.document);
+        return Array.isArray(document?.assertions) ? document.assertions.flatMap((candidate, index) => {
+            const assertion = asRecord(candidate);
+            return typeof assertion?.id === "string" && typeof assertion.status === "string"
+                ? [{ id: assertion.id, status: assertion.status, reference: derivedReference(reference, `/assertions/${index}`) }]
+                : [];
+        }) : [];
+    });
+    return [...base, ...assertions.map(({ id, status, reference }) => directObservation(dataset, `verifier-assertion-${stableSuffix(id)}`, "Verifier assertion outcome identified by the cited native record.", status, "assertion-status", [], [reference]))];
+}
+function toolOperations(events) {
+    const groups = new Map();
+    for (const event of events.filter(({ family }) => family === "tool")) {
+        const id = operationId(event, events);
+        if (id === undefined)
+            continue;
+        const grouped = groups.get(id) ?? [];
+        grouped.push(event);
+        groups.set(id, grouped);
+    }
+    return [...groups].sort(([left], [right]) => left.localeCompare(right))
+        .flatMap(([id, grouped]) => groupToolEvents(id, grouped, events).groups.map(([scopedId, scoped]) => operation(scopedId, scoped)));
+}
+function operation(id, grouped) {
+    const toolNames = new Set(grouped.flatMap((event) => scalarString(event.attributes.toolName) ?? []));
+    const inputDigests = new Set(grouped.flatMap((event) => scalarString(event.attributes.inputDigest) ?? []));
+    return {
+        id,
+        events: grouped,
+        ...(toolNames.size === 1 ? { toolName: [...toolNames][0] } : {}),
+        ...(inputDigests.size === 1 ? { inputDigest: [...inputDigests][0] } : {}),
+        failed: grouped.some(explicitToolFailure),
+    };
+}
+function actorScope(event) {
+    return explicitAgentScope(event) ?? directSessionScope(event);
+}
+function explicitAgentScope(event) {
+    const id = scalarString(event.attributes.agentId) ?? (event.actor.kind === "agent" ? event.actor.id : undefined);
+    return id === undefined ? undefined : `agent:${id}`;
+}
+function directSessionScope(event) {
+    const retained = scalarString(event.attributes.sessionId);
+    if (retained !== undefined)
+        return `session:${retained}`;
+    const scopeId = scalarString(event.scope.id);
+    return (event.scope.kind === "session" || event.scope.kind === "turn") && scopeId !== undefined
+        ? `${event.scope.kind}:${scopeId}` : undefined;
+}
+function sessionScope(event, allEvents) {
+    const direct = directSessionScope(event);
+    if (direct !== undefined)
+        return direct;
+    const reference = canonicalizeMetadata(event.source.nativeReference);
+    const sibling = allEvents.find((candidate) => candidate.id !== event.id
+        && canonicalizeMetadata(candidate.source.nativeReference) === reference && directSessionScope(candidate) !== undefined);
+    if (sibling !== undefined)
+        return directSessionScope(sibling);
+    for (const relation of event.relations.known) {
+        const related = allEvents.find(({ id }) => id === relation.eventId);
+        if (related === undefined)
+            continue;
+        const relatedDirect = directSessionScope(related);
+        if (relatedDirect !== undefined)
+            return relatedDirect;
+        const relatedReference = canonicalizeMetadata(related.source.nativeReference);
+        const relatedSibling = allEvents.find((candidate) => candidate.id !== related.id
+            && canonicalizeMetadata(candidate.source.nativeReference) === relatedReference && directSessionScope(candidate) !== undefined);
+        if (relatedSibling !== undefined)
+            return directSessionScope(relatedSibling);
+    }
+    return undefined;
+}
+function groupToolEvents(id, events, allEvents) {
+    const sessions = new Set(events.flatMap((event) => sessionScope(event, allEvents) ?? []));
+    if (sessions.size === 0)
+        return splitToolEventsByAgent(id, events);
+    const bySession = new Map([...sessions].sort().map((session) => [session, []]));
+    const agentSessions = new Map();
+    for (const event of events) {
+        const agent = explicitAgentScope(event);
+        const session = sessionScope(event, allEvents);
+        if (agent === undefined || session === undefined)
+            continue;
+        const linked = agentSessions.get(agent) ?? new Set();
+        linked.add(session);
+        agentSessions.set(agent, linked);
+    }
+    const ambiguous = [];
+    for (const event of events) {
+        const session = sessionScope(event, allEvents);
+        if (session !== undefined)
+            bySession.get(session).push(event);
+        else if (sessions.size === 1)
+            bySession.values().next().value.push(event);
+        else {
+            const linked = agentSessions.get(explicitAgentScope(event) ?? "");
+            if (linked?.size === 1)
+                bySession.get([...linked][0]).push(event);
+            else
+                ambiguous.push(event);
+        }
+    }
+    const groups = [];
+    for (const [session, grouped] of bySession) {
+        const split = splitToolEventsByAgent(`${session}:${id}`, grouped);
+        groups.push(...split.groups);
+        ambiguous.push(...split.ambiguous);
+    }
+    return { groups, ambiguous };
+}
+function splitToolEventsByAgent(id, events) {
+    const agents = new Set(events.flatMap((event) => explicitAgentScope(event) ?? []));
+    if (agents.size <= 1)
+        return { groups: [[id, [...events]]], ambiguous: [] };
+    return {
+        groups: [...agents].sort().map((agent) => [`${agent}:${id}`, events.filter((event) => explicitAgentScope(event) === agent)]),
+        ambiguous: events.filter((event) => explicitAgentScope(event) === undefined),
+    };
+}
+function ambiguousActorScopedToolEvents(events) {
+    const groups = new Map();
+    for (const event of events.filter(({ family }) => family === "tool")) {
+        const id = operationId(event, events);
+        if (id === undefined)
+            continue;
+        const grouped = groups.get(id) ?? [];
+        grouped.push(event);
+        groups.set(id, grouped);
+    }
+    return [...groups.entries()].flatMap(([id, grouped]) => groupToolEvents(id, grouped, events).ambiguous);
+}
+function uniqueEvents(events) {
+    return [...new Map(events.map((event) => [event.id, event])).values()];
+}
+function repeatedOperations(operations, ambiguousStarts) {
+    if (ambiguousStarts.length > 0) {
+        const events = [...operations.flatMap(({ events }) => events), ...ambiguousStarts];
+        return { count: 0, citations: citations(events), events, reason: "Identity-less tool starts make repeated-operation identity ambiguous." };
+    }
+    if (operations.length === 0)
+        return { count: 0, citations: [], events: [] };
+    if (operations.some(({ toolName, inputDigest }) => toolName === undefined || inputDigest === undefined)) {
+        const events = operations.flatMap(({ events }) => events);
+        return { count: 0, citations: citations(events), events, reason: "Repetition requires an explicit tool identity and native-input digest for every logical operation." };
+    }
+    const seen = new Map();
+    let count = 0;
+    const records = [];
+    for (const operation of operations) {
+        const signature = JSON.stringify([operation.toolName, operation.inputDigest]);
+        const first = seen.get(signature);
+        if (first !== undefined) {
+            count += 1;
+            records.push(...first.events, ...operation.events);
+        }
+        else
+            seen.set(signature, operation);
+    }
+    return { count, citations: citations(records), events: records };
+}
+function followedOperations(operations, ambiguousStarts) {
+    const failed = operations.filter(({ failed }) => failed);
+    if (failed.length === 0)
+        return { same: 0, alternate: 0, citations: [], events: [] };
+    if (ambiguousStarts.some(({ nativeOrder }) => nativeOrder.status !== "known")) {
+        const events = [...failed.flatMap(({ events }) => events), ...ambiguousStarts];
+        return {
+            same: 0,
+            alternate: 0,
+            citations: citations(events),
+            events,
+            reason: "An identity-less tool start has unknown native order relative to a failed operation.",
+        };
+    }
+    const ordered = operations.map((operation) => ({ operation, starts: orderedEvents(operation.events, false), failures: orderedEvents(operation.events, true) }));
+    if (ordered.some(({ operation, starts }) => starts.length === 0 || operation.toolName === undefined)
+        || ordered.filter(({ operation }) => operation.failed).some(({ failures }) => failures.length === 0)) {
+        const events = operations.flatMap(({ events }) => events);
+        return {
+            same: 0,
+            alternate: 0,
+            citations: citations(events),
+            events,
+            reason: "Failure-followed-by-operation requires explicit tool identities and source-local order for starts and failures.",
+        };
+    }
+    let same = 0;
+    let alternate = 0;
+    const records = [];
+    for (const current of ordered.filter(({ operation }) => operation.failed)) {
+        records.push(...current.operation.events);
+        const nextOperations = [];
+        for (const failure of current.failures) {
+            const candidates = ordered.flatMap(({ operation, starts }) => starts.map((start) => ({ operation, start })))
+                .filter(({ operation, start }) => operation.id !== current.operation.id
+                && start.domain === failure.domain && start.value > failure.value);
+            const nextOrder = candidates.length === 0 ? Number.POSITIVE_INFINITY : Math.min(...candidates.map(({ start }) => start.value));
+            const intervening = ambiguousStarts.filter(({ nativeOrder }) => nativeOrder.status === "known"
+                && nativeOrder.domain === failure.domain && nativeOrder.value > failure.value && nativeOrder.value <= nextOrder);
+            if (intervening.length > 0) {
+                const next = candidates.filter(({ start }) => start.value === nextOrder).flatMap(({ operation }) => operation.events);
+                const events = [...current.operation.events, ...intervening, ...next];
+                return {
+                    same: 0,
+                    alternate: 0,
+                    citations: citations(events),
+                    events,
+                    reason: "An identity-less tool start can be the next operation after a failure.",
+                };
+            }
+            if (candidates.length === 0)
+                continue;
+            const tied = candidates.filter(({ start }) => start.value === nextOrder);
+            const tiedClassifications = new Set(tied.map(({ operation }) => operation.toolName === current.operation.toolName ? "same" : "alternate"));
+            if (tiedClassifications.size > 1) {
+                const events = [current.operation, ...tied.map(({ operation }) => operation)].flatMap(({ events }) => events);
+                return {
+                    same: 0,
+                    alternate: 0,
+                    citations: citations(events),
+                    events,
+                    reason: "Tied next operations in one native-order domain disagree on tool classification.",
+                };
+            }
+            nextOperations.push(...tied.map(({ operation }) => operation));
+        }
+        const classifications = new Set(nextOperations.map((operation) => operation.toolName === current.operation.toolName ? "same" : "alternate"));
+        if (classifications.size > 1) {
+            const events = [current.operation, ...nextOperations].flatMap(({ events }) => events);
+            return {
+                same: 0,
+                alternate: 0,
+                citations: citations(events),
+                events,
+                reason: "Independent native-order domains disagree on the next tool operation classification.",
+            };
+        }
+        const classification = [...classifications][0];
+        if (classification === "same")
+            same += 1;
+        if (classification === "alternate")
+            alternate += 1;
+        if (classification !== undefined)
+            records.push(...nextOperations.flatMap(({ events }) => events));
+    }
+    return { same, alternate, citations: citations(records), events: records };
+}
+function isToolStart(event) {
+    return event.family === "tool" && (event.phase === "before" || event.phase === "instant");
+}
+function validationAfterMutation(dataset) {
+    const registrationValue = registration("validation-after-last-mutation");
+    const mutations = dataset.events.filter((event) => event.family === "artifact" && event.attributes.mutation === true);
+    const validations = dataset.events.filter(({ family }) => family === "validation");
+    const records = [...mutations, ...validations];
+    const capabilityReason = unavailableCapability(dataset, registrationValue, true);
+    if (capabilityReason !== undefined)
+        return unavailable(dataset, registrationValue, capabilityReason, citations(records), records);
+    if (mutations.length === 0)
+        return unavailable(dataset, registrationValue, "No normalized event explicitly identifies a mutation.", citations(records), records);
+    const ordered = records.flatMap((event) => event.nativeOrder.status === "known"
+        ? [{ event, value: event.nativeOrder.value, domain: event.nativeOrder.domain }] : []);
+    if (ordered.length !== records.length || new Set(ordered.map(({ domain }) => domain)).size !== 1) {
+        return unavailable(dataset, registrationValue, "Mutation and validation ordering is unknown or spans unrelated native-order domains.", citations(records), records);
+    }
+    const lastMutation = Math.max(...ordered.filter(({ event }) => event.family === "artifact").map(({ value }) => value));
+    const value = ordered.some(({ event, value: order }) => event.family === "validation" && order > lastMutation);
+    return known(dataset, registrationValue, value, "boolean", citations(records), records);
+}
+function resourceObservation(dataset, id, fields, unit) {
+    const resourceEvents = dataset.events.filter((event) => typeof event.attributes.resourceSemantics === "string");
+    const candidates = resourceEvents.flatMap((event) => {
+        if (typeof event.attributes.resourceSemantics !== "string")
+            return [];
+        const aliases = fields.flatMap((field) => typeof event.attributes[field] === "number"
+            ? [{ field, value: event.attributes[field] }] : []);
+        return aliases.length === 0 ? [] : [{
+                event,
+                field: aliases.map(({ field }) => field).join("/"),
+                value: aliases[0].value,
+                semantics: event.attributes.resourceSemantics,
+                aliasConflict: new Set(aliases.map(({ value }) => value)).size > 1,
+            }];
+    });
+    const field = fields.join("/");
+    const registrationValue = registration(id);
+    const capabilityReason = unavailableCapability(dataset, registrationValue, resourceEvents.length === 0);
+    if (capabilityReason !== undefined)
+        return unavailable(dataset, registrationValue, capabilityReason, citations(candidates.map(({ event }) => event)), candidates.map(({ event }) => event));
+    if (candidates.length === 0)
+        return unavailable(dataset, registrationValue, `No supported native ${field} record is available.`, []);
+    const finals = candidates.filter(({ semantics }) => semantics === "cumulative-final");
+    if (finals.length > 0) {
+        const invalid = invalidResourceReason(finals, field, unit);
+        if (invalid !== undefined)
+            return unavailable(dataset, registrationValue, invalid, citations(finals.map(({ event }) => event)), finals.map(({ event }) => event));
+        const values = new Set(finals.map(({ value }) => value));
+        return values.size === 1
+            ? known(dataset, registrationValue, finals[0].value, unit, citations(finals.map(({ event }) => event)), finals.map(({ event }) => event))
+            : unavailable(dataset, registrationValue, `Conflicting cumulative-final ${field} records are available.`, citations(finals.map(({ event }) => event)), finals.map(({ event }) => event));
+    }
+    if (candidates.every(({ semantics }) => semantics === "increment")) {
+        const invalid = invalidResourceReason(candidates, field, unit);
+        return invalid === undefined
+            ? known(dataset, registrationValue, candidates.reduce((sum, { value }) => sum + value, 0), unit, citations(candidates.map(({ event }) => event)), candidates.map(({ event }) => event))
+            : unavailable(dataset, registrationValue, invalid, citations(candidates.map(({ event }) => event)), candidates.map(({ event }) => event));
+    }
+    if (candidates.every(({ semantics }) => semantics === "cumulative-snapshot")) {
+        const snapshots = resourceEvents.filter(({ attributes }) => attributes.resourceSemantics === "cumulative-snapshot");
+        return cumulativeResourceObservation(dataset, registrationValue, candidates, snapshots, field, unit);
+    }
+    return unavailable(dataset, registrationValue, `${field} records have overlapping or unordered usage semantics.`, citations(candidates.map(({ event }) => event)), candidates.map(({ event }) => event));
+}
+function cumulativeResourceObservation(dataset, extractor, candidates, semanticEvents, field, unit) {
+    const ordered = semanticEvents.flatMap((event) => event.nativeOrder.status === "known"
+        ? [{ event, order: event.nativeOrder.value, domain: event.nativeOrder.domain }] : []);
+    if (semanticEvents.length > 1 && (ordered.length !== semanticEvents.length || new Set(ordered.map(({ domain }) => domain)).size !== 1)) {
+        return unavailable(dataset, extractor, `${field} cumulative snapshot records have unknown or unrelated native order.`, citations(semanticEvents), semanticEvents);
+    }
+    const latestEvents = semanticEvents.length === 1
+        ? semanticEvents
+        : ordered.filter(({ order }) => order === Math.max(...ordered.map(({ order: value }) => value))).map(({ event }) => event);
+    const latestIds = new Set(latestEvents.map(({ id }) => id));
+    const latest = candidates.filter(({ event }) => latestIds.has(event.id));
+    if (latest.length === 0) {
+        return unavailable(dataset, extractor, `Latest cumulative snapshot omits ${field}.`, citations(latestEvents), latestEvents);
+    }
+    const invalid = invalidResourceReason(latest, field, unit);
+    if (invalid !== undefined)
+        return unavailable(dataset, extractor, invalid, citations(latest.map(({ event }) => event)), latest.map(({ event }) => event));
+    const values = new Set(latest.map(({ value }) => value));
+    return values.size === 1
+        ? known(dataset, extractor, latest[0].value, unit, citations(latest.map(({ event }) => event)), latest.map(({ event }) => event))
+        : unavailable(dataset, extractor, `Conflicting latest cumulative ${field} snapshots are available.`, citations(latest.map(({ event }) => event)), latest.map(({ event }) => event));
+}
+function invalidResourceReason(candidates, field, unit) {
+    if (candidates.some(({ aliasConflict }) => aliasConflict))
+        return `${field} aliases conflict within one native record.`;
+    return candidates.some(({ value }) => !Number.isFinite(value) || value < 0 || unit === "tokens" && !Number.isSafeInteger(value))
+        ? `${field} contains a negative or non-integral native value.` : undefined;
+}
+function countOrUnavailable(dataset, extractor, count, evidence, reason, unit = "requests", sourceEvents = []) {
+    if (reason !== undefined)
+        return unavailable(dataset, extractor, reason, evidence, sourceEvents);
+    const unavailableReason = unavailableCapability(dataset, extractor, count === 0);
+    if (unavailableReason !== undefined)
+        return unavailable(dataset, extractor, unavailableReason, evidence, sourceEvents);
+    return known(dataset, extractor, count, unit, evidence, sourceEvents);
+}
+function directObservation(dataset, id, definition, value, unit, events, extraCitations = []) {
+    return known(dataset, outcomeRegistry(id, definition), value, unit, citations(events, extraCitations), events);
+}
+function known(dataset, extractor, value, unit, evidence, sourceEvents = []) {
+    return observation(dataset, extractor, { status: "known", value, unit }, evidence, sourceEvents);
+}
+function unavailable(dataset, extractor, reason, evidence, sourceEvents = []) {
+    return observation(dataset, extractor, { status: "unavailable", reason }, evidence, sourceEvents);
+}
+function observation(dataset, extractor, value, evidence, sourceEvents) {
+    const unique = uniqueReferences(evidence);
+    return {
+        schemaVersion: "ebo.structural-observation/v1",
+        id: `${dataset.attemptId}:${extractor.id}`,
+        runId: dataset.runId,
+        attemptId: dataset.attemptId,
+        extractor: { id: extractor.id, version: STRUCTURAL_EXTRACTOR_VERSION, requiredCapabilities: extractor.requiredCapabilities },
+        definition: extractor.definition,
+        denominator: { scope: "attempt", id: dataset.attemptId, value: 1, unit: "attempt" },
+        value,
+        sourceEventIds: [...new Set(sourceEvents.map(({ id }) => id))].sort(),
+        sourceRecordCount: unique.length,
+        citations: unique,
+    };
+}
+function operationId(event, events) {
+    const direct = [event.attributes.toolUseId, event.attributes.toolCallId, event.attributes.actionId, event.attributes.callId, event.attributes.itemId]
+        .map(scalarString).find((value) => value !== undefined)
+        ?? (event.scope.kind === "operation" ? event.scope.id : undefined);
+    if (direct !== undefined)
+        return direct;
+    for (const relation of event.relations.known) {
+        // ponytail: linear lookup keeps the extractor stateless; index IDs if million-record profiles require it.
+        const related = events.find(({ id }) => id === relation.eventId);
+        const relatedId = related === undefined ? undefined : operationIdWithoutRelations(related);
+        if (relatedId !== undefined)
+            return relatedId;
+    }
+    return undefined;
+}
+function operationIdWithoutRelations(event) {
+    return [event.attributes.toolUseId, event.attributes.toolCallId, event.attributes.actionId, event.attributes.callId, event.attributes.itemId]
+        .map(scalarString).find((value) => value !== undefined)
+        ?? (event.scope.kind === "operation" ? event.scope.id : undefined);
+}
+function requestId(event) {
+    return [event.attributes.requestId, event.attributes.callId, event.attributes.llmResponseId]
+        .map(scalarString).find((value) => value !== undefined)
+        ?? (event.scope.kind === "operation" ? event.scope.id : undefined);
+}
+function logicalRequestCount(events) {
+    const groups = new Map();
+    const unidentified = events.filter((event) => {
+        const id = requestId(event);
+        if (id === undefined)
+            return true;
+        const grouped = groups.get(id) ?? [];
+        grouped.push(event);
+        groups.set(id, grouped);
+        return false;
+    });
+    let count = 0;
+    let ambiguousScopes = 0;
+    for (const grouped of groups.values()) {
+        const scopes = new Set(grouped.flatMap((event) => actorScope(event) ?? []));
+        count += Math.max(1, scopes.size);
+        if (scopes.size > 1)
+            ambiguousScopes += grouped.filter((event) => actorScope(event) === undefined).length;
+    }
+    const ambiguities = [
+        unidentified.length > 0 ? `${unidentified.length} record(s) lack a source-native request identity` : undefined,
+        ambiguousScopes > 0 ? `${ambiguousScopes} record(s) lack a native scope while the same request ID occurs in multiple scopes` : undefined,
+    ].filter((reason) => reason !== undefined);
+    return { count, ...(ambiguities.length === 0 ? {} : { reason: `Model-request count is unavailable because ${ambiguities.join(" and ")}.` }) };
+}
+function explicitToolFailure(event) {
+    return event.attributes.isError === true || event.attributes.errorScope === "agent-tool"
+        || event.attributes.hook === "PostToolUseFailure" || event.attributes.status === "failed"
+        || event.attributes.status === "error" || event.attributes.status === "declined";
+}
+function orderedEvents(events, failures) {
+    return events.filter((event) => failures ? explicitToolFailure(event) : event.phase === "before" || event.phase === "instant")
+        .flatMap((event) => event.nativeOrder.status === "known"
+        ? [{ value: event.nativeOrder.value, domain: event.nativeOrder.domain }] : []);
+}
+function isCompactionBoundary(event) {
+    if (event.family !== "context")
+        return false;
+    const subtype = scalarString(event.attributes.subtype);
+    const hook = scalarString(event.attributes.hook);
+    const method = scalarString(event.attributes.method);
+    const eventType = scalarString(event.attributes.eventType);
+    return subtype === "compact_boundary" || hook === "PreCompact" || hook === "PostCompact"
+        || method === "thread/compacted" || eventType?.startsWith("compaction/") === true
+        || event.source.nativeType === "Condensation" || event.source.nativeType === "CondensationSummaryEvent";
+}
+function importAssessmentMode(dataset, capture) {
+    const record = capture?.records.find(({ record }) => record.kind === "assessment-mode")?.record.document;
+    if (record === "observational" || record === "verified")
+        return record;
+    if (capture?.records.some(({ record }) => record.kind === "verifier") === true)
+        return "verified";
+    const value = dataset.events.find((event) => event.source.nativeType === "assessment-mode")?.attributes.assessmentMode;
+    return value === "observational" || value === "verified" ? value : "unknown";
+}
+function unavailableCapability(dataset, extractor, zero) {
+    for (const requirement of extractor.requiredCapabilities) {
+        const capability = requirement === "evidence:nativeOrder"
+            ? dataset.capabilityProfile.evidence.nativeOrder
+            : dataset.capabilityProfile.families[requirement.slice("family:".length)];
+        if (capability.status === "unsupported")
+            return capability.detail ?? `Required capability ${requirement} is unsupported.`;
+        if (zero && capability.status === "partial")
+            return capability.detail ?? `Required capability ${requirement} is partial, so an observed zero is not supported.`;
+    }
+    return undefined;
+}
+function citations(events, extra = []) {
+    return uniqueReferences([...events.map(({ source }) => source.nativeReference), ...extra]);
+}
+function uniqueReferences(references) {
+    return [...new Map(references.map((reference) => [canonicalizeMetadata(reference), structuredClone(reference)])).values()]
+        .sort((left, right) => canonicalizeMetadata(left).localeCompare(canonicalizeMetadata(right)));
+}
+function derivedReference(reference, pointer) {
+    return { artifactId: reference.artifactId, recordLocator: reference.recordLocator === "#" ? `#${pointer}` : `${reference.recordLocator}#${pointer}` };
+}
+function scalarString(value) {
+    return typeof value === "string" && value !== "" ? value : undefined;
+}
+function stableSuffix(value) {
+    return createHash("sha256").update(value).digest("hex").slice(0, 16);
+}
+function registry(id, requiredCapabilities, definition) {
+    return { id, requiredCapabilities, definition };
+}
+function registration(id) {
+    const found = STRUCTURAL_EXTRACTOR_REGISTRY.find((candidate) => candidate.id === id);
+    if (found === undefined)
+        throw new Error(`Unknown structural extractor "${id}".`);
+    return found;
+}
+function outcomeRegistry(id, definition) {
+    return registry(`outcome-${id}`, [], definition);
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : undefined;
+}