harnery 0.32.0 → 0.34.0

package/dist/core/events/v3/targets.d.ts

@@ -0,0 +1,23 @@
+import { type FingerprintContextV3 } from "./canonical.js";
+import type { EventPayloadV3 } from "./contract.js";
+export type TargetDescriptorV3 = EventPayloadV3<"tool.requested">["targets"][number];
+export interface ExtractTargetsV3Input {
+    coordRoot: string;
+    toolNamespace: string;
+    toolName: string;
+    toolInput: unknown;
+    fingerprintContext: FingerprintContextV3;
+}
+export interface DescribePathTargetV3Input {
+    coordRoot: string;
+    value: string;
+    access: TargetDescriptorV3["access"];
+    fingerprintContext: FingerprintContextV3;
+    extractorVersion: string;
+}
+/** Describe one known path without exposing values outside the coordination root. */
+export declare function describePathTargetV3(input: DescribePathTargetV3Input): TargetDescriptorV3;
+/** Versioned, tool-specific target extraction. Unknown tools deliberately emit no guessed target. */
+export declare function extractTargetsV3(input: ExtractTargetsV3Input): TargetDescriptorV3[];
+export declare function exactToolInputFingerprintV3(context: FingerprintContextV3, toolNamespace: string, toolName: string, toolInput: unknown): import("./canonical.js").FingerprintV3;
+//# sourceMappingURL=targets.d.ts.map

package/dist/core/events/v3/targets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"targets.d.ts","sourceRoot":"","sources":["../../../../src/core/events/v3/targets.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,oBAAoB,EAAiB,MAAM,gBAAgB,CAAC;AAC1E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,MAAM,MAAM,kBAAkB,GAAG,cAAc,CAAC,gBAAgB,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAErF,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,kBAAkB,EAAE,oBAAoB,CAAC;CAC1C;AAED,MAAM,WAAW,yBAAyB;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IACrC,kBAAkB,EAAE,oBAAoB,CAAC;IACzC,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,qFAAqF;AACrF,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,yBAAyB,GAAG,kBAAkB,CAUzF;AAED,qGAAqG;AACrG,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,kBAAkB,EAAE,CA0DnF;AAED,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,oBAAoB,EAC7B,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,OAAO,0CAOnB"}

package/dist/core/events/v3/targets.js

