harnery 0.33.0 → 0.34.0

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

@@ -0,0 +1,34 @@
+import { type EventV3ControlState } from "./control.js";
+export interface InitializeEventLedgerV3Input {
+    coordRoot: string;
+    harneryBuild: string;
+    hostBuild: string;
+    configDigest: `sha256:${string}`;
+    approvalRecordId: string;
+    forceNewEpoch?: boolean;
+    resumeCandidate?: boolean;
+    now?: () => Date;
+}
+export interface InitializeEventLedgerV3Result {
+    state: "active";
+    initialized: boolean;
+    archived_epoch?: string;
+    control: Extract<EventV3ControlState, {
+        state: "active";
+    }>;
+}
+/**
+ * Ensure programmatic Harnery entry points have the same universal V3
+ * boundary as `harn init`. Only a genuinely absent control pair is created;
+ * candidate, damaged, or incompatible state still fails closed.
+ */
+export declare function ensureEventLedgerV3(coordRoot: string, approvalRecordId?: string): Extract<EventV3ControlState, {
+    state: "active";
+}>;
+/**
+ * Ensure a root has one current V3 epoch. An incompatible or explicitly
+ * replaced epoch is moved intact to the V3 archive before the new control
+ * pair is published. No historical ledger bytes are rewritten or deleted.
+ */
+export declare function initializeEventLedgerV3(input: InitializeEventLedgerV3Input): InitializeEventLedgerV3Result;
+//# sourceMappingURL=bootstrap.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../../../../src/core/events/v3/bootstrap.ts"],"names":[],"mappings":"AAiBA,OAAO,EAML,KAAK,mBAAmB,EAGzB,MAAM,cAAc,CAAC;AAKtB,MAAM,WAAW,4BAA4B;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,UAAU,MAAM,EAAE,CAAC;IACjC,gBAAgB,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,6BAA6B;IAC5C,KAAK,EAAE,QAAQ,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC,mBAAmB,EAAE;QAAE,KAAK,EAAE,QAAQ,CAAA;KAAE,CAAC,CAAC;CAC5D;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,EACjB,gBAAgB,SAAiC,GAChD,OAAO,CAAC,mBAAmB,EAAE;IAAE,KAAK,EAAE,QAAQ,CAAA;CAAE,CAAC,CAenD;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,4BAA4B,GAClC,6BAA6B,CAkE/B"}

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

