engineering-behavior-observatory 0.2.1

package/dist/src/atlas.js

@@ -0,0 +1,235 @@
+import { createServer } from "node:http";
+import { statSync } from "node:fs";
+import { mkdir, mkdtemp, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { aggregateEvaluation, selectAggregationAttempts } from "./aggregation.js";
+import { assertNoDuplicateJsonKeys, canonicalizeMetadata, digestMetadata, validateArtifact } from "./artifacts.js";
+import { createRetainedBehaviorEvidence } from "./retained-evidence.js";
+import { readCorpusIndex, validateCorpusIndex } from "./corpus.js";
+import { readPortableRunBundleExport, sanitizeDerivedExport } from "./exports.js";
+import { assertCalibrationDestination, effectiveReviewOutcome, isDisputedReviewOutcome } from "./human-calibration.js";
+import { readBoundedFile } from "./scheduler.js";
+import { renderAtlas } from "./atlas-html.js";
+import { writeAtlasGrafana } from "./atlas-grafana.js";
+export const ATLAS_FILTERS = ["model", "harness", "task", "trial", "capture", "outcome", "review", "category", "assessment", "q"];
+export function atlasBehaviorPartitions(view) {
+    return view.report.groups.flatMap((group) => (group.behaviors ?? []).map((partition) => ({ group: Object.values(group.dimensions).join(" · ") || "Selected cohort", partition })));
+}
+export function atlasBehaviorRows(view) {
+    const rows = atlasBehaviorPartitions(view).flatMap(({ group, partition }) => partition.assessments.map(({ assessment, measurement }) => ({ group, category: partition.behavior.categoryId, dimension: partition.behavior.dimensionId, vocabulary: partition.behavior.vocabularyVersion, rubric: `${partition.rubric.id}@${partition.rubric.version}`, evaluator: canonicalizeMetadata(partition.evaluator), assessment, label: `${group} · ${partition.behavior.categoryId} · ${assessment}`, status: measurement.status, numerator: measurement.status === "available" ? measurement.numerator.value : null, denominator: measurement.denominator.value, unit: measurement.denominator.unit, exclusions: measurement.exclusions.map(({ reason, count }) => `${reason}: ${count}`).join("; "), cohortDigest: view.cohortDigest })));
+    return rows.length ? rows : [{ group: "Selected cohort", category: "unavailable", dimension: "unavailable", vocabulary: "unavailable", rubric: "unavailable", evaluator: "unavailable", assessment: "unavailable", label: "Behavior distribution unavailable", status: "unavailable", numerator: null, denominator: 0, unit: "confirmed-attempt-dimension", exclusions: "No behavior assessment partition is available.", cohortDigest: view.cohortDigest }];
+}
+const digest = (value) => `sha256:${digestMetadata(value).value}`;
+const attemptKey = (value) => `${value.runId}\0${value.attemptId}`;
+export async function loadAtlas(requestPath) {
+    const request = readJson(requestPath);
+    exactKeys(request, ["schemaVersion", "aggregationRequest", "title", "operatorNarrative", "reviewPackets", "traces", "grafanaUrl", "atlasUrl", "tempoDatasourceUid", "sharing"]);
+    if (request.schemaVersion !== "ebo.atlas-request/v1" || typeof request.title !== "string" || !request.title.trim() || typeof request.aggregationRequest !== "string")
+        throw new Error("Invalid or incompatible Atlas request.");
+    if (request.operatorNarrative !== undefined && typeof request.operatorNarrative !== "string")
+        throw new Error("Operator narrative must be text.");
+    if (request.grafanaUrl !== undefined)
+        localUrl(request.grafanaUrl);
+    if (request.atlasUrl !== undefined)
+        localUrl(request.atlasUrl);
+    const traceKeys = new Set();
+    for (const trace of request.traces ?? []) {
+        if (typeof trace.runId !== "string" || !trace.runId || typeof trace.attemptId !== "string" || !trace.attemptId
+            || !/^[a-f0-9]{32}$/u.test(trace.traceId) || !Number.isFinite(Date.parse(trace.originalStart))
+            || (trace.replayStart !== undefined && !Number.isFinite(Date.parse(trace.replayStart))))
+            throw new Error("Invalid trace identity or timestamp.");
+        const key = attemptKey(trace);
+        if (traceKeys.has(key))
+            throw new Error("Atlas trace attempt keys must be unique; conflicting trace bindings are not allowed.");
+        traceKeys.add(key);
+    }
+    const base = dirname(resolve(requestPath));
+    for (const path of request.reviewPackets ?? []) {
+        if (typeof path !== "string" || !statSync(resolve(base, path), { throwIfNoEntry: false })?.isFile())
+            throw new Error("Configured human review packet is unavailable.");
+    }
+    const aggregationPath = resolve(base, request.aggregationRequest);
+    const aggregation = readArtifact(aggregationPath);
+    const aggregateBase = dirname(aggregationPath);
+    const source = aggregation.sources;
+    const corpusRoot = resolve(aggregateBase, source.corpusRoot);
+    const corpusEntries = readCorpusIndex(resolve(aggregateBase, source.corpusIndex));
+    const issues = validateCorpusIndex(corpusRoot, corpusEntries);
+    if (issues.length)
+        throw new Error("Atlas corpus index is stale or invalid; rebuild and validate it before querying.");
+    const input = {
+        lineage: { requestDigest: digest(aggregation), corpusIndexDigest: digest(corpusEntries) }, corpusEntries,
+        observationSets: source.observationSets.map(({ bundleRoot, path }) => ({ bundleRoot: resolve(aggregateBase, bundleRoot), document: readArtifact(resolve(aggregateBase, path)) })),
+        assertions: source.assertions.map(({ bundleRoot, path }) => ({ bundleRoot: resolve(aggregateBase, bundleRoot), document: readArtifact(resolve(aggregateBase, path)) })),
+        calibrations: source.calibrations.map(({ selection, history }) => ({ selection: readArtifact(resolve(aggregateBase, selection)), history: readArtifact(resolve(aggregateBase, history)) })),
+        comparisons: aggregation.comparisons.map(({ eligibilityGates, ...comparison }) => ({ ...comparison, eligibility: eligibilityGates.map(({ request, report }) => ({ request: readArtifact(resolve(aggregateBase, request)), report: readArtifact(resolve(aggregateBase, report)) })) })),
+    };
+    // Validate the complete source before any case or review state is exposed.
+    const validated = await aggregateEvaluation(input, aggregation);
+    const cases = [];
+    const seenAssertions = new Set();
+    for (const entry of corpusEntries.filter(({ manifestKind }) => manifestKind === "run")) {
+        const ownAssertions = input.assertions.filter(({ document }) => attemptKey(document) === attemptKey(entry));
+        const context = { runId: entry.runId, attemptId: entry.attemptId, model: entry.modelId ?? "unavailable", harness: entry.harnessId ?? "unavailable", harnessVersion: entry.harnessVersion ?? "unavailable", task: entry.taskId ?? "unavailable", trial: entry.trialId ?? "unavailable", capture: entry.captureQualification ?? "unavailable", outcome: entry.terminalState ?? "unavailable", ...(entry.retryOf ? { retryOf: entry.retryOf } : {}) };
+        let trace;
+        const traceSource = request.traces?.find((item) => attemptKey(item) === attemptKey(entry));
+        if (traceSource) {
+            if (request.grafanaUrl && request.tempoDatasourceUid) {
+                const panes = { atlas: { datasource: request.tempoDatasourceUid, queries: [{ refId: "A", queryType: "traceId", query: traceSource.traceId }], range: { from: "now-1h", to: "now" } } };
+                trace = { href: `${localUrl(request.grafanaUrl)}/explore?schemaVersion=1&panes=${encodeURIComponent(JSON.stringify(panes))}`, originalStart: traceSource.originalStart, ...(traceSource.replayStart ? { replayStart: traceSource.replayStart } : {}) };
+            }
+        }
+        if (!ownAssertions.length)
+            cases.push({ ...context, key: digest(context).slice(7), category: "unavailable", assessment: "unavailable", review: "unavailable", decisions: [], citations: [], ...(trace ? { trace } : {}) });
+        for (const { document: assertion, bundleRoot } of ownAssertions) {
+            const assertionDigest = digest(assertion);
+            if (seenAssertions.has(assertionDigest))
+                continue;
+            seenAssertions.add(assertionDigest);
+            const reviews = input.calibrations.flatMap(({ selection, history }) => selection.candidates.filter(({ assertion: binding }) => binding.id === assertion.id && binding.digest === assertionDigest).map((candidate) => ({ candidate, history })));
+            const latest = reviews[0];
+            const outcome = latest ? effectiveReviewOutcome(latest.candidate, latest.history.decisions) : assertion.judgment.disposition === "abstained" ? "judge-abstained" : "unreviewed";
+            const review = latest && isDisputedReviewOutcome(latest.candidate, latest.history.decisions) ? "disputed" : { "judge-abstained": "abstained", unreviewed: "proposed", unresolved: "insufficient-evidence", confirmed: "confirmed", rejected: "rejected" }[outcome];
+            const evidence = await createRetainedBehaviorEvidence(bundleRoot);
+            const citations = assertion.judgment.citations.map((citation) => {
+                const normalizedEvent = evidence.dataset.events.find(({ id }) => id === citation.eventId);
+                const native = evidence.capture.records.find(({ reference }) => canonicalizeMetadata(reference) === canonicalizeMetadata(citation.nativeReference));
+                if (!normalizedEvent || !native)
+                    throw new Error("Atlas citation cannot resolve to normalized and native evidence.");
+                return { ...citation, normalizedEvent: displaySafe(normalizedEvent), nativeRecord: displaySafe(evidence.dataset.adapter.harness === "claude-agent-sdk" ? native.record.document : native.record) };
+            });
+            const decisions = [...new Map(reviews.flatMap(({ history }) => history.decisions.filter(({ assertion: binding }) => binding.id === assertion.id && binding.digest === assertionDigest)).map((decision) => [digest(decision), decision])).values()];
+            cases.push({ ...context, key: assertionDigest.slice(7), assertion: displaySafe(assertion), assertionDigest, category: assertion.behavior.categoryId, assessment: assertion.judgment.disposition === "assessed" ? assertion.judgment.assessment : "abstained", review, decisions: displaySafe(decisions), citations, ...(trace ? { trace } : {}) });
+        }
+    }
+    return { request, aggregation, input, corpusRoot, requestPath: resolve(requestPath), cases, sourceDigest: digest({ request, lineage: validated.sourceLineage }) };
+}
+export async function queryAtlas(source, filters = {}) {
+    exactKeys(filters, [...ATLAS_FILTERS]);
+    for (const value of Object.values(filters))
+        if (typeof value !== "string" || value.length > 500)
+            throw new Error("Invalid Atlas filter.");
+    const eligible = selectAggregationAttempts(source.input.corpusEntries, source.aggregation.selectedAttemptPolicy);
+    const eligibleIds = new Set(eligible.map(attemptKey));
+    const eligibleCases = source.cases.filter((item) => eligibleIds.has(attemptKey(item)));
+    const matches = eligibleCases.filter((item) => Object.entries(filters).every(([key, value]) => !value || (key === "q" ? [item.runId, item.attemptId, item.model, item.task, item.assertion?.judgment.rationale ?? "", item.category].join(" ").toLocaleLowerCase().includes(value.toLocaleLowerCase()) : item[key] === value)));
+    // Filters select attempts through matching cases; all judgments on those attempts
+    // remain in aggregation so a constructive filter cannot erase an adverse rerun.
+    const ids = new Set(matches.map(attemptKey));
+    const corpusEntries = source.input.corpusEntries.filter((entry) => ids.has(attemptKey(entry)));
+    const report = await aggregateEvaluation({ ...source.input, lineage: { ...source.input.lineage, corpusIndexDigest: digest(corpusEntries) }, corpusEntries, observationSets: source.input.observationSets.filter(({ document }) => ids.has(attemptKey(document))), assertions: source.input.assertions.filter(({ document }) => ids.has(attemptKey(document))) }, source.aggregation);
+    const filterOptions = Object.fromEntries(ATLAS_FILTERS.filter((key) => key !== "q").map((key) => [key, [...new Set(eligibleCases.map((item) => String(item[key])))].sort()]));
+    const sourceAttempts = new Set(source.input.corpusEntries.filter(({ manifestKind }) => manifestKind === "run").map(attemptKey)).size;
+    return { schemaVersion: "ebo.atlas-view/v1", title: source.request.title, atlasUrl: localUrl(source.request.atlasUrl ?? "http://127.0.0.1:13011"), mode: "restricted-local-only", generatedAt: new Date().toISOString(), sourceDigest: source.sourceDigest, cohortDigest: digest({ source: source.sourceDigest, filters, lineage: report.sourceLineage }), filters, filterOptions, report, cases: matches, matchingCases: matches.length, sourceAttempts, policyExcludedAttempts: sourceAttempts - eligible.length, filteredOutAttempts: eligible.length - ids.size, ...(source.request.operatorNarrative ? { operatorNarrative: displaySafe({ text: source.request.operatorNarrative }).text } : {}), reviewPackets: (source.request.reviewPackets ?? []).map((path) => pathToFileURL(resolve(dirname(source.requestPath), path)).href), ...(source.request.grafanaUrl ? { grafanaUrl: localUrl(source.request.grafanaUrl) } : {}) };
+}
+export async function shareAtlas(source, view) {
+    const sharing = source.request.sharing;
+    if (!sharing)
+        throw new Error("Sharing unavailable: configure approved exports and explicit report fields first.");
+    if (["review", "category", "assessment", "q"].some((key) => view.filters[key]))
+        throw new Error("Shareable summaries cannot use semantic, human-review, or free-text evidence filters; their cohort counts would disclose unapproved findings.");
+    exactKeys(sharing, ["policy", "approvedExports", "fields"]);
+    const supported = ["cohort", "aggregate-metrics", "source-digests"];
+    if (sharing.fields.length !== supported.length || !supported.every((field) => sharing.fields.includes(field)))
+        throw new Error("Unsupported report-field sharing; only cohort, aggregate-metrics and source-digests are supported.");
+    const approved = await Promise.all(sharing.approvedExports.map((root) => readPortableRunBundleExport(resolve(dirname(source.requestPath), root), sharing.policy)));
+    if (view.report.sourceLineage.manifests.some(({ digest }) => !approved.some(({ sourceManifestDigest }) => sourceManifestDigest === digest)))
+        throw new Error("Every selected source manifest requires a policy-validated approved export.");
+    // Semantic assertions, human prose, evidence records and operator narrative have
+    // no portable sharing classification yet. The shareable surface excludes them.
+    const { operatorNarrative: _narrative, grafanaUrl: _grafana, atlasUrl: _atlas, ...metadata } = view;
+    const correlations = source.input.corpusEntries.flatMap(({ runId, attemptId, bundleId }) => [runId, attemptId, bundleId].filter((value) => value !== undefined));
+    const sanitized = sanitizeDerivedExport({ ...metadata, title: "Approved cohort summary", mode: sharing.policy.sharingClass, cases: [], matchingCases: null, reviewPackets: [], filterOptions: {}, filters: view.filters, report: { ...view.report, groups: view.report.groups.map(({ dimensions, metrics, variations }) => ({ dimensions, metrics: metrics.filter(({ population }) => population !== "assertion" && population !== "reviewed-assertion"), variations })), comparisons: [], sourceLineage: { ...view.report.sourceLineage, assertions: [], calibrations: [], comparisonGates: [] }, limitations: [...view.report.limitations, "Sharing excludes semantic findings, human decisions, native content, local links and operator narrative: those fields lack export approval."] } }, sharing.policy, correlations);
+    return sanitized;
+}
+export async function writeAtlas(requestPath, outputRoot, filters = {}, share = false) {
+    const source = await loadAtlas(requestPath);
+    const view = await queryAtlas(source, filters);
+    const result = share ? await shareAtlas(source, view) : view;
+    assertCalibrationDestination([source.corpusRoot, ...source.input.assertions.map(({ bundleRoot }) => bundleRoot)], outputRoot);
+    if (statSync(outputRoot, { throwIfNoEntry: false }))
+        throw new Error("Atlas output destination already exists.");
+    await mkdir(dirname(resolve(outputRoot)), { recursive: true, mode: 0o700 });
+    const staging = await mkdtemp(join(dirname(resolve(outputRoot)), ".ebo-atlas-"));
+    try {
+        await writeFile(join(staging, "index.html"), renderAtlas(result, false), { mode: 0o600, flag: "wx" });
+        await writeFile(join(staging, "report.json"), `${canonicalizeMetadata(result)}\n`, { mode: 0o600, flag: "wx" });
+        if (!share)
+            await writeAtlasGrafana(staging, result);
+        await rename(staging, outputRoot);
+    }
+    finally {
+        await rm(staging, { recursive: true, force: true });
+    }
+    return result;
+}
+export async function serveAtlas(requestPath, port = 13011) {
+    if (!Number.isSafeInteger(port) || port < 0 || port > 65535)
+        throw new Error("Invalid Atlas port.");
+    await loadAtlas(requestPath);
+    const server = createServer(async (req, res) => {
+        res.setHeader("Cache-Control", "no-store");
+        res.setHeader("X-Content-Type-Options", "nosniff");
+        res.setHeader("Referrer-Policy", "no-referrer");
+        try {
+            if (req.method !== "GET") {
+                res.writeHead(405).end();
+                return;
+            }
+            if (!req.headers.host || !["127.0.0.1", "localhost", "[::1]"].includes(new URL(`http://${req.headers.host}`).hostname)) {
+                res.writeHead(403).end();
+                return;
+            }
+            if (req.headers.origin && !["127.0.0.1", "localhost", "[::1]"].includes(new URL(req.headers.origin).hostname)) {
+                res.writeHead(403).end();
+                return;
+            }
+            const url = new URL(req.url ?? "/", "http://127.0.0.1");
+            if (!["/", "/api/view", "/api/metrics", "/api/behaviors", "/api/behavior-chart", "/api/comparisons", "/api/cases", "/report.html", "/report.json"].includes(url.pathname)) {
+                res.writeHead(404).end();
+                return;
+            }
+            const filters = {};
+            for (const [key, value] of url.searchParams) {
+                if (key === "share")
+                    continue;
+                if (!ATLAS_FILTERS.includes(key))
+                    throw new Error("Unknown Atlas query parameter.");
+                if (value && (key === "q" || value !== "$__all"))
+                    filters[key] = value;
+            }
+            const source = await loadAtlas(requestPath);
+            let view = await queryAtlas(source, filters);
+            if (url.searchParams.get("share") === "true")
+                view = await shareAtlas(source, view);
+            if (url.pathname === "/" || url.pathname === "/report.html") {
+                res.setHeader("Content-Type", "text/html; charset=utf-8");
+                res.end(renderAtlas(view, url.pathname === "/"));
+            }
+            else {
+                res.setHeader("Content-Type", "application/json; charset=utf-8");
+                if (url.pathname === "/api/comparisons") {
+                    res.end(JSON.stringify(view.report.comparisons.map(({ id, measure, matchedDifference, claimStatus, limitations }) => ({ comparison: id, measure, status: claimStatus, numerator: matchedDifference.status === "available" ? matchedDifference.numerator.value : null, denominator: matchedDifference.denominator.value, unit: matchedDifference.denominator.unit, exclusions: matchedDifference.exclusions.map(({ reason, count }) => `${reason}: ${count}`).join("; "), limitations: limitations.join(" ") }))));
+                    return;
+                }
+                const rows = url.pathname === "/api/metrics" ? view.report.groups.flatMap((group) => group.metrics.map((metric) => ({ group: Object.values(group.dimensions).join(" · "), metric: metric.id, status: metric.measurement.status, numerator: metric.measurement.numerator.value, denominator: metric.measurement.denominator.value, unit: metric.measurement.denominator.unit, exclusions: metric.measurement.exclusions.map(({ reason, count }) => `${reason}: ${count}`).join("; "), cohortDigest: view.cohortDigest }))) : view;
+                res.end(JSON.stringify(url.pathname === "/api/behavior-chart" ? atlasBehaviorRows(view).map(({ label, numerator }) => ({ label, count: numerator })) : url.pathname === "/api/behaviors" ? atlasBehaviorRows(view) : url.pathname === "/api/cases" ? view.cases.map(({ runId, attemptId, model, harness, task, trial, category, assessment, review, key }) => ({ runId, attemptId, model, harness, task, trial, category, assessment, review, href: `http://${req.headers.host}/?${new URLSearchParams(filters)}#case-${key}` })) : rows));
+            }
+        }
+        catch (error) {
+            res.writeHead(400, { "Content-Type": "text/plain; charset=utf-8" });
+            res.end(error instanceof Error ? error.message : "Atlas query failed.");
+        }
+    });
+    await new Promise((accept, reject) => { server.once("error", reject); server.listen(port, "127.0.0.1", accept); });
+    return server;
+}
+function readJson(path) { const text = readBoundedFile(path).toString("utf8"); assertNoDuplicateJsonKeys(text); return JSON.parse(text); }
+function displaySafe(value) { return sanitizeDerivedExport(value, { sharingClass: "partner", maxArtifactBytes: 16 * 1024 * 1024, maxStringBytes: 128 * 1024 }); }
+function readArtifact(path) { const value = readJson(path); const errors = validateArtifact(path, value); if (errors.length)
+    throw new Error(`Invalid Atlas source: ${errors[0].field} ${errors[0].message}`); return value; }
+function exactKeys(value, keys) { if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).some((key) => !keys.includes(key)))
+    throw new Error("Unknown or invalid Atlas fields."); }
+function localUrl(value) { const url = new URL(value); if (url.protocol !== "http:" || !["127.0.0.1", "localhost", "[::1]"].includes(url.hostname) || url.username || url.password || url.search || url.hash || url.pathname !== "/")
+    throw new Error("Atlas integration URL must be a local HTTP origin."); return url.origin; }

