engineering-behavior-observatory 0.2.1

package/dist/src/structural-observations.d.ts

@@ -0,0 +1,124 @@
+import { type AgentSdkNativeRecord } from "./agent-sdk-normalizer.js";
+import { type AdapterCoverageReport, type NormalizedDataset } from "./normalization-integrity.js";
+import type { NativeEvidenceReference, NativeEvidenceResolver, NormalizationInput, UniformEventFamily } from "./uniform-events.js";
+export declare const STRUCTURAL_EXTRACTOR_VERSION = "1.0.0";
+export { CLAUDE_AGENT_SDK_NORMALIZATION_ADAPTER_VERSION } from "./agent-sdk-normalizer.js";
+type RequiredCapability = `family:${UniformEventFamily}` | "evidence:nativeOrder";
+type KnownValue = {
+    status: "known";
+    value: string | number | boolean;
+    unit: string;
+};
+type UnavailableValue = {
+    status: "unavailable";
+    reason: string;
+};
+export type StructuralObservation = {
+    schemaVersion: "ebo.structural-observation/v1";
+    id: string;
+    runId: string;
+    attemptId: string;
+    extractor: {
+        id: string;
+        version: typeof STRUCTURAL_EXTRACTOR_VERSION;
+        requiredCapabilities: readonly RequiredCapability[];
+    };
+    definition: string;
+    denominator: {
+        scope: "attempt";
+        id: string;
+        value: 1;
+        unit: "attempt";
+    };
+    value: KnownValue | UnavailableValue;
+    sourceEventIds: readonly string[];
+    sourceRecordCount: number;
+    citations: readonly NativeEvidenceReference[];
+};
+export type StructuralObservationSet = {
+    schemaVersion: "ebo.structural-observation-set/v1";
+    runId: string;
+    attemptId: string;
+    assessmentMode: "observational" | "verified" | "unknown";
+    extractorVersion: typeof STRUCTURAL_EXTRACTOR_VERSION;
+    normalization: {
+        datasetDigest: `sha256:${string}`;
+        adapter: NormalizedDataset["adapter"];
+        capabilityProfile?: NormalizedDataset["capabilityProfile"];
+        coverage: AdapterCoverageReport;
+    };
+    observations: readonly StructuralObservation[];
+};
+export declare const STRUCTURAL_EXTRACTOR_REGISTRY: readonly [{
+    readonly id: "model-request-count";
+    readonly requiredCapabilities: readonly RequiredCapability[];
+    readonly definition: string;
+}, {
+    readonly id: "tool-operation-count";
+    readonly requiredCapabilities: readonly RequiredCapability[];
+    readonly definition: string;
+}, {
+    readonly id: "tool-native-record-count";
+    readonly requiredCapabilities: readonly RequiredCapability[];
+    readonly definition: string;
+}, {
+    readonly id: "unidentified-tool-native-record-count";
+    readonly requiredCapabilities: readonly RequiredCapability[];
+    readonly definition: string;
+}, {
+    readonly id: "tool-error-count";
+    readonly requiredCapabilities: readonly RequiredCapability[];
+    readonly definition: string;
+}, {
+    readonly id: "repeated-tool-operation-count";
+    readonly requiredCapabilities: readonly RequiredCapability[];
+    readonly definition: string;
+}, {
+    readonly id: "failure-followed-by-same-tool-count";
+    readonly requiredCapabilities: readonly RequiredCapability[];
+    readonly definition: string;
+}, {
+    readonly id: "failure-followed-by-alternate-tool-count";
+    readonly requiredCapabilities: readonly RequiredCapability[];
+    readonly definition: string;
+}, {
+    readonly id: "validation-after-last-mutation";
+    readonly requiredCapabilities: readonly RequiredCapability[];
+    readonly definition: string;
+}, {
+    readonly id: "compaction-boundary-record-count";
+    readonly requiredCapabilities: readonly RequiredCapability[];
+    readonly definition: string;
+}, {
+    readonly id: "input-token-count";
+    readonly requiredCapabilities: readonly RequiredCapability[];
+    readonly definition: string;
+}, {
+    readonly id: "output-token-count";
+    readonly requiredCapabilities: readonly RequiredCapability[];
+    readonly definition: string;
+}, {
+    readonly id: "cache-read-input-token-count";
+    readonly requiredCapabilities: readonly RequiredCapability[];
+    readonly definition: string;
+}, {
+    readonly id: "cache-creation-input-token-count";
+    readonly requiredCapabilities: readonly RequiredCapability[];
+    readonly definition: string;
+}, {
+    readonly id: "total-token-count";
+    readonly requiredCapabilities: readonly RequiredCapability[];
+    readonly definition: string;
+}, {
+    readonly id: "total-cost-usd";
+    readonly requiredCapabilities: readonly RequiredCapability[];
+    readonly definition: string;
+}, {
+    readonly id: "attempt-latency-ms";
+    readonly requiredCapabilities: readonly RequiredCapability[];
+    readonly definition: string;
+}];
+export declare function createAgentSdkStructuralObservationSet(bundleRoot: string): Promise<StructuralObservationSet>;
+export declare function createRetainedStructuralObservationSet(bundleRoot: string): Promise<StructuralObservationSet>;
+export declare function createStructuralObservationSet(dataset: NormalizedDataset, coverage: AdapterCoverageReport, nativeCapture?: NormalizationInput<AgentSdkNativeRecord>): StructuralObservationSet;
+export declare function validateStructuralObservationSet(report: StructuralObservationSet, resolver: NativeEvidenceResolver): Promise<void>;