@@ -0,0 +1,175 @@
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fsyncParentDirectory } from "../../workflow/durable-record.js";
+import { canonicalJsonV3, sha256V3 } from "./canonical.js";
+import { ADAPTER_CAPABILITY_PROFILES_V3 } from "./capabilities.js";
+import { buildActivationManifestV3, buildCandidateGenesisManifestV3, EVENT_V3_ACTIVATION_MANIFEST, EVENT_V3_GENESIS_MANIFEST, readEventV3ControlState, repairEventV3ControlPair, } from "./control.js";
+import { loadOrCreateFingerprintKeyStoreV3 } from "./fingerprint-keys.js";
+import { EVENT_V3_SCHEMA_DIGEST } from "./generated.js";
+import { liveEventV3BuildId, livePlatformV3 } from "./live-routing.js";
+/**
+ * Ensure programmatic Harnery entry points have the same universal V3
+ * boundary as `harn init`. Only a genuinely absent control pair is created;
+ * candidate, damaged, or incompatible state still fails closed.
+ */
+export function ensureEventLedgerV3(coordRoot, approvalRecordId = "harnery-runtime-v3-universal") {
+    const root = resolve(coordRoot);
+    const current = readEventV3ControlState(root);
+    if (current.state === "active")
+        return current;
+    if (current.state !== "closed") {
+        throw new Error(`event_v3_control_unavailable:${current.state}`);
+    }
+    const configPath = join(root, ".harnery", "config.jsonc");
+    return initializeEventLedgerV3({
+        coordRoot: root,
+        harneryBuild: repositoryBuild(rootOfHarnery()),
+        hostBuild: repositoryBuild(root),
+        configDigest: sha256V3(existsSync(configPath) ? readFileSync(configPath) : Buffer.from("{}\n")),
+        approvalRecordId,
+    }).control;
+}
+/**
+ * Ensure a root has one current V3 epoch. An incompatible or explicitly
+ * replaced epoch is moved intact to the V3 archive before the new control
+ * pair is published. No historical ledger bytes are rewritten or deleted.
+ */
+export function initializeEventLedgerV3(input) {
+    const root = resolve(input.coordRoot);
+    let current = readEventV3ControlState(root);
+    if (input.resumeCandidate && current.state === "repairable") {
+        current = repairEventV3ControlPair(root);
+    }
+    if (!input.forceNewEpoch && current.state === "active") {
+        return { state: "active", initialized: false, control: current };
+    }
+    if (!input.forceNewEpoch && input.resumeCandidate && current.state === "candidate") {
+        return activateCandidateEpoch(root, current.genesis, input.approvalRecordId);
+    }
+    if (!input.forceNewEpoch && current.state === "candidate") {
+        throw new Error("event_v3_candidate_requires_explicit_activation_or_epoch_replacement");
+    }
+    const now = input.now ?? (() => new Date());
+    const createdAt = now().toISOString();
+    const archivedEpoch = archiveCurrentEpoch(root, createdAt);
+    const keys = loadOrCreateFingerprintKeyStoreV3(root, now);
+    const harneryBuild = safeBuild(input.harneryBuild);
+    const hostBuild = safeBuild(input.hostBuild);
+    const producerId = "prd_harnery-init";
+    const bootId = `boot_${createHash("sha256").update(`${root}\0${createdAt}`).digest("hex")}`;
+    const buildId = liveEventV3BuildId(harneryBuild);
+    const rootId = `root_${createHash("sha256").update(root).digest("hex")}`;
+    const instanceId = `inst_init_${createHash("sha256").update(`${root}\0${createdAt}`).digest("hex")}`;
+    const capabilityDigests = Object.values(ADAPTER_CAPABILITY_PROFILES_V3)
+        .map((profile) => sha256V3(canonicalJsonV3(profile)))
+        .sort();
+    const candidate = buildCandidateGenesisManifestV3({
+        profile: {
+            initial_schema_digest: EVENT_V3_SCHEMA_DIGEST,
+            contract_source_digest: EVENT_V3_SCHEMA_DIGEST,
+            harnery_commit: harneryBuild,
+            host_repository_commit: hostBuild,
+            producer_build_ids: [buildId],
+            adapter_capability_profile_digests: capabilityDigests,
+            config_digest: input.configDigest,
+            canonicalizer_version: "harnery-jcs-nfc-v1",
+            fingerprint_version: "hmac-sha256-v1",
+            privacy_key_epoch: keys.active_epoch_id,
+            candidate_created_at: createdAt,
+        },
+        root_id: rootId,
+        instance_id: instanceId,
+        producer: {
+            producer_id: producerId,
+            boot_id: bootId,
+            sequence: 1,
+            build_id: buildId,
+            platform: livePlatformV3(),
+        },
+    });
+    publishControlFile(join(root, EVENT_V3_GENESIS_MANIFEST), candidate);
+    const candidateState = repairEventV3ControlPair(root);
+    if (candidateState.state !== "candidate") {
+        throw new Error(`event_v3_candidate_initialization_failed:${candidateState.state}`);
+    }
+    const activated = activateCandidateEpoch(root, candidate, input.approvalRecordId);
+    return {
+        ...activated,
+        ...(archivedEpoch ? { archived_epoch: archivedEpoch } : {}),
+    };
+}
+function activateCandidateEpoch(root, candidate, approvalRecordId) {
+    const producer = candidate.event.producer;
+    const activation = buildActivationManifestV3({
+        candidate,
+        approval_record_id: approvalRecordId,
+        activation_approved_at: candidate.profile.candidate_created_at,
+        producer: {
+            producer_id: producer.producer_id,
+            boot_id: producer.boot_id,
+            sequence: producer.sequence + 1,
+            build_id: producer.build_id,
+            platform: producer.platform,
+            ...(producer.bridge ? { bridge: producer.bridge } : {}),
+        },
+    });
+    publishControlFile(join(root, EVENT_V3_ACTIVATION_MANIFEST), activation);
+    const active = repairEventV3ControlPair(root);
+    if (active.state !== "active") {
+        throw new Error(`event_v3_activation_failed:${active.state}`);
+    }
+    return { state: "active", initialized: true, control: active };
+}
+function archiveCurrentEpoch(root, createdAt) {
+    const current = join(root, ".harnery", "ledgers", "v3");
+    if (!existsSync(current))
+        return undefined;
+    const archives = join(root, ".harnery", "ledgers", "v3-archives");
+    mkdirSync(archives, { recursive: true, mode: 0o700 });
+    const stamp = createdAt.replace(/[^0-9]/g, "");
+    let target = join(archives, `epoch-${stamp}`);
+    let suffix = 0;
+    while (existsSync(target))
+        target = join(archives, `epoch-${stamp}-${++suffix}`);
+    renameSync(current, target);
+    fsyncParentDirectory(target);
+    return target;
+}
+function publishControlFile(path, value) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const temp = `${path}.tmp.${process.pid}`;
+    const fd = openSync(temp, "wx", 0o600);
+    try {
+        writeFileSync(fd, `${canonicalJsonV3(value)}\n`, "utf8");
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    chmodSync(temp, 0o600);
+    renameSync(temp, path);
+    fsyncParentDirectory(path);
+}
+function safeBuild(value) {
+    const normalized = value.normalize("NFC").trim();
+    if (/^[a-zA-Z0-9._-]{1,120}$/.test(normalized))
+        return normalized;
+    return createHash("sha256")
+        .update(normalized || "unknown")
+        .digest("hex");
+}
+function rootOfHarnery() {
+    return resolve(import.meta.dir, "../../../..");
+}
+function repositoryBuild(root) {
+    const result = spawnSync("git", ["-C", root, "rev-parse", "HEAD"], {
+        encoding: "utf8",
+        timeout: 5000,
+    });
+    const commit = result.status === 0 ? result.stdout.trim() : "";
+    if (/^[0-9a-f]{40,64}$/.test(commit))
+        return commit;
+    return createHash("sha256").update(resolve(root)).digest("hex");
+}

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

