engineering-behavior-observatory 0.2.1

package/dist/src/uniform-events.d.ts

@@ -0,0 +1,120 @@
+export declare const UNIFORM_EVENT_FAMILIES: readonly ["message", "model-request", "tool", "context", "permission", "delegation", "artifact", "validation", "runtime", "outcome"];
+export type UniformEventFamily = typeof UNIFORM_EVENT_FAMILIES[number];
+export type EvidenceUnavailable = {
+    status: "unknown" | "unsupported";
+    reason: string;
+};
+export type EvidenceValue<Value> = {
+    status: "known";
+    value: Value;
+} | EvidenceUnavailable;
+export type NativeOrderEvidence = {
+    status: "known";
+    value: number;
+    domain: string;
+} | EvidenceUnavailable;
+export type NativeEvidenceReference = {
+    artifactId: string;
+    recordLocator: string;
+};
+export type ContentReference = {
+    nativeReference: NativeEvidenceReference;
+    mediaType?: string;
+    role?: string;
+};
+export type UniformAttributeScalar = string | number | boolean | null;
+export type UniformAttributeValue = UniformAttributeScalar | readonly UniformAttributeScalar[];
+export type UniformEvent = {
+    schemaVersion: "ebo.uniform-event/v1";
+    id: string;
+    runId: string;
+    attemptId: string;
+    source: {
+        harness: string;
+        nativeType: string;
+        nativeReference: NativeEvidenceReference;
+    };
+    nativeOrder: NativeOrderEvidence;
+    nativeTime: EvidenceValue<string>;
+    actor: {
+        kind: "user" | "agent" | "model" | "tool" | "harness" | "operator" | "system";
+        id?: string;
+    };
+    family: UniformEventFamily;
+    phase: "before" | "during" | "after" | "instant";
+    scope: {
+        kind: "run" | "attempt" | "session" | "turn" | "operation" | "workspace" | "artifact";
+        id?: string;
+    };
+    relations: {
+        parent: EvidenceValue<string>;
+        known: ReadonlyArray<{
+            kind: "child" | "caused-by" | "correlates-with";
+            eventId: string;
+        }>;
+    };
+    attributes: Readonly<Record<string, UniformAttributeValue>>;
+    content: EvidenceValue<readonly ContentReference[]>;
+};
+export type AdapterCapability = {
+    status: "available" | "partial" | "unsupported";
+    detail?: string;
+};
+export type AdapterCapabilityProfile = {
+    schemaVersion: "ebo.adapter-capability-profile/v1";
+    adapterId: string;
+    harness: string;
+    nativeTypes: readonly string[];
+    families: Record<UniformEventFamily, AdapterCapability>;
+    evidence: Record<"nativeOrder" | "nativeTime" | "parentage" | "content", AdapterCapability>;
+};
+export type CapturedNativeRecord<NativeRecord> = {
+    reference: NativeEvidenceReference;
+    record: NativeRecord;
+};
+export interface NativeCaptureAdapter<Request, NativeRecord> {
+    readonly id: string;
+    readonly harness: string;
+    capture(request: Request): Promise<QualifiedNativeCapture<NativeRecord>>;
+}
+export type QualifiedNativeCapture<NativeRecord> = {
+    runId: string;
+    attemptId: string;
+    qualification: "qualified" | "qualified-with-gaps";
+    records: readonly CapturedNativeRecord<NativeRecord>[];
+};
+export type NormalizationInput<NativeRecord> = QualifiedNativeCapture<NativeRecord>;
+export type UnmappedNativeRecord = {
+    reference: NativeEvidenceReference;
+    reason: string;
+};
+export type NormalizationResult = {
+    events: readonly UniformEvent[];
+    unmapped: readonly UnmappedNativeRecord[];
+};
+export interface UniformEventNormalizationAdapter<NativeRecord> {
+    readonly id: string;
+    readonly harness: string;
+    readonly capabilityProfile: AdapterCapabilityProfile;
+    normalize(input: NormalizationInput<NativeRecord>): Promise<NormalizationResult>;
+}
+export type HarnessAdapter<Request = unknown, NativeRecord = unknown> = {
+    capture: NativeCaptureAdapter<Request, NativeRecord>;
+    normalization: UniformEventNormalizationAdapter<NativeRecord>;
+};
+export interface NativeEvidenceResolver {
+    resolve(reference: NativeEvidenceReference): boolean | NativeEvidenceResolution | Promise<boolean | NativeEvidenceResolution>;
+}
+export type NativeEvidenceResolution = {
+    runId: string;
+    attemptId: string;
+    digest: `sha256:${string}`;
+};
+export declare class AdapterRegistry {
+    #private;
+    constructor(adapters: readonly HarnessAdapter[]);
+    get(harness: string): HarnessAdapter | undefined;
+    list(): readonly HarnessAdapter[];
+}
+export declare function validateUniformEvents(events: readonly UniformEvent[], resolver: NativeEvidenceResolver): Promise<void>;
+export declare function assertAdapterContract<Request, NativeRecord>(adapter: HarnessAdapter<Request, NativeRecord>, request: Request, resolver: NativeEvidenceResolver): Promise<NormalizationResult>;

