@kici-dev/orchestrator 0.1.3 → 0.1.6

package/dist/reporting/check-run-tracking-store.d.ts

@@ -0,0 +1,133 @@
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import type { StepProgressEntry } from './check-run-summary.js';
+/**
+ * Composite key identifying a single check-run row.
+ *
+ * Matches the table primary key `(provider, owner, repo, sha, check_name)`.
+ * Used by the L1 in-memory cache and as the parameter shape for every
+ * store method.
+ */
+export interface CheckRunTrackingKey {
+    provider: string;
+    owner: string;
+    repo: string;
+    sha: string;
+    checkName: string;
+}
+/**
+ * Snapshot of all per-key check-run state. Mirrors the columns of the
+ * `check_run_tracking` table with the in-memory shapes the consumer
+ * already uses.
+ */
+export interface CheckRunTrackingState {
+    /** GitHub Checks API check-run ID. Undefined when not yet created. */
+    checkRunId?: number;
+    /** Build check-run lifecycle marker. */
+    buildCreationState?: 'pending' | 'completed';
+    /** Live step-progress entries shown in the check run's `output.summary`. */
+    stepProgress: StepProgressEntry[];
+    /** Timestamp the first running-step transition was sent to GitHub. */
+    inProgressSentAt?: Date;
+    /** KiCI run this check-run belongs to. Used by `cleanupRun`. */
+    runId?: string;
+    /** Last persisted update time; powers debounce-after-failover recovery. */
+    updatedAt?: Date;
+}
+/**
+ * DB persistence for `CheckRunReporter` check-run state.
+ *
+ * Backed by the `check_run_tracking` table — one row per
+ * `(provider, owner, repo, sha, check_name)`. Replaces six in-memory
+ * `Map`s previously held inside `CheckRunReporter`:
+ *
+ *   - `checkRunIds`            → `check_run_id` column
+ *   - `pendingBuildCreations`  → `build_creation_state` column
+ *   - `stepProgress`           → `step_progress_json` column
+ *   - `inProgressSent`         → `in_progress_sent_at` column
+ *   - `runIdToKeys`            → indexed `run_id` column + `listKeysByRunId`
+ *
+ * The `progressTimers` Map is intentionally NOT persisted — debounce
+ * timers are reconstructed on demand. After a coord failover the very
+ * next `updateStepProgress` either flushes immediately (debounce window
+ * elapsed) or starts a fresh timer.
+ *
+ * The consumer keeps an L1 in-memory cache in front of this store; the
+ * store itself is stateless beyond the connection it holds.
+ */
+export declare class CheckRunTrackingStore {
+    private readonly db;
+    constructor(db: Kysely<Database>);
+    /**
+     * Atomically set / overwrite the check-run ID for a key.
+     *
+     * Performed as an upsert so a re-issued setPending after a coord
+     * failover replaces the prior ID rather than silently leaving a row
+     * mismatched with the GitHub-side state.
+     */
+    setCheckRunId(key: CheckRunTrackingKey, checkRunId: number): Promise<void>;
+    /**
+     * Lookup the check-run ID for a key. Returns undefined if no row exists
+     * yet OR the row exists but the GitHub create has not finished
+     * persisting an ID (the build-creation in-flight window).
+     */
+    getCheckRunId(key: CheckRunTrackingKey): Promise<number | undefined>;
+    /**
+     * Mark a build check-run as having an in-flight create. Returns true if
+     * this caller won the race (no prior row, or row had no in-flight state).
+     * Used to prevent a replacement coord from re-issuing a `checks.create()`
+     * against the same SHA when the original create is still pending.
+     */
+    markBuildCreationPending(key: CheckRunTrackingKey, runId?: string): Promise<void>;
+    /**
+     * Mark a build check-run create as complete. Idempotent.
+     */
+    markBuildCreationComplete(key: CheckRunTrackingKey): Promise<void>;
+    /**
+     * Replace the step-progress array for a key.
+     */
+    setStepProgress(key: CheckRunTrackingKey, steps: StepProgressEntry[], runId?: string): Promise<void>;
+    /**
+     * Mark the first in-progress transition as sent. Used to keep the
+     * single "did we already kick this check run into in_progress?" guard
+     * cluster-wide.
+     */
+    markInProgressSent(key: CheckRunTrackingKey, runId?: string): Promise<void>;
+    /**
+     * Get the full state snapshot for a key. Used by the L1 cache to
+     * hydrate on miss and by tests to verify the on-disk layout. Returns
+     * undefined when no row exists.
+     */
+    getState(key: CheckRunTrackingKey): Promise<CheckRunTrackingState | undefined>;
+    /**
+     * Delete a single row. Returns true if the row existed.
+     */
+    deleteRow(key: CheckRunTrackingKey): Promise<boolean>;
+    /**
+     * List every key currently tracked for a runId. Used by `cleanupRun`
+     * to reproduce the runId → keys reverse index that the in-memory map
+     * provided. Index `idx_check_run_tracking_run_id` keeps this O(matches).
+     */
+    listKeysByRunId(runId: string): Promise<CheckRunTrackingKey[]>;
+    /**
+     * Delete every row for a runId. Mirrors the bulk-cleanup semantics of
+     * `cleanupRun` so a single call from execution-tracker prune releases
+     * all rows for the run.
+     */
+    deleteByRunId(runId: string): Promise<number>;
+    private selectRow;
+    private upsertRow;
+}
+/**
+ * Convert a raw DB row to the in-memory `CheckRunTrackingState` shape.
+ * Exported for direct use from tests that bypass the store.
+ */
+export declare function rowToState(row: {
+    check_run_id: number | string | null;
+    build_creation_state: string | null;
+    step_progress_json: unknown;
+    in_progress_sent_at: Date | null;
+    run_id: string | null;
+    updated_at: Date;
+}): CheckRunTrackingState;
+//# sourceMappingURL=check-run-tracking-store.d.ts.map