@@ -0,0 +1,20 @@
+import type { EventOfTypeV3, EventPayloadV3, EventTypeV3 } from "./contract.js";
+type EventWithoutDiscriminator<T extends EventTypeV3> = Omit<EventOfTypeV3<T>, "attestation_id" | "contract" | "event_id" | "event_type" | "payload" | "time">;
+type RootEventTypeV3 = "ledger.genesis" | "ledger.activated" | "ledger.schema_advanced" | "ledger.comparability_advanced";
+type AttestationInputV3<T extends EventTypeV3> = T extends RootEventTypeV3 ? {
+    attestation_id?: never;
+} : {
+    attestation_id: `att_${string}`;
+};
+export type BuildEventV3Input<T extends EventTypeV3> = EventWithoutDiscriminator<T> & AttestationInputV3<T> & {
+    payload: EventPayloadV3<T>;
+    event_id?: `evt_${string}`;
+    observed_at?: string;
+    recorded_at?: string;
+    monotonic_ns?: string;
+    clock_id?: `clk_${string}`;
+    skew?: "normal" | "regressed" | "unknown";
+};
+export declare function buildEventV3<T extends EventTypeV3>(eventType: T, input: BuildEventV3Input<T>): EventOfTypeV3<T>;
+export {};
+//# sourceMappingURL=builder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../../../src/core/events/v3/builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAKhF,KAAK,yBAAyB,CAAC,CAAC,SAAS,WAAW,IAAI,IAAI,CAC1D,aAAa,CAAC,CAAC,CAAC,EAChB,gBAAgB,GAAG,UAAU,GAAG,UAAU,GAAG,YAAY,GAAG,SAAS,GAAG,MAAM,CAC/E,CAAC;AAEF,KAAK,eAAe,GAChB,gBAAgB,GAChB,kBAAkB,GAClB,wBAAwB,GACxB,+BAA+B,CAAC;AAEpC,KAAK,kBAAkB,CAAC,CAAC,SAAS,WAAW,IAAI,CAAC,SAAS,eAAe,GACtE;IAAE,cAAc,CAAC,EAAE,KAAK,CAAA;CAAE,GAC1B;IAAE,cAAc,EAAE,OAAO,MAAM,EAAE,CAAA;CAAE,CAAC;AAExC,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,WAAW,IAAI,yBAAyB,CAAC,CAAC,CAAC,GACjF,kBAAkB,CAAC,CAAC,CAAC,GAAG;IACtB,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC;IAC3B,QAAQ,CAAC,EAAE,OAAO,MAAM,EAAE,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,MAAM,EAAE,CAAC;IAC3B,IAAI,CAAC,EAAE,QAAQ,GAAG,WAAW,GAAG,SAAS,CAAC;CAC3C,CAAC;AAEJ,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,EAChD,SAAS,EAAE,CAAC,EACZ,KAAK,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAC1B,aAAa,CAAC,CAAC,CAAC,CAwBlB"}

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