package/dist/src/behavior-assertions.d.ts

@@ -0,0 +1,95 @@
+import { type AgentSdkNativeRecord } from "./agent-sdk-normalizer.js";
+import { type AdapterCoverageReport, type NormalizedDataset } from "./normalization-integrity.js";
+import type { NativeEvidenceReference, NativeEvidenceResolution, NativeEvidenceResolver, NormalizationInput } from "./uniform-events.js";
+type DigestString = `sha256:${string}`;
+type VersionedIdentity = {
+    id: string;
+    version: string;
+};
+export type BehaviorVocabulary = {
+    schemaVersion: "ebo.behavior-vocabulary/v1";
+    version: string;
+    categories: ReadonlyArray<{
+        id: string;
+        name: string;
+        dimensions: ReadonlyArray<{
+            id: string;
+            name: string;
+        }>;
+    }>;
+};
+export type BehaviorCitation = {
+    eventId: string;
+    nativeReference: NativeEvidenceReference;
+};
+type AssessedJudgment = {
+    disposition: "assessed";
+    assessment: "constructive" | "adverse" | "mixed" | "context-dependent";
+    confidence: {
+        value: number;
+        scale: "evaluator-reported-0-to-1";
+    };
+    rationale: string;
+    alternativeExplanation: string;
+    citations: readonly BehaviorCitation[];
+};
+type AbstainedJudgment = {
+    disposition: "abstained";
+    reason: string;
+    missingEvidenceCapability?: string;
+    rationale: string;
+    alternativeExplanation: string;
+    citations: readonly BehaviorCitation[];
+};
+export type BehaviorAssertion = {
+    schemaVersion: "ebo.behavior-assertion/v1";
+    id: string;
+    runId: string;
+    attemptId: string;
+    dataset: {
+        schemaVersion: "ebo.normalized-dataset/v1";
+        digest: DigestString;
+    };
+    behavior: {
+        vocabularyVersion: string;
+        categoryId: string;
+        dimensionId: string;
+    };
+    rubric: VersionedIdentity;
+    evaluator: VersionedIdentity & {
+        configurationDigest?: DigestString;
+    };
+    judgment: AssessedJudgment | AbstainedJudgment;
+};
+export type BehaviorReview = {
+    schemaVersion: "ebo.behavior-review/v1";
+    id: string;
+    assertion: {
+        id: string;
+        schemaVersion: "ebo.behavior-assertion/v1";
+        digest: DigestString;
+    };
+    state: "proposed" | "confirmed" | "disputed" | "rejected" | "insufficient-evidence";
+    reviewer?: {
+        kind: "human";
+        id: string;
+    };
+    rationale?: string;
+};
+export type ResolvedBehaviorCitation = BehaviorCitation & {
+    resolution: NativeEvidenceResolution;
+};
+export type AgentSdkBehaviorEvidence = {
+    capture: NormalizationInput<AgentSdkNativeRecord>;
+    dataset: NormalizedDataset;
+    resolver: NativeEvidenceResolver;
+    coverage: AdapterCoverageReport;
+};
+export declare const DEFAULT_BEHAVIOR_VOCABULARY: BehaviorVocabulary;
+export declare function validateBehaviorAssertion(assertion: BehaviorAssertion, dataset: NormalizedDataset, resolver: NativeEvidenceResolver, vocabulary?: BehaviorVocabulary): Promise<readonly ResolvedBehaviorCitation[]>;
+export declare function validateBehaviorReview(assertion: BehaviorAssertion, review: BehaviorReview): void;
+export declare function isConfirmedBehaviorAssertion(assertion: BehaviorAssertion, dataset: NormalizedDataset, resolver: NativeEvidenceResolver, review?: BehaviorReview, vocabulary?: BehaviorVocabulary): Promise<boolean>;
+export declare function validateAgentSdkBehaviorAssertion(bundleRoot: string, assertion: BehaviorAssertion, review?: BehaviorReview): Promise<readonly ResolvedBehaviorCitation[]>;
+export declare function createAgentSdkBehaviorEvidence(bundleRoot: string): Promise<AgentSdkBehaviorEvidence>;
+export declare function validateRetainedBehaviorAssertion(bundleRoot: string, assertion: BehaviorAssertion, review?: BehaviorReview): Promise<readonly ResolvedBehaviorCitation[]>;
+export {};

