@kici-dev/orchestrator 0.6.1 → 0.8.0

package/dist/providers/github/deliveries.d.ts

@@ -0,0 +1,118 @@
+/**
+ * GitHub App webhook-delivery replay.
+ *
+ * GitHub keeps every App webhook delivery for a retention window and can be
+ * asked to send one again. That is the only way to recover a window of events
+ * an orchestrator never received — GitHub itself does not retry a delivery its
+ * destination failed to accept, so a window lost while the destination was
+ * unreachable is gone unless somebody replays it.
+ *
+ * Both endpoints are App-level and accept only a JWT signed with the App
+ * private key, which the orchestrator holds and nothing upstream does:
+ *
+ *   GET  /app/hook/deliveries                       (cursor-paginated)
+ *   POST /app/hook/deliveries/{delivery_id}/attempts
+ *
+ * Verified against docs.github.com/en/rest/apps/webhooks on 2026-09-03.
+ */
+import { z } from 'zod';
+import type { Octokit } from '@octokit/rest';
+import { type GitHubAppConfig } from './auth.js';
+/**
+ * Safety ceiling on pages walked in one replay. GitHub returns deliveries
+ * newest-first, so the walk normally stops as soon as it passes `since`; this
+ * bounds a pathological case (a very old `since` on a very busy App) instead of
+ * paginating an App's whole retention window.
+ */
+export declare const MAX_DELIVERY_PAGES = 100;
+/** What happened to one delivery in a replay. */
+export declare const RedeliverOutcome: z.ZodEnum<{
+    failed: "failed";
+    redelivered: "redelivered";
+    "would-redeliver": "would-redeliver";
+}>;
+export type RedeliverOutcome = z.infer<typeof RedeliverOutcome>;
+/** One delivery as `GET /app/hook/deliveries` returns it (the fields used here). */
+export interface GithubWebhookDelivery {
+    id: number;
+    guid: string;
+    /** ISO-8601 timestamp GitHub attempted the delivery. */
+    delivered_at: string;
+    redelivery: boolean;
+    event: string;
+    action: string | null;
+    status: string;
+    status_code: number;
+    installation_id: number | null;
+    repository_id: number | null;
+}
+/** Per-delivery result of a replay. */
+export interface RedeliverResult {
+    deliveryId: number;
+    guid: string;
+    deliveredAt: string;
+    event: string;
+    action: string | null;
+    /** The original delivery's HTTP status as GitHub recorded it. */
+    originalStatusCode: number;
+    outcome: RedeliverOutcome;
+    /** Present when `outcome` is `failed`. */
+    error?: string;
+}
+/** The whole replay, as the admin route and the CLI report it. */
+export interface RedeliverWindowResult {
+    since: string;
+    until: string;
+    dryRun: boolean;
+    /** Deliveries GitHub holds whose `delivered_at` falls in the window. */
+    matched: number;
+    /**
+     * True when the page walk hit its ceiling before reaching a delivery older
+     * than `since`, so `matched` counts only what was gathered and the window
+     * holds more. Callers must say so rather than reporting a partial replay as
+     * a complete one.
+     */
+    truncated: boolean;
+    redelivered: number;
+    failed: number;
+    results: RedeliverResult[];
+}
+/** The one Octokit method this module needs, so a test can hand in a stub. */
+export type GithubRequest = Pick<Octokit, 'request'>;
+export interface RedeliverWindowOptions {
+    /** Inclusive lower bound on `delivered_at`. */
+    since: Date;
+    /** Exclusive upper bound on `delivered_at`. */
+    until: Date;
+    /** List and report the matching deliveries without asking GitHub to resend. */
+    dryRun?: boolean;
+    /** Injected for tests; defaults to a JWT-authenticated App client. */
+    octokit?: GithubRequest;
+}
+/** Read the `cursor` query value out of the `Link: <...>; rel="next"` header. */
+export declare function nextCursorFromLink(link: string | undefined): string | null;
+/**
+ * Walk `GET /app/hook/deliveries` newest-first and return every delivery whose
+ * `delivered_at` falls in `[since, until)`.
+ *
+ * The walk stops at the first page whose oldest delivery predates `since`:
+ * GitHub orders the feed newest-first, so nothing older can match afterwards.
+ */
+export declare function listDeliveriesInWindow(octokit: GithubRequest, opts: {
+    since: Date;
+    until: Date;
+}): Promise<{
+    deliveries: GithubWebhookDelivery[];
+    truncated: boolean;
+}>;
+/** Ask GitHub to send one delivery again. Resolves once GitHub accepts (202). */
+export declare function redeliverDelivery(octokit: GithubRequest, deliveryId: number): Promise<void>;
+/**
+ * Replay every delivery GitHub holds for this App in `[since, until)`.
+ *
+ * A per-delivery failure is recorded and the replay continues: an operator
+ * recovering an outage window wants the deliveries that can be replayed, plus
+ * an honest list of the ones that could not.
+ */
+export declare function redeliverWindow(app: GitHubAppConfig, opts: RedeliverWindowOptions): Promise<RedeliverWindowResult>;
+//# sourceMappingURL=deliveries.d.ts.map