@@ -0,0 +1,28 @@
+import { EVENT_V3_CONTRACT_MAJOR, EVENT_V3_CONTRACT_NAME } from "./contract.js";
+import { EVENT_V3_SCHEMA_DIGEST } from "./generated.js";
+import { clockIdV3, eventIdV3 } from "./ids.js";
+export function buildEventV3(eventType, input) {
+    const now = input.recorded_at ?? new Date().toISOString();
+    return {
+        contract: {
+            name: EVENT_V3_CONTRACT_NAME,
+            major: EVENT_V3_CONTRACT_MAJOR,
+            schema_digest: EVENT_V3_SCHEMA_DIGEST,
+        },
+        event_id: input.event_id ?? eventIdV3(),
+        event_type: eventType,
+        time: {
+            observed_at: input.observed_at ?? now,
+            recorded_at: now,
+            ...(input.monotonic_ns ? { monotonic_ns: input.monotonic_ns } : {}),
+            clock_id: input.clock_id ?? clockIdV3(),
+            skew: input.skew ?? "unknown",
+        },
+        producer: input.producer,
+        scope: input.scope,
+        ...(input.attestation_id ? { attestation_id: input.attestation_id } : {}),
+        links: input.links,
+        provenance: input.provenance,
+        payload: input.payload,
+    };
+}

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