package/dist/src/behavior-assertions.js

@@ -0,0 +1,154 @@
+import { readFileSync } from "node:fs";
+import { createRetainedBehaviorEvidence } from "./retained-evidence.js";
+import { CLAUDE_AGENT_SDK_NORMALIZATION_ADAPTER_VERSION, claudeAgentSdkNormalizationAdapter, createAgentSdkNativeEvidenceResolver, readQualifiedClaudeAgentSdkCapture, } from "./agent-sdk-normalizer.js";
+import { canonicalizeMetadata, digestMetadata, validateArtifact } from "./artifacts.js";
+import { describeNormalizedDataset, validateNormalizedDataset, } from "./normalization-integrity.js";
+export const DEFAULT_BEHAVIOR_VOCABULARY = loadDefaultVocabulary();
+export async function validateBehaviorAssertion(assertion, dataset, resolver, vocabulary = DEFAULT_BEHAVIOR_VOCABULARY) {
+    assertValid("behavior assertion", assertion);
+    assertVocabulary(vocabulary);
+    await validateNormalizedDataset(dataset, resolver);
+    const datasetDigest = digest(dataset);
+    if (assertion.dataset.schemaVersion !== dataset.schemaVersion || assertion.dataset.digest !== datasetDigest) {
+        throw new Error("Behavior assertion normalized dataset version or digest does not match.");
+    }
+    if (assertion.runId !== dataset.runId || assertion.attemptId !== dataset.attemptId) {
+        throw new Error("Behavior assertion belongs to the wrong run or attempt.");
+    }
+    if (assertion.behavior.vocabularyVersion !== vocabulary.version) {
+        throw new Error("Behavior assertion uses the wrong vocabulary version.");
+    }
+    const category = vocabulary.categories.find(({ id }) => id === assertion.behavior.categoryId);
+    if (category === undefined || !category.dimensions.some(({ id }) => id === assertion.behavior.dimensionId)) {
+        throw new Error("Behavior assertion does not identify one declared behavior dimension.");
+    }
+    const eventIds = new Set();
+    const events = new Map(dataset.events.map((event) => [event.id, event]));
+    const records = new Map(dataset.nativeRecords.map((record) => [referenceKey(record.reference), record]));
+    const resolved = [];
+    for (const citation of assertion.judgment.citations) {
+        if (eventIds.has(citation.eventId))
+            throw new Error(`Behavior assertion cites event "${citation.eventId}" more than once.`);
+        eventIds.add(citation.eventId);
+        const event = events.get(citation.eventId);
+        if (event === undefined)
+            throw new Error(`Behavior assertion cites unknown normalized event "${citation.eventId}".`);
+        if (referenceKey(citation.nativeReference) !== referenceKey(event.source.nativeReference)) {
+            throw new Error(`Behavior assertion citation for event "${citation.eventId}" does not match its native source.`);
+        }
+        const nativeRecord = records.get(referenceKey(citation.nativeReference));
+        if (nativeRecord === undefined) {
+            throw new Error(`Behavior assertion citation for event "${citation.eventId}" has no captured native record.`);
+        }
+        const resolution = await resolver.resolve(citation.nativeReference);
+        if (typeof resolution !== "object" || resolution.runId !== dataset.runId
+            || resolution.attemptId !== dataset.attemptId || resolution.digest !== nativeRecord.digest) {
+            throw new Error(`Behavior assertion citation for event "${citation.eventId}" is stale or belongs to another attempt.`);
+        }
+        resolved.push({ ...structuredClone(citation), resolution });
+    }
+    return resolved;
+}
+export function validateBehaviorReview(assertion, review) {
+    assertValid("behavior assertion", assertion);
+    assertValid("behavior review", review);
+    if (review.assertion.id !== assertion.id || review.assertion.schemaVersion !== assertion.schemaVersion
+        || review.assertion.digest !== digest(assertion)) {
+        throw new Error("Behavior review assertion identity or digest does not match.");
+    }
+}
+export async function isConfirmedBehaviorAssertion(assertion, dataset, resolver, review, vocabulary = DEFAULT_BEHAVIOR_VOCABULARY) {
+    await validateBehaviorAssertion(assertion, dataset, resolver, vocabulary);
+    if (review === undefined)
+        return false;
+    validateBehaviorReview(assertion, review);
+    return assertion.judgment.disposition === "assessed" && review.state === "confirmed";
+}
+export async function validateAgentSdkBehaviorAssertion(bundleRoot, assertion, review) {
+    const { dataset, resolver } = await createAgentSdkBehaviorEvidence(bundleRoot);
+    const citations = await validateBehaviorAssertion(assertion, dataset, resolver);
+    if (review !== undefined)
+        validateBehaviorReview(assertion, review);
+    return citations;
+}
+export async function createAgentSdkBehaviorEvidence(bundleRoot) {
+    const capture = await readQualifiedClaudeAgentSdkCapture(bundleRoot);
+    const normalization = await claudeAgentSdkNormalizationAdapter.normalize(capture);
+    const dataset = describeNormalizedDataset({
+        capture,
+        normalization,
+        capabilityProfile: normalization.capabilityProfile,
+        adapterVersion: CLAUDE_AGENT_SDK_NORMALIZATION_ADAPTER_VERSION,
+        nativeType: agentSdkNativeType,
+        contentDigest: (reference) => agentSdkContentDigest(capture, reference),
+    });
+    const resolver = createAgentSdkNativeEvidenceResolver(capture);
+    const coverage = await validateNormalizedDataset(dataset, resolver);
+    return { capture, dataset, resolver, coverage };
+}
+export async function validateRetainedBehaviorAssertion(bundleRoot, assertion, review) {
+    const { dataset, resolver } = await createRetainedBehaviorEvidence(bundleRoot);
+    const citations = await validateBehaviorAssertion(assertion, dataset, resolver);
+    if (review !== undefined)
+        validateBehaviorReview(assertion, review);
+    return citations;
+}
+function assertVocabulary(vocabulary) {
+    assertValid("behavior vocabulary", vocabulary);
+    const categoryIds = vocabulary.categories.map(({ id }) => id);
+    if (new Set(categoryIds).size !== categoryIds.length)
+        throw new Error("Behavior vocabulary category IDs must be unique.");
+    for (const category of vocabulary.categories) {
+        const dimensionIds = category.dimensions.map(({ id }) => id);
+        if (new Set(dimensionIds).size !== dimensionIds.length) {
+            throw new Error(`Behavior vocabulary dimension IDs in category "${category.id}" must be unique.`);
+        }
+    }
+}
+function loadDefaultVocabulary() {
+    const vocabulary = JSON.parse(readFileSync(new URL("../../ontology/behavior-categories.v1.json", import.meta.url), "utf8"));
+    assertVocabulary(vocabulary);
+    return vocabulary;
+}
+function digest(value) {
+    return `sha256:${digestMetadata(value).value}`;
+}
+function referenceKey(reference) {
+    return canonicalizeMetadata(reference);
+}
+function assertValid(label, value) {
+    const errors = validateArtifact(label, value);
+    if (errors.length > 0)
+        throw new Error(errors.map(({ field, message }) => `${label} ${field}: ${message}`).join("\n"));
+}
+function agentSdkNativeType(record) {
+    const document = asRecord(record.document);
+    if (record.kind === "session")
+        return text(document?.nativeType) ?? "session";
+    if (record.kind === "hook")
+        return text(document?.hook) ?? "hook";
+    return {
+        telemetry: "agent-sdk-telemetry",
+        workspace: "workspace-outcome",
+        verifier: "verifier-result",
+        "assessment-mode": "assessment-mode",
+        manifest: "terminal-record",
+    }[record.kind] ?? record.kind;
+}
+function agentSdkContentDigest(capture, reference) {
+    for (const { record } of capture.records) {
+        if (record.kind !== "workspace" && record.kind !== "diagnostic")
+            continue;
+        const descriptor = asRecord(record.document);
+        if (descriptor?.id === reference.artifactId && typeof descriptor.digest === "string"
+            && /^sha256:[a-f0-9]{64}$/u.test(descriptor.digest))
+            return descriptor.digest;
+    }
+    return undefined;
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : undefined;
+}
+function text(value) {
+    return typeof value === "string" && value !== "" ? value : undefined;
+}

package/dist/src/cli.d.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { type SemanticJudgeBackend } from "./semantic-judge.js";
+export declare function main(args?: string[], write?: (message: string) => void, dependencies?: {
+    semanticJudgeBackend?: SemanticJudgeBackend;
+}): number | Promise<number>;