harnery 0.33.0 → 0.34.0

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

@@ -0,0 +1,77 @@
+import type { LatencyMetricV3 } from "./latency.js";
+import type { ReadLedgerV3Result } from "./reader.js";
+export declare const EVENT_V3_ECONOMICS_PROJECTION_VERSION: "event-v3-economics-v1";
+export interface TokenTotalsV3 {
+    input_tokens: number;
+    output_tokens: number;
+    cache_read_tokens: number;
+    cache_write_tokens: number;
+}
+export type TokenTotalsMetricV3 = {
+    state: "observed";
+    value: TokenTotalsV3;
+} | {
+    state: "unknown";
+    known: TokenTotalsV3;
+    reasons: string[];
+};
+export type CostMetricV3 = {
+    state: "observed";
+    usd: number;
+    pricing_key: string;
+} | {
+    state: "unknown";
+    known_usd: number;
+    reasons: string[];
+};
+export interface ModelPricingV3 {
+    input_usd_per_million: number;
+    output_usd_per_million: number;
+    cache_read_usd_per_million?: number;
+    cache_write_usd_per_million?: number;
+}
+export interface EconomicsProjectionOptionsV3 {
+    pricing?: Record<string, ModelPricingV3>;
+}
+export interface TurnEconomicsV3 {
+    generation_id: string;
+    turn_id: string;
+    terminal_event_id: string;
+    model_key: string | null;
+    usage_method: string | null;
+    tokens: TokenTotalsMetricV3;
+    inference_ms: LatencyMetricV3;
+    harness_ms: LatencyMetricV3;
+    slowest_hook: string | null;
+    slowest_hook_ms: number | null;
+    cost: CostMetricV3;
+}
+export interface GenerationEconomicsV3 {
+    generation_id: string;
+    turn_count: number;
+    tokens: TokenTotalsMetricV3;
+    inference_ms: LatencyMetricV3;
+    harness_ms: LatencyMetricV3;
+    cost: CostMetricV3;
+}
+export interface EconomicsProjectionV3 {
+    projection_version: typeof EVENT_V3_ECONOMICS_PROJECTION_VERSION;
+    turns: TurnEconomicsV3[];
+    generations: GenerationEconomicsV3[];
+}
+export type DelegationRollupDiagnosticCodeV3 = "delegation_cycle" | "generation_economics_missing";
+export interface DelegationRollupV3 {
+    root_generation_id: string;
+    generation_ids: string[];
+    tokens: TokenTotalsMetricV3;
+    inference_ms: LatencyMetricV3;
+    harness_ms: LatencyMetricV3;
+    cost: CostMetricV3;
+    diagnostics: Array<{
+        code: DelegationRollupDiagnosticCodeV3;
+        generation_id: string;
+    }>;
+}
+export declare function projectEconomicsV3(read: ReadLedgerV3Result, options?: EconomicsProjectionOptionsV3): EconomicsProjectionV3;
+export declare function projectDelegationRollupV3(read: ReadLedgerV3Result, economics: EconomicsProjectionV3, rootGenerationId: string): DelegationRollupV3;
+//# sourceMappingURL=economics.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"economics.d.ts","sourceRoot":"","sources":["../../../../src/core/events/v3/economics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,eAAO,MAAM,qCAAqC,EAAG,uBAAgC,CAAC;AAEtF,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,MAAM,mBAAmB,GAC3B;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,aAAa,CAAA;CAAE,GAC3C;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAElE,MAAM,MAAM,YAAY,GACpB;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACvD;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAE/D,MAAM,WAAW,cAAc;IAC7B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,0BAA0B,CAAC,EAAE,MAAM,CAAC;IACpC,2BAA2B,CAAC,EAAE,MAAM,CAAC;CACtC;AAED,MAAM,WAAW,4BAA4B;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,MAAM,EAAE,mBAAmB,CAAC;IAC5B,YAAY,EAAE,eAAe,CAAC;IAC9B,UAAU,EAAE,eAAe,CAAC;IAC5B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,IAAI,EAAE,YAAY,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,mBAAmB,CAAC;IAC5B,YAAY,EAAE,eAAe,CAAC;IAC9B,UAAU,EAAE,eAAe,CAAC;IAC5B,IAAI,EAAE,YAAY,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,kBAAkB,EAAE,OAAO,qCAAqC,CAAC;IACjE,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,WAAW,EAAE,qBAAqB,EAAE,CAAC;CACtC;AAED,MAAM,MAAM,gCAAgC,GAAG,kBAAkB,GAAG,8BAA8B,CAAC;AAEnG,MAAM,WAAW,kBAAkB;IACjC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,MAAM,EAAE,mBAAmB,CAAC;IAC5B,YAAY,EAAE,eAAe,CAAC;IAC9B,UAAU,EAAE,eAAe,CAAC;IAC5B,IAAI,EAAE,YAAY,CAAC;IACnB,WAAW,EAAE,KAAK,CAAC;QACjB,IAAI,EAAE,gCAAgC,CAAC;QACvC,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC,CAAC;CACJ;AASD,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,kBAAkB,EACxB,OAAO,GAAE,4BAAiC,GACzC,qBAAqB,CAmDvB;AAED,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,kBAAkB,EACxB,SAAS,EAAE,qBAAqB,EAChC,gBAAgB,EAAE,MAAM,GACvB,kBAAkB,CAqEpB"}

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