@@ -0,0 +1,31 @@
+export declare const EVENT_V3_CANONICALIZER: "harnery-jcs-nfc-v1";
+export type JsonPrimitive = null | boolean | number | string;
+export type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * Canonical JSON used for V3 contract digests, event bytes, and fingerprints.
+ *
+ * It follows RFC 8785's ECMAScript number and string serialization, adds the
+ * V3 NFC rule for keys and values, and rejects values that JSON would silently
+ * erase or reinterpret. Object keys are serialized directly instead of via an
+ * intermediate object so integer-looking keys remain in lexical order.
+ */
+export declare function canonicalJsonV3(value: unknown): string;
+export declare function sha256V3(value: string | Uint8Array): `sha256:${string}`;
+export interface FingerprintV3 {
+    algorithm: "hmac-sha256";
+    canonicalizer: typeof EVENT_V3_CANONICALIZER;
+    key_epoch: `pep_${string}`;
+    scope: "generation" | "root";
+    digest: `sha256:${string}`;
+}
+export interface FingerprintContextV3 {
+    epochId: `pep_${string}`;
+    epochKey: Uint8Array;
+    rootId: `root_${string}`;
+    generationId?: `gen_${string}`;
+}
+export declare function fingerprintV3(context: FingerprintContextV3, domain: string, value: unknown, scope?: "generation" | "root"): FingerprintV3;
+export declare function normalizeNativeIdV3(context: FingerprintContextV3, namespace: string, nativeId: string): `hid_${string}`;
+//# sourceMappingURL=canonical.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.d.ts","sourceRoot":"","sources":["../../../../src/core/events/v3/canonical.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,sBAAsB,EAAG,oBAA6B,CAAC;AAEpE,MAAM,MAAM,aAAa,GAAG,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAC7D,MAAM,MAAM,SAAS,GAAG,aAAa,GAAG,SAAS,EAAE,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEnF;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEtD;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,UAAU,MAAM,EAAE,CAEvE;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,aAAa,CAAC;IACzB,aAAa,EAAE,OAAO,sBAAsB,CAAC;IAC7C,SAAS,EAAE,OAAO,MAAM,EAAE,CAAC;IAC3B,KAAK,EAAE,YAAY,GAAG,MAAM,CAAC;IAC7B,MAAM,EAAE,UAAU,MAAM,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,MAAM,EAAE,CAAC;IACzB,QAAQ,EAAE,UAAU,CAAC;IACrB,MAAM,EAAE,QAAQ,MAAM,EAAE,CAAC;IACzB,YAAY,CAAC,EAAE,OAAO,MAAM,EAAE,CAAC;CAChC;AAED,wBAAgB,aAAa,CAC3B,OAAO,EAAE,oBAAoB,EAC7B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,EACd,KAAK,GAAE,YAAY,GAAG,MAAqB,GAC1C,aAAa,CAqCf;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,oBAAoB,EAC7B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,OAAO,MAAM,EAAE,CAkBjB"}

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

