@aztec/prover-node 0.0.1-commit.2f68f620 → 0.0.1-commit.321f6a9

package/dest/session-manager.d.ts

@@ -0,0 +1,158 @@
+import { type EpochNumber } from '@aztec/foundation/branded-types';
+import type { EthAddress } from '@aztec/foundation/eth-address';
+import { type LoggerBindings } from '@aztec/foundation/log';
+import type { DateProvider } from '@aztec/foundation/timer';
+import type { EpochProverFactory } from '@aztec/prover-client';
+import type { L2BlockSource } from '@aztec/stdlib/block';
+import type { EpochProvingJobState } from '@aztec/stdlib/interfaces/server';
+import type { CheckpointStore } from './checkpoint-store.js';
+import { CheckpointProver } from './job/checkpoint-prover.js';
+import type { EpochProvingJobData } from './job/epoch-proving-job-data.js';
+import { EpochSession, type EpochSessionDeps, type EpochSessionHooks, type SessionSpec } from './job/epoch-session.js';
+import type { ProverNodeJobMetrics } from './metrics.js';
+import type { ProofPublishingService } from './proof-publishing-service.js';
+/** Trigger payload for `reconcile`. */
+export type ReconcileTrigger = {
+    kind: 'checkpoint';
+    epoch: EpochNumber;
+} | {
+    kind: 'prune';
+    affectedEpochs: EpochNumber[];
+} | {
+    kind: 'tick';
+} | {
+    kind: 'start-proof';
+    spec: SessionSpec;
+};
+/** Config bag for session lifecycle decisions. */
+export type SessionManagerConfig = {
+    /** Cap on the number of non-terminal sessions (full + partial). 0 disables. */
+    maxPendingJobs: number;
+    /** Interval at which the internal periodic tick fires `reconcile({ kind: 'tick' })`. */
+    tickIntervalMs: number;
+    /** Forwarded to every session: delay before top-tree proving, letting late reorgs settle. */
+    finalizationDelayMs: number | undefined;
+};
+export type SessionManagerDeps = {
+    checkpointStore: CheckpointStore;
+    l2BlockSource: Pick<L2BlockSource, 'isEpochComplete' | 'getCheckpoints' | 'getL1Constants' | 'getBlockNumber' | 'getBlockData'>;
+    proverFactory: EpochProverFactory;
+    proverId: EthAddress;
+    publishingService: ProofPublishingService;
+    metrics: ProverNodeJobMetrics;
+    dateProvider: DateProvider;
+    config: SessionManagerConfig;
+    /**
+     * Fired once when a full session ends in its own genuine failure (`EpochSession.hasFailed()` — top-tree
+     * or submit failed with every prover healthy). The owner uploads a post-mortem here. Not fired for a
+     * `stopped` session (a prover under it failed — possibly a prune), which is recovered on re-add instead.
+     */
+    onSessionFailed?: (session: EpochSession) => Promise<void>;
+    bindings?: LoggerBindings;
+};
+/**
+ * Owns the lifecycle of every `EpochSession`. Each L2BlockStream event and periodic tick
+ * arrives via a dedicated entry point (`onCheckpointAdded`, `onPrune`, `onTick`, etc.) which
+ * schedules a `reconcile(trigger)` on a serial queue. Reconcile walks both session
+ * maps, cancels any session whose canonical content has shifted, re-creates it with
+ * the same spec but new content, and opens fresh full sessions for any epoch implicated
+ * by the trigger.
+ */
+export declare class SessionManager {
+    private readonly deps;
+    private readonly log;
+    private readonly fullSessions;
+    private readonly partialSessions;
+    /**
+     * Serialises every reconcile call. The trigger sources (L2BlockStream events, the
+     * periodic tick, JSON-RPC `startProof`) run independently, so without this queue two
+     * reconciles could interleave on the `await session.cancel(...)` step and orphan a
+     * freshly-constructed session.
+     */
+    private readonly reconcileQueue;
+    /** Cached L1 constants, populated on first read. */
+    private cachedL1Constants;
+    /** Test-only hooks applied to every session this manager constructs. */
+    private sessionHooks;
+    /** Periodic tick that nudges reconcile to pick up newly-complete epochs. Started by `start()`. */
+    private epochTicker;
+    constructor(deps: SessionManagerDeps);
+    /**
+     * Starts the periodic tick. Separated from the constructor so tests can drive `onTick()`
+     * manually without the background ticker interleaving. Idempotent.
+     */
+    start(): void;
+    /**
+     * Installs hooks applied to every session constructed from now on. Used by the e2e
+     * harness to interpose around top-tree proving (gate it, override it, observe it)
+     * without monkey-patching the orchestrator factory.
+     */
+    setSessionHooks(hooks: EpochSessionHooks): void;
+    /** Every live (non-terminal) session. */
+    allSessions(): EpochSession[];
+    /** Returns the full session for `epoch`, if any. */
+    getFullSession(epoch: EpochNumber): EpochSession | undefined;
+    /** Returns the partial session for `spec`, if any. */
+    getPartialSession(spec: SessionSpec): EpochSession | undefined;
+    /** Observability summary used by the prover-node API. */
+    getJobs(): {
+        uuid: string;
+        status: EpochProvingJobState;
+        epochNumber: EpochNumber;
+    }[];
+    /** Called by ProverNode after a chain-checkpointed event has been added to the store. */
+    onCheckpointAdded(epoch: EpochNumber): Promise<void>;
+    /** Called by ProverNode after a chain-pruned event has flipped store provers to pruned. */
+    onPrune(affectedEpochs: EpochNumber[]): Promise<void>;
+    /**
+     * Called periodically by ProverNode's ticker. Picks up epochs that have become complete
+     * by time without a fresh checkpoint event (e.g. the epoch's last slots are empty), and
+     * advances to the next epoch once the previous one is proven on L1.
+     */
+    onTick(): Promise<void>;
+    /**
+     * Schedules a proof attempt for the supplied epoch and returns the job id without waiting for
+     * the proof to complete — proving can far outlast an HTTP request, so callers poll `getJobs()`
+     * for the outcome. Every session — full or partial — begins at the epoch's first slot; the
+     * partial's spec stops at the last canonical slot, while the full's stops at the epoch's last
+     * slot. Dedupes against any existing session covering the same range, returning its id.
+     */
+    startProof(epoch: EpochNumber): Promise<string>;
+    /** Stops the tick, drains the reconcile queue, and cancels every live session. */
+    stop(): Promise<void>;
+    private scheduleReconcile;
+    private reconcile;
+    private recreateInvalidSessions;
+    /** A session may be built over a checkpoint set only when it is non-empty and contains no failed prover. */
+    private canBuildOver;
+    private openFullSessionIfReady;
+    private openPartialSession;
+    protected constructSession(spec: SessionSpec, checkpoints: readonly CheckpointProver[]): EpochSession;
+    /** Extracted for test override. */
+    protected doConstructSession(spec: SessionSpec, checkpoints: readonly CheckpointProver[], sessionDeps: EpochSessionDeps, hooks?: EpochSessionHooks): EpochSession;
+    private buildSessionDeps;
+    private computeDeadline;
+    private runSession;
+    /**
+     * Builds the EpochProvingJobData snapshot for a post-mortem failure upload from a set of
+     * checkpoint provers. Includes every checkpoint regardless of whether sub-tree proving
+     * completed — partial state is still useful for post-mortem analysis.
+     */
+    static buildProvingData(checkpoints: readonly CheckpointProver[]): EpochProvingJobData;
+    private atMaxSessionLimit;
+    private epochsForTrigger;
+    private nextUnprovenEpoch;
+    private checkpointsForSpec;
+    /**
+     * True if any prover in the set has failed. The epoch cannot be proven over a failed prover (it can
+     * never produce its block proofs), so a session must not be built or rebuilt over it until a prune/re-add
+     * has replaced it with a fresh prover.
+     */
+    private hasFailedProver;
+    private fireAndForgetCancel;
+    private checkpointsMatch;
+    private archiverFullyCovered;
+    private isProvenChainEncompassing;
+    private getL1Constants;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2Vzc2lvbi1tYW5hZ2VyLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvc2Vzc2lvbi1tYW5hZ2VyLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFBZSxLQUFLLFdBQVcsRUFBRSxNQUFNLGlDQUFpQyxDQUFDO0FBRWhGLE9BQU8sS0FBSyxFQUFFLFVBQVUsRUFBRSxNQUFNLCtCQUErQixDQUFDO0FBQ2hFLE9BQU8sRUFBZSxLQUFLLGNBQWMsRUFBZ0IsTUFBTSx1QkFBdUIsQ0FBQztBQUd2RixPQUFPLEtBQUssRUFBRSxZQUFZLEVBQUUsTUFBTSx5QkFBeUIsQ0FBQztBQUM1RCxPQUFPLEtBQUssRUFBRSxrQkFBa0IsRUFBRSxNQUFNLHNCQUFzQixDQUFDO0FBQy9ELE9BQU8sS0FBSyxFQUFFLGFBQWEsRUFBRSxNQUFNLHFCQUFxQixDQUFDO0FBUXpELE9BQU8sS0FBSyxFQUFFLG9CQUFvQixFQUFFLE1BQU0saUNBQWlDLENBQUM7QUFFNUUsT0FBTyxLQUFLLEVBQUUsZUFBZSxFQUFFLE1BQU0sdUJBQXVCLENBQUM7QUFDN0QsT0FBTyxFQUFFLGdCQUFnQixFQUFFLE1BQU0sNEJBQTRCLENBQUM7QUFDOUQsT0FBTyxLQUFLLEVBQUUsbUJBQW1CLEVBQUUsTUFBTSxpQ0FBaUMsQ0FBQztBQUMzRSxPQUFPLEVBQ0wsWUFBWSxFQUNaLEtBQUssZ0JBQWdCLEVBQ3JCLEtBQUssaUJBQWlCLEVBRXRCLEtBQUssV0FBVyxFQUVqQixNQUFNLHdCQUF3QixDQUFDO0FBQ2hDLE9BQU8sS0FBSyxFQUFFLG9CQUFvQixFQUFFLE1BQU0sY0FBYyxDQUFDO0FBQ3pELE9BQU8sS0FBSyxFQUFFLHNCQUFzQixFQUFFLE1BQU0sK0JBQStCLENBQUM7QUFFNUUsdUNBQXVDO0FBQ3ZDLE1BQU0sTUFBTSxnQkFBZ0IsR0FDeEI7SUFBRSxJQUFJLEVBQUUsWUFBWSxDQUFDO0lBQUMsS0FBSyxFQUFFLFdBQVcsQ0FBQTtDQUFFLEdBQzFD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

package/dest/session-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-manager.d.ts","sourceRoot":"","sources":["../src/session-manager.ts"],"names":[],"mappings":"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"}

package/dest/session-manager.js

@@ -0,0 +1,486 @@
+import { BlockNumber } from '@aztec/foundation/branded-types';
+import { createLogger } from '@aztec/foundation/log';
+import { SerialQueue } from '@aztec/foundation/queue';
+import { RunningPromise } from '@aztec/foundation/running-promise';
+import { getEpochAtSlot, getProofSubmissionDeadlineTimestamp, getSlotRangeForEpoch } from '@aztec/stdlib/epoch-helpers';
+import { CheckpointProver } from './job/checkpoint-prover.js';
+import { EpochSession, specKey } from './job/epoch-session.js';
+/**
+ * Owns the lifecycle of every `EpochSession`. Each L2BlockStream event and periodic tick
+ * arrives via a dedicated entry point (`onCheckpointAdded`, `onPrune`, `onTick`, etc.) which
+ * schedules a `reconcile(trigger)` on a serial queue. Reconcile walks both session
+ * maps, cancels any session whose canonical content has shifted, re-creates it with
+ * the same spec but new content, and opens fresh full sessions for any epoch implicated
+ * by the trigger.
+ */ export class SessionManager {
+    deps;
+    log;
+    fullSessions;
+    partialSessions;
+    /**
+   * Serialises every reconcile call. The trigger sources (L2BlockStream events, the
+   * periodic tick, JSON-RPC `startProof`) run independently, so without this queue two
+   * reconciles could interleave on the `await session.cancel(...)` step and orphan a
+   * freshly-constructed session.
+   */ reconcileQueue;
+    /** Cached L1 constants, populated on first read. */ cachedL1Constants;
+    /** Test-only hooks applied to every session this manager constructs. */ sessionHooks;
+    /** Periodic tick that nudges reconcile to pick up newly-complete epochs. Started by `start()`. */ epochTicker;
+    constructor(deps){
+        this.deps = deps;
+        this.fullSessions = new Map();
+        this.partialSessions = new Map();
+        this.reconcileQueue = new SerialQueue();
+        this.log = createLogger('prover-node:session-manager', deps.bindings);
+        this.reconcileQueue.start();
+    }
+    /**
+   * Starts the periodic tick. Separated from the constructor so tests can drive `onTick()`
+   * manually without the background ticker interleaving. Idempotent.
+   */ start() {
+        if (this.epochTicker) {
+            return;
+        }
+        this.epochTicker = new RunningPromise(()=>this.onTick(), this.log, this.deps.config.tickIntervalMs);
+        this.epochTicker.start();
+    }
+    /**
+   * Installs hooks applied to every session constructed from now on. Used by the e2e
+   * harness to interpose around top-tree proving (gate it, override it, observe it)
+   * without monkey-patching the orchestrator factory.
+   */ setSessionHooks(hooks) {
+        this.sessionHooks = hooks;
+    }
+    // ---------------- read-only views ----------------
+    /** Every live (non-terminal) session. */ allSessions() {
+        return [
+            ...this.fullSessions.values(),
+            ...this.partialSessions.values()
+        ];
+    }
+    /** Returns the full session for `epoch`, if any. */ getFullSession(epoch) {
+        return this.fullSessions.get(epoch);
+    }
+    /** Returns the partial session for `spec`, if any. */ getPartialSession(spec) {
+        return this.partialSessions.get(specKey(spec));
+    }
+    /** Observability summary used by the prover-node API. */ getJobs() {
+        return this.allSessions().map((s)=>({
+                uuid: s.getId(),
+                status: s.getState(),
+                epochNumber: s.getEpochNumber()
+            }));
+    }
+    // ---------------- event entry points ----------------
+    /** Called by ProverNode after a chain-checkpointed event has been added to the store. */ onCheckpointAdded(epoch) {
+        return this.scheduleReconcile({
+            kind: 'checkpoint',
+            epoch
+        });
+    }
+    /** Called by ProverNode after a chain-pruned event has flipped store provers to pruned. */ onPrune(affectedEpochs) {
+        return this.scheduleReconcile({
+            kind: 'prune',
+            affectedEpochs
+        });
+    }
+    /**
+   * Called periodically by ProverNode's ticker. Picks up epochs that have become complete
+   * by time without a fresh checkpoint event (e.g. the epoch's last slots are empty), and
+   * advances to the next epoch once the previous one is proven on L1.
+   */ onTick() {
+        return this.scheduleReconcile({
+            kind: 'tick'
+        });
+    }
+    // ---------------- public API ----------------
+    /**
+   * Schedules a proof attempt for the supplied epoch and returns the job id without waiting for
+   * the proof to complete — proving can far outlast an HTTP request, so callers poll `getJobs()`
+   * for the outcome. Every session — full or partial — begins at the epoch's first slot; the
+   * partial's spec stops at the last canonical slot, while the full's stops at the epoch's last
+   * slot. Dedupes against any existing session covering the same range, returning its id.
+   */ async startProof(epoch) {
+        const canonical = await this.deps.checkpointStore.listForEpoch(epoch);
+        if (canonical.length === 0) {
+            throw new EmptyEpochError(epoch);
+        }
+        // Don't re-prove an epoch the L1 proven chain already encompasses — it was already proven
+        // (possibly by another prover node), so a fresh proof would be wasted work.
+        if (await this.isProvenChainEncompassing(canonical)) {
+            throw new EpochAlreadyProvenError(epoch);
+        }
+        const l1Constants = await this.getL1Constants();
+        const [fromSlot] = getSlotRangeForEpoch(epoch, l1Constants);
+        const toSlot = canonical[canonical.length - 1].slotNumber;
+        const spec = {
+            kind: 'partial',
+            epochNumber: epoch,
+            fromSlot,
+            toSlot
+        };
+        // Reuse a session already covering this exact range rather than scheduling a duplicate.
+        const existingFull = this.getFullSession(epoch);
+        if (existingFull && !existingFull.isTerminal() && existingFull.getSpec().fromSlot === fromSlot && existingFull.getSpec().toSlot === toSlot) {
+            return existingFull.getId();
+        }
+        const existingPartial = this.getPartialSession(spec);
+        if (existingPartial && !existingPartial.isTerminal()) {
+            return existingPartial.getId();
+        }
+        await this.scheduleReconcile({
+            kind: 'start-proof',
+            spec
+        });
+        const created = this.getPartialSession(spec);
+        if (!created) {
+            throw new Error(`Failed to schedule partial proof for epoch ${epoch}`);
+        }
+        return created.getId();
+    }
+    /** Stops the tick, drains the reconcile queue, and cancels every live session. */ async stop() {
+        await this.epochTicker?.stop();
+        await this.reconcileQueue.cancel();
+        const sessions = this.allSessions();
+        // A clean shutdown is just a restart, so preserve the in-flight broker jobs (abortJobs: false)
+        // for the restarted node to reuse rather than re-proving the epoch from scratch.
+        await Promise.allSettled(sessions.map((s)=>s.cancel('prover-node stopping', {
+                abortJobs: false
+            })));
+    }
+    // ---------------- reconcile ----------------
+    scheduleReconcile(trigger) {
+        return this.reconcileQueue.put(()=>this.reconcile(trigger));
+    }
+    async reconcile(trigger) {
+        this.log.debug(`Reconciling`, {
+            trigger
+        });
+        this.recreateInvalidSessions();
+        const implicatedEpochs = await this.epochsForTrigger(trigger);
+        for (const epoch of implicatedEpochs){
+            await this.openFullSessionIfReady(epoch);
+        }
+        if (trigger.kind === 'start-proof') {
+            this.openPartialSession(trigger.spec);
+        }
+    }
+    recreateInvalidSessions() {
+        for (const [key, session] of Array.from(this.fullSessions.entries())){
+            const canonical = this.checkpointsForSpec(session.getSpec());
+            const contentChanged = !this.checkpointsMatch(session.getCheckpoints(), canonical);
+            if (session.isTerminal()) {
+                // A full session that failed on its own account is retained as a "do not re-prove" marker while
+                // its content is unchanged — this is what stops the tick re-proving a deterministically-failing
+                // epoch. When the content changes (a re-add), it is replaced so the epoch retries over the new
+                // provers. Any other terminal full session is simply dropped.
+                if (session.hasFailed() && !contentChanged) {
+                    continue;
+                }
+                this.fullSessions.delete(key);
+                if (contentChanged && this.canBuildOver(canonical)) {
+                    const newSession = this.constructSession(session.getSpec(), canonical);
+                    this.fullSessions.set(key, newSession);
+                    void this.runSession(newSession);
+                }
+                continue;
+            }
+            if (contentChanged) {
+                this.fireAndForgetCancel(session, 'canonical content changed');
+                this.fullSessions.delete(key);
+                if (this.canBuildOver(canonical)) {
+                    const newSession = this.constructSession(session.getSpec(), canonical);
+                    this.fullSessions.set(key, newSession);
+                    void this.runSession(newSession);
+                }
+            }
+        }
+        for (const [key, session] of Array.from(this.partialSessions.entries())){
+            if (session.isTerminal()) {
+                this.partialSessions.delete(key);
+                continue;
+            }
+            const canonical = this.checkpointsForSpec(session.getSpec());
+            if (!this.checkpointsMatch(session.getCheckpoints(), canonical)) {
+                this.fireAndForgetCancel(session, 'canonical content changed');
+                this.partialSessions.delete(key);
+                if (this.canBuildOver(canonical)) {
+                    const newSession = this.constructSession(session.getSpec(), canonical);
+                    this.partialSessions.set(key, newSession);
+                    void this.runSession(newSession);
+                }
+            }
+        }
+    }
+    /** A session may be built over a checkpoint set only when it is non-empty and contains no failed prover. */ canBuildOver(canonical) {
+        return canonical.length > 0 && !this.hasFailedProver(canonical);
+    }
+    async openFullSessionIfReady(epoch) {
+        // A session present here already covers the epoch: either live, or a retained genuinely-failed
+        // session kept by `recreateInvalidSessions` as a "do not re-prove" marker. Either way, don't open
+        // another — the retained-failed one is replaced only when its canonical content changes.
+        if (this.fullSessions.has(epoch)) {
+            return;
+        }
+        if (this.atMaxSessionLimit()) {
+            this.log.debug(`Skipping full-session open for epoch ${epoch}: max pending jobs reached`);
+            return;
+        }
+        if (!await this.deps.l2BlockSource.isEpochComplete(epoch)) {
+            return;
+        }
+        const l1Constants = await this.getL1Constants();
+        const archiverCps = await this.deps.l2BlockSource.getCheckpoints({
+            epoch
+        });
+        if (archiverCps.length === 0) {
+            return;
+        }
+        const [fromSlot, toSlot] = getSlotRangeForEpoch(epoch, l1Constants);
+        const canonical = this.deps.checkpointStore.listInSlotRange(fromSlot, toSlot);
+        if (!this.archiverFullyCovered(archiverCps, canonical)) {
+            this.log.debug(`Skipping full-session open for epoch ${epoch}: archiver checkpoints not all in store`, {
+                archiverCount: archiverCps.length,
+                storeCount: canonical.length
+            });
+            return;
+        }
+        if (this.hasFailedProver(canonical)) {
+            // A checkpoint prover in the set has failed (a sub-tree fault or a prune-induced fork fault), so a
+            // session over it would fail immediately. Don't re-create it every tick — it recovers when a
+            // prune/re-add replaces the failed prover with a fresh one, or fails for good at expiry.
+            this.log.debug(`Skipping full-session open for epoch ${epoch}: a checkpoint prover has failed`, {
+                epoch
+            });
+            return;
+        }
+        const spec = {
+            kind: 'full',
+            epochNumber: epoch,
+            fromSlot,
+            toSlot
+        };
+        const session = this.constructSession(spec, canonical);
+        this.fullSessions.set(epoch, session);
+        void this.runSession(session);
+    }
+    openPartialSession(spec) {
+        const canonical = this.deps.checkpointStore.listInSlotRange(spec.fromSlot, spec.toSlot);
+        if (canonical.length === 0 || this.hasFailedProver(canonical)) {
+            return;
+        }
+        // Reuse a live partial session for this epoch whose checkpoint set already matches the
+        // canonical content — e.g. a repeated `startProof` with no new checkpoints mined since the
+        // last one. Reconstructing would re-prove identical content and burn a pending-job slot.
+        const existing = Array.from(this.partialSessions.values()).find((s)=>s.getSpec().epochNumber === spec.epochNumber && !s.isTerminal() && this.checkpointsMatch(s.getCheckpoints(), canonical));
+        if (existing) {
+            return;
+        }
+        if (this.atMaxSessionLimit()) {
+            throw new Error(`Maximum pending proving jobs ${this.deps.config.maxPendingJobs} reached.`);
+        }
+        const session = this.constructSession(spec, canonical);
+        this.partialSessions.set(specKey(spec), session);
+        void this.runSession(session);
+    }
+    // ---------------- session construction ----------------
+    constructSession(spec, checkpoints) {
+        return this.doConstructSession(spec, checkpoints, this.buildSessionDeps(spec.epochNumber), this.sessionHooks);
+    }
+    /** Extracted for test override. */ doConstructSession(spec, checkpoints, sessionDeps, hooks) {
+        return new EpochSession(spec, checkpoints, {
+            ...sessionDeps,
+            hooks
+        });
+    }
+    buildSessionDeps(epochNumber) {
+        const config = {
+            finalizationDelayMs: this.deps.config.finalizationDelayMs
+        };
+        return {
+            proverFactory: this.deps.proverFactory,
+            proverId: this.deps.proverId,
+            publishingService: this.deps.publishingService,
+            metrics: this.deps.metrics,
+            dateProvider: this.deps.dateProvider,
+            deadline: this.computeDeadline(epochNumber),
+            config,
+            bindings: this.deps.bindings
+        };
+    }
+    computeDeadline(epochNumber) {
+        if (!this.cachedL1Constants) {
+            return undefined;
+        }
+        const ts = getProofSubmissionDeadlineTimestamp(epochNumber, this.cachedL1Constants);
+        return new Date(Number(ts) * 1000);
+    }
+    async runSession(session) {
+        // A reconcile may have cancelled this session before it starts (content-change
+        // recreation). Don't proceed — start() would build a TopTreeJob that should never run.
+        if (session.isTerminal()) {
+            this.log.debug(`Skipping start for ${session.getId()}: already terminal (${session.getState()})`);
+            return;
+        }
+        const state = await session.start();
+        this.log.info(`Session ${session.getId()} exited with state ${state}`);
+        // A full session that failed on its own account (top-tree/submit failed with every prover healthy)
+        // is a genuine, race-free failure: upload its post-mortem once. `recreateInvalidSessions` retains
+        // the terminal session so this fires exactly once (it is never re-run over the same content). A
+        // `stopped` session (a prover under it failed) is not uploaded — it may be a prune, and recovers on
+        // re-add.
+        if (session.getKind() === 'full' && session.hasFailed() && this.deps.onSessionFailed) {
+            try {
+                await this.deps.onSessionFailed(session);
+            } catch (err) {
+                this.log.error(`Error in onSessionFailed callback for epoch ${session.getEpochNumber()}`, err);
+            }
+        }
+    }
+    /**
+   * Builds the EpochProvingJobData snapshot for a post-mortem failure upload from a set of
+   * checkpoint provers. Includes every checkpoint regardless of whether sub-tree proving
+   * completed — partial state is still useful for post-mortem analysis.
+   */ static buildProvingData(checkpoints) {
+        if (checkpoints.length === 0) {
+            throw new Error('Cannot build proving data from an empty checkpoint set');
+        }
+        const txs = new Map();
+        const l1ToL2Messages = {};
+        for (const c of checkpoints){
+            for (const [hash, tx] of c.txs){
+                txs.set(hash, tx);
+            }
+            l1ToL2Messages[c.checkpoint.number] = c.l1ToL2Messages;
+        }
+        return {
+            epochNumber: checkpoints[0].epochNumber,
+            checkpoints: checkpoints.map((c)=>c.checkpoint),
+            txs,
+            l1ToL2Messages,
+            previousBlockHeader: checkpoints[0].previousBlockHeader,
+            attestations: []
+        };
+    }
+    // ---------------- reconcile helpers ----------------
+    atMaxSessionLimit() {
+        const { maxPendingJobs: max } = this.deps.config;
+        if (!max || max <= 0) {
+            return false;
+        }
+        const live = this.allSessions().filter((s)=>!s.isTerminal()).length;
+        return live >= max;
+    }
+    /**
+   * Maps a reconcile trigger to the epochs whose full session should be (re)opened.
+   *
+   * The periodic `tick` returns the next unproven epoch every time; it does not track prior attempts.
+   * `openFullSessionIfReady` is what keeps this from re-proving a doomed epoch: it refuses to build a
+   * session when any checkpoint prover in the set has failed, so a stuck epoch is cheaply skipped each
+   * tick rather than re-proved. `checkpoint` and `prune` fire when an epoch's canonical content changes
+   * (a checkpoint arrives, or a reorg prunes/replaces one) — which is what installs a fresh prover in
+   * place of a failed one, letting the next open succeed and recovering a pruned-then-re-added epoch.
+   */ async epochsForTrigger(trigger) {
+        switch(trigger.kind){
+            case 'checkpoint':
+                return [
+                    trigger.epoch
+                ];
+            case 'prune':
+                return trigger.affectedEpochs;
+            case 'tick':
+                {
+                    const epoch = await this.nextUnprovenEpoch();
+                    return epoch === undefined ? [] : [
+                        epoch
+                    ];
+                }
+            case 'start-proof':
+                return [];
+        }
+    }
+    /**
+   * The next epoch to prove: the epoch containing the first block after the proven tip.
+   * Returns undefined when that block has not been mined yet (e.g. nothing new to prove).
+   * Subsequent ticks advance only once the chain's proven height moves forward, so epochs
+   * are proven in order rather than all at once.
+   */ async nextUnprovenEpoch() {
+        const lastProven = await this.deps.l2BlockSource.getBlockNumber({
+            tag: 'proven'
+        }) ?? BlockNumber.ZERO;
+        const firstToProve = BlockNumber(lastProven + 1);
+        const header = (await this.deps.l2BlockSource.getBlockData({
+            number: firstToProve
+        }))?.header;
+        if (!header) {
+            return undefined;
+        }
+        return getEpochAtSlot(header.getSlot(), await this.getL1Constants());
+    }
+    checkpointsForSpec(spec) {
+        return this.deps.checkpointStore.listInSlotRange(spec.fromSlot, spec.toSlot);
+    }
+    /**
+   * True if any prover in the set has failed. The epoch cannot be proven over a failed prover (it can
+   * never produce its block proofs), so a session must not be built or rebuilt over it until a prune/re-add
+   * has replaced it with a fresh prover.
+   */ hasFailedProver(checkpoints) {
+        return checkpoints.some((c)=>c.isFailed());
+    }
+    fireAndForgetCancel(session, reason) {
+        void session.cancel(reason).catch((err)=>this.log.warn(`Error cancelling session ${session.getId()}`, err));
+    }
+    checkpointsMatch(a, b) {
+        if (a.length !== b.length) {
+            return false;
+        }
+        for(let i = 0; i < a.length; i++){
+            if (a[i].id !== b[i].id || a[i].isCancelled()) {
+                return false;
+            }
+        }
+        return true;
+    }
+    archiverFullyCovered(archiverCps, storeCps) {
+        if (storeCps.length < archiverCps.length) {
+            return false;
+        }
+        // Compare by content-addressed id (number, slot, archive root) rather than checkpoint number:
+        // a reorg can keep the number while changing the checkpoint's post-state archive root.
+        const storeIds = new Set(storeCps.map((p)=>p.id));
+        return archiverCps.every((cp)=>storeIds.has(CheckpointProver.idFor(cp.checkpoint)));
+    }
+    /**
+   * Returns true if the L1 proven tip already covers every canonical checkpoint in the set — i.e.
+   * the epoch has already been fully proven, so there is no point starting a new proof for it.
+   * Conservatively returns false when nothing is proven yet.
+   */ async isProvenChainEncompassing(canonical) {
+        const provenBlock = await this.deps.l2BlockSource.getBlockNumber({
+            tag: 'proven'
+        });
+        if (!provenBlock || provenBlock <= 0) {
+            return false;
+        }
+        const lastCheckpoint = canonical[canonical.length - 1].checkpoint;
+        const lastBlock = lastCheckpoint.blocks[lastCheckpoint.blocks.length - 1].number;
+        return provenBlock >= lastBlock;
+    }
+    async getL1Constants() {
+        if (!this.cachedL1Constants) {
+            this.cachedL1Constants = await this.deps.l2BlockSource.getL1Constants();
+        }
+        return this.cachedL1Constants;
+    }
+}
+class EmptyEpochError extends Error {
+    constructor(epochNumber){
+        super(`No blocks found for epoch ${epochNumber}`);
+        this.name = 'EmptyEpochError';
+    }
+}
+class EpochAlreadyProvenError extends Error {
+    constructor(epochNumber){
+        super(`Epoch ${epochNumber} is already proven on L1`);
+        this.name = 'EpochAlreadyProvenError';
+    }
+}