@@ -0,0 +1,274 @@
+export const EVENT_V3_ECONOMICS_PROJECTION_VERSION = "event-v3-economics-v1";
+export function projectEconomicsV3(read, options = {}) {
+    if (!read.complete)
+        throw new Error("economics projection requires a complete V3 ledger read");
+    const models = new Map();
+    const turns = [];
+    for (const positioned of read.events) {
+        const event = positioned.event;
+        const generationId = event.scope.generation_id;
+        if (generationId &&
+            (event.event_type === "session.started" || event.event_type === "session.attestation_changed")) {
+            models.set(generationId, modelKey(event.payload.runtime_attestation));
+        }
+        if (event.event_type !== "turn.completed")
+            continue;
+        const tokens = tokensFromObservation(event.payload.usage);
+        const model = generationId ? (models.get(generationId) ?? null) : null;
+        const slowestHook = slowestHookFromObservation(event.payload.harness);
+        turns.push({
+            generation_id: generationId ?? "",
+            turn_id: event.scope.turn_id ?? "",
+            terminal_event_id: event.event_id,
+            model_key: model,
+            usage_method: usageMethod(event.payload.usage),
+            tokens,
+            inference_ms: timingFromObservation(event.payload.inference, "api_time_ms", "inference_unknown"),
+            harness_ms: timingFromObservation(event.payload.harness, "hook_time_ms", "harness_unknown"),
+            slowest_hook: slowestHook.name,
+            slowest_hook_ms: slowestHook.duration_ms,
+            cost: costForTurn(tokens, model, options.pricing),
+        });
+    }
+    const grouped = new Map();
+    for (const turn of turns) {
+        const generationTurns = grouped.get(turn.generation_id) ?? [];
+        generationTurns.push(turn);
+        grouped.set(turn.generation_id, generationTurns);
+    }
+    const generations = [...grouped.entries()].map(([generationId, generationTurns]) => ({
+        generation_id: generationId,
+        turn_count: generationTurns.length,
+        tokens: sumTokenMetrics(generationTurns.map(({ tokens }) => tokens)),
+        inference_ms: sumTimingMetrics(generationTurns.map(({ inference_ms }) => inference_ms)),
+        harness_ms: sumTimingMetrics(generationTurns.map(({ harness_ms }) => harness_ms)),
+        cost: sumCostMetrics(generationTurns.map(({ cost }) => cost)),
+    }));
+    generations.sort((left, right) => left.generation_id.localeCompare(right.generation_id));
+    return { projection_version: EVENT_V3_ECONOMICS_PROJECTION_VERSION, turns, generations };
+}
+export function projectDelegationRollupV3(read, economics, rootGenerationId) {
+    if (!read.complete)
+        throw new Error("delegation rollup requires a complete V3 ledger read");
+    const children = new Map();
+    for (const positioned of read.events) {
+        const event = positioned.event;
+        if (event.event_type !== "agent.completed")
+            continue;
+        const parent = event.scope.generation_id;
+        const child = string(event.payload.child_generation_id);
+        if (!parent || !child)
+            continue;
+        const set = children.get(parent) ?? new Set();
+        set.add(child);
+        children.set(parent, set);
+    }
+    const generationIds = [];
+    const diagnostics = [];
+    const visited = new Set();
+    const active = new Set();
+    const visit = (generationId) => {
+        if (active.has(generationId)) {
+            diagnostics.push({ code: "delegation_cycle", generation_id: generationId });
+            return;
+        }
+        if (visited.has(generationId))
+            return;
+        visited.add(generationId);
+        active.add(generationId);
+        generationIds.push(generationId);
+        for (const child of [...(children.get(generationId) ?? [])].sort())
+            visit(child);
+        active.delete(generationId);
+    };
+    visit(rootGenerationId);
+    const byGeneration = new Map(economics.generations.map((generation) => [generation.generation_id, generation]));
+    const included = generationIds.flatMap((generationId) => {
+        const generation = byGeneration.get(generationId);
+        if (generation)
+            return [generation];
+        diagnostics.push({ code: "generation_economics_missing", generation_id: generationId });
+        return [];
+    });
+    const missing = diagnostics
+        .filter(({ code }) => code === "generation_economics_missing")
+        .map(({ generation_id }) => `generation_economics_missing:${generation_id}`);
+    return {
+        root_generation_id: rootGenerationId,
+        generation_ids: generationIds,
+        tokens: sumTokenMetrics([
+            ...included.map(({ tokens }) => tokens),
+            ...missing.map((reason) => ({
+                state: "unknown",
+                known: zeroTokens(),
+                reasons: [reason],
+            })),
+        ]),
+        inference_ms: sumTimingMetrics([
+            ...included.map(({ inference_ms }) => inference_ms),
+            ...missing.map((reason) => ({ state: "unknown", known_ms: 0, reasons: [reason] })),
+        ]),
+        harness_ms: sumTimingMetrics([
+            ...included.map(({ harness_ms }) => harness_ms),
+            ...missing.map((reason) => ({ state: "unknown", known_ms: 0, reasons: [reason] })),
+        ]),
+        cost: sumCostMetrics([
+            ...included.map(({ cost }) => cost),
+            ...missing.map((reason) => ({ state: "unknown", known_usd: 0, reasons: [reason] })),
+        ]),
+        diagnostics,
+    };
+}
+function modelKey(runtimeAttestation) {
+    const model = record(record(runtimeAttestation).model);
+    if (model.state !== "observed")
+        return null;
+    const value = record(model.value);
+    const provider = string(value.provider);
+    const id = string(value.id);
+    return provider && id ? `${provider}/${id}` : null;
+}
+function tokensFromObservation(value) {
+    const observation = record(value);
+    if (observation.state !== "observed") {
+        return { state: "unknown", known: zeroTokens(), reasons: [observationReason(value)] };
+    }
+    const usage = record(observation.value);
+    if (!nonnegative(usage.input_tokens) || !nonnegative(usage.output_tokens)) {
+        return { state: "unknown", known: zeroTokens(), reasons: ["usage_invalid"] };
+    }
+    return {
+        state: "observed",
+        value: {
+            input_tokens: usage.input_tokens,
+            output_tokens: usage.output_tokens,
+            cache_read_tokens: nonnegative(usage.cache_read_tokens)
+                ? usage.cache_read_tokens
+                : 0,
+            cache_write_tokens: nonnegative(usage.cache_write_tokens)
+                ? usage.cache_write_tokens
+                : 0,
+        },
+    };
+}
+function usageMethod(value) {
+    const observation = record(value);
+    return observation.state === "observed" ? string(record(observation.value).method) || null : null;
+}
+function timingFromObservation(value, field, fallback) {
+    const observation = record(value);
+    const fieldValue = record(observation.value)[field];
+    return observation.state === "observed" && nonnegative(fieldValue)
+        ? { state: "observed", value_ms: fieldValue }
+        : { state: "unknown", known_ms: 0, reasons: [observationReason(value) || fallback] };
+}
+function slowestHookFromObservation(value) {
+    const observation = record(value);
+    if (observation.state !== "observed")
+        return { name: null, duration_ms: null };
+    const harness = record(observation.value);
+    const name = string(harness.slowest_hook);
+    const duration = harness.slowest_hook_ms;
+    return name && nonnegative(duration) && Number.isSafeInteger(duration)
+        ? { name, duration_ms: duration }
+        : { name: null, duration_ms: null };
+}
+function costForTurn(tokens, model, pricing) {
+    const reasons = tokens.state === "unknown" ? ["usage_unknown"] : [];
+    const tokenValue = tokens.state === "observed" ? tokens.value : tokens.known;
+    if (!model)
+        return { state: "unknown", known_usd: 0, reasons: [...reasons, "model_unknown"].sort() };
+    const rates = pricing?.[model];
+    if (!rates) {
+        return {
+            state: "unknown",
+            known_usd: 0,
+            reasons: [...reasons, `pricing_unavailable:${model}`].sort(),
+        };
+    }
+    if (tokenValue.cache_read_tokens > 0 && rates.cache_read_usd_per_million === undefined) {
+        reasons.push("cache_read_pricing_unavailable");
+    }
+    if (tokenValue.cache_write_tokens > 0 && rates.cache_write_usd_per_million === undefined) {
+        reasons.push("cache_write_pricing_unavailable");
+    }
+    const usd = (tokenValue.input_tokens * rates.input_usd_per_million +
+        tokenValue.output_tokens * rates.output_usd_per_million +
+        tokenValue.cache_read_tokens * (rates.cache_read_usd_per_million ?? 0) +
+        tokenValue.cache_write_tokens * (rates.cache_write_usd_per_million ?? 0)) /
+        1_000_000;
+    return reasons.length > 0
+        ? { state: "unknown", known_usd: roundUsd(usd), reasons }
+        : { state: "observed", usd: roundUsd(usd), pricing_key: model };
+}
+function sumTokenMetrics(metrics) {
+    const total = zeroTokens();
+    const reasons = [];
+    for (const metric of metrics) {
+        addTokens(total, metric.state === "observed" ? metric.value : metric.known);
+        if (metric.state === "unknown")
+            reasons.push(...metric.reasons);
+    }
+    return reasons.length === 0
+        ? { state: "observed", value: total }
+        : { state: "unknown", known: total, reasons: unique(reasons) };
+}
+function sumTimingMetrics(metrics) {
+    let known = 0;
+    const reasons = [];
+    for (const metric of metrics) {
+        known += metric.state === "observed" ? metric.value_ms : metric.known_ms;
+        if (metric.state === "unknown")
+            reasons.push(...metric.reasons);
+    }
+    return reasons.length === 0
+        ? { state: "observed", value_ms: known }
+        : { state: "unknown", known_ms: known, reasons: unique(reasons) };
+}
+function sumCostMetrics(metrics) {
+    let known = 0;
+    const reasons = [];
+    const keys = new Set();
+    for (const metric of metrics) {
+        known += metric.state === "observed" ? metric.usd : metric.known_usd;
+        if (metric.state === "observed")
+            keys.add(metric.pricing_key);
+        else
+            reasons.push(...metric.reasons);
+    }
+    return reasons.length === 0
+        ? { state: "observed", usd: roundUsd(known), pricing_key: [...keys].sort().join("+") }
+        : { state: "unknown", known_usd: roundUsd(known), reasons: unique(reasons) };
+}
+function zeroTokens() {
+    return { input_tokens: 0, output_tokens: 0, cache_read_tokens: 0, cache_write_tokens: 0 };
+}
+function addTokens(target, value) {
+    target.input_tokens += value.input_tokens;
+    target.output_tokens += value.output_tokens;
+    target.cache_read_tokens += value.cache_read_tokens;
+    target.cache_write_tokens += value.cache_write_tokens;
+}
+function nonnegative(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+function observationReason(value) {
+    const observation = record(value);
+    const state = string(observation.state) || "unknown";
+    const reason = string(observation.reason);
+    return reason ? `${state}:${reason}` : state;
+}
+function roundUsd(value) {
+    return Math.round(value * 1_000_000_000_000) / 1_000_000_000_000;
+}
+function unique(values) {
+    return [...new Set(values)].sort();
+}
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function string(value) {
+    return typeof value === "string" ? value : "";
+}

package/dist/core/events/v3/finalization-view.d.ts

@@ -0,0 +1,26 @@
+import type { ReadLedgerV3Result } from "./reader.js";
+export declare const EVENT_V3_FINALIZATION_VIEW_VERSION: 1;
+export type FinalizationScopeV3ErrorCode = "authority_unsafe" | "instance_not_live";
+export declare class FinalizationScopeV3Error extends Error {
+    readonly code: FinalizationScopeV3ErrorCode;
+    constructor(code: FinalizationScopeV3ErrorCode);
+}
+export interface FinalizationScopeV3 {
+    projection_version: typeof EVENT_V3_FINALIZATION_VIEW_VERSION;
+    contract_major: 2;
+    instance_id: string;
+    session_id: string;
+    generation_id: string;
+    lifecycle_state?: string;
+    files_touched: string[];
+    source_event_id: string;
+    source_position: {
+        segment_ordinal: number;
+        byte_offset: number;
+    };
+}
+/** Read and validate the current V3 finalization boundary for one live instance. */
+export declare function readFinalizationScopeV3(coordRoot: string, instanceId: string): FinalizationScopeV3;
+/** Pure adapter used by replay tests and safety consumers. */
+export declare function projectFinalizationScopeV3(read: ReadLedgerV3Result, instanceId: string): FinalizationScopeV3;
+//# sourceMappingURL=finalization-view.d.ts.map

package/dist/core/events/v3/finalization-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"finalization-view.d.ts","sourceRoot":"","sources":["../../../../src/core/events/v3/finalization-view.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,eAAO,MAAM,kCAAkC,EAAG,CAAU,CAAC;AAE7D,MAAM,MAAM,4BAA4B,GAAG,kBAAkB,GAAG,mBAAmB,CAAC;AAEpF,qBAAa,wBAAyB,SAAQ,KAAK;aACrB,IAAI,EAAE,4BAA4B;gBAAlC,IAAI,EAAE,4BAA4B;CAI/D;AAED,MAAM,WAAW,mBAAmB;IAClC,kBAAkB,EAAE,OAAO,kCAAkC,CAAC;IAC9D,cAAc,EAAE,CAAC,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE;QAAE,eAAe,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;CACnE;AAED,oFAAoF;AACpF,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB,mBAAmB,CAErB;AAED,8DAA8D;AAC9D,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,kBAAkB,EACxB,UAAU,EAAE,MAAM,GACjB,mBAAmB,CAErB"}

package/dist/core/events/v3/finalization-view.js

@@ -0,0 +1,37 @@
+import { projectCoordinationViewV3, readCoordinationViewV3, } from "./coordination-view.js";
+export const EVENT_V3_FINALIZATION_VIEW_VERSION = 1;
+export class FinalizationScopeV3Error extends Error {
+    code;
+    constructor(code) {
+        super(`event_v3_finalization_scope:${code}`);
+        this.code = code;
+        this.name = "FinalizationScopeV3Error";
+    }
+}
+/** Read and validate the current V3 finalization boundary for one live instance. */
+export function readFinalizationScopeV3(coordRoot, instanceId) {
+    return finalizationScopeFromCoordinationViewV3(readCoordinationViewV3(coordRoot), instanceId);
+}
+/** Pure adapter used by replay tests and safety consumers. */
+export function projectFinalizationScopeV3(read, instanceId) {
+    return finalizationScopeFromCoordinationViewV3(projectCoordinationViewV3(read), instanceId);
+}
+function finalizationScopeFromCoordinationViewV3(view, instanceId) {
+    if (!view.authority_safe)
+        throw new FinalizationScopeV3Error("authority_unsafe");
+    const instance = view.instances[instanceId];
+    if (!instance?.authority_eligible) {
+        throw new FinalizationScopeV3Error("instance_not_live");
+    }
+    return {
+        projection_version: EVENT_V3_FINALIZATION_VIEW_VERSION,
+        contract_major: 2,
+        instance_id: instance.instance_id,
+        session_id: instance.session_id,
+        generation_id: instance.generation_id,
+        lifecycle_state: instance.lifecycle_state,
+        files_touched: [...instance.files_touched],
+        source_event_id: instance.last_event_id,
+        source_position: { ...instance.source_position },
+    };
+}

package/dist/core/events/v3/fingerprint-keys.d.ts

@@ -0,0 +1,25 @@
+import type { FingerprintContextV3 } from "./canonical.js";
+export declare const FINGERPRINT_KEY_STORE_RELATIVE_PATH: ".harnery/private/fingerprint-keys.json";
+export interface FingerprintKeyEpochV3 {
+    epoch_id: `pep_${string}`;
+    key_base64url: string;
+    created_at: string;
+}
+export interface FingerprintKeyStoreV3 {
+    format: "harnery-v3-fingerprint-keys";
+    format_version: 1;
+    active_epoch_id: `pep_${string}`;
+    epochs: FingerprintKeyEpochV3[];
+}
+export interface RotateFingerprintEpochV3Options {
+    activeGenerationCount: number;
+    now?: () => Date;
+}
+export declare function fingerprintKeyStorePathV3(coordRoot: string): string;
+/** Load the private key store, creating its first epoch under an exclusive publication lock. */
+export declare function loadOrCreateFingerprintKeyStoreV3(coordRoot: string, now?: () => Date): FingerprintKeyStoreV3;
+export declare function readFingerprintKeyStoreV3(coordRoot: string): FingerprintKeyStoreV3;
+/** Start a new comparison epoch only when no generation can still emit under the prior key. */
+export declare function rotateFingerprintEpochV3(coordRoot: string, options: RotateFingerprintEpochV3Options): FingerprintKeyStoreV3;
+export declare function fingerprintContextV3(coordRoot: string, rootId: `root_${string}`, generationId?: `gen_${string}`, epochId?: `pep_${string}`): FingerprintContextV3;
+//# sourceMappingURL=fingerprint-keys.d.ts.map

package/dist/core/events/v3/fingerprint-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint-keys.d.ts","sourceRoot":"","sources":["../../../../src/core/events/v3/fingerprint-keys.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAO3D,eAAO,MAAM,mCAAmC,EAC9C,wCAAiD,CAAC;AAEpD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,OAAO,MAAM,EAAE,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,6BAA6B,CAAC;IACtC,cAAc,EAAE,CAAC,CAAC;IAClB,eAAe,EAAE,OAAO,MAAM,EAAE,CAAC;IACjC,MAAM,EAAE,qBAAqB,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,+BAA+B;IAC9C,qBAAqB,EAAE,MAAM,CAAC;IAC9B,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED,gGAAgG;AAChG,wBAAgB,iCAAiC,CAC/C,SAAS,EAAE,MAAM,EACjB,GAAG,GAAE,MAAM,IAAuB,GACjC,qBAAqB,CAiBvB;AAED,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,GAAG,qBAAqB,CAGlF;AAgBD,+FAA+F;AAC/F,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,+BAA+B,GACvC,qBAAqB,CAmBvB;AAED,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,QAAQ,MAAM,EAAE,EACxB,YAAY,CAAC,EAAE,OAAO,MAAM,EAAE,EAC9B,OAAO,CAAC,EAAE,OAAO,MAAM,EAAE,GACxB,oBAAoB,CAWtB"}

package/dist/core/events/v3/fingerprint-keys.js

@@ -0,0 +1,217 @@
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { hostname } from "node:os";
+import { join, resolve } from "node:path";
+import { fsyncParentDirectory } from "../../workflow/durable-record.js";
+import { acquireNoClobberLease } from "../../workflow/workspaces/leases.js";
+const KEY_BYTES = 32;
+const LOCK_RETRIES = 200;
+const LOCK_RETRY_MS = 5;
+const sleepCell = new Int32Array(new SharedArrayBuffer(4));
+export const FINGERPRINT_KEY_STORE_RELATIVE_PATH = ".harnery/private/fingerprint-keys.json";
+export function fingerprintKeyStorePathV3(coordRoot) {
+    return join(resolve(coordRoot), FINGERPRINT_KEY_STORE_RELATIVE_PATH);
+}
+/** Load the private key store, creating its first epoch under an exclusive publication lock. */
+export function loadOrCreateFingerprintKeyStoreV3(coordRoot, now = () => new Date()) {
+    const path = fingerprintKeyStorePathV3(coordRoot);
+    if (existsSync(path)) {
+        return readFingerprintKeyStoreV3(coordRoot);
+    }
+    return withKeyStoreLock(coordRoot, () => {
+        if (existsSync(path))
+            return readFingerprintKeyStoreV3(coordRoot);
+        const epoch = createEpoch(now);
+        const store = {
+            format: "harnery-v3-fingerprint-keys",
+            format_version: 1,
+            active_epoch_id: epoch.epoch_id,
+            epochs: [epoch],
+        };
+        publishKeyStore(path, store, false);
+        return store;
+    });
+}
+export function readFingerprintKeyStoreV3(coordRoot) {
+    const path = fingerprintKeyStorePathV3(coordRoot);
+    return validateKeyStore(readKeyStoreValue(path));
+}
+function readKeyStoreValue(path) {
+    const mode = statSync(path).mode & 0o777;
+    if ((mode & 0o077) !== 0) {
+        throw new Error("fingerprint key store permissions are not owner-only");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        throw new Error("fingerprint key store is unreadable or malformed");
+    }
+    return parsed;
+}
+/** Start a new comparison epoch only when no generation can still emit under the prior key. */
+export function rotateFingerprintEpochV3(coordRoot, options) {
+    if (!Number.isSafeInteger(options.activeGenerationCount) || options.activeGenerationCount < 0) {
+        throw new Error("active generation count must be a non-negative integer");
+    }
+    if (options.activeGenerationCount !== 0) {
+        throw new Error("fingerprint epoch rotation is blocked while generations are active");
+    }
+    loadOrCreateFingerprintKeyStoreV3(coordRoot, options.now);
+    return withKeyStoreLock(coordRoot, () => {
+        const current = readFingerprintKeyStoreV3(coordRoot);
+        const epoch = createEpoch(options.now ?? (() => new Date()));
+        const next = {
+            ...current,
+            active_epoch_id: epoch.epoch_id,
+            epochs: [...current.epochs, epoch],
+        };
+        publishKeyStore(fingerprintKeyStorePathV3(coordRoot), next, true);
+        return next;
+    });
+}
+export function fingerprintContextV3(coordRoot, rootId, generationId, epochId) {
+    const store = readFingerprintKeyStoreV3(coordRoot);
+    const selectedId = epochId ?? store.active_epoch_id;
+    const epoch = store.epochs.find((candidate) => candidate.epoch_id === selectedId);
+    if (!epoch)
+        throw new Error("requested fingerprint epoch is unavailable");
+    return {
+        epochId: epoch.epoch_id,
+        epochKey: Buffer.from(epoch.key_base64url, "base64url"),
+        rootId,
+        generationId,
+    };
+}
+function withKeyStoreLock(coordRoot, operation) {
+    const privateDir = join(resolve(coordRoot), ".harnery/private");
+    mkdirSync(privateDir, { recursive: true, mode: 0o700 });
+    chmodSync(privateDir, 0o700);
+    const leasePath = join(privateDir, "fingerprint-key-lease");
+    const authority = createHash("sha256").update(resolve(coordRoot)).digest("hex");
+    let lease;
+    for (let attempt = 0; attempt < LOCK_RETRIES; attempt += 1) {
+        try {
+            lease = acquireNoClobberLease({
+                path: leasePath,
+                scope: "event-v3-fingerprint-key",
+                authoritySha256: authority,
+                staleAfterMs: 5_000,
+                validateStaleOwner: (owner) => owner.host === hostname() && !pidIsAlive(owner.pid),
+            });
+            break;
+        }
+        catch (error) {
+            if (attempt === LOCK_RETRIES - 1)
+                throw error;
+            Atomics.wait(sleepCell, 0, 0, LOCK_RETRY_MS);
+        }
+    }
+    if (!lease)
+        throw new Error("fingerprint key store publication lease is busy");
+    try {
+        return operation();
+    }
+    finally {
+        lease.release();
+    }
+}
+function pidIsAlive(pid) {
+    if (!Number.isSafeInteger(pid) || pid < 1)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== "ESRCH";
+    }
+}
+function publishKeyStore(path, store, replacing) {
+    if (!replacing && existsSync(path))
+        throw new Error("fingerprint key store already exists");
+    const temporary = `${path}.tmp-${process.pid}-${randomUUID()}`;
+    let fd;
+    try {
+        fd = openSync(temporary, "wx", 0o600);
+        writeFileSync(fd, `${JSON.stringify(store)}\n`, "utf8");
+        fsyncSync(fd);
+        closeSync(fd);
+        fd = undefined;
+        chmodSync(temporary, 0o600);
+        if (!replacing && existsSync(path))
+            throw new Error("fingerprint key store already exists");
+        renameSync(temporary, path);
+        fsyncParentDirectory(path);
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+        if (existsSync(temporary))
+            unlinkSync(temporary);
+    }
+}
+function createEpoch(now) {
+    return {
+        epoch_id: `pep_${randomUUID()}`,
+        key_base64url: randomBytes(KEY_BYTES).toString("base64url"),
+        created_at: now().toISOString(),
+    };
+}
+function validateKeyStore(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("fingerprint key store has an invalid envelope");
+    }
+    const record = value;
+    const keys = Object.keys(record).sort();
+    if (keys.join("\0") !== "active_epoch_id\0epochs\0format\0format_version") {
+        throw new Error("fingerprint key store has unsupported fields");
+    }
+    if (record.format !== "harnery-v3-fingerprint-keys" || record.format_version !== 1) {
+        throw new Error("fingerprint key store format is unsupported");
+    }
+    if (typeof record.active_epoch_id !== "string" ||
+        !/^pep_[a-zA-Z0-9._-]{1,128}$/.test(record.active_epoch_id)) {
+        throw new Error("fingerprint key store active epoch is invalid");
+    }
+    if (!Array.isArray(record.epochs) || record.epochs.length === 0) {
+        throw new Error("fingerprint key store has no epochs");
+    }
+    const seen = new Set();
+    const epochs = record.epochs.map((candidate) => {
+        if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) {
+            throw new Error("fingerprint key epoch is invalid");
+        }
+        const epoch = candidate;
+        if (Object.keys(epoch).sort().join("\0") !== "created_at\0epoch_id\0key_base64url") {
+            throw new Error("fingerprint key epoch has unsupported fields");
+        }
+        if (typeof epoch.epoch_id !== "string" || !/^pep_[a-zA-Z0-9._-]{1,128}$/.test(epoch.epoch_id)) {
+            throw new Error("fingerprint key epoch ID is invalid");
+        }
+        if (seen.has(epoch.epoch_id))
+            throw new Error("fingerprint key epoch is duplicated");
+        seen.add(epoch.epoch_id);
+        if (typeof epoch.key_base64url !== "string") {
+            throw new Error("fingerprint key bytes are invalid");
+        }
+        const key = Buffer.from(epoch.key_base64url, "base64url");
+        if (key.length !== KEY_BYTES || key.toString("base64url") !== epoch.key_base64url) {
+            throw new Error("fingerprint key bytes are invalid");
+        }
+        if (typeof epoch.created_at !== "string" || Number.isNaN(Date.parse(epoch.created_at))) {
+            throw new Error("fingerprint key epoch time is invalid");
+        }
+        return epoch;
+    });
+    if (!seen.has(record.active_epoch_id)) {
+        throw new Error("fingerprint key store active epoch is missing");
+    }
+    return {
+        format: "harnery-v3-fingerprint-keys",
+        format_version: 1,
+        active_epoch_id: record.active_epoch_id,
+        epochs,
+    };
+}