@@ -0,0 +1,100 @@
+import { createHash, createHmac, hkdfSync } from "node:crypto";
+export const EVENT_V3_CANONICALIZER = "harnery-jcs-nfc-v1";
+/**
+ * Canonical JSON used for V3 contract digests, event bytes, and fingerprints.
+ *
+ * It follows RFC 8785's ECMAScript number and string serialization, adds the
+ * V3 NFC rule for keys and values, and rejects values that JSON would silently
+ * erase or reinterpret. Object keys are serialized directly instead of via an
+ * intermediate object so integer-looking keys remain in lexical order.
+ */
+export function canonicalJsonV3(value) {
+    return serialize(value, new Set());
+}
+export function sha256V3(value) {
+    return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+export function fingerprintV3(context, domain, value, scope = "generation") {
+    assertDomain(domain);
+    const rootKey = Buffer.from(hkdfSync("sha256", context.epochKey, Buffer.from(context.epochId, "utf8"), Buffer.from(`harnery:v3:root\0${context.rootId}`, "utf8"), 32));
+    let comparisonKey = rootKey;
+    if (scope === "generation") {
+        if (!context.generationId) {
+            throw new Error("generation-scoped fingerprint requires a generation ID");
+        }
+        comparisonKey = Buffer.from(hkdfSync("sha256", rootKey, Buffer.from(context.generationId, "utf8"), Buffer.from("harnery:v3:generation", "utf8"), 32));
+    }
+    const digest = createHmac("sha256", comparisonKey)
+        .update(`harnery:v3:${domain}\0`, "utf8")
+        .update(canonicalJsonV3(value), "utf8")
+        .digest("hex");
+    return {
+        algorithm: "hmac-sha256",
+        canonicalizer: EVENT_V3_CANONICALIZER,
+        key_epoch: context.epochId,
+        scope,
+        digest: `sha256:${digest}`,
+    };
+}
+export function normalizeNativeIdV3(context, namespace, nativeId) {
+    if (!/^[a-z][a-z0-9._-]{0,63}$/.test(namespace)) {
+        throw new Error("native ID namespace is invalid");
+    }
+    const rootKey = Buffer.from(hkdfSync("sha256", context.epochKey, Buffer.from(context.epochId, "utf8"), Buffer.from(`harnery:v3:root\0${context.rootId}`, "utf8"), 32));
+    const digest = createHmac("sha256", rootKey)
+        .update(`harnery:v3:native-id\0${namespace}\0`, "utf8")
+        .update(nativeId.normalize("NFC"), "utf8")
+        .digest("hex");
+    return `hid_${digest}`;
+}
+function serialize(value, ancestors) {
+    if (value === null)
+        return "null";
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (typeof value === "string")
+        return JSON.stringify(value.normalize("NFC"));
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new Error("canonical JSON rejects non-finite numbers");
+        return JSON.stringify(Object.is(value, -0) ? 0 : value);
+    }
+    if (typeof value !== "object") {
+        throw new Error(`canonical JSON rejects ${typeof value}`);
+    }
+    if (ancestors.has(value))
+        throw new Error("canonical JSON rejects cycles");
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value)) {
+            return `[${value.map((item) => serialize(item, ancestors)).join(",")}]`;
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new Error("canonical JSON accepts only plain objects");
+        }
+        const normalized = new Map();
+        for (const [key, item] of Object.entries(value)) {
+            const normalizedKey = key.normalize("NFC");
+            if (normalized.has(normalizedKey)) {
+                throw new Error("canonical JSON key collision after Unicode normalization");
+            }
+            normalized.set(normalizedKey, item);
+        }
+        const keys = [...normalized.keys()].sort(compareUtf16);
+        return `{${keys
+            .map((key) => `${JSON.stringify(key)}:${serialize(normalized.get(key), ancestors)}`)
+            .join(",")}}`;
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+function compareUtf16(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function assertDomain(domain) {
+    if (!/^[a-z][a-z0-9._-]{0,63}$/.test(domain)) {
+        throw new Error("fingerprint domain is invalid");
+    }
+}

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

@@ -0,0 +1,31 @@
+import type { Adapter } from "../../adapter.js";
+export type CapabilitySupportV3 = "native" | "derived" | "conditional" | "unsupported";
+export type CursorExecutionModeV3 = "local" | "cloud" | "unknown";
+export type AdapterWaitKindV3 = "permission" | "needs_input" | "decision" | "approval" | "scheduled" | "rate_limit" | "unknown";
+export type BaseAdapterSignalV3 = "session_start" | "session_end" | "prompt" | "turn_id" | "turn_completion" | "tool_request" | "tool_result" | "tool_failure" | "tool_call_id" | "tool_duration" | "permission" | "subagent" | "shell" | "pre_compaction" | "post_compaction" | "context_usage" | "model_identity";
+export type AdapterSignalV3 = BaseAdapterSignalV3 | "model_usage" | "inference_timing" | "harness_timing" | "capability_drift";
+export interface AdapterCapabilityProfileV3 {
+    format: "harnery-v3-adapter-capabilities";
+    format_version: 1;
+    adapter: Adapter;
+    signals: Record<AdapterSignalV3, CapabilitySupportV3>;
+}
+export declare const ADAPTER_CAPABILITY_PROFILES_V3: Record<Adapter, AdapterCapabilityProfileV3>;
+export declare function adapterCapabilityProfileV3(adapter: Adapter): AdapterCapabilityProfileV3;
+export declare function adapterCapabilityProfileDigestV3(adapter: Adapter): `cap_${string}`;
+export declare function adapterSignalSupportV3(adapter: Adapter, signal: AdapterSignalV3): CapabilitySupportV3;
+/**
+ * Adapter hooks only expose permission waits today. Other wait kinds can be
+ * authored by coordination producers, but they are not observable from an
+ * adapter's native turn channel.
+ */
+export declare function adapterWaitKindSupportV3(adapter: Adapter, kind: AdapterWaitKindV3): CapabilitySupportV3;
+/** No current adapter supplies an independent completed-turn wait aggregate. */
+export declare function adapterTurnWaitCountSupportV3(_adapter: Adapter): CapabilitySupportV3;
+/**
+ * Local Cursor sessions expose the generic tool channel. Cloud/private-worker
+ * sessions cannot guarantee whole-turn delivery because hooks may start only
+ * after the execution environment becomes writable.
+ */
+export declare function cursorToolChannelSupportV3(mode: CursorExecutionModeV3): CapabilitySupportV3;
+//# sourceMappingURL=capabilities.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../../../src/core/events/v3/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAGhD,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,SAAS,GAAG,aAAa,GAAG,aAAa,CAAC;AAEvF,MAAM,MAAM,qBAAqB,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;AAElE,MAAM,MAAM,iBAAiB,GACzB,YAAY,GACZ,aAAa,GACb,UAAU,GACV,UAAU,GACV,WAAW,GACX,YAAY,GACZ,SAAS,CAAC;AAEd,MAAM,MAAM,mBAAmB,GAC3B,eAAe,GACf,aAAa,GACb,QAAQ,GACR,SAAS,GACT,iBAAiB,GACjB,cAAc,GACd,aAAa,GACb,cAAc,GACd,cAAc,GACd,eAAe,GACf,YAAY,GACZ,UAAU,GACV,OAAO,GACP,gBAAgB,GAChB,iBAAiB,GACjB,eAAe,GACf,gBAAgB,CAAC;AAErB,MAAM,MAAM,eAAe,GACvB,mBAAmB,GACnB,aAAa,GACb,kBAAkB,GAClB,gBAAgB,GAChB,kBAAkB,CAAC;AAEvB,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,iCAAiC,CAAC;IAC1C,cAAc,EAAE,CAAC,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC,eAAe,EAAE,mBAAmB,CAAC,CAAC;CACvD;AAmED,eAAO,MAAM,8BAA8B,EAAE,MAAM,CAAC,OAAO,EAAE,0BAA0B,CAatF,CAAC;AAEF,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,OAAO,GAAG,0BAA0B,CAEvF;AAED,wBAAgB,gCAAgC,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,MAAM,EAAE,CAElF;AAED,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,eAAe,GACtB,mBAAmB,CAErB;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,iBAAiB,GACtB,mBAAmB,CAErB;AAED,gFAAgF;AAChF,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,OAAO,GAAG,mBAAmB,CAEpF;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,qBAAqB,GAAG,mBAAmB,CAI3F"}

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

@@ -0,0 +1,107 @@
+import { canonicalJsonV3, sha256V3 } from "./canonical.js";
+const SHARED_SIGNAL_SUPPORT = {
+    session_start: "native",
+    prompt: "native",
+    turn_completion: "native",
+    tool_request: "native",
+    tool_result: "native",
+    tool_failure: "native",
+    tool_call_id: "native",
+    tool_duration: "derived",
+    subagent: "native",
+    shell: "native",
+    pre_compaction: "native",
+    model_identity: "conditional",
+};
+const BASE_SIGNAL_SUPPORT = {
+    "claude-code": {
+        ...SHARED_SIGNAL_SUPPORT,
+        session_end: "native",
+        turn_id: "conditional",
+        permission: "native",
+        post_compaction: "native",
+        context_usage: "unsupported",
+    },
+    codex: {
+        ...SHARED_SIGNAL_SUPPORT,
+        session_end: "native",
+        turn_id: "native",
+        permission: "native",
+        post_compaction: "native",
+        context_usage: "unsupported",
+    },
+    cursor: {
+        ...SHARED_SIGNAL_SUPPORT,
+        session_end: "native",
+        turn_id: "unsupported",
+        tool_request: "conditional",
+        tool_result: "conditional",
+        tool_failure: "conditional",
+        tool_call_id: "conditional",
+        tool_duration: "conditional",
+        shell: "conditional",
+        permission: "conditional",
+        post_compaction: "unsupported",
+        context_usage: "unsupported",
+    },
+};
+function profile(adapter, economics) {
+    return {
+        format: "harnery-v3-adapter-capabilities",
+        format_version: 1,
+        adapter,
+        signals: {
+            ...BASE_SIGNAL_SUPPORT[adapter],
+            ...economics,
+            harness_timing: "derived",
+            capability_drift: "derived",
+        },
+    };
+}
+export const ADAPTER_CAPABILITY_PROFILES_V3 = {
+    "claude-code": profile("claude-code", {
+        model_usage: "conditional",
+        inference_timing: "unsupported",
+    }),
+    codex: profile("codex", {
+        model_usage: "conditional",
+        inference_timing: "unsupported",
+    }),
+    cursor: profile("cursor", {
+        model_usage: "unsupported",
+        inference_timing: "unsupported",
+    }),
+};
+export function adapterCapabilityProfileV3(adapter) {
+    return ADAPTER_CAPABILITY_PROFILES_V3[adapter];
+}
+export function adapterCapabilityProfileDigestV3(adapter) {
+    return `cap_${sha256V3(canonicalJsonV3(adapterCapabilityProfileV3(adapter))).slice(7)}`;
+}
+export function adapterSignalSupportV3(adapter, signal) {
+    return adapterCapabilityProfileV3(adapter).signals[signal];
+}
+/**
+ * Adapter hooks only expose permission waits today. Other wait kinds can be
+ * authored by coordination producers, but they are not observable from an
+ * adapter's native turn channel.
+ */
+export function adapterWaitKindSupportV3(adapter, kind) {
+    return kind === "permission" ? adapterSignalSupportV3(adapter, "permission") : "unsupported";
+}
+/** No current adapter supplies an independent completed-turn wait aggregate. */
+export function adapterTurnWaitCountSupportV3(_adapter) {
+    return "unsupported";
+}
+/**
+ * Local Cursor sessions expose the generic tool channel. Cloud/private-worker
+ * sessions cannot guarantee whole-turn delivery because hooks may start only
+ * after the execution environment becomes writable.
+ */
+export function cursorToolChannelSupportV3(mode) {
+    if (mode === "local")
+        return "native";
+    if (mode === "cloud")
+        return "unsupported";
+    return "conditional";
+}

package/dist/core/events/v3/capability-drift.d.ts

@@ -0,0 +1,22 @@
+import type { Adapter } from "../../adapter.js";
+import { type AdapterSignalV3 } from "./capabilities.js";
+import type { EventPayloadV3, EventV3 } from "./contract.js";
+export interface CapabilityDeliveryV3 {
+    signal: AdapterSignalV3;
+    expected_count: number;
+    observed_count: number;
+}
+export type CapabilityDriftPayloadV3 = EventPayloadV3<"health.capability_drift">;
+/**
+ * Compare measurable adapter promises against one completed generation.
+ *
+ * Conditional and unsupported promises never drift: absence is allowed by
+ * their contract. Native and derived promises report only when a concrete
+ * opportunity existed, keeping a quiet generation from manufacturing health
+ * failures.
+ */
+export declare function capabilityDriftPayloadsV3(adapter: Adapter, events: readonly EventV3[], options?: {
+    generation_ended?: boolean;
+}): CapabilityDriftPayloadV3[];
+export declare function measurableDeliveriesV3(events: readonly EventV3[]): CapabilityDeliveryV3[];
+//# sourceMappingURL=capability-drift.d.ts.map

package/dist/core/events/v3/capability-drift.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-drift.d.ts","sourceRoot":"","sources":["../../../../src/core/events/v3/capability-drift.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EACL,KAAK,eAAe,EAGrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAE7D,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,eAAe,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,wBAAwB,GAAG,cAAc,CAAC,yBAAyB,CAAC,CAAC;AAEjF;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,SAAS,OAAO,EAAE,EAC1B,OAAO,GAAE;IAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAO,GAC3C,wBAAwB,EAAE,CAsB5B;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,oBAAoB,EAAE,CAEzF"}