harnery 0.34.1 → 0.36.0

package/dist/core/events/v3/producers/coordination-recorder.d.ts

@@ -1,8 +1,12 @@
 import type { Adapter } from "../../../adapter.js";
-import { type AuthorityReceiptV3, type AuthorityReconcilerV3 } from "../authority-outbox.js";
+import { type AuthorityReceiptV3, type AuthorityReconcilerV3, type AuthorityTransactionV3 } from "../authority-outbox.js";
 import type { EventV3 } from "../contract.js";
 import { type EventV3WriteMode } from "../control.js";
 import { type CoordinationAuthoritySignalV3, type CoordinationObservationBySignalV3 } from "./coordination.js";
+export interface PendingCoordinationTransactionV3Location {
+    producer_state_file: string;
+    transaction: AuthorityTransactionV3;
+}
 export interface RecordCoordinationAuthorityV3Input<S extends CoordinationAuthoritySignalV3 = CoordinationAuthoritySignalV3> {
     coordRoot: string;
     mode: EventV3WriteMode;
@@ -50,4 +54,10 @@ export type RecordCoordinationAuthorityV3Result = {
  * settled is refused rather than guessed at.
  */
 export declare function recordCoordinationAuthorityV3<S extends CoordinationAuthoritySignalV3>(input: RecordCoordinationAuthorityV3Input<S>): RecordCoordinationAuthorityV3Result;
+/** Locate the one private producer state that owns a pending authority transaction. */
+export declare function findPendingCoordinationTransactionV3(coordRoot: string, transactionId: string): PendingCoordinationTransactionV3Location | null;
+/** Clear one transaction from its exact producer state after durable quarantine is established. */
+export declare function withPendingCoordinationTransactionRecoveryV3<T>(coordRoot: string, producerStateFile: string, transaction: AuthorityTransactionV3, allowAlreadyCleared: boolean, operation: (control: {
+    clearPending: () => "cleared" | "already_cleared";
+}) => T): T;
 //# sourceMappingURL=coordination-recorder.d.ts.map

package/dist/core/events/v3/producers/coordination-recorder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"coordination-recorder.d.ts","sourceRoot":"","sources":["../../../../../src/core/events/v3/producers/coordination-recorder.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAGnD,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAK3B,MAAM,wBAAwB,CAAC;AAGhC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,KAAK,gBAAgB,EAA2B,MAAM,eAAe,CAAC;AAK/E,OAAO,EACL,KAAK,6BAA6B,EAClC,KAAK,iCAAiC,EAEvC,MAAM,mBAAmB,CAAC;AAyC3B,MAAM,WAAW,kCAAkC,CACjD,CAAC,SAAS,6BAA6B,GAAG,6BAA6B;IAEvE,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,gBAAgB,CAAC;IACvB,MAAM,EAAE,CAAC,CAAC;IACV,WAAW,EAAE,iCAAiC,CAAC,CAAC,CAAC,CAAC;IAClD,OAAO,EAAE,OAAO,CAAC;IACjB,uBAAuB,EAAE,MAAM,CAAC;IAChC,iBAAiB,EAAE,QAAQ,MAAM,EAAE,CAAC;IACpC,mBAAmB,EAAE,QAAQ,MAAM,EAAE,CAAC;IACtC,WAAW,EAAE,OAAO,MAAM,EAAE,CAAC;IAC7B,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;IACpD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,2BAA2B,EAAE,UAAU,MAAM,EAAE,CAAC;IAChD,oBAAoB,EAAE,UAAU,MAAM,EAAE,CAAC;IACzC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,qBAAqB,CAAC;CACnC;AAED,MAAM,MAAM,mCAAmC,GAC3C;IAAE,KAAK,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,KAAK,EAAE,wBAAwB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,KAAK,EAAE,kBAAkB,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,GACvE;IAAE,KAAK,EAAE,qBAAqB,CAAC;IAAC,cAAc,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,GAC/E;IACE,KAAK,EAAE,UAAU,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,kBAAkB,CAAC;IAC5B,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC;AAEN;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAAC,CAAC,SAAS,6BAA6B,EACnF,KAAK,EAAE,kCAAkC,CAAC,CAAC,CAAC,GAC3C,mCAAmC,CA4LrC"}
+{"version":3,"file":"coordination-recorder.d.ts","sourceRoot":"","sources":["../../../../../src/core/events/v3/producers/coordination-recorder.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAGnD,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAK5B,MAAM,wBAAwB,CAAC;AAGhC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,KAAK,gBAAgB,EAA2B,MAAM,eAAe,CAAC;AAK/E,OAAO,EACL,KAAK,6BAA6B,EAClC,KAAK,iCAAiC,EAEvC,MAAM,mBAAmB,CAAC;AAyC3B,MAAM,WAAW,wCAAwC;IACvD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,WAAW,EAAE,sBAAsB,CAAC;CACrC;AAED,MAAM,WAAW,kCAAkC,CACjD,CAAC,SAAS,6BAA6B,GAAG,6BAA6B;IAEvE,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,gBAAgB,CAAC;IACvB,MAAM,EAAE,CAAC,CAAC;IACV,WAAW,EAAE,iCAAiC,CAAC,CAAC,CAAC,CAAC;IAClD,OAAO,EAAE,OAAO,CAAC;IACjB,uBAAuB,EAAE,MAAM,CAAC;IAChC,iBAAiB,EAAE,QAAQ,MAAM,EAAE,CAAC;IACpC,mBAAmB,EAAE,QAAQ,MAAM,EAAE,CAAC;IACtC,WAAW,EAAE,OAAO,MAAM,EAAE,CAAC;IAC7B,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;IACpD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,2BAA2B,EAAE,UAAU,MAAM,EAAE,CAAC;IAChD,oBAAoB,EAAE,UAAU,MAAM,EAAE,CAAC;IACzC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,qBAAqB,CAAC;CACnC;AAED,MAAM,MAAM,mCAAmC,GAC3C;IAAE,KAAK,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,KAAK,EAAE,wBAAwB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,KAAK,EAAE,kBAAkB,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,GACvE;IAAE,KAAK,EAAE,qBAAqB,CAAC;IAAC,cAAc,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,GAC/E;IACE,KAAK,EAAE,UAAU,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,kBAAkB,CAAC;IAC5B,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC;AAEN;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAAC,CAAC,SAAS,6BAA6B,EACnF,KAAK,EAAE,kCAAkC,CAAC,CAAC,CAAC,GAC3C,mCAAmC,CAwNrC;AAED,uFAAuF;AACvF,wBAAgB,oCAAoC,CAClD,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,GACpB,wCAAwC,GAAG,IAAI,CAgBjD;AAED,mGAAmG;AACnG,wBAAgB,4CAA4C,CAAC,CAAC,EAC5D,SAAS,EAAE,MAAM,EACjB,iBAAiB,EAAE,MAAM,EACzB,WAAW,EAAE,sBAAsB,EACnC,mBAAmB,EAAE,OAAO,EAC5B,SAAS,EAAE,CAAC,OAAO,EAAE;IAAE,YAAY,EAAE,MAAM,SAAS,GAAG,iBAAiB,CAAA;CAAE,KAAK,CAAC,GAC/E,CAAC,CA+BH"}

package/dist/core/events/v3/producers/coordination-recorder.js

@@ -1,10 +1,10 @@
 import { createHash, randomUUID } from "node:crypto";
-import { chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
 import { hostname } from "node:os";
-import { join, resolve } from "node:path";
+import { basename, join, resolve } from "node:path";
 import { fsyncParentDirectory } from "../../../workflow/durable-record.js";
 import { acquireNoClobberLease } from "../../../workflow/workspaces/leases.js";
-import { buildAuthorityTransactionV3, publishAuthorityTransactionV3, reconcileAuthorityTransactionV3, } from "../authority-outbox.js";
+import { authorityRecoveryIntentPathV3, buildAuthorityTransactionV3, publishAuthorityTransactionV3, reconcileAuthorityTransactionV3, } from "../authority-outbox.js";
 import { canonicalJsonV3, normalizeNativeIdV3 } from "../canonical.js";
 import { markObservedClockRegressionV3 } from "../clock-order.js";
 import { readEventV3ControlState } from "../control.js";
@@ -13,7 +13,7 @@ import { clockIdV3, spanIdV3 } from "../ids.js";
 import { closeSpanStateV3, openSpanStateV3 } from "../span-state.js";
 import { EVENT_V3_LEDGER_RELATIVE_ROOT } from "../writer.js";
 import { normalizeCoordinationAuthorityV3, } from "./coordination.js";
-import { readHookProducerStateV3 } from "./recorder.js";
+import { readJoinableHookProducerStateV3 } from "./recorder.js";
 const COORDINATION_STATE_FORMAT = "harnery-v3-coordination-producer";
 const COORDINATION_STATE_VERSION = 2;
 const MAX_OBSERVATIONS = 512;
@@ -28,7 +28,7 @@ export function recordCoordinationAuthorityV3(input) {
     const control = readEventV3ControlState(input.coordRoot);
     if (control.state !== input.mode)
         return { state: "gate_closed", reason: control.state };
-    const hook = readHookProducerStateV3(input.coordRoot, input.adapter, input.native_actor_session_id);
+    const hook = readJoinableHookProducerStateV3(input.coordRoot, input.adapter, input.native_actor_session_id, input.actor_instance_id);
     if (!hook ||
         hook.terminal ||
         hook.instance_id !== input.actor_instance_id ||
@@ -37,6 +37,9 @@ export function recordCoordinationAuthorityV3(input) {
     }
     const rootId = control.genesis.event.scope.root_id;
     const epochId = control.genesis.profile.privacy_key_epoch;
+    const epochFence = {
+        expectedGenesisId: control.genesis.event.payload.genesis_id,
+    };
     const rootContext = fingerprintContextV3(input.coordRoot, rootId, undefined, epochId);
     const producerSource = normalizeNativeIdV3(rootContext, "agent-coord.producer", `${input.adapter}\0${input.native_actor_session_id}\0${hook.generation_id}`);
     const sourceId = normalizeNativeIdV3(rootContext, "agent-coord.observation", input.observation.native_observation_id);
@@ -47,7 +50,24 @@ export function recordCoordinationAuthorityV3(input) {
         if (state && !matchesHookState(state, hook, input, epochId)) {
             throw new Error("V3 coordination producer state does not match the joined hook generation");
         }
+        if (state && state.attestation_id !== hook.attestation_id) {
+            // A mid-generation re-attestation (session.attestation_changed) moves
+            // the hook's attestation id without opening a new generation. The
+            // producer keeps its one continuous sequence, clock, and observation
+            // dedupe for the generation and stamps later events with the live
+            // attestation — the same in-place adoption the hook producer performs.
+            // Refusing here would wedge the producer forever, since its state path
+            // is derived from the generation alone and can never be superseded.
+            state.attestation_id = hook.attestation_id;
+        }
         if (state?.pending) {
+            if (existsSync(authorityRecoveryIntentPathV3(input.coordRoot, state.pending.transaction.transaction_id))) {
+                return {
+                    state: "pending_transaction",
+                    transaction_id: state.pending.transaction.transaction_id,
+                    mutation_kind: state.pending.transaction.mutation.kind,
+                };
+            }
             if (state.pending.source_id !== sourceId) {
                 // A writer that died mid-commit leaves `pending` owned by an
                 // observation that will never retry (hook observations are one-shot).
@@ -58,8 +78,8 @@ export function recordCoordinationAuthorityV3(input) {
                 // still refuses rather than guessing at a conflicting mutation.
                 const stale = state.pending;
                 try {
-                    publishAuthorityTransactionV3(input.coordRoot, stale.transaction);
-                    reconcileAuthorityTransactionV3(input.coordRoot, stale.transaction.transaction_id, input.reconciler);
+                    publishAuthorityTransactionV3(input.coordRoot, stale.transaction, epochFence);
+                    reconcileAuthorityTransactionV3(input.coordRoot, stale.transaction.transaction_id, input.reconciler, epochFence);
                 }
                 catch {
                     return {
@@ -74,8 +94,8 @@ export function recordCoordinationAuthorityV3(input) {
             }
             else {
                 const pending = state.pending;
-                publishAuthorityTransactionV3(input.coordRoot, pending.transaction);
-                const receipt = reconcileAuthorityTransactionV3(input.coordRoot, pending.transaction.transaction_id, input.reconciler);
+                publishAuthorityTransactionV3(input.coordRoot, pending.transaction, epochFence);
+                const receipt = reconcileAuthorityTransactionV3(input.coordRoot, pending.transaction.transaction_id, input.reconciler, epochFence);
                 const event = eventFromTransaction(pending.transaction);
                 applyCoordinationEvent(state, pending.source_id, pending.transaction, event);
                 state.pending = undefined;
@@ -168,8 +188,8 @@ export function recordCoordinationAuthorityV3(input) {
             delete state.open_waits[waitId];
         state.pending = { source_id: sourceId, transaction };
         publishCoordinationState(path, state);
-        publishAuthorityTransactionV3(input.coordRoot, transaction);
-        const receipt = reconcileAuthorityTransactionV3(input.coordRoot, transaction.transaction_id, input.reconciler);
+        publishAuthorityTransactionV3(input.coordRoot, transaction, epochFence);
+        const receipt = reconcileAuthorityTransactionV3(input.coordRoot, transaction.transaction_id, input.reconciler, epochFence);
         applyCoordinationEvent(state, sourceId, transaction, normalized.event);
         state.pending = undefined;
         publishCoordinationState(path, state);
@@ -179,6 +199,59 @@ export function recordCoordinationAuthorityV3(input) {
         lease.release();
     }
 }
+/** Locate the one private producer state that owns a pending authority transaction. */
+export function findPendingCoordinationTransactionV3(coordRoot, transactionId) {
+    const directory = coordinationProducerDirectory(coordRoot);
+    if (!existsSync(directory))
+        return null;
+    const matches = readdirSync(directory)
+        .filter((name) => /^hid_[a-f0-9]{64}\.json$/.test(name))
+        .sort()
+        .flatMap((name) => {
+        const state = readCoordinationState(join(directory, name));
+        return state.pending?.transaction.transaction_id === transactionId
+            ? [{ producer_state_file: name, transaction: state.pending.transaction }]
+            : [];
+    });
+    if (matches.length > 1) {
+        throw new Error("authority transaction is pending in more than one coordination producer");
+    }
+    return matches[0] ?? null;
+}
+/** Clear one transaction from its exact producer state after durable quarantine is established. */
+export function withPendingCoordinationTransactionRecoveryV3(coordRoot, producerStateFile, transaction, allowAlreadyCleared, operation) {
+    if (!/^hid_[a-f0-9]{64}\.json$/.test(producerStateFile)) {
+        throw new Error("coordination producer state file is invalid");
+    }
+    const path = join(coordinationProducerDirectory(coordRoot), basename(producerStateFile));
+    if (!existsSync(path))
+        throw new Error("coordination producer state is missing");
+    const lease = acquireCoordinationLease(coordRoot, path);
+    try {
+        const state = readCoordinationState(path);
+        if (!state.pending && !allowAlreadyCleared) {
+            throw new Error("coordination producer no longer owns the pending transaction");
+        }
+        if (state.pending) {
+            if (state.pending.transaction.transaction_id !== transaction.transaction_id ||
+                canonicalJsonV3(state.pending.transaction) !== canonicalJsonV3(transaction)) {
+                throw new Error("coordination producer pending transaction changed during recovery");
+            }
+        }
+        return operation({
+            clearPending: () => {
+                if (!state.pending)
+                    return "already_cleared";
+                state.pending = undefined;
+                publishCoordinationState(path, state);
+                return "cleared";
+            },
+        });
+    }
+    finally {
+        lease.release();
+    }
+}
 function newCoordinationState(input, hook, epochId) {
     return {
         format: COORDINATION_STATE_FORMAT,
@@ -206,7 +279,8 @@ function matchesHookState(state, hook, input, epochId) {
         state.actor_instance_id === input.actor_instance_id &&
         state.session_id === hook.session_id &&
         state.generation_id === hook.generation_id &&
-        state.attestation_id === hook.attestation_id &&
+        // attestation_id is deliberately absent: a re-attestation within the
+        // generation is a continuation, adopted by the caller, not a mismatch.
         state.privacy_epoch_id === epochId &&
         state.producer_id === input.producer_id &&
         state.build_id === input.build_id &&
@@ -229,7 +303,10 @@ function eventFromTransaction(transaction) {
     return JSON.parse(transaction.event_row);
 }
 function coordinationStatePath(coordRoot, producerSource) {
-    return join(resolve(coordRoot), EVENT_V3_LEDGER_RELATIVE_ROOT, "private-producers/agent-coord", `${producerSource}.json`);
+    return join(coordinationProducerDirectory(coordRoot), `${producerSource}.json`);
+}
+function coordinationProducerDirectory(coordRoot) {
+    return join(resolve(coordRoot), EVENT_V3_LEDGER_RELATIVE_ROOT, "private-producers/agent-coord");
 }
 function acquireCoordinationLease(coordRoot, statePath) {
     const directory = join(statePath, "..");

package/dist/core/events/v3/producers/diagnostic-summaries.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Producer-side bound on duplicate diagnostic file creation.
+ *
+ * A producer fault can emit the same diagnostic thousands of times per day,
+ * and every emission used to become one loose file in the diagnostics spool.
+ * This module keeps the first bounded loose exemplars per
+ * (category, reason, instance) key and UTC day unchanged, then coalesces
+ * further identical emissions into one deterministic summary file per key and
+ * window, preserving the exact logical count, first and last times,
+ * represented bytes, hourly rate buckets, and bounded exemplar digests.
+ *
+ * Below the bound the gate creates no state at all: admitted loose filenames
+ * carry the key digest as a suffix, and the gate counts a key's emissions for
+ * the window from those filenames alone. A summary file and its short-lived
+ * per-key lease exist only for a key that actually crossed the bound, so a
+ * healthy spool gains zero files and zero directories from this mitigation.
+ *
+ * The mitigation is fail-open: any count, lease, read, or publish failure
+ * admits the loose diagnostic exactly as before and appends to a lock-free,
+ * size-capped emergency log. It never deletes, moves, or rewrites an existing
+ * loose diagnostic, and it never calls back into the diagnostic writer.
+ */
+export declare const DIAGNOSTIC_SUMMARY_FORMAT: "harnery-v3-diagnostic-summary";
+export declare const DIAGNOSTIC_SUMMARY_VERSION: 1;
+/**
+ * Loose exemplars admitted per (category, reason, instance) key per UTC day
+ * before identical emissions coalesce into the key's summary. Frozen from a
+ * whole-history measurement: healthy categories peak well under this value
+ * per day across ALL keys combined, while a producer fault exceeds it within
+ * minutes. The bound is enforced from filename counts without cross-process
+ * locking, so simultaneous writers straddling the crossing can admit a few
+ * extra exemplars; the bound is a flood stop, not an exact quota.
+ */
+export declare const DIAGNOSTIC_LOOSE_EXEMPLAR_LIMIT = 32;
+export declare const DIAGNOSTIC_MITIGATION_HEALTH_FILE = "mitigation-health.ndjson";
+export interface DiagnosticContentFingerprint {
+    bytes: number;
+    sha256: string;
+}
+export interface DiagnosticGateInputV3 {
+    /** Already sanitized by the diagnostic writer. */
+    category: string;
+    reason?: string;
+    instanceId?: string;
+    fingerprint: DiagnosticContentFingerprint;
+    /** Approved scalar metadata only; stored once per summary. */
+    metadata: Record<string, string | number | boolean | null>;
+}
+export type DiagnosticGateDecisionV3 = {
+    admit: true;
+    /**
+     * Appended to the loose filename before `.json` so future gate calls
+     * can count the key's admitted exemplars from the directory listing.
+     * Empty when the gate is disabled.
+     */
+    loose_name_suffix: string;
+} | {
+    admit: false;
+    /** The summary file the emission was durably coalesced into. */
+    summary_path: string;
+};
+export interface DiagnosticSummaryV3 {
+    format: typeof DIAGNOSTIC_SUMMARY_FORMAT;
+    format_version: typeof DIAGNOSTIC_SUMMARY_VERSION;
+    category: string;
+    reason: string;
+    instance_id: string;
+    /** UTC day this summary covers, as YYYY-MM-DD. */
+    window: string;
+    /** Loose exemplar files observed for the key when the bound was crossed. */
+    loose_count: number;
+    /** Identical emissions coalesced here instead of becoming loose files. */
+    summarized_count: number;
+    first_summarized_at: string | null;
+    last_summarized_at: string | null;
+    /** Sum of content-fingerprint bytes across summarized emissions. */
+    represented_bytes: number;
+    /** Digests of the first summarized emissions, bounded. */
+    exemplars: DiagnosticContentFingerprint[];
+    /** Approved scalar metadata from the first summarized emission. */
+    metadata: Record<string, string | number | boolean | null>;
+    /** Summarized-only counts per UTC hour ("YYYY-MM-DDTHH"), pruned. */
+    recent_hours: Record<string, number>;
+}
+/** Aggregate of the append-only emergency fail-open log. */
+export interface DiagnosticMitigationHealthV3 {
+    fail_open_count: number;
+    last_fail_open_at: string | null;
+    by_stage: Record<string, number>;
+    /** True when the log hit its size cap and later fail-opens were dropped. */
+    truncated: boolean;
+}
+export declare function diagnosticSummariesRootV3(coordRoot: string): string;
+export declare function diagnosticSummariesEnabledV3(): boolean;
+/**
+ * Decide whether one diagnostic emission may become a loose file.
+ *
+ * Below the per-key bound (counted from digest-suffixed loose filenames) the
+ * emission is admitted with the suffix to append, and no summary or lease
+ * state is created. At or past the bound the emission is durably coalesced
+ * into the key's summary under a short per-key lease and `admit: false` is
+ * returned with the summary path. Any mitigation failure, and the disabled
+ * gate, admit the loose write exactly as before.
+ */
+export declare function gateProducerDiagnosticV3(coordRoot: string, input: DiagnosticGateInputV3, nowMs?: number): DiagnosticGateDecisionV3;
+export interface DiagnosticSummaryListingV3 {
+    summaries: DiagnosticSummaryV3[];
+    /** Physical summary files, including any that failed validation. */
+    file_count: number;
+    unreadable_count: number;
+    mitigation_health: DiagnosticMitigationHealthV3 | null;
+}
+/**
+ * Read every summary in the active epoch's `diagnostic-summaries/` subtree.
+ * Skips lease state, temp files, and the mitigation health log (which is
+ * aggregated into `mitigation_health` instead). Never throws; a missing
+ * subtree returns an empty listing.
+ */
+export declare function listDiagnosticSummariesV3(coordRoot: string): DiagnosticSummaryListingV3;
+/**
+ * Sum summarized-only occurrences inside a lookback window, from hour
+ * buckets. Hour-granular and conservative: a bucket is counted only when its
+ * whole hour lies inside `[sinceMs, nowMs]`, so a boundary bucket is excluded
+ * (up to 59 minutes undercounted) rather than fully included (up to 59
+ * minutes overcounted), and a future-dated bucket from clock skew never
+ * inflates a window.
+ */
+export declare function countSummarizedSinceV3(summaries: readonly DiagnosticSummaryV3[], sinceMs: number, filter?: (summary: DiagnosticSummaryV3) => boolean, nowMs?: number): number;
+//# sourceMappingURL=diagnostic-summaries.d.ts.map

package/dist/core/events/v3/producers/diagnostic-summaries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostic-summaries.d.ts","sourceRoot":"","sources":["../../../../../src/core/events/v3/producers/diagnostic-summaries.ts"],"names":[],"mappings":"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"}