package/dist/src/uniform-events.js

@@ -0,0 +1,158 @@
+import { validateArtifact } from "./artifacts.js";
+export const UNIFORM_EVENT_FAMILIES = [
+    "message",
+    "model-request",
+    "tool",
+    "context",
+    "permission",
+    "delegation",
+    "artifact",
+    "validation",
+    "runtime",
+    "outcome",
+];
+export class AdapterRegistry {
+    #adapters;
+    constructor(adapters) {
+        const entries = adapters.map((adapter) => {
+            assertAdapterIdentity(adapter);
+            return [adapter.capture.harness, adapter];
+        });
+        if (new Set(entries.map(([harness]) => harness)).size !== entries.length) {
+            throw new Error("Adapter registry contains duplicate harnesses.");
+        }
+        this.#adapters = new Map(entries);
+    }
+    get(harness) {
+        return this.#adapters.get(harness);
+    }
+    list() {
+        return [...this.#adapters.values()];
+    }
+}
+export async function validateUniformEvents(events, resolver) {
+    const ids = new Set();
+    for (const event of events) {
+        assertValidArtifact(`uniform event ${event.id}`, event);
+        if (ids.has(event.id))
+            throw new Error(`Duplicate uniform event ID "${event.id}".`);
+        ids.add(event.id);
+    }
+    for (const event of events) {
+        await assertResolvable(event.source.nativeReference, resolver);
+        if (event.content.status === "known") {
+            for (const content of event.content.value)
+                await assertResolvable(content.nativeReference, resolver);
+        }
+        const relationTargets = [
+            ...(event.relations.parent.status === "known" ? [event.relations.parent.value] : []),
+            ...event.relations.known.map(({ eventId }) => eventId),
+        ];
+        if (relationTargets.some((eventId) => !ids.has(eventId))) {
+            throw new Error(`Uniform event "${event.id}" has an unresolved event relation.`);
+        }
+    }
+    const parentById = new Map(events.flatMap((event) => event.relations.parent.status === "known"
+        ? [[event.id, event.relations.parent.value]]
+        : []));
+    const resolved = new Set();
+    for (const event of events) {
+        if (resolved.has(event.id))
+            continue;
+        const ancestry = new Set();
+        const path = [];
+        let current = event.id;
+        while (current !== undefined && !resolved.has(current)) {
+            if (ancestry.has(current))
+                throw new Error(`Uniform event "${event.id}" has cyclic parentage.`);
+            ancestry.add(current);
+            path.push(current);
+            current = parentById.get(current);
+        }
+        for (const eventId of path)
+            resolved.add(eventId);
+    }
+}
+export async function assertAdapterContract(adapter, request, resolver) {
+    assertAdapterIdentity(adapter);
+    assertValidArtifact(`adapter capability profile ${adapter.normalization.id}`, adapter.normalization.capabilityProfile);
+    const capture = await adapter.capture.capture(request);
+    if (!["qualified", "qualified-with-gaps"].includes(capture.qualification)) {
+        throw new Error("Uniform event normalization requires capture-qualified evidence.");
+    }
+    const result = await adapter.normalization.normalize(capture);
+    await validateUniformEvents(result.events, resolver);
+    for (const { reference } of capture.records)
+        await assertResolvable(reference, resolver);
+    for (const event of result.events) {
+        if (event.runId !== capture.runId || event.attemptId !== capture.attemptId) {
+            throw new Error("Normalized event identity does not match the qualified attempt.");
+        }
+        if (event.source.harness !== adapter.normalization.harness) {
+            throw new Error("Normalized event source does not match its adapter harness.");
+        }
+        if (!adapter.normalization.capabilityProfile.nativeTypes.includes(event.source.nativeType)) {
+            throw new Error(`Adapter emitted undeclared native type "${event.source.nativeType}".`);
+        }
+        if (adapter.normalization.capabilityProfile.families[event.family].status === "unsupported") {
+            throw new Error(`Adapter mapped unsupported event family "${event.family}".`);
+        }
+        const capabilities = adapter.normalization.capabilityProfile.evidence;
+        assertEvidenceCapability(capabilities.nativeOrder, event.nativeOrder.status, "nativeOrder");
+        assertEvidenceCapability(capabilities.nativeTime, event.nativeTime.status, "nativeTime");
+        assertEvidenceCapability(capabilities.content, event.content.status, "content");
+        assertEvidenceCapability(capabilities.parentage, event.relations.parent.status, "parentage");
+        if (capabilities.parentage.status === "unsupported" && event.relations.known.length > 0) {
+            throw new Error("Adapter evidence capability contradicts event parentage.");
+        }
+    }
+    const capturedKeys = capture.records.map(({ reference }) => referenceKey(reference));
+    if (new Set(capturedKeys).size !== capturedKeys.length) {
+        throw new Error("Capture adapter returned duplicate native references.");
+    }
+    const captured = new Set(capturedKeys);
+    const mapped = new Set(result.events.map(({ source }) => referenceKey(source.nativeReference)));
+    const unmapped = result.unmapped.map(({ reference }) => referenceKey(reference));
+    if (new Set(unmapped).size !== unmapped.length)
+        throw new Error("Normalizer returned a native record as unmapped more than once.");
+    const unmappedSet = new Set(unmapped);
+    for (const reference of new Set([...mapped, ...unmappedSet])) {
+        if (!captured.has(reference))
+            throw new Error("Normalizer returned a native reference that was not captured.");
+    }
+    for (const reference of captured) {
+        if (mapped.has(reference) === unmappedSet.has(reference)) {
+            throw new Error("Every captured native record must be mapped or explicitly retained as unmapped.");
+        }
+    }
+    return result;
+}
+function assertAdapterIdentity(adapter) {
+    if (adapter.capture.id !== adapter.normalization.id || adapter.capture.harness !== adapter.normalization.harness) {
+        throw new Error("Capture and normalization adapters must have matching identities.");
+    }
+    const profile = adapter.normalization.capabilityProfile;
+    if (profile.adapterId !== adapter.normalization.id || profile.harness !== adapter.normalization.harness) {
+        throw new Error("Adapter capability profile does not match its adapter identity.");
+    }
+}
+function assertEvidenceCapability(capability, evidenceStatus, field) {
+    if ((capability.status === "unsupported") !== (evidenceStatus === "unsupported")
+        && capability.status !== "partial") {
+        throw new Error(`Adapter evidence capability contradicts event ${field}.`);
+    }
+}
+function assertValidArtifact(artifact, document) {
+    const errors = validateArtifact(artifact, document);
+    if (errors.length > 0) {
+        throw new Error(errors.map(({ field, message }) => `${artifact} ${field}: ${message}`).join("\n"));
+    }
+}
+async function assertResolvable(reference, resolver) {
+    if (!await resolver.resolve(reference)) {
+        throw new Error(`Native evidence reference ${reference.artifactId}:${reference.recordLocator} is unresolved.`);
+    }
+}
+function referenceKey(reference) {
+    return JSON.stringify([reference.artifactId, reference.recordLocator]);
+}

package/dist/src/verifiers.d.ts

@@ -0,0 +1,116 @@
+import { type ArtifactReference } from "./contracts.js";
+export type VerifierAssertionStatus = "passed" | "failed" | "not-run";
+export type VerifierAssertion = {
+    id: string;
+    status: VerifierAssertionStatus;
+};
+export type VerifierPassedAssertion = Omit<VerifierAssertion, "status"> & {
+    status: "passed";
+};
+export type VerifierNotRunAssertion = Omit<VerifierAssertion, "status"> & {
+    status: "not-run";
+};
+export type VerifierWorkspace = {
+    artifactId: string;
+    digest: string;
+    fingerprint?: string;
+};
+export type DiagnosticOrigin = {
+    stream: "stdout" | "stderr";
+    locator: string;
+    digest: string;
+    sizeBytes: number;
+    truncated: boolean;
+};
+export type DiagnosticReference = DiagnosticOrigin & {
+    source?: DiagnosticOrigin;
+};
+export type VerifierExecutionReference = {
+    locator: string;
+    digest: string;
+    format?: "commonjs" | "module";
+};
+type VerifierResultBase = {
+    schemaVersion: "verifier-result/v1";
+    bundleId: string;
+    durationMs?: number;
+    error?: string;
+    errorRedacted?: boolean;
+    verifier?: VerifierExecutionReference;
+    assertions: VerifierAssertion[];
+    diagnostics?: DiagnosticReference[];
+};
+export type VerifierPassedResult = Omit<VerifierResultBase, "error" | "assertions"> & {
+    status: "passed";
+    error?: never;
+    errorRedacted?: never;
+    exitCode?: 0;
+    workspace: VerifierWorkspace;
+    assertions: VerifierPassedAssertion[];
+};
+export type VerifierFailedResult = Omit<VerifierResultBase, "error"> & {
+    status: "failed";
+    error?: never;
+    errorRedacted?: never;
+    exitCode: number;
+    workspace: VerifierWorkspace;
+};
+export type VerifierRunResult = VerifierPassedResult | VerifierFailedResult | VerifierErrorResult;
+export type VerifierErrorResult = VerifierResultBase & {
+    status: "error";
+    error: string;
+    exitCode?: number;
+    workspace?: VerifierWorkspace;
+};
+export type VerifierNotRunResult = Omit<VerifierResultBase, "durationMs" | "diagnostics" | "assertions" | "errorRedacted"> & {
+    status: "not-run";
+    durationMs?: never;
+    diagnostics?: never;
+    workspace?: never;
+    exitCode?: never;
+    errorRedacted?: never;
+    assertions: VerifierNotRunAssertion[];
+};
+export type VerifierResult = VerifierRunResult | VerifierNotRunResult;
+type CompleteResultFields = {
+    durationMs: number;
+    diagnostics: DiagnosticReference[];
+};
+export type CompleteVerifierResult = (VerifierPassedResult & CompleteResultFields) | (VerifierFailedResult & CompleteResultFields) | (VerifierErrorResult & CompleteResultFields & {
+    workspace: VerifierWorkspace;
+});
+export type ExecuteVerifierOptions = {
+    bundleId: string;
+    verifierRoot: string;
+    verifier: ArtifactReference;
+    workspacePath: string;
+    workspaceFingerprint: string;
+    workspace: VerifierWorkspace & {
+        fingerprint: string;
+    };
+    artifactRoot: string;
+    command?: string;
+    args?: readonly string[];
+    moduleFormat?: "commonjs" | "module";
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+    diagnosticDirectory?: string;
+    signal?: AbortSignal;
+};
+export declare function digestWorkspace(workspacePath: string, signal?: AbortSignal): Promise<string>;
+export declare function digestWorkspaceTree(workspacePath: string, signal?: AbortSignal): Promise<string>;
+/**
+ * Execute a digest-pinned verifier in a private staging directory.
+ *
+ * The verifier receives the staged implementation path followed by the
+ * evaluated workspace path. Its stdout is the assertion JSON protocol; stderr
+ * is retained as bounded diagnostic evidence.
+ */
+export declare function executeVerifier(options: ExecuteVerifierOptions): Promise<CompleteVerifierResult>;
+export declare function serializeVerifierResult(result: VerifierResult): string;
+export declare function writeVerifierResult(artifactRoot: string, relativePath: string, result: VerifierResult): Promise<{
+    algorithm: "sha256";
+    value: string;
+}>;
+export {};