package/dist/providers/local/lock-file-fetcher.d.ts

@@ -15,6 +15,14 @@ import type { LockFileFetcher, LockFile } from '@kici-dev/engine';
 export declare class LocalLockFileFetcher implements LockFileFetcher {
     private readonly repoBasePath;
     readonly provider: 'local';
+    /**
+     * Never cached: `ref` is ignored below, so a cache keyed on it would serve the
+     * first lock file read to every later trigger for the lifetime of the entry —
+     * a `kici run --local` dispatch always triggers at `HEAD`, and an in-place run
+     * carries its uncommitted edits under an unchanged sha. Reading the file from
+     * disk is what makes those edits reach the run.
+     */
+    readonly cacheable: false;
     /**
      * @param repoBasePath - Base directory for the repo(s). When repoIdentifier
      *   starts with 'file://', it is stripped and used as-is. Otherwise

package/dist/providers/universal-git/config.d.ts

@@ -51,7 +51,7 @@ export declare const SshHostKeyPolicy: z.ZodEnum<{
 export type SshHostKeyPolicy = z.infer<typeof SshHostKeyPolicy>;
 /**
  * Reference to a secret in the orchestrator's secret store. Resolved at
- * dispatch time via `SecretResolver.resolveNamed()`. The secret itself lives
+ * dispatch time via `SecretResolver.resolveNamedInternal()`. The secret itself lives
  * at scope `__source__/<sourceId>`, key = `credentialRef.key`, optionally
  * in a specific backend via `credentialRef.store` (defaults to `pg`).
  */

package/dist/queue/cleanup.d.ts

@@ -7,6 +7,7 @@ import type { ClusterSettingsReader } from '../cluster/cluster-settings-reader.j
 import type { LogStorage } from '../reporting/log-storage.js';
 import { JobQueue } from './job-queue.js';
 import { type CanRouteLabels, type TerminalizeDeps } from './terminalize-unroutable.js';
+import { type RetentionWindows } from './retention.js';
 /**
  * Optional cleanup dependencies + retention knobs. Present in platform/hybrid
  * mode (the only wiring site, `orchestrator-core`, always supplies them); the
@@ -33,6 +34,17 @@ export interface CleanupExtras {
     stepLogTtlDays?: number;
     /** Store for `check_run_tracking`; the retention sweep runs only when wired. */
     checkRunTrackingStore?: CheckRunTrackingStore;
+    /**
+     * Database-side retention windows, in days. Absent leaves the history sweep
+     * off entirely, which is what a caller that has not wired it gets.
+     */
+    retentionWindows?: RetentionWindows;
+    /**
+     * True when the cold store is configured. Its archivers then own the tables
+     * they register and the history sweep leaves those alone — one owner per
+     * table.
+     */
+    coldStoreEnabled?: boolean;
     /** Live cluster-settings reader; absent ⇒ the config default is used as-is. */
     clusterSettings?: ClusterSettingsReader;
     /** `check_run_tracking` row retention (days); 0 disables. Default 7. */
@@ -96,6 +108,7 @@ export declare function runCleanup(dedup: {
     dispatchRowsPruned: number;
     logObjectsPruned: number;
     checkRunRowsPruned: number;
+    historyRowsPruned: number;
 }>;
 /**
  * Build a per-tick handler for the queue-cleanup scheduled job.

package/dist/queue/job-queue.d.ts

@@ -1,7 +1,50 @@
-import { type Kysely } from 'kysely';
-import { type LabelMatcher, type ResourceRequest } from '@kici-dev/engine';
+import { type Kysely, type SqlBool } from 'kysely';
+import { type CanonicalLabel, type CanonicalMatcher, type LabelMatcher, type ResourceRequest } from '@kici-dev/engine';
 import type { Database } from '../db/types.js';
 import type { ClusterSettingsReader } from '../cluster/cluster-settings-reader.js';
+/**
+ * The ownership predicate, in its two forms. Both come from here so they cannot
+ * drift apart, because they answer the same question from opposite directions.
+ *
+ * **Strict selection** (`recoverableByOwner`) picks the rows a cluster-wide
+ * sweep may act on: mine, or a dead instance's. A NULL owner is EXCLUDED — it
+ * reads as "unknown owner", never as "not mine", which is the convention
+ * migration 119 established for the scaler plane. Sparing it is what makes a
+ * rolling upgrade safe: every row a pre-upgrade coordinator dispatched carries
+ * a NULL owner, and recovering those would fail every job the rest of the
+ * cluster is running, on every coordinator boot — precisely the window in which
+ * coordinators boot. A spared orphan is not lost; the stale detector reaps it on
+ * the dispatch-time clock.
+ *
+ * **Permissive write guard** (`writableByOwner`) gates a write on a row this
+ * coordinator has already selected some other way: mine, unknown, or a dead
+ * instance's. It INCLUDES a NULL owner, because a legitimate local disconnect
+ * must still be able to move a pre-upgrade row. Its job is to stop a path that
+ * forgot the selection filter from flipping a row a LIVE sibling owns.
+ */
+export interface OwnershipPredicateOptions {
+    /** This coordinator's instance id. Undefined ⇒ no instance identity. */
+    instanceId?: string;
+    /** How stale a `cluster_instances` heartbeat may be and still read as live. */
+    graceMs: number;
+    /** Fully qualified owner column, defaulting to the dispatch queue's. */
+    ownerColumn?: string;
+    /**
+     * Instance ids currently connected as peers. OR-ed in as live, so a peer whose
+     * heartbeat row is momentarily stale is not mistaken for dead.
+     */
+    livePeerIds?: readonly string[];
+}
+/**
+ * Strict selection: the rows a cluster-wide sweep may recover. Excludes a NULL
+ * owner and excludes any row whose owner is still live.
+ */
+export declare function recoverableByOwner(opts: OwnershipPredicateOptions): import("kysely").RawBuilder<SqlBool>;
+/**
+ * Permissive write guard: allow the write unless a LIVE sibling owns the row.
+ * A NULL owner passes.
+ */
+export declare function writableByOwner(opts: OwnershipPredicateOptions): import("kysely").RawBuilder<SqlBool>;
 /** Info about an expired dispatch_queue entry, returned by markExpired(). */
 export interface ExpiredJobInfo {
     /** dispatch_queue row ID */
@@ -15,11 +58,15 @@ export interface ExpiredJobInfo {
      * any agent could ever have run it. A job that expires with NO matching agent
      * is `unroutable` (a fleet/label problem); one whose agent existed but never
      * freed up is `timed_out_stale` (a capacity problem).
+     *
+     * Canonical: the probe compares them against a live agent's canonical labels,
+     * so a case-sensitive read here would report a routable job `unroutable` and
+     * send the operator hunting a fleet problem that does not exist.
      */
-    runsOnLabels: string[];
-    runsOnPatterns: LabelMatcher[];
-    excludeLabels: string[];
-    excludePatterns: LabelMatcher[];
+    runsOnLabels: CanonicalLabel[];
+    runsOnPatterns: CanonicalMatcher[];
+    excludeLabels: CanonicalLabel[];
+    excludePatterns: CanonicalMatcher[];
 }
 /**
  * A pending job as the unroutable probe sees it: the same routing facts the
@@ -103,6 +150,8 @@ export interface QueuedJobInput {
     sourceTarUrl?: string;
     /** Content hash of the pre-compiled bundle for verification. */
     sourceTarHash?: string;
+    /** SHA-256 of the source tarball's own bytes (what `sourceTarHash` never was). */
+    sourceTarDigest?: string;
     /** URL to pre-built dependency tarball (from dep cache). Passed through to job.dispatch. */
     depsUrl?: string;
     /** SHA-256 hash of the dependency tarball for integrity verification. */
@@ -140,7 +189,8 @@ export interface QueuedJob {
     runId: string;
     workflowName: string;
     jobName: string;
-    runsOnLabels: string[];
+    /** Canonical: folded by `rowToQueuedJob`, whatever case the row holds. */
+    runsOnLabels: CanonicalLabel[];
     jobConfig: Record<string, unknown>;
     repoUrl: string;
     ref: string;
@@ -160,18 +210,24 @@ export interface QueuedJob {
     sourceTarUrl?: string;
     /** Content hash of the pre-compiled bundle for verification. */
     sourceTarHash?: string;
+    /** SHA-256 of the source tarball's own bytes (what `sourceTarHash` never was). */
+    sourceTarDigest?: string;
     /** URL to pre-built dependency tarball (from dep cache). Passed through to job.dispatch. */
     depsUrl?: string;
     /** SHA-256 hash of the dependency tarball for integrity verification. */
     depsHash?: string;
     /** Request trace ID for cross-tier correlation. Passed through to job.dispatch. */
     requestId?: string;
-    /** Labels that the dispatched agent must NOT have. */
-    excludeLabels: string[];
-    /** Regex matchers the agent's labels must satisfy (JS post-filter on the exact @> prefilter). */
-    runsOnPatterns: LabelMatcher[];
-    /** Regex matchers that disqualify an agent (JS post-filter). */
-    excludePatterns: LabelMatcher[];
+    /** Labels that the dispatched agent must NOT have. Canonical. */
+    excludeLabels: CanonicalLabel[];
+    /**
+     * Regex matchers the agent's labels must satisfy (JS post-filter on the exact
+     * `@>` prefilter). Canonical, so the stored pattern carries the `i` flag
+     * whether or not the lock file that produced it did.
+     */
+    runsOnPatterns: CanonicalMatcher[];
+    /** Regex matchers that disqualify an agent (JS post-filter). Canonical. */
+    excludePatterns: CanonicalMatcher[];
     /**
      * Per-job resource request and limit (K8s-style). Materialized from `jobConfig.resources`
      * by `rowToQueuedJob` so callers can read it without re-parsing the JSON column.
@@ -207,6 +263,8 @@ export declare class JobQueue {
     private readonly defaultMaxDepth;
     private readonly defaultTimeoutMs;
     private readonly clusterSettings?;
+    private readonly instanceId?;
+    private readonly ownershipGraceMs;
     /** Per-job (per-org) queue-timeout resolver; falls back to defaultTimeoutMs. */
     private readonly getQueueTimeoutMs?;
     /** 1-second TTL cache for pending depth count to avoid extra SELECT COUNT per enqueue. */
@@ -225,7 +283,23 @@ export declare class JobQueue {
         getQueueTimeoutMs?: (job: {
             jobConfig?: Record<string, unknown>;
         }) => Promise<number>;
+        /**
+         * This coordinator's instance id, stamped onto every row it dispatches so
+         * a cluster-wide sweep can tell its own rows from a sibling's. Optional
+         * for the same reason `AgentRegistryDeps.instanceId` is: a worker with no
+         * cluster identity (and every unit test) leaves it undefined and the
+         * column stays NULL, which reads as "unknown owner".
+         */
+        instanceId?: string;
+        /**
+         * How stale a `cluster_instances` heartbeat may be and still read as
+         * live. Defaults to {@link instanceLivenessGraceMs} at the default
+         * recovery grace period.
+         */
+        ownershipGraceMs?: number;
     });
+    /** Ownership predicate inputs, in the shape both predicate builders take. */
+    private ownershipOptions;
     /**
      * Enqueue a job. Checks depth first, rejects with 'queue full' if >= the
      * fleet-wide `queue_max_depth` (cluster_settings, falling back to the config
@@ -530,6 +604,19 @@ export declare class JobQueue {
      * refreshing the cache periodically via {@link JobQueue.getDepthBreakdown}.
      */
     readCachedDepthBreakdown(): DispatchQueueDepthBreakdown | null;
+    /**
+     * The run's dispatched-or-recovering rows with the durable facts a cancel
+     * needs to route: which agent holds the job, and which coordinator dispatched
+     * it. Both come from the row rather than from a process map, because the
+     * coordinator handling a cancel is the owner only by chance — the Platform
+     * routes `run.cancel.request` by routing key and picks any connected pool
+     * member.
+     */
+    getDispatchedJobOwnersByRunId(runId: string): Promise<Array<{
+        jobId: string;
+        agentId: string | null;
+        ownerInstanceId: string | null;
+    }>>;
     /**
      * Get job IDs for a run that are currently dispatched or recovering.
      * Used by the cancel-run API to send job.cancel to the right agents.
@@ -544,8 +631,47 @@ export declare class JobQueue {
      * replacement coord on Raft leader switch can recreate the recovery
      * timer (via `getRecoveringJobs()` on boot) or expire the row in
      * the leader-gated sweep (`sweepExpiredRecoveries()`).
+     *
+     * Carries the permissive ownership write guard: a row owned by a LIVE sibling
+     * is left alone. Callers are expected to have selected owned rows already
+     * ({@link JobQueue.getOrphanedDispatchedJobs}); this is the backstop for a
+     * path that forgets to, since flipping a live sibling's row to `recovering`
+     * starts a 120-second clock that ends by failing a job nobody disconnected
+     * from. A NULL owner still passes — a local disconnect must be able to move a
+     * pre-upgrade row.
+     *
+     * @returns whether a row was flipped.
+     */
+    markRecovering(jobId: string, deadline?: Date, agentId?: string): Promise<boolean>;
+    /**
+     * The `dispatched` rows this coordinator may start recovery timers for on
+     * boot: its own, and those whose owning coordinator is no longer alive.
+     *
+     * Replaces an unfiltered `getJobsByStatus(Dispatched)` over the shared table.
+     * That scan made every coordinator boot flip every sibling's in-flight row to
+     * `recovering`; the agents running those jobs were never disconnected, so
+     * nothing reclaimed them, and 120 seconds later the booting coordinator
+     * failed every one of them while they ran to completion. The documented
+     * rolling-restart procedure triggered it on every restart.
+     *
+     * A NULL owner is spared — see {@link recoverableByOwner} for why, and for
+     * what reaps a genuinely orphaned one instead.
+     */
+    getOrphanedDispatchedJobs(): Promise<Array<{
+        id: string;
+        runId: string;
+        agentId: string | null;
+    }>>;
+    /**
+     * How many `dispatched` rows this coordinator deliberately left alone on
+     * boot: owned by a live sibling, or of unknown ownership. Read only to log
+     * and count the decision, so "recovery spared N rows" is visible rather than
+     * being the silent absence of a log line.
      */
-    markRecovering(jobId: string, deadline?: Date, agentId?: string): Promise<void>;
+    countSparedDispatchedJobs(): Promise<{
+        ownedElsewhere: number;
+        unknownOwner: number;
+    }>;
     /**
      * Stamp the dispatch-acknowledgment deadline for a dispatched job.
      * Only touches rows still in 'dispatched' for safety.
@@ -621,6 +747,28 @@ export declare class JobQueue {
      *   was not in 'dispatched' state (nothing requeued).
      */
     requeue(jobId: string): Promise<number | null>;
+    /**
+     * Requeue a dispatched job **only** when its ack genuinely never landed.
+     *
+     * One atomic guarded UPDATE that both proves the ack is still outstanding
+     * and requeues. It exists because {@link requeue}'s only guard is
+     * `status = 'dispatched'`, and an acked, executing job is still
+     * `dispatched` — so an ack timer that fires late (a coordinator restart
+     * re-armed it, or the ack raced the deadline) requeues a running job and a
+     * second agent claims it. Both agents then execute the same job.
+     *
+     * The proof has to happen in the same statement as the requeue: the ack path
+     * clears `ack_deadline`/`ack_agent_id`, so a separate read-then-requeue is a
+     * race, and a guard bolted onto a caller that clears the deadline first can
+     * never see the evidence it needs.
+     *
+     * {@link requeue} stays for `job.reject` and the scaler-disconnect path,
+     * whose rows legitimately carry no deadline.
+     *
+     * @returns the post-increment dispatch_attempts, or null when the ack landed
+     *   (or the row moved on) and nothing was requeued.
+     */
+    requeueIfAwaitingAck(jobId: string, expectedAgentId: string | null): Promise<number | null>;
     /**
      * Get the full QueuedJob row by ID regardless of status. Used by the
      * dispatcher's redispatch path, which needs runsOnLabels / excludeLabels /

package/dist/queue/retention.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Database-side retention for the tables that scale with run volume.
+ *
+ * The cold store is the other half of this: its archivers do
+ * archive-then-delete inside one transaction and own the four tables they
+ * register. But the cold store needs `KICI_COLD_STORE_ENABLED=true` and a
+ * bucket, and with neither — the default, and the quickstart path — nothing
+ * aged at all, so `execution_steps`, `event_log` and `access_log` grew without
+ * bound on the operator's own disk.
+ *
+ * Two rules keep the tiers from fighting:
+ *
+ *   - When the cold store is on, this tier skips every table an archiver
+ *     registers. Two owners deleting the same rows would race the archiver's
+ *     FK guard and could delete a parent whose archive chunk was never
+ *     written. One owner per table.
+ *   - Nothing is deleted on the first pass. The first pass with a non-zero
+ *     window stamps `cluster_settings.retention_announced_at` and reports what
+ *     it would remove; deletion begins a week later. An upgrade that silently
+ *     deleted an operator's history on its first night would be a behaviour
+ *     change nobody was warned about.
+ *
+ * Every delete is batched — select ids under a `LIMIT`, then delete by id,
+ * looping until a pass comes back short. One unbounded `DELETE` over a table
+ * holding millions of rows holds locks for as long as it runs.
+ */
+import { type Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+/** Rows selected, and deleted, per statement. */
+export declare const RETENTION_BATCH_SIZE = 5000;
+/** Days between the announce stamp and the first deletion. */
+export declare const RETENTION_ANNOUNCE_DAYS = 7;
+/** Terminal run statuses. A run still queued, running, held or cancelling is
+ *  live work whatever its age. */
+export declare const TERMINAL_RUN_STATUS_LIST: readonly string[];
+/** Terminal held-run statuses. A pending hold is never pruned. */
+export declare const TERMINAL_HELD_RUN_STATUSES: readonly string[];
+/**
+ * Tables the cold-store archivers register. When the cold store is on these
+ * are theirs alone — including the `execution_jobs` / `execution_steps`
+ * children, which the run archiver removes with their parent.
+ */
+export declare const COLD_STORE_OWNED_TABLES: readonly string[];
+/** The `cluster_settings` columns this module reads. */
+export type ClusterRetentionColumn = 'run_retention_days' | 'audit_retention_days' | 'provenance_retention_days' | 'held_run_retention_days';
+export interface RetentionWindows {
+    /** Terminal runs, and the jobs and steps beneath them. 0 disables. */
+    runRetentionDays: number;
+    /** access_log, secret_audit_log, event_log. 0 disables. */
+    auditRetentionDays: number;
+    /** attestations, pending_attestations. 0 disables. */
+    provenanceRetentionDays: number;
+    /** Terminal held_runs. 0 disables. */
+    heldRunRetentionDays: number;
+}
+export interface PruneExpiredHistoryDeps {
+    db: Kysely<Database>;
+    windows: RetentionWindows;
+    /** True when the cold store is configured and owns its tables. */
+    coldStoreEnabled: boolean;
+    now?: () => Date;
+    batchSize?: number;
+}
+export interface RetentionSummary {
+    /** Rows deleted, per table. */
+    deleted: Record<string, number>;
+    /** Rows that WOULD have been deleted, while the announce window runs. */
+    pending: Record<string, number>;
+    /** True while the announce window has not elapsed, so nothing was deleted. */
+    announcing: boolean;
+}
+/** True when every window is 0, i.e. the operator disabled the whole tier. */
+export declare function allWindowsDisabled(windows: RetentionWindows): boolean;
+/**
+ * Delete rows in bounded batches, returning the total removed.
+ *
+ * The loop stops as soon as a pass comes back short, which is what bounds it
+ * on a table that is still being written to.
+ */
+export declare function deleteInBatches(table: string, selectIds: (limit: number) => Promise<string[]>, deleteIds: (ids: string[]) => Promise<void>, batchSize: number): Promise<number>;
+/**
+ * Read the announce stamp, setting it on the first pass that has work to do.
+ *
+ * Returns true once the window has elapsed and deletion may begin.
+ */
+export declare function announceGatePassed(db: Kysely<Database>, now: Date, announceDays?: number): Promise<boolean>;
+/**
+ * Prune every table this tier owns, honouring the windows, the cold-store
+ * ownership split, and the announce gate.
+ */
+export declare function pruneExpiredHistory(deps: PruneExpiredHistoryDeps): Promise<RetentionSummary>;
+/**
+ * Resolve the effective windows: a live `cluster_settings` value wins over the
+ * configured default.
+ *
+ * `getNumber` returns a genuine 0 when the operator set the knob to 0, which is
+ * the documented way to disable a window — so this stays a fallback-on-null
+ * read, never `||`.
+ */
+export declare function resolveRetentionWindows(defaults: RetentionWindows, clusterSettings?: {
+    getNumber(column: ClusterRetentionColumn, fallback: number): Promise<number>;
+}): Promise<RetentionWindows>;
+/** Wrap {@link pruneExpiredHistory} so a failure never aborts the sweep. */
+export declare function pruneExpiredHistorySafely(deps: PruneExpiredHistoryDeps): Promise<RetentionSummary>;
+//# sourceMappingURL=retention.d.ts.map