harnery 0.34.1 → 0.36.0

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

@@ -4,8 +4,8 @@ import type { TurnHarnessV3, TurnInferenceV3, TurnUsageV3 } from "./contract.js"
 export type TelemetryObservationV3<T> = {
     state: "observed";
     value: T;
-    attestation: "native" | "derived";
-    confidence: "exact" | "high";
+    attestation: "native" | "derived" | "inferred";
+    confidence: "exact" | "high" | "medium" | "low";
 } | {
     state: "unsupported";
     capability: string;
@@ -14,17 +14,31 @@ export type TelemetryObservationV3<T> = {
     capability: string;
     reason: string;
 };
-export interface ContextMeasurementV3 {
-    used_tokens: number;
-    limit_tokens: number;
-    remaining_tokens?: number;
+interface ContextMeasurementClockV3 {
     measured_at: string;
     method: string;
 }
+export type ContextMeasurementV3 = ContextMeasurementClockV3 & ({
+    used_tokens: number;
+    limit_tokens: number;
+    remaining_tokens?: number;
+} | {
+    used_percent: number;
+    remaining_percent?: number;
+});
 export interface TurnTelemetryV3 {
     usage: TelemetryObservationV3<TurnUsageV3>;
     inference: TelemetryObservationV3<TurnInferenceV3>;
     context: TelemetryObservationV3<ContextMeasurementV3>;
+    /** Private producer metadata; the context event persists only its safe fields. */
+    context_provenance?: ContextTelemetryProvenanceV3;
+}
+export interface ContextTelemetryProvenanceV3 {
+    source_event: string;
+    source_witness?: string;
+    runtime_version?: string;
+    attestation: "native" | "derived" | "inferred";
+    confidence: "exact" | "high" | "medium" | "low";
 }
 export type TurnTelemetryCapabilitySupportV3 = Partial<Pick<Record<AdapterSignalV3, CapabilitySupportV3>, "model_usage" | "inference_timing" | "context_usage">>;
 export interface HarnessTimingAccumulatorV3 {
@@ -38,4 +52,5 @@ export declare function extractTurnTelemetryV3(adapter: Adapter, payload: Record
 export declare function emptyHarnessTimingV3(): HarnessTimingAccumulatorV3;
 export declare function recordHarnessTimingV3(accumulator: HarnessTimingAccumulatorV3, hook: string, durationMs: number): HarnessTimingAccumulatorV3;
 export declare function harnessObservationV3(accumulator: HarnessTimingAccumulatorV3): TelemetryObservationV3<TurnHarnessV3>;
+export {};
 //# sourceMappingURL=turn-telemetry.d.ts.map

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

@@ -1 +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"}
+{"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;IACE,KAAK,EAAE,UAAU,CAAC;IAClB,KAAK,EAAE,CAAC,CAAC;IACT,WAAW,EAAE,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAC;IAC/C,UAAU,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;CACjD,GACD;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,UAAU,yBAAyB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,oBAAoB,GAAG,yBAAyB,GAC1D,CACI;IACE,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,GACD;IACE,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CACJ,CAAC;AAEJ,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;IACtD,kFAAkF;IAClF,kBAAkB,CAAC,EAAE,4BAA4B,CAAC;CACnD;AAED,MAAM,WAAW,4BAA4B;IAC3C,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAC;IAC/C,UAAU,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;CACjD;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,CAyFjB;AA+DD,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

@@ -40,9 +40,11 @@ export function extractTurnTelemetryV3(adapter, payload, observedAt = new Date()
         }
         : missing(adapter, "inference_timing", support.inference_timing);
     const usedTokens = number(context?.used_tokens) ??
+        number(context?.context_tokens) ??
         number(context?.input_tokens) ??
         number(context?.total_tokens) ??
         number(payload.used_tokens) ??
+        number(payload.context_tokens) ??
         number(payload.total_input_tokens) ??
         number(usage?.total_tokens) ??
         number(usage?.prompt_tokens) ??
@@ -60,10 +62,15 @@ export function extractTurnTelemetryV3(adapter, payload, observedAt = new Date()
         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);
+    const usedPercent = finiteNumber(context?.context_usage_percent) ??
+        finiteNumber(context?.used_percent) ??
+        finiteNumber(context?.used_percentage) ??
+        finiteNumber(payload.context_usage_percent) ??
+        finiteNumber(payload.used_percent);
+    const contextMeasurement = contextObservation(adapter, usedTokens, limitTokens, usedPercent, observedAt, support.context_usage);
     return { usage: usageObservation, inference: inferenceObservation, context: contextMeasurement };
 }
-function contextObservation(adapter, usedTokens, limitTokens, observedAt, override) {
+function contextObservation(adapter, usedTokens, limitTokens, usedPercent, observedAt, override) {
     if (usedTokens !== undefined && limitTokens !== undefined && limitTokens > 0) {
         return {
             state: "observed",
@@ -78,6 +85,26 @@ function contextObservation(adapter, usedTokens, limitTokens, observedAt, overri
             confidence: "exact",
         };
     }
+    if (usedPercent !== undefined && usedPercent >= 0 && usedPercent <= 100) {
+        return {
+            state: "observed",
+            value: {
+                used_percent: usedPercent,
+                remaining_percent: Math.max(0, 100 - usedPercent),
+                measured_at: observedAt,
+                method: `${adapter.replaceAll("-", "_")}_hook`,
+            },
+            attestation: "native",
+            confidence: "exact",
+        };
+    }
+    if (usedPercent !== undefined) {
+        return {
+            state: "expected_but_missing",
+            capability: "context_usage",
+            reason: "context_usage_percent_invalid",
+        };
+    }
     if (usedTokens !== undefined || limitTokens !== undefined) {
         return {
             state: "expected_but_missing",
@@ -151,6 +178,9 @@ function record(value) {
 function number(value) {
     return typeof value === "number" ? safeInteger(value) : undefined;
 }
+function finiteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
 function safeInteger(value) {
     return Number.isFinite(value) && value >= 0 ? Math.floor(value) : undefined;
 }

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

@@ -2,7 +2,7 @@ import type { EventV3 } from "./contract.js";
 export declare const EVENT_V3_LEDGER_RELATIVE_ROOT: ".harnery/ledgers/v3";
 export type EventV3DurabilityState = "committed" | "ready";
 export interface WriteEventV3Result {
-    state: EventV3DurabilityState;
+    state: EventV3DurabilityState | "epoch_replaced";
     event_id: string;
     row_digest: `sha256:${string}`;
     ready_path?: string;
@@ -17,6 +17,16 @@ export interface WriteEventV3Options {
      * the option exists for matched harness-cost experiments.
      */
     deferDrain?: boolean;
+    /**
+     * Epoch fence: the genesis id of the epoch this event was produced for.
+     * An event carries per-epoch authority (producer boot sequences start at 1
+     * and every causal link must resolve inside its own epoch), so committing
+     * it into a replaced epoch would poison the new authority. When set, the
+     * write refuses with `epoch_replaced` if the live genesis no longer
+     * matches, the spooled ready row is tagged with the id, and the drain
+     * quarantines any tagged row whose epoch has been replaced underneath it.
+     */
+    expectedGenesisId?: `gex_${string}`;
     now?: () => number;
     onStep?: (step: EventV3WriteStep, eventId?: string) => void;
 }
@@ -34,6 +44,7 @@ export declare function drainReadyEventsV3(coordRoot: string, options?: WriteEve
 export declare function withEventV3LedgerLease<T>(coordRoot: string, options: WriteEventV3Options, operation: () => T): T;
 export declare function drainReadyEventsUnderLeaseV3(paths: ReturnType<typeof eventV3Paths>, options?: WriteEventV3Options): number;
 export declare function eventV3Paths(coordRoot: string): {
+    coordRoot: string;
     root: string;
     active: string;
     catalog: string;
@@ -44,6 +55,7 @@ export declare function eventV3Paths(coordRoot: string): {
     lease: string;
 };
 export declare function ensureEventV3Layout(coordRoot: string): {
+    coordRoot: string;
     root: string;
     active: string;
     catalog: string;

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

@@ -1 +1 @@
-{"version":3,"file":"writer.d.ts","sourceRoot":"","sources":["../../../../src/core/events/v3/writer.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAO7C,eAAO,MAAM,6BAA6B,EAAG,qBAA8B,CAAC;AAE5E,MAAM,MAAM,sBAAsB,GAAG,WAAW,GAAG,OAAO,CAAC;AAE3D,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,sBAAsB,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,UAAU,MAAM,EAAE,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,kBAAkB,CAAC;CACtC;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,gBAAgB,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7D;AAED,MAAM,MAAM,gBAAgB,GACxB,oBAAoB,GACpB,iBAAiB,GACjB,sBAAsB,GACtB,qBAAqB,GACrB,oBAAoB,GACpB,mBAAmB,GACnB,iBAAiB,CAAC;AAEtB;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,mBAAwB,GAChC,kBAAkB,CA4CpB;AAED,sEAAsE;AACtE,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,MAAM,CAK/F;AAED,wBAAgB,sBAAsB,CAAC,CAAC,EACtC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,mBAAmB,EAC5B,SAAS,EAAE,MAAM,CAAC,GACjB,CAAC,CAoBH;AAED,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,UAAU,CAAC,OAAO,YAAY,CAAC,EACtC,OAAO,GAAE,mBAAwB,GAChC,MAAM,CA2CR;AAsDD,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM;;;;;;;;;EAY7C;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM;;;;;;;;;EA8BpD"}
+{"version":3,"file":"writer.d.ts","sourceRoot":"","sources":["../../../../src/core/events/v3/writer.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAa7C,eAAO,MAAM,6BAA6B,EAAG,qBAA8B,CAAC;AAE5E,MAAM,MAAM,sBAAsB,GAAG,WAAW,GAAG,OAAO,CAAC;AAE3D,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,sBAAsB,GAAG,gBAAgB,CAAC;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,UAAU,MAAM,EAAE,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,kBAAkB,CAAC;CACtC;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;;;OAQG;IACH,iBAAiB,CAAC,EAAE,OAAO,MAAM,EAAE,CAAC;IACpC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,gBAAgB,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7D;AAED,MAAM,MAAM,gBAAgB,GACxB,oBAAoB,GACpB,iBAAiB,GACjB,sBAAsB,GACtB,qBAAqB,GACrB,oBAAoB,GACpB,mBAAmB,GACnB,iBAAiB,CAAC;AAEtB;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,mBAAwB,GAChC,kBAAkB,CAoDpB;AAED,sEAAsE;AACtE,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,MAAM,CAK/F;AAED,wBAAgB,sBAAsB,CAAC,CAAC,EACtC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,mBAAmB,EAC5B,SAAS,EAAE,MAAM,CAAC,GACjB,CAAC,CAoBH;AAED,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,UAAU,CAAC,OAAO,YAAY,CAAC,EACtC,OAAO,GAAE,mBAAwB,GAChC,MAAM,CA4DR;AAkID,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM;;;;;;;;;;EAc7C;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM;;;;;;;;;;EA8BpD"}

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

@@ -5,7 +5,10 @@ import { join, resolve } from "node:path";
 import { fsyncParentDirectory } from "../../workflow/durable-record.js";
 import { acquireNoClobberLease } from "../../workflow/workspaces/leases.js";
 import { canonicalJsonV3, sha256V3 } from "./canonical.js";
+import { genesisIdFromManifestV3, liveGenesisIdV3 } from "./control.js";
+import { advanceControlWitnessV3, readAdvanceableControlWitnessV3 } from "./control-witness.js";
 import { EVENT_V3_SCHEMA_DIGEST } from "./generated.js";
+import { readEventV3AppendValidationCheckpointV3, } from "./reader.js";
 import { assertEventV3 } from "./validate.js";
 const MAX_LINE_BYTES = 16 * 1024;
 const DEFAULT_LEASE_MS = 5_000;
@@ -29,7 +32,11 @@ export function writeEventV3(coordRoot, event, options = {}) {
     }
     const paths = ensureEventV3Layout(coordRoot);
     const rowDigest = sha256V3(row);
-    const readyName = `${String(event.producer.sequence).padStart(16, "0")}-${event.event_id}-${rowDigest.slice(7)}.ready`;
+    if (options.expectedGenesisId && liveGenesisIdV3(coordRoot) !== options.expectedGenesisId) {
+        return { state: "epoch_replaced", event_id: event.event_id, row_digest: rowDigest };
+    }
+    const epochTag = options.expectedGenesisId ? `-${options.expectedGenesisId}` : "";
+    const readyName = `${String(event.producer.sequence).padStart(16, "0")}-${event.event_id}-${rowDigest.slice(7)}${epochTag}.ready`;
     const readyPath = join(paths.spool, readyName);
     writeReadyRecord(paths.spool, readyPath, row, event.event_id, options.onStep);
     if (options.deferDrain) {
@@ -52,14 +59,18 @@ export function writeEventV3(coordRoot, event, options = {}) {
             diagnostic_code: "wal_drain_failed",
         };
     }
-    return existsSync(readyPath)
-        ? {
+    if (existsSync(readyPath)) {
+        return {
             state: "ready",
             event_id: event.event_id,
             row_digest: rowDigest,
             ready_path: readyPath,
-        }
-        : { state: "committed", event_id: event.event_id, row_digest: rowDigest };
+        };
+    }
+    if (existsSync(`${readyPath.slice(0, -".ready".length)}.epoch-replaced`)) {
+        return { state: "epoch_replaced", event_id: event.event_id, row_digest: rowDigest };
+    }
+    return { state: "committed", event_id: event.event_id, row_digest: rowDigest };
 }
 /** Drain every durable ready record under the fenced append lease. */
 export function drainReadyEventsV3(coordRoot, options = {}) {
@@ -89,8 +100,12 @@ export function withEventV3LedgerLease(coordRoot, options, operation) {
     }
 }
 export function drainReadyEventsUnderLeaseV3(paths, options = {}) {
+    let priorWitness = readAdvanceableControlWitnessV3(paths.coordRoot);
     if (repairUnterminatedActiveFrame(paths.active)) {
         options.onStep?.("active_tail_repaired");
+        // The repair can remove IDs that the old witness considered committed.
+        // Never use that stale checkpoint to release a dependent ready row.
+        priorWitness = undefined;
     }
     requeueCommittedReceipts(paths.spool);
     const readyNames = readdirSync(paths.spool)
@@ -98,7 +113,11 @@ export function drainReadyEventsUnderLeaseV3(paths, options = {}) {
         .sort();
     if (readyNames.length === 0)
         return 0;
-    const readyRows = causallyOrderedReadyRows(readyNames.map((readyName) => {
+    const drainableNames = quarantineReplacedEpochRows(paths, readyNames);
+    if (drainableNames.length === 0)
+        return 0;
+    const checkpoint = priorWitness?.checkpoint ?? readEventV3AppendValidationCheckpointV3(paths.coordRoot);
+    const readyRows = causallyOrderedReadyRows(drainableNames.map((readyName) => {
         const readyPath = join(paths.spool, readyName);
         const row = readAndValidateReadyRow(readyPath);
         return {
@@ -107,7 +126,9 @@ export function drainReadyEventsUnderLeaseV3(paths, options = {}) {
             row,
             event: JSON.parse(row),
         };
-    }));
+    }), checkpoint?.genesis_id ? checkpoint : undefined);
+    if (readyRows.length === 0)
+        return 0;
     const activeFd = openSync(paths.active, "a", 0o600);
     let committed = 0;
     try {
@@ -130,14 +151,51 @@ export function drainReadyEventsUnderLeaseV3(paths, options = {}) {
     finally {
         closeSync(activeFd);
     }
+    if (committed > 0 && priorWitness) {
+        advanceControlWitnessV3(paths.coordRoot, priorWitness, genesisIdFromManifestV3(join(paths.root, "genesis.json")));
+    }
     return committed;
 }
 /**
- * Keep the spool's deterministic filename order except where a ready event
- * names another ready event as a cause. Those dependencies are committed
- * first; a cycle stays in the WAL and never poisons the active authority.
+ * Keep the spool's deterministic filename order except where an event depends
+ * on an uncommitted cause or attestation declaration. The authenticated
+ * checkpoint proves what the active authority already contains; rows whose
+ * prerequisite has not reached either the authority or this ready batch stay
+ * in the WAL. This covers the cross-process window where a dependent row is
+ * published before the row that mints its attestation.
  */
-function causallyOrderedReadyRows(rows) {
+function causallyOrderedReadyRows(rows, checkpoint) {
+    // Bare writer fixtures and pre-genesis bootstrap rows have no semantic
+    // authority to consult. Preserve the original within-batch causal ordering;
+    // once a genesis exists, the validated checkpoint becomes the writer fence.
+    if (!checkpoint)
+        return causallyOrderedReadyRowsWithinBatch(rows);
+    const pending = new Map(rows.map((row) => [row.event.event_id, row]));
+    const ordered = [];
+    const committedEventIds = new Set(checkpoint.seen_event_ids);
+    const committedAttestationIds = new Set(checkpoint.attestation_ids);
+    while (pending.size > 0) {
+        const next = rows.find(({ event }) => {
+            const causes = event.links.caused_by;
+            return (pending.has(event.event_id) &&
+                causes.every((eventId) => committedEventIds.has(eventId)) &&
+                attestationPrerequisitesV3(event).every((attestationId) => committedAttestationIds.has(attestationId)));
+        });
+        if (!next)
+            break;
+        pending.delete(next.event.event_id);
+        ordered.push(next);
+        committedEventIds.add(next.event.event_id);
+        const minted = mintedAttestationV3(next.event);
+        if (minted)
+            committedAttestationIds.add(minted);
+    }
+    if (pending.size > 0 && dependenciesResolveInsidePendingV3(pending, committedEventIds)) {
+        throw new Error("ready V3 events contain a causal dependency cycle");
+    }
+    return ordered;
+}
+function causallyOrderedReadyRowsWithinBatch(rows) {
     const pending = new Map(rows.map((row) => [row.event.event_id, row]));
     const ordered = [];
     while (pending.size > 0) {
@@ -152,6 +210,31 @@ function causallyOrderedReadyRows(rows) {
     }
     return ordered;
 }
+function mintedAttestationV3(event) {
+    return event.event_type === "session.started" ||
+        event.event_type === "session.attestation_changed"
+        ? event.attestation_id
+        : undefined;
+}
+function attestationPrerequisitesV3(event) {
+    if (event.event_type === "session.started")
+        return [];
+    if (event.event_type === "session.attestation_changed") {
+        return [event.payload.prior_attestation_id];
+    }
+    return event.attestation_id ? [event.attestation_id] : [];
+}
+function dependenciesResolveInsidePendingV3(pending, committedEventIds) {
+    const pendingAttestations = new Set([...pending.values()]
+        .map(({ event }) => mintedAttestationV3(event))
+        .filter((value) => value !== undefined));
+    return [...pending.values()].every(({ event }) => {
+        const causes = event.links.caused_by;
+        const causesStayInside = causes.every((eventId) => committedEventIds.has(eventId) || pending.has(eventId));
+        const attestationsStayInside = attestationPrerequisitesV3(event).every((attestationId) => pendingAttestations.has(attestationId));
+        return causesStayInside && attestationsStayInside;
+    });
+}
 /**
  * A `.committed` receipt is created only after the active row is flushed. If
  * the process dies before unlinking it, replaying the exact canonical row is
@@ -178,8 +261,10 @@ function requeueCommittedReceipts(spool) {
     }
 }
 export function eventV3Paths(coordRoot) {
-    const root = join(resolve(coordRoot), EVENT_V3_LEDGER_RELATIVE_ROOT);
+    const resolvedCoordRoot = resolve(coordRoot);
+    const root = join(resolvedCoordRoot, EVENT_V3_LEDGER_RELATIVE_ROOT);
     return {
+        coordRoot: resolvedCoordRoot,
         root,
         active: join(root, "active.ndjson"),
         catalog: join(root, "catalog.json"),
@@ -302,6 +387,35 @@ function eventIdFromReadyName(name) {
     const match = name.match(/^\d{16}-(evt_[0-9a-f-]{36})-/);
     return match?.[1];
 }
+function epochTagFromReadyName(name) {
+    const match = name.match(/-(gex_[0-9a-f-]{36})\.ready$/);
+    return match ? match[1] : undefined;
+}
+/**
+ * Move every ready row tagged with a replaced epoch out of the drainable
+ * spool. A tagged row was produced for exactly one epoch; committing it into
+ * a successor would break that epoch's boot-sequence and causal-link
+ * authority, so the row is preserved beside the spool as `.epoch-replaced`
+ * evidence instead of ever reaching the active file.
+ */
+function quarantineReplacedEpochRows(paths, readyNames) {
+    if (!readyNames.some((name) => epochTagFromReadyName(name) !== undefined))
+        return readyNames;
+    const liveGenesisId = genesisIdFromManifestV3(join(paths.root, "genesis.json"));
+    const drainable = [];
+    for (const name of readyNames) {
+        const tag = epochTagFromReadyName(name);
+        if (tag === undefined || tag === liveGenesisId) {
+            drainable.push(name);
+            continue;
+        }
+        const readyPath = join(paths.spool, name);
+        const quarantinePath = `${readyPath.slice(0, -".ready".length)}.epoch-replaced`;
+        renameSync(readyPath, quarantinePath);
+        fsyncParentDirectory(quarantinePath);
+    }
+    return drainable;
+}
 function readFileTail(fd, buffer, position) {
     let read = 0;
     while (read < buffer.length) {

package/dist/core/governor/plan-read.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plan-read.d.ts","sourceRoot":"","sources":["../../../src/core/governor/plan-read.ts"],"names":[],"mappings":"AAIA,OAAO,EAIL,KAAK,mBAAmB,EAExB,KAAK,kBAAkB,EAGvB,KAAK,yBAAyB,EAQ/B,MAAM,iBAAiB,CAAC;AA0BzB,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,kBAAkB,EAAE,MAAM,GACzB,mBAAmB,CAwErB;AAED,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,kBAAkB,CAsBpB;AAED,wBAAgB,6BAA6B,CAC3C,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,yBAAyB,GAAG,SAAS,CAWvC"}
+{"version":3,"file":"plan-read.d.ts","sourceRoot":"","sources":["../../../src/core/governor/plan-read.ts"],"names":[],"mappings":"AAKA,OAAO,EAIL,KAAK,mBAAmB,EAExB,KAAK,kBAAkB,EAGvB,KAAK,yBAAyB,EAQ/B,MAAM,iBAAiB,CAAC;AAwBzB,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,kBAAkB,EAAE,MAAM,GACzB,mBAAmB,CAwErB;AAED,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,kBAAkB,CAsBpB;AAED,wBAAgB,6BAA6B,CAC3C,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,yBAAyB,GAAG,SAAS,CAWvC"}

package/dist/core/governor/plan-read.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { readSegmentedJsonlFileSync } from "../storage/durable-history.js";
 import { readWorkItem } from "../work/read.js";
 import { GOVERNOR_PLAN_SCHEMA_VERSION, MAX_GOVERNOR_PLAN_REVIEWERS, MAX_GOVERNOR_PLAN_REVISION_ROUNDS, } from "./plan-types.js";
 const PLAN_ID = /^plan-[0-9]{4}-[a-f0-9]{8}$/;
@@ -11,8 +12,6 @@ const PLAN_KEY = /^[a-z][a-z0-9-]{0,31}$/;
 const TEMPLATE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
 const MAX_PLANS = 100;
 const MAX_RECORD_BYTES = 256 * 1024;
-const MAX_EVENTS_BYTES = 512 * 1024;
-const MAX_EVENTS = 100;
 const EVENT_TYPES = new Set([
     "plan.awaiting_approval",
     "plan.resumed",
@@ -192,25 +191,10 @@ function deriveStatus(coordRoot, events, proposal) {
     return { status: "interrupted", work_ids: [], reason: latest?.reason };
 }
 function readEvents(path, planId) {
-    if (!existsSync(path))
-        return [];
-    const size = statSync(path).size;
-    if (size > MAX_EVENTS_BYTES)
-        throw new Error("governor plan events exceed their byte limit");
-    const body = readFileSync(path, "utf8");
-    if (body && !body.endsWith("\n"))
-        throw new Error(`governor plan ${planId} has a partial event`);
-    const lines = body.split("\n").filter(Boolean);
-    if (lines.length > MAX_EVENTS)
-        throw new Error(`governor plan exceeds ${MAX_EVENTS} events`);
-    return lines.map((line, index) => {
-        let event;
-        try {
-            event = JSON.parse(line);
-        }
-        catch (error) {
-            throw new Error(`cannot parse governor plan ${planId} event ${index + 1}: ${error.message}`);
-        }
+    return readSegmentedJsonlFileSync(path, {
+        max_record_bytes: MAX_RECORD_BYTES,
+        max_records: 1_000_000,
+    }).map((event, index) => {
         validateEvent(event, planId, index + 1);
         return event;
     });

package/dist/core/governor/planning.js

@@ -1,6 +1,7 @@
 import { createHash, randomBytes, randomUUID } from "node:crypto";
-import { appendFileSync, chmodSync, existsSync, linkSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { chmodSync, existsSync, linkSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
 import { dirname, join, resolve } from "node:path";
+import { appendSegmentedJsonlFile } from "../storage/durable-history.js";
 import { createWorkItem, readWorkItem } from "../work/index.js";
 import { digestResult, readWorkflowProof, runWorkflow, WorkflowParkedError, workflowScriptDigest, } from "../workflow/index.js";
 import { readGovernorPlan, readGovernorPlanReviewReceipt, readGovernorPlans } from "./plan-read.js";
@@ -1253,13 +1254,10 @@ function appendPlanEvent(coordRootRaw, goalId, planId, input) {
         actor: bounded(input.actor, "plan actor", 200),
         reason: bounded(input.reason, "plan reason", MAX_REASON),
     };
-    const line = `${JSON.stringify(event)}\n`;
-    const existing = existsSync(path) ? statSync(path).size : 0;
-    if (existing + Buffer.byteLength(line) > MAX_EVENTS_BYTES) {
-        throw new Error("governor plan event log would exceed its byte limit");
-    }
-    appendFileSync(path, line, { encoding: "utf8", mode: 0o600 });
-    chmodSync(path, 0o600);
+    appendSegmentedJsonlFile(path, event, {
+        max_record_bytes: MAX_RECORD_BYTES,
+        max_segment_bytes: MAX_EVENTS_BYTES,
+    });
 }
 function appendPlanEventIfMissing(coordRoot, goalId, planId, eventType, input) {
     const plan = readGovernorPlan(coordRoot, goalId, planId);

package/dist/core/governor/service-read.d.ts

@@ -3,4 +3,16 @@ export declare function readGovernorServiceConfig(coordRootRaw: string): Governo
 export declare function readGovernorServiceRuntime(coordRootRaw: string): GovernorServiceRuntime | undefined;
 export declare function readGovernorServiceStatus(coordRootRaw: string): GovernorServiceStatus;
 export declare function governorServiceLogPath(coordRoot: string): string;
+export interface GovernorServiceLogReadOptions {
+    max_bytes?: number;
+    max_records?: number;
+}
+export interface GovernorServiceLogReadResult {
+    lines: readonly string[];
+    bytes_read: number;
+    records_examined: number;
+    truncated: boolean;
+}
+/** Read shared generations plus untouched legacy history under one aggregate budget. */
+export declare function readGovernorServiceLogs(coordRootRaw: string, options?: GovernorServiceLogReadOptions): GovernorServiceLogReadResult;
 //# sourceMappingURL=service-read.d.ts.map

package/dist/core/governor/service-read.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service-read.d.ts","sourceRoot":"","sources":["../../../src/core/governor/service-read.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,qBAAqB,EACrB,sBAAsB,EACtB,qBAAqB,EAEtB,MAAM,cAAc,CAAC;AAMtB,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,MAAM,GAAG,qBAAqB,CA0BrF;AAED,wBAAgB,0BAA0B,CACxC,YAAY,EAAE,MAAM,GACnB,sBAAsB,GAAG,SAAS,CAgBpC;AAED,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,MAAM,GAAG,qBAAqB,CAkBrF;AAED,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEhE"}
+{"version":3,"file":"service-read.d.ts","sourceRoot":"","sources":["../../../src/core/governor/service-read.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EACV,qBAAqB,EACrB,sBAAsB,EACtB,qBAAqB,EAEtB,MAAM,cAAc,CAAC;AAOtB,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,MAAM,GAAG,qBAAqB,CA0BrF;AAED,wBAAgB,0BAA0B,CACxC,YAAY,EAAE,MAAM,GACnB,sBAAsB,GAAG,SAAS,CAgBpC;AAED,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,MAAM,GAAG,qBAAqB,CAkBrF;AAED,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAahE;AAED,MAAM,WAAW,6BAA6B;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,4BAA4B;IAC3C,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,OAAO,CAAC;CACpB;AAeD,wFAAwF;AACxF,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,6BAAkC,GAC1C,4BAA4B,CA6D9B"}