package/dist/routes/admin-access-log.d.ts

@@ -27,6 +27,7 @@ type AdminEnv = {
     Variables: {
         role: Role;
         userId: string;
+        routingKey: string | null;
     };
 };
 export declare function createAdminAccessLogRoutes(deps: AdminAccessLogRoutesDeps): Hono<AdminEnv>;

package/dist/routes/admin-backends.d.ts

@@ -12,6 +12,14 @@ import { Hono } from 'hono';
 import type { BackendSyncManager } from '@kici-dev/engine';
 import type { BackendRegistry } from '../secrets/backend-registry.js';
 import type { BackendHealthChecker } from '../secrets/backend-health.js';
+import type { Role } from '../secrets/rbac.js';
+type AdminBackendsEnv = {
+    Variables: {
+        role: Role;
+        userId: string;
+        routingKey: string | null;
+    };
+};
 interface BackendRouteDeps {
     registry: BackendRegistry;
     healthChecker: BackendHealthChecker;
@@ -23,6 +31,6 @@ interface BackendRouteDeps {
  * @param deps - Backend route dependencies (registry, health checker, sync manager)
  * @returns Hono app with backend routes
  */
-export declare function createBackendRoutes(deps: BackendRouteDeps): Hono;
+export declare function createBackendRoutes(deps: BackendRouteDeps): Hono<AdminBackendsEnv>;
 export {};
 //# sourceMappingURL=admin-backends.d.ts.map

package/dist/routes/admin-cluster-name.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Admin API routes for managing this orchestrator's cluster name
+ * (`cluster_meta.cluster_name`).
+ *
+ * The cluster name is the human-friendly identifier that surfaces in
+ * Platform's connection registry and in the dashboard's per-orch URL
+ * segment (`/orgs/:cId/orchestrators/:clusterName/...`). Operators
+ * read and rename it via `kici-admin cluster-name {get,set}`.
+ *
+ * Routes:
+ *
+ *   - `GET /api/v1/admin/cluster-name` →
+ *     `{ clusterName: string, looksAutoGenerated: boolean }`
+ *   - `PUT /api/v1/admin/cluster-name` → body `{ name: string }`,
+ *     validates via the shared `clusterNameSchema` and persists.
+ *     Returns `{ clusterName, prior }`. Renames are recorded in
+ *     `access_log` so the audit trail captures who changed it and when.
+ *
+ * Mutation requires `secret.write` (same posture as the rest of
+ * admin-org-settings). The orchestrator publishes the new name on the
+ * next `source.register` — the route response includes a hint so the
+ * CLI can tell the operator to reconnect to make Platform aware.
+ */
+import { Hono } from 'hono';
+import type { Kysely } from 'kysely';
+import { CLUSTER_NAME_REGEX } from '@kici-dev/engine/protocol/cluster-name';
+import type { Database } from '../db/types.js';
+import type { RbacEnforcer, Role } from '../secrets/rbac.js';
+import type { AccessLogWriter } from '../audit/access-log.js';
+interface ClusterNameRouteDeps {
+    db: Kysely<Database>;
+    rbac: RbacEnforcer;
+    /**
+     * Optional — when wired, each rename emits one `access_log` row
+     * (`cluster_name.update`) with `orgId=null` carrying the prior + new
+     * value in `meta`. Cluster-name is orch-scoped, not org-scoped, so
+     * the row's `orgId` is null by design.
+     */
+    accessLog?: AccessLogWriter;
+}
+type AdminEnv = {
+    Variables: {
+        role: Role;
+        userId: string;
+        routingKey: string | null;
+    };
+};
+export declare function createClusterNameRoutes(deps: ClusterNameRouteDeps): Hono<AdminEnv>;
+export { CLUSTER_NAME_REGEX };
+//# sourceMappingURL=admin-cluster-name.d.ts.map

package/dist/routes/admin-db.d.ts

@@ -11,10 +11,18 @@
 import { Hono } from 'hono';
 import type { Kysely } from 'kysely';
 import type pg from 'pg';
+import type { Role } from '../secrets/rbac.js';
 interface DbRouteDeps {
     db: Kysely<any>;
     pool: pg.Pool;
 }
-export declare function createDbRoutes(deps: DbRouteDeps): Hono;
+type AdminDbEnv = {
+    Variables: {
+        role: Role;
+        userId: string;
+        routingKey: string | null;
+    };
+};
+export declare function createDbRoutes(deps: DbRouteDeps): Hono<AdminDbEnv>;
 export {};
 //# sourceMappingURL=admin-db.d.ts.map

package/dist/routes/admin-environments.d.ts

@@ -1,12 +1,15 @@
 /**
  * Admin API routes for environment management.
  *
- *   POST   /api/v1/admin/environments                        — create (upsert)
- *   POST   /api/v1/admin/environments/:name/bind             — bind a scope pattern
- *   PATCH  /api/v1/admin/environments/:name/policy           — update policy fields
- *   GET    /api/v1/admin/environments?orgId=<id>             — list environments
- *   GET    /api/v1/admin/environments/:name?orgId=<id>       — show env + vars + bindings
- *   POST   /api/v1/admin/environments/templates              — create/update a template
+ *   POST   /api/v1/admin/environments                                    — create (upsert)
+ *   POST   /api/v1/admin/environments/:name/bind                         — bind a scope pattern
+ *   PATCH  /api/v1/admin/environments/:name/policy                       — update policy fields
+ *   GET    /api/v1/admin/environments?orgId=<id>                         — list environments
+ *   GET    /api/v1/admin/environments/:name?orgId=<id>                   — show env + vars + bindings
+ *   POST   /api/v1/admin/environments/templates                          — create/update a template
+ *   GET    /api/v1/admin/environments/:name/variables?orgId=<id>         — list org-level variables
+ *   PUT    /api/v1/admin/environments/:name/variables/:key?orgId=<id>    — upsert variable
+ *   DELETE /api/v1/admin/environments/:name/variables/:key?orgId=<id>    — delete variable
  *
  * Backs the `kici-admin environment` dual-mode CLI. Offline (direct-DB) mode
  * bypasses this router entirely — the CLI calls `*Direct` helpers from
@@ -29,6 +32,7 @@ type AdminEnvEnv = {
     Variables: {
         role: Role;
         userId: string;
+        routingKey: string | null;
     };
 };
 /**

package/dist/routes/admin-event-dlq.d.ts

@@ -32,6 +32,7 @@ type AdminEnv = {
     Variables: {
         role: Role;
         userId: string;
+        routingKey: string | null;
     };
 };
 export declare function createAdminEventDlqRoutes(deps: AdminEventDlqRoutesDeps): Hono<AdminEnv>;

package/dist/routes/admin-event-log.d.ts

@@ -35,6 +35,7 @@ type AdminEnv = {
     Variables: {
         role: Role;
         userId: string;
+        routingKey: string | null;
     };
 };
 export declare function createAdminEventLogRoutes(deps: AdminEventLogRoutesDeps): Hono<AdminEnv>;

package/dist/routes/admin-events.d.ts

@@ -13,6 +13,9 @@ import type { GenericSourceManager } from '../webhook/generic-sources.js';
 import type { TrustStore } from '../events/trust-store.js';
 import type { TokenManager } from '../secrets/token-manager.js';
 import type { RbacEnforcer, Role } from '../secrets/rbac.js';
+import type { AppConfig } from '../config.js';
+import type { ProviderRegistry } from '../provider-registry.js';
+import type { SecretResolver } from '../secrets/secret-resolver.js';
 /**
  * Dependencies for admin event routes.
  */
@@ -21,6 +24,21 @@ interface AdminEventRouteDeps {
     trustStore: TrustStore;
     tokenManager: TokenManager;
     rbac: RbacEnforcer;
+    /**
+     * The in-process bundle registry. The POST /generic-sources handler
+     * registers an internal / universal-git bundle into this registry
+     * immediately after the source row lands in the DB, so the next
+     * webhook against that source resolves the right normalizer without
+     * waiting for an orchestrator restart.
+     */
+    providerRegistry: ProviderRegistry;
+    /** Needed by `registerProviderBundleForSource` to gate internal-bundle
+     *  registration on `canServeGenericProviderType` and read the
+     *  `internalProviderRepoPath` / `internalProviderCloneUrl` config. */
+    config: AppConfig;
+    /** Required for universal-git source registration — `null` is allowed;
+     *  rows with `git_config` are skipped + metric-bumped in that case. */
+    secretResolver: SecretResolver | null;
     /**
      * Optional — when provided, the `POST /api/v1/admin/events/emit` route is
      * mounted so operators can INSERT into `kici_events` + `pg_notify` via HTTP.
@@ -33,6 +51,7 @@ type AdminEventEnv = {
     Variables: {
         role: Role;
         userId: string;
+        routingKey: string | null;
     };
 };
 /**

package/dist/routes/admin-maintenance.d.ts

@@ -14,9 +14,17 @@
  */
 import { Hono } from 'hono';
 import type { Kysely } from 'kysely';
+import type { Role } from '../secrets/rbac.js';
 interface MaintenanceRouteDeps {
     db: Kysely<any>;
 }
-export declare function createMaintenanceRoutes(deps: MaintenanceRouteDeps): Hono;
+type AdminMaintenanceEnv = {
+    Variables: {
+        role: Role;
+        userId: string;
+        routingKey: string | null;
+    };
+};
+export declare function createMaintenanceRoutes(deps: MaintenanceRouteDeps): Hono<AdminMaintenanceEnv>;
 export {};
 //# sourceMappingURL=admin-maintenance.d.ts.map

package/dist/routes/admin-org-settings.d.ts

@@ -11,11 +11,20 @@
  */
 import { Hono } from 'hono';
 import { type Kysely } from 'kysely';
+import { DashboardWriteOperation } from '@kici-dev/engine/protocol/dashboard-write-operations';
 import type { Database } from '../db/types.js';
 import type { RbacEnforcer, Role } from '../secrets/rbac.js';
+import type { AccessLogWriter } from '../audit/access-log.js';
 interface OrgSettingsRouteDeps {
     db: Kysely<Database>;
     rbac: RbacEnforcer;
+    /**
+     * Optional — when wired, each `dashboard_write_policy` flip emits one
+     * `access_log` row (`org_settings.dashboard_write_policy.update`)
+     * carrying the operation name + prior/next state in `actor_meta`.
+     * Reset calls additionally stamp `reset: true`.
+     */
+    accessLog?: AccessLogWriter;
 }
 type AdminEnv = {
     Variables: {
@@ -25,5 +34,5 @@ type AdminEnv = {
     };
 };
 export declare function createOrgSettingsRoutes(deps: OrgSettingsRouteDeps): Hono<AdminEnv>;
-export {};
+export { DashboardWriteOperation };
 //# sourceMappingURL=admin-org-settings.d.ts.map

package/dist/routes/admin-queue-execution.d.ts

@@ -20,6 +20,7 @@ type AdminQEEnv = {
     Variables: {
         role: Role;
         userId: string;
+        routingKey: string | null;
     };
 };
 export declare function createAdminQueueExecutionRoutes(deps: AdminQueueExecutionRoutesDeps): Hono<AdminQEEnv>;

package/dist/routes/admin-registrations.d.ts

@@ -24,6 +24,7 @@ type AdminRegEnv = {
     Variables: {
         role: Role;
         userId: string;
+        routingKey: string | null;
     };
 };
 /**

package/dist/routes/admin-runs.d.ts

@@ -44,6 +44,7 @@ type AdminRunEnv = {
     Variables: {
         role: Role;
         userId: string;
+        routingKey: string | null;
     };
 };
 /**

package/dist/routes/admin-scheduled-jobs.d.ts

@@ -29,6 +29,7 @@ type AdminEnv = {
     Variables: {
         role: Role;
         userId: string;
+        routingKey: string | null;
     };
 };
 export declare function createAdminScheduledJobsRoutes(deps: AdminScheduledJobsRoutesDeps): Hono<AdminEnv>;

package/dist/routes/admin-sources.d.ts

@@ -10,9 +10,32 @@
  */
 import { Hono } from 'hono';
 import type { SourceStore } from '../sources/source-store.js';
+import type { Role } from '../secrets/rbac.js';
 interface SourceRouteDeps {
     sourceStore: SourceStore;
+    /**
+     * Resolve the public webhook URL for a freshly added source so the CLI can
+     * print it. Platform/hybrid mode registers the source with the Platform and
+     * reads the URL from the `source.register.ack`; independent mode returns a
+     * null URL with an explanatory `webhookNote`. Omitted in deployments with no
+     * resolver wired (the route then returns `webhookUrl: null`).
+     */
+    resolveSourceWebhookUrl?: (params: {
+        routingKey: string;
+        provider: string;
+        sourceId: string;
+    }) => Promise<{
+        webhookUrl: string | null;
+        webhookNote?: string;
+    }>;
 }
-export declare function createSourceRoutes(deps: SourceRouteDeps): Hono;
+type AdminSourcesEnv = {
+    Variables: {
+        role: Role;
+        userId: string;
+        routingKey: string | null;
+    };
+};
+export declare function createSourceRoutes(deps: SourceRouteDeps): Hono<AdminSourcesEnv>;
 export {};
 //# sourceMappingURL=admin-sources.d.ts.map

package/dist/routes/admin.d.ts

@@ -23,6 +23,7 @@ import type { BackendHealthChecker } from '../secrets/backend-health.js';
 import type { BackendSyncManager } from '@kici-dev/engine';
 import type { Kysely } from 'kysely';
 import type pg from 'pg';
+import type { AccessLogWriter } from '../audit/access-log.js';
 /**
  * Dependencies for admin API routes.
  */
@@ -62,6 +63,20 @@ export interface AdminRouteDeps {
     broadcastAgentTokenRevoke?: (tokenId: string) => void;
     /** Optional -- for source management endpoints. */
     sourceStore?: SourceStore;
+    /**
+     * Optional -- resolves the public webhook URL for a newly added source so
+     * `kici-admin source add` can print it. Wired in platform/hybrid mode to
+     * register-and-await the Platform ack; independent mode returns a null URL
+     * with a note.
+     */
+    resolveSourceWebhookUrl?: (params: {
+        routingKey: string;
+        provider: string;
+        sourceId: string;
+    }) => Promise<{
+        webhookUrl: string | null;
+        webhookNote?: string;
+    }>;
     /** Optional -- for DB migration endpoints. */
     db?: Kysely<any>;
     /** Optional -- for DB migration endpoints. */
@@ -83,6 +98,13 @@ export interface AdminRouteDeps {
      * response reports `reEncryptedConfigs: 0`.
      */
     sharedStore?: SharedConfigStore;
+    /**
+     * Optional -- attribution writer for routes that emit an `access_log`
+     * row directly (today: org-settings dashboard-write policy flips). When
+     * unset, those routes execute the mutation without recording — the
+     * write is best-effort, never gating.
+     */
+    accessLog?: AccessLogWriter;
 }
 /** Hono env type for admin routes with context variables. */
 type AdminEnv = {

package/dist/scaler/manager.d.ts

@@ -8,6 +8,7 @@
  */
 import type { ResourceRequest } from '@kici-dev/engine';
 import type { ScalerBackend, ScalerConfig, ScaleResult, ScalerEvent, ResourceCap, ValidationResult } from './types.js';
+import type { ScalerStateStore, ScalerStateRecovery } from './scaler-state-store.js';
 /**
  * Resolved per-job resource amounts (cpus + bytes) for both `requests` and
  * `limits`. The scaler manager produces this from the job's declared resources
@@ -125,6 +126,14 @@ export declare class ScalerManager {
      */
     private readonly onScalerEvent?;
     private readonly warmPool;
+    /**
+     * Optional DB-backed state store. When wired (production path), every
+     * mutation to `spawningAgents` / `agentJobCorrelation` / `reservations`
+     * is write-through-cached to Postgres so a coord crash mid-spawn no
+     * longer orphans agents, strands reservations, or loses correlation.
+     * Unit tests can omit the store and operate from in-memory Maps only.
+     */
+    private readonly stateStore?;
     constructor(deps: {
         config: ScalerConfig;
         backends: Array<{
@@ -133,6 +142,11 @@ export declare class ScalerManager {
         }>;
         /** Callback for relaying scaler events with runId/jobId context. */
         onScalerEvent?: (runId: string, jobId: string, event: ScalerEvent) => void;
+        /**
+         * Optional DB-backed state store. Tests omit it; production wires it
+         * up via the orchestrator-core bootstrap.
+         */
+        stateStore?: ScalerStateStore;
         /**
          * Optional machine-ledger options. When `machinePools` are configured,
          * the manager initializes a `MachineLedger` keyed off this directory and
@@ -316,6 +330,30 @@ export declare class ScalerManager {
      * entries would leak in spawningAgents forever.
      */
     private pruneStaleSpawningEntries;
+    private persistSpawningAgent;
+    private deleteSpawningAgentFromStore;
+    private persistReservation;
+    private deleteReservationFromStore;
+    private persistAgentJob;
+    private deleteAgentJobFromStore;
+    /**
+     * Hydrate the in-memory Maps from the DB-backed state store after a
+     * coord boot or Raft leader switch. Reconstructs:
+     *
+     *   - `spawningAgents` (with `boundJobId` preserved for eager-dispatch on register)
+     *   - `agentJobCorrelation` (so scaler-lifecycle events route correctly)
+     *   - `reservations` + `perScalerUsage` (so the cap-check critical
+     *     section reflects the cluster-wide truth, not the local empty
+     *     starting state)
+     *
+     * The `globalUsage` counter is recomputed from `perScalerUsage` to
+     * keep the cap math consistent. `eventBuffer` is NOT restored — events
+     * emitted by the previous coord before correlation are lost (see
+     * wishlist for the rationale).
+     *
+     * No-op when no store is wired (unit-test path).
+     */
+    recoverState(): Promise<ScalerStateRecovery>;
     private generateAgentId;
     /**
      * Start log forwarding for a scaler-managed agent if its backend supports LogCapture.

package/dist/scaler/scaler-state-store.d.ts

@@ -0,0 +1,102 @@
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import type { ScalerEvent } from './types.js';
+/**
+ * Snapshot of a spawning-agent record. Mirrors the row shape in
+ * `scaler_spawning_agents`.
+ */
+export interface SpawningAgentSnapshot {
+    agentId: string;
+    scalerName: string;
+    labelSet: string[];
+    runId?: string;
+    jobId?: string;
+    boundJobId?: string;
+    spawnedAt: Date;
+}
+/**
+ * Snapshot of an agent-job correlation. Mirrors the row shape in
+ * `scaler_agent_jobs`.
+ */
+export interface AgentJobCorrelationSnapshot {
+    agentId: string;
+    runId: string;
+    jobId: string;
+}
+/**
+ * Snapshot of a resource reservation. Mirrors the row shape in
+ * `scaler_reservations`.
+ */
+export interface ReservationSnapshot {
+    agentId: string;
+    scalerName: string;
+    cpus: number;
+    memBytes: number;
+}
+/**
+ * DB persistence for `ScalerManager` HA-critical state.
+ *
+ * Backed by three tables — `scaler_spawning_agents`, `scaler_agent_jobs`,
+ * `scaler_reservations` — so a Raft leader switch / coord crash no
+ * longer:
+ *
+ *  - orphans an agent that is mid-spawn (lost `boundJobId` → eager
+ *    dispatch silently downgraded to a generic queue drain),
+ *  - strands a reservation (resource counted as used until the agent's
+ *    backend GC eventually disconnects, minutes later),
+ *  - drops the agent → run/job correlation (execution-tracker loses
+ *    scaler-lifecycle events emitted by the new coord).
+ *
+ * The consumer keeps the in-memory Maps as L1 caches. On boot /
+ * become-leader the caches are hydrated via `recoverState()`.
+ *
+ * `perScalerUsage` / `globalUsage` are NOT stored — they are derived
+ * state recomputed from `SUM(...) FROM scaler_reservations` on
+ * recovery, which means the on-disk reservation rows are the single
+ * source of truth for the cap-check critical section.
+ *
+ * The `eventBuffer` Map is also not persisted: events emitted before
+ * correlation are observability, not correctness. A coord crash before
+ * `correlateAgentToJob()` runs accepts losing those events (see the
+ * wishlist for the rationale).
+ */
+export declare class ScalerStateStore {
+    private readonly db;
+    constructor(db: Kysely<Database>);
+    upsertSpawningAgent(snapshot: SpawningAgentSnapshot): Promise<void>;
+    deleteSpawningAgent(agentId: string): Promise<void>;
+    listSpawningAgents(): Promise<SpawningAgentSnapshot[]>;
+    /**
+     * Delete every spawning-agent row whose `spawned_at` is older than the
+     * given cutoff. Used by the leader-gated GC sweep so a coord that
+     * crashed mid-spawn doesn't leave the row blocking the spawn-timeout
+     * detection forever. Returns the row count GC'd.
+     */
+    sweepStaleSpawningAgents(olderThan: Date): Promise<number>;
+    upsertAgentJob(snapshot: AgentJobCorrelationSnapshot): Promise<void>;
+    deleteAgentJob(agentId: string): Promise<void>;
+    listAgentJobs(): Promise<AgentJobCorrelationSnapshot[]>;
+    upsertReservation(snapshot: ReservationSnapshot): Promise<void>;
+    deleteReservation(agentId: string): Promise<void>;
+    listReservations(): Promise<ReservationSnapshot[]>;
+}
+/**
+ * Aggregate event surface for "the scaler manager fully replayed its
+ * state from the DB after a leader switch". Kept here (vs in
+ * manager.ts) so `ScalerManager.recoverState()` can declare a clean
+ * return type. `bufferedEventsLost` always returns 0 today — the
+ * `eventBuffer` Map is intentionally not persisted — but the field
+ * exists so a future buffer-table addition is type-compatible.
+ */
+export interface ScalerStateRecovery {
+    spawningAgentsRehydrated: number;
+    agentJobsRehydrated: number;
+    reservationsRehydrated: number;
+    bufferedEventsLost: number;
+}
+/**
+ * Re-export for the buffered-events note above; sole reason
+ * `ScalerEvent` is imported is to keep that comment compile-checked.
+ */
+export type { ScalerEvent };
+//# sourceMappingURL=scaler-state-store.d.ts.map