@@ -0,0 +1,134 @@
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { fingerprintV3 } from "./canonical.js";
+/** Describe one known path without exposing values outside the coordination root. */
+export function describePathTargetV3(input) {
+    return pathTarget({
+        coordRoot: input.coordRoot,
+        fingerprintContext: input.fingerprintContext,
+    }, input.value, input.access, input.extractorVersion);
+}
+/** Versioned, tool-specific target extraction. Unknown tools deliberately emit no guessed target. */
+export function extractTargetsV3(input) {
+    const record = plainRecord(input.toolInput);
+    if (!record)
+        return [];
+    const name = input.toolName.toLowerCase();
+    const descriptors = [];
+    const addPath = (value, access, version) => {
+        if (typeof value !== "string" || value.length === 0)
+            return;
+        descriptors.push(pathTarget(input, value, access, version));
+    };
+    const addOpaque = (kind, value, access, version) => {
+        if (typeof value !== "string" || value.length === 0)
+            return;
+        descriptors.push({
+            kind,
+            access,
+            fingerprint: fingerprintV3(input.fingerprintContext, `semantic-target.${kind}`, value, "root"),
+            extractor_version: version,
+        });
+    };
+    if (["read", "write", "edit", "multiedit", "notebookedit", "notebook_edit"].includes(name)) {
+        const access = name === "read" ? "read" : "write";
+        for (const field of ["file_path", "path", "notebook_path"]) {
+            addPath(record[field], access, "file-tool-v1");
+        }
+        if (Array.isArray(record.paths)) {
+            for (const path of record.paths)
+                addPath(path, access, "file-tool-v1");
+        }
+    }
+    else if (["grep", "search", "rg"].includes(name)) {
+        addPath(record.path, "read", "search-tool-v1");
+        addOpaque("pattern", record.pattern ?? record.query, "read", "search-tool-v1");
+    }
+    else if (["glob", "find"].includes(name)) {
+        addPath(record.path, "read", "glob-tool-v1");
+        addOpaque("pattern", record.pattern ?? record.glob, "read", "glob-tool-v1");
+    }
+    else if (["webfetch", "web_fetch", "fetch", "open"].includes(name)) {
+        addOpaque("url", record.url ?? record.ref_id, "read", "web-tool-v1");
+    }
+    else if (["websearch", "web_search", "search_query"].includes(name)) {
+        addOpaque("query", record.query ?? record.q, "read", "web-search-v1");
+    }
+    else if (["bash", "shell", "exec_command"].includes(name)) {
+        addPath(record.workdir ?? record.cwd, "execute", "command-tool-v1");
+    }
+    else if (["artifact", "view_image", "image"].includes(name)) {
+        addPath(record.path ?? record.file_path, "read", "artifact-tool-v1");
+        addOpaque("artifact", record.artifact_id, "read", "artifact-tool-v1");
+    }
+    else if (["apply_patch", "patch"].includes(name)) {
+        if (typeof record.patch === "string") {
+            for (const path of extractPatchPaths(record.patch))
+                addPath(path, "write", "patch-tool-v1");
+        }
+    }
+    return deduplicateTargets(descriptors);
+}
+export function exactToolInputFingerprintV3(context, toolNamespace, toolName, toolInput) {
+    return fingerprintV3(context, "exact-input", {
+        tool_namespace: toolNamespace,
+        tool_name: toolName,
+        input: toolInput,
+    });
+}
+function pathTarget(input, value, access, version) {
+    const root = resolve(input.coordRoot);
+    const valueUsesWindowsRoot = /^(?:[a-zA-Z]:[\\/]|\\\\)/.test(value);
+    const coordRootUsesWindowsRoot = /^(?:[a-zA-Z]:[\\/]|\\\\)/.test(input.coordRoot);
+    const valueUsesPosixRoot = value.startsWith("/");
+    const foreignAbsolute = (valueUsesWindowsRoot && !coordRootUsesWindowsRoot) ||
+        (valueUsesPosixRoot && coordRootUsesWindowsRoot);
+    const resolved = resolve(root, value);
+    const relativePath = relative(root, resolved);
+    const contained = !foreignAbsolute &&
+        relativePath !== ".." &&
+        !relativePath.startsWith(`..${sep}`) &&
+        !isAbsolute(relativePath);
+    if (contained) {
+        const portable = relativePath.length === 0 ? "." : relativePath.split(sep).join("/");
+        return {
+            kind: "workspace_path",
+            access,
+            display: portable,
+            fingerprint: fingerprintV3(input.fingerprintContext, "semantic-target.workspace-path", portable, "root"),
+            extractor_version: version,
+        };
+    }
+    return {
+        kind: "external_path",
+        access,
+        fingerprint: fingerprintV3(input.fingerprintContext, "semantic-target.external-path", value.normalize("NFC").replaceAll("\\", "/"), "root"),
+        extractor_version: version,
+    };
+}
+function extractPatchPaths(patch) {
+    const paths = [];
+    for (const line of patch.split("\n")) {
+        const match = line.match(/^\*\*\* (?:Add|Update|Delete) File: (.+)$/);
+        if (match?.[1])
+            paths.push(match[1]);
+    }
+    return paths;
+}
+function deduplicateTargets(targets) {
+    const seen = new Set();
+    return targets.filter((target) => {
+        const key = `${target.kind}\0${target.access}\0${target.fingerprint.digest}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+function plainRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        return undefined;
+    return value;
+}

package/dist/core/events/v3/turn-telemetry.d.ts

@@ -0,0 +1,41 @@
+import type { Adapter } from "../../adapter.js";
+import { type AdapterSignalV3, type CapabilitySupportV3 } from "./capabilities.js";
+import type { TurnHarnessV3, TurnInferenceV3, TurnUsageV3 } from "./contract.js";
+export type TelemetryObservationV3<T> = {
+    state: "observed";
+    value: T;
+    attestation: "native" | "derived";
+    confidence: "exact" | "high";
+} | {
+    state: "unsupported";
+    capability: string;
+} | {
+    state: "expected_but_missing";
+    capability: string;
+    reason: string;
+};
+export interface ContextMeasurementV3 {
+    used_tokens: number;
+    limit_tokens: number;
+    remaining_tokens?: number;
+    measured_at: string;
+    method: string;
+}
+export interface TurnTelemetryV3 {
+    usage: TelemetryObservationV3<TurnUsageV3>;
+    inference: TelemetryObservationV3<TurnInferenceV3>;
+    context: TelemetryObservationV3<ContextMeasurementV3>;
+}
+export type TurnTelemetryCapabilitySupportV3 = Partial<Pick<Record<AdapterSignalV3, CapabilitySupportV3>, "model_usage" | "inference_timing" | "context_usage">>;
+export interface HarnessTimingAccumulatorV3 {
+    hook_time_ms: number;
+    hook_count: number;
+    slowest_hook?: string;
+    slowest_hook_ms: number;
+}
+/** Extract only telemetry explicitly reported by a hook/status payload. */
+export declare function extractTurnTelemetryV3(adapter: Adapter, payload: Record<string, unknown>, observedAt?: string, support?: TurnTelemetryCapabilitySupportV3): TurnTelemetryV3;
+export declare function emptyHarnessTimingV3(): HarnessTimingAccumulatorV3;
+export declare function recordHarnessTimingV3(accumulator: HarnessTimingAccumulatorV3, hook: string, durationMs: number): HarnessTimingAccumulatorV3;
+export declare function harnessObservationV3(accumulator: HarnessTimingAccumulatorV3): TelemetryObservationV3<TurnHarnessV3>;
+//# sourceMappingURL=turn-telemetry.d.ts.map

package/dist/core/events/v3/turn-telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-telemetry.d.ts","sourceRoot":"","sources":["../../../../src/core/events/v3/turn-telemetry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EACL,KAAK,eAAe,EAEpB,KAAK,mBAAmB,EACzB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjF,MAAM,MAAM,sBAAsB,CAAC,CAAC,IAChC;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,CAAC,CAAC;IAAC,WAAW,EAAE,QAAQ,GAAG,SAAS,CAAC;IAAC,UAAU,EAAE,OAAO,GAAG,MAAM,CAAA;CAAE,GAChG;IAAE,KAAK,EAAE,aAAa,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAC5C;IAAE,KAAK,EAAE,sBAAsB,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1E,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,sBAAsB,CAAC,WAAW,CAAC,CAAC;IAC3C,SAAS,EAAE,sBAAsB,CAAC,eAAe,CAAC,CAAC;IACnD,OAAO,EAAE,sBAAsB,CAAC,oBAAoB,CAAC,CAAC;CACvD;AAED,MAAM,MAAM,gCAAgC,GAAG,OAAO,CACpD,IAAI,CACF,MAAM,CAAC,eAAe,EAAE,mBAAmB,CAAC,EAC5C,aAAa,GAAG,kBAAkB,GAAG,eAAe,CACrD,CACF,CAAC;AAEF,MAAM,WAAW,0BAA0B;IACzC,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,2EAA2E;AAC3E,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,UAAU,SAA2B,EACrC,OAAO,GAAE,gCAAqC,GAC7C,eAAe,CAgFjB;AAwCD,wBAAgB,oBAAoB,IAAI,0BAA0B,CAEjE;AAED,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,0BAA0B,EACvC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,GACjB,0BAA0B,CAU5B;AAED,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,0BAA0B,GACtC,sBAAsB,CAAC,aAAa,CAAC,CAsBvC"}

package/dist/core/events/v3/turn-telemetry.js

@@ -0,0 +1,168 @@
+import { adapterSignalSupportV3, } from "./capabilities.js";
+/** Extract only telemetry explicitly reported by a hook/status payload. */
+export function extractTurnTelemetryV3(adapter, payload, observedAt = new Date().toISOString(), support = {}) {
+    const context = record(payload.context_window) ??
+        record(payload.model_context_window) ??
+        record(payload.context_usage);
+    const usage = record(payload.usage) ??
+        record(payload.token_usage) ??
+        record(context?.current_usage) ??
+        undefined;
+    const input = number(usage?.input_tokens);
+    const output = number(usage?.output_tokens);
+    const cacheRead = number(usage?.cache_read_tokens) ?? number(usage?.cache_read_input_tokens);
+    const cacheWrite = number(usage?.cache_write_tokens) ?? number(usage?.cache_creation_input_tokens);
+    const usageObservation = input !== undefined && output !== undefined
+        ? {
+            state: "observed",
+            value: {
+                input_tokens: input,
+                output_tokens: output,
+                ...(cacheRead !== undefined ? { cache_read_tokens: cacheRead } : {}),
+                ...(cacheWrite !== undefined ? { cache_write_tokens: cacheWrite } : {}),
+                method: `${adapter.replaceAll("-", "_")}_hook`,
+            },
+            attestation: "native",
+            confidence: "exact",
+        }
+        : missing(adapter, "model_usage", support.model_usage);
+    const inferenceMs = number(payload.api_time_ms) ??
+        number(payload.inference_time_ms) ??
+        number(record(payload.timing)?.api_time_ms) ??
+        number(usage?.api_time_ms);
+    const requestCount = number(payload.request_count) ?? number(record(payload.timing)?.request_count) ?? 1;
+    const inferenceObservation = inferenceMs !== undefined
+        ? {
+            state: "observed",
+            value: { api_time_ms: inferenceMs, request_count: requestCount },
+            attestation: "native",
+            confidence: "exact",
+        }
+        : missing(adapter, "inference_timing", support.inference_timing);
+    const usedTokens = number(context?.used_tokens) ??
+        number(context?.input_tokens) ??
+        number(context?.total_tokens) ??
+        number(payload.used_tokens) ??
+        number(payload.total_input_tokens) ??
+        number(usage?.total_tokens) ??
+        number(usage?.prompt_tokens) ??
+        (usage
+            ? sumDefined([
+                number(usage.input_tokens),
+                number(usage.cache_read_input_tokens),
+                number(usage.cache_creation_input_tokens),
+            ])
+            : undefined);
+    const limitTokens = number(context?.context_window_size) ??
+        number(context?.window_tokens) ??
+        number(context?.context_window_tokens) ??
+        number(context?.max_tokens) ??
+        number(payload.context_window_size) ??
+        number(payload.context_window_tokens) ??
+        (typeof payload.context_window === "number" ? number(payload.context_window) : undefined);
+    const contextMeasurement = contextObservation(adapter, usedTokens, limitTokens, observedAt, support.context_usage);
+    return { usage: usageObservation, inference: inferenceObservation, context: contextMeasurement };
+}
+function contextObservation(adapter, usedTokens, limitTokens, observedAt, override) {
+    if (usedTokens !== undefined && limitTokens !== undefined && limitTokens > 0) {
+        return {
+            state: "observed",
+            value: {
+                used_tokens: usedTokens,
+                limit_tokens: limitTokens,
+                remaining_tokens: Math.max(0, limitTokens - usedTokens),
+                measured_at: observedAt,
+                method: `${adapter.replaceAll("-", "_")}_hook`,
+            },
+            attestation: "native",
+            confidence: "exact",
+        };
+    }
+    if (usedTokens !== undefined || limitTokens !== undefined) {
+        return {
+            state: "expected_but_missing",
+            capability: "context_usage",
+            reason: usedTokens === undefined
+                ? "context_used_tokens_not_reported"
+                : limitTokens === undefined
+                    ? "context_limit_tokens_not_reported"
+                    : "context_limit_tokens_invalid",
+        };
+    }
+    return missing(adapter, "context_usage", override);
+}
+export function emptyHarnessTimingV3() {
+    return { hook_time_ms: 0, hook_count: 0, slowest_hook_ms: 0 };
+}
+export function recordHarnessTimingV3(accumulator, hook, durationMs) {
+    const duration = safeInteger(durationMs);
+    if (duration === undefined)
+        return accumulator;
+    const name = safeToken(hook, "unknown_hook");
+    return {
+        hook_time_ms: accumulator.hook_time_ms + duration,
+        hook_count: accumulator.hook_count + 1,
+        slowest_hook: duration >= accumulator.slowest_hook_ms ? name : accumulator.slowest_hook,
+        slowest_hook_ms: Math.max(duration, accumulator.slowest_hook_ms),
+    };
+}
+export function harnessObservationV3(accumulator) {
+    return accumulator.hook_count > 0
+        ? {
+            state: "observed",
+            value: {
+                hook_time_ms: accumulator.hook_time_ms,
+                hook_count: accumulator.hook_count,
+                ...(accumulator.slowest_hook
+                    ? {
+                        slowest_hook: accumulator.slowest_hook,
+                        slowest_hook_ms: accumulator.slowest_hook_ms,
+                    }
+                    : {}),
+            },
+            attestation: "derived",
+            confidence: "high",
+        }
+        : {
+            state: "expected_but_missing",
+            capability: "harness_timing",
+            reason: "no_hook_timing_samples",
+        };
+}
+function missing(adapter, signal, override) {
+    const declared = override ?? adapterSignalSupportV3(adapter, signal);
+    if (declared === "unsupported")
+        return { state: "unsupported", capability: signal };
+    return {
+        state: "expected_but_missing",
+        capability: signal,
+        reason: signal === "model_usage"
+            ? "not_reported"
+            : declared === "conditional"
+                ? "conditional_signal_not_reported"
+                : "promised_signal_not_reported",
+    };
+}
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function number(value) {
+    return typeof value === "number" ? safeInteger(value) : undefined;
+}
+function safeInteger(value) {
+    return Number.isFinite(value) && value >= 0 ? Math.floor(value) : undefined;
+}
+function sumDefined(values) {
+    return values.some((value) => value !== undefined)
+        ? values.reduce((total, value) => total + (value ?? 0), 0)
+        : undefined;
+}
+function safeToken(value, fallback) {
+    const normalized = value
+        .normalize("NFC")
+        .replace(/[^a-zA-Z0-9._:/+-]/g, "_")
+        .slice(0, 128);
+    return /^[a-zA-Z0-9]/.test(normalized) ? normalized : fallback;
+}

package/dist/core/events/v3/validate.d.ts

@@ -0,0 +1,9 @@
+import { type EventV3 } from "./contract.js";
+export interface EventV3ValidationResult {
+    ok: boolean;
+    event?: EventV3;
+    issues: string[];
+}
+export declare function validateEventV3(value: unknown): EventV3ValidationResult;
+export declare function assertEventV3(value: unknown): asserts value is EventV3;
+//# sourceMappingURL=validate.d.ts.map

package/dist/core/events/v3/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../../src/core/events/v3/validate.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,OAAO,EAAiB,MAAM,eAAe,CAAC;AAE5D,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAuCD,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,uBAAuB,CAkBvE;AAkSD,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAKtE"}

package/dist/core/events/v3/validate.js

@@ -0,0 +1,281 @@
+import { Value } from "@sinclair/typebox/value";
+import { canonicalJsonV3 } from "./canonical.js";
+import { EventV3Schema } from "./contract.js";
+export function validateEventV3(value) {
+    if (!Value.Check(EventV3Schema, value)) {
+        return {
+            ok: false,
+            issues: [...Value.Errors(EventV3Schema, value)]
+                .slice(0, 12)
+                .map((error) => `${error.path || "/"}:${error.type}`),
+        };
+    }
+    const event = value;
+    const issues = [
+        ...validateBaseSemantics(event),
+        ...validateSpanSemantics(event),
+        ...validateRecoverySemantics(event),
+    ];
+    return issues.length === 0
+        ? { ok: true, event: value, issues: [] }
+        : { ok: false, issues };
+}
+function validateBaseSemantics(event) {
+    const issues = [];
+    const targets = event.event_type === "tool.requested"
+        ? arrayOfRecords(event.payload.targets)
+        : event.event_type === "coord.claim_changed"
+            ? [record(event.payload.target)]
+            : [];
+    for (const [index, target] of targets.entries()) {
+        if (target.display === undefined)
+            continue;
+        const prefix = event.event_type === "tool.requested" ? `/payload/targets/${index}` : "/payload/target";
+        if (target.kind !== "workspace_path") {
+            issues.push(`${prefix}/display:forbidden_for_target_kind`);
+        }
+        else if (typeof target.display !== "string" || !safeWorkspaceDisplay(target.display)) {
+            issues.push(`${prefix}/display:workspace_path_invalid`);
+        }
+    }
+    if (event.producer.bridge === "codex-wsl" && event.producer.platform !== "linux") {
+        issues.push("/producer/platform:codex-wsl_requires_linux_writer");
+    }
+    if (event.provenance.attribution.state === "verified" &&
+        event.provenance.attribution.method === "unattributed") {
+        issues.push("/provenance/attribution:verified_unattributed");
+    }
+    if (event.event_type === "session.started") {
+        validateAttestationDeclaration(event, issues);
+    }
+    if (event.event_type === "session.attestation_changed") {
+        const declaration = validateAttestationDeclaration(event, issues);
+        if (event.payload.prior_attestation_id === declaration.attestation_id) {
+            issues.push("/payload/prior_attestation_id:must_change");
+        }
+    }
+    if (event.event_type === "turn.completed") {
+        const harnessObservation = record(event.payload.harness);
+        if (harnessObservation.state === "observed") {
+            const harness = record(harnessObservation.value);
+            const slowestHookMs = harness.slowest_hook_ms;
+            if (slowestHookMs !== undefined && typeof harness.slowest_hook !== "string") {
+                issues.push("/payload/harness/value/slowest_hook:required_with_duration");
+            }
+            if (typeof slowestHookMs === "number" &&
+                typeof harness.hook_time_ms === "number" &&
+                slowestHookMs > harness.hook_time_ms) {
+                issues.push("/payload/harness/value/slowest_hook_ms:must_not_exceed_hook_time");
+            }
+        }
+    }
+    if (event.links.caused_by.includes(event.event_id)) {
+        issues.push("/links/caused_by:self_reference");
+    }
+    if (event.links.span_id !== undefined && event.links.span_id === event.links.parent_span_id) {
+        issues.push("/links/parent_span_id:self_reference");
+    }
+    if (event.event_type === "session.termination_observed" &&
+        event.payload.observer_instance_id === event.payload.subject_instance_id) {
+        issues.push("/payload/observer_instance_id:observer_must_differ_from_subject");
+    }
+    if (event.event_type === "progress.observed") {
+        const evidenceIds = Array.isArray(event.payload.evidence_event_ids)
+            ? event.payload.evidence_event_ids
+            : [];
+        if (evidenceIds.includes(event.event_id)) {
+            issues.push("/payload/evidence_event_ids:self_reference");
+        }
+    }
+    if ((event.event_type === "coord.task_changed" ||
+        event.event_type === "coord.lifecycle_changed" ||
+        event.event_type === "coord.identity_attested") &&
+        !record(event.payload.authority).transaction_id) {
+        issues.push("/payload/authority/transaction_id:required_for_authority_transition");
+    }
+    if (event.event_type === "decision.state_changed") {
+        const authority = record(event.payload.authority);
+        if (!authority.transaction_id && !authority.record_id) {
+            issues.push("/payload/authority:durable_reference_required");
+        }
+    }
+    if (event.event_type === "coord.claim_changed" &&
+        event.payload.operation !== "denied" &&
+        !record(event.payload.authority).transaction_id) {
+        issues.push("/payload/authority/transaction_id:required_for_authority_transition");
+    }
+    if (event.event_type === "coord.claim_changed" &&
+        record(event.payload.target).access !== event.payload.access) {
+        issues.push("/payload/target/access:must_match_claim_access");
+    }
+    if (event.event_type === "ledger.activated" &&
+        event.payload.eligible_after_event_id !== event.event_id) {
+        issues.push("/payload/eligible_after_event_id:must_reference_activation_event");
+    }
+    return issues;
+}
+function validateAttestationDeclaration(event, issues) {
+    const declaration = record(event.payload.runtime_attestation);
+    if (declaration.attestation_id !== event.attestation_id) {
+        issues.push("/payload/runtime_attestation/attestation_id:mismatch");
+    }
+    if (declaration.generation_id !== event.scope.generation_id) {
+        issues.push("/payload/runtime_attestation/generation_id:mismatch");
+    }
+    if (declaration.declared_by_event_id !== event.event_id) {
+        issues.push("/payload/runtime_attestation/declared_by_event_id:mismatch");
+    }
+    return declaration;
+}
+function validateSpanSemantics(event) {
+    const span = spanFrom(event.payload.span);
+    if (!span)
+        return [];
+    const issues = [];
+    if (span.span_id === span.parent_span_id) {
+        issues.push("/payload/span/parent_span_id:self_reference");
+    }
+    if (span.open_event_id === event.event_id) {
+        issues.push("/payload/span/open_event_id:self_reference");
+    }
+    if (event.links.span_id !== undefined && event.links.span_id !== span.span_id) {
+        issues.push("/payload/span/span_id:must_match_links");
+    }
+    if (event.links.parent_span_id !== undefined &&
+        event.links.parent_span_id !== span.parent_span_id) {
+        issues.push("/payload/span/parent_span_id:must_match_links");
+    }
+    if (span.open_event_id !== undefined && !event.links.caused_by.includes(span.open_event_id)) {
+        issues.push("/payload/span/open_event_id:must_be_causal_parent");
+    }
+    const duration = observationFrom(event.payload.duration_ms);
+    if (duration && canonicalJsonV3(duration) !== canonicalJsonV3(span.duration_ms)) {
+        issues.push("/payload/duration_ms:must_match_span_duration");
+    }
+    const openedAt = Date.parse(span.opened_at);
+    const completedAt = Date.parse(event.time.observed_at);
+    if (openedAt > completedAt &&
+        (span.duration_ms.state !== "expected_but_missing" ||
+            span.duration_ms.reason !== "clock_regressed")) {
+        issues.push("/payload/span/duration_ms:clock_regression_must_be_missing");
+    }
+    return issues;
+}
+function validateRecoverySemantics(event) {
+    if (event.event_type !== "tool.requested" &&
+        event.event_type !== "tool.completed" &&
+        event.event_type !== "command.completed") {
+        return [];
+    }
+    const issues = [];
+    const recovery = recoveryFrom(event.payload.recovery);
+    if (!recovery) {
+        if (event.event_type !== "command.completed" && event.provenance.attestation === "derived") {
+            issues.push("/payload/recovery:required_for_derived_tool_event");
+        }
+        return issues;
+    }
+    if (event.provenance.attestation !== "derived") {
+        issues.push("/payload/recovery:requires_derived_attestation");
+    }
+    if (recovery.requested_event_id === event.event_id) {
+        issues.push("/payload/recovery/requested_event_id:self_reference");
+    }
+    if (event.event_type === "tool.requested") {
+        if (recovery.reason !== "request_not_observed") {
+            issues.push("/payload/recovery/reason:invalid_for_tool_requested");
+        }
+        if (recovery.requested_event_id !== undefined) {
+            issues.push("/payload/recovery/requested_event_id:forbidden_on_derived_request");
+        }
+        if (recovery.elapsed_upper_bound_ms !== undefined) {
+            issues.push("/payload/recovery/elapsed_upper_bound_ms:forbidden_on_tool_requested");
+        }
+        return issues;
+    }
+    if (event.payload.outcome !== "unknown") {
+        issues.push("/payload/outcome:recovery_requires_unknown_outcome");
+    }
+    const span = spanFrom(event.payload.span);
+    const duration = observationFrom(event.payload.duration_ms);
+    for (const [path, candidate] of [
+        ["/payload/span/duration_ms", span?.duration_ms],
+        ["/payload/duration_ms", duration],
+    ]) {
+        if (!candidate)
+            continue;
+        if (candidate.state !== "unknown") {
+            issues.push(`${path}:recovery_requires_unknown_duration`);
+        }
+        else if (candidate.reason !== recovery.reason) {
+            issues.push(`${path}:recovery_reason_mismatch`);
+        }
+    }
+    const upperBound = recovery.elapsed_upper_bound_ms;
+    if (upperBound?.state === "observed") {
+        if (upperBound.attestation !== "derived" || upperBound.confidence !== "exact") {
+            issues.push("/payload/recovery/elapsed_upper_bound_ms:requires_exact_derived_monotonic_time");
+        }
+    }
+    else if (upperBound &&
+        (upperBound.state !== "unknown" ||
+            (upperBound.reason !== "recovery_clock_mismatch" &&
+                upperBound.reason !== "recovery_monotonic_clock_unavailable" &&
+                upperBound.reason !== "recovery_monotonic_clock_regressed"))) {
+        issues.push("/payload/recovery/elapsed_upper_bound_ms:invalid_clock_proof");
+    }
+    if (event.event_type === "command.completed") {
+        if (recovery.reason !== "command_completion_not_observed") {
+            issues.push("/payload/recovery/reason:invalid_for_command_completed");
+        }
+        if (event.payload.exit_code !== undefined) {
+            issues.push("/payload/exit_code:forbidden_on_recovered_command");
+        }
+        if (recovery.elapsed_upper_bound_ms !== undefined) {
+            issues.push("/payload/recovery/elapsed_upper_bound_ms:forbidden_on_command_completed");
+        }
+        return issues;
+    }
+    if (recovery.reason === "request_not_observed" ||
+        recovery.reason === "command_completion_not_observed") {
+        issues.push("/payload/recovery/reason:invalid_for_tool_completed");
+    }
+    return issues;
+}
+function safeWorkspaceDisplay(value) {
+    return (value === "." ||
+        (!value.startsWith("/") &&
+            !/^[a-zA-Z]:/.test(value) &&
+            !value.includes("\\") &&
+            !value.split("/").includes("..")));
+}
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function arrayOfRecords(value) {
+    return Array.isArray(value) ? value.map(record) : [];
+}
+function observationFrom(value) {
+    const candidate = record(value);
+    return typeof candidate.state === "string"
+        ? candidate
+        : undefined;
+}
+function spanFrom(value) {
+    const candidate = record(value);
+    return typeof candidate.span_id === "string" && observationFrom(candidate.duration_ms)
+        ? candidate
+        : undefined;
+}
+function recoveryFrom(value) {
+    const candidate = record(value);
+    return typeof candidate.reason === "string" ? candidate : undefined;
+}
+export function assertEventV3(value) {
+    const result = validateEventV3(value);
+    if (!result.ok) {
+        throw new Error(`event failed V3 contract validation (${result.issues.join(", ")})`);
+    }
+}