@kici-dev/orchestrator 0.6.1 → 0.7.0

package/dist/dashboard/handler.d.ts

@@ -1,6 +1,6 @@
 import { type Kysely } from 'kysely';
 import { type ColdStore } from '@kici-dev/shared';
-import type { DashboardRunDetailRequest, DashboardRunsListRequest, DashboardRunsListResponse, DashboardRunsFiltersRequest, DashboardRunsFiltersResponse, DashboardSourcesListRequest, DashboardSourcesListResponse, DashboardStepLogsRequest, DashboardAttestationsListRequest, DashboardAttestationsListAllRequest, DashboardAttestationGetRequest, DashboardAttestationRetryRequest, DashboardPayloadRequest, DashboardOrchLogsRequest, DashboardEventLogListRequest, DashboardEventLogActivityRequest, DashboardEventLogDetailRequest, DashboardEventLogPayloadStreamRequest, DashboardAccessLogListRequest, DashboardEventDlqListRequest, DashboardEventDlqCountRequest, DashboardEventDlqRetryRequest, DashboardEventDlqDiscardRequest, RunRerunRequest, RunCancelRequest, ManualScheduleRequest, DashboardRunStructuredRequest, DashboardArtifactsListRequest } from '@kici-dev/engine';
+import type { DashboardRunDetailRequest, DashboardRunsListRequest, DashboardRunsListResponse, DashboardRunsFiltersRequest, DashboardRunsFiltersResponse, DashboardSourcesListRequest, DashboardSourcesListResponse, DashboardAdminTokensListRequest, DashboardAdminTokensListResponse, DashboardStepLogsRequest, DashboardAttestationsListRequest, DashboardAttestationsListAllRequest, DashboardAttestationGetRequest, DashboardAttestationRetryRequest, DashboardPayloadRequest, DashboardOrchLogsRequest, DashboardEventLogListRequest, DashboardEventLogActivityRequest, DashboardEventLogDetailRequest, DashboardEventLogPayloadStreamRequest, DashboardAccessLogListRequest, DashboardEventDlqListRequest, DashboardEventDlqCountRequest, DashboardEventDlqRetryRequest, DashboardEventDlqDiscardRequest, RunRerunRequest, RunCancelRequest, ManualScheduleRequest, DashboardRunStructuredRequest, DashboardArtifactsListRequest } from '@kici-dev/engine';
 import type { Database } from '../db/types.js';
 import type { LogStorage } from '../reporting/log-storage.js';
 import type { CacheStorage } from '../storage/types.js';
@@ -233,7 +233,7 @@ export declare class DashboardHandler {
      * unioning both source tables. Uses the identical name/subtype/provider
      * derivation as `handleSourcesList` so a run summary's `source` block
      * matches what the sources page shows for the same routing key. Routing
-     * keys with no live source row are simply absent from the map (the caller
+     * keys with no live source row are absent from the map (the caller
      * falls back to the run's own provider).
      */
     private resolveSourceIdentities;
@@ -303,6 +303,26 @@ export declare class DashboardHandler {
      * carries the wire actor so the customer can audit any operator read.
      */
     handleSourcesList(msg: DashboardSourcesListRequest): Promise<DashboardSourcesListResponse>;
+    /**
+     * Handle a dashboard.admin-tokens.list request.
+     *
+     * Returns the orchestrator's live admin-token inventory for the Platform's
+     * RBAC drift report. `admin_tokens` is orchestrator-wide — an orchestrator
+     * serves exactly one org — so the projection is not filtered by `orgId`; the
+     * handler-bound `orgId` / `routingKey` attribute the access_log row, the same
+     * inline-ctx pattern `handleSourcesList` uses.
+     *
+     * Only live tokens are returned: a revoked or already-expired token is not a
+     * finding, so reporting one would be noise the operator learns to ignore.
+     *
+     * `token_hash` is never selected. The report has no use for it, and a hash is
+     * a credential verifier — relaying one would put an offline-crackable value
+     * on the dashboard plane.
+     *
+     * Reading who holds admin tokens is itself privileged, so every read writes
+     * an access_log row carrying the wire actor.
+     */
+    handleAdminTokensList(msg: DashboardAdminTokensListRequest): Promise<DashboardAdminTokensListResponse>;
     /**
      * Handle a dashboard.step.logs request.
      * Looks up the step's log_path and reads content from LogStorage.

package/dist/db/deferred-indexes.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Indexes built after boot, outside the migration set.
+ *
+ * A migration cannot build an index without locking the table it indexes.
+ * Kysely runs the whole pending batch inside one transaction and offers no
+ * per-migration opt-out, and PostgreSQL rejects `CREATE INDEX CONCURRENTLY`
+ * inside a transaction block outright — so a migration's only option is a
+ * plain `CREATE INDEX`, which holds an exclusive lock for the whole build. On
+ * a table holding millions of rows that is a multi-minute outage bolted onto
+ * an upgrade.
+ *
+ * So an index on a table that scales with run volume goes here instead. Each
+ * entry is built `CONCURRENTLY` on its own connection with no statement
+ * timeout, under an advisory lock distinct from the migration lock, after the
+ * server is already serving. `IF NOT EXISTS` makes every build idempotent, and
+ * a failed build retries on the next boot.
+ *
+ * `hack/check-migration-safety.ts` enforces that new indexes on those tables
+ * land here rather than in a migration.
+ */
+import type pg from 'pg';
+import { type Logger } from '@kici-dev/shared';
+/**
+ * Distinct from the migrator's `543210001`: an index build must not block, or
+ * be blocked by, a peer applying migrations.
+ */
+export declare const DEFERRED_INDEX_LOCK_KEY = 543210002;
+export interface DeferredIndex {
+    /** Index name, matching the one the SQL creates. */
+    name: string;
+    /** A single `CREATE INDEX CONCURRENTLY IF NOT EXISTS` statement. */
+    sql: string;
+}
+/**
+ * Every index the retention sweep and the age-based readers depend on.
+ *
+ * Each one supports a `... < cutoff` scan that would otherwise walk the whole
+ * table on every cleanup tick. The tables already carry indexes for their
+ * serving-path queries; these cover the aging path, whose predicate is not
+ * prefixed by an organization or routing key.
+ */
+export declare const DEFERRED_INDEXES: ReadonlyArray<DeferredIndex>;
+/**
+ * Drop a leftover invalid index before rebuilding it.
+ *
+ * An interrupted `CREATE INDEX CONCURRENTLY` leaves the index in place marked
+ * invalid: it is not used by the planner, and `IF NOT EXISTS` sees it and
+ * skips. Without this, the very first failed build would make the retry a
+ * permanent no-op — the opposite of the "retries on the next boot" contract.
+ */
+export declare function dropIfInvalid(client: Pick<pg.Client, 'query'>, name: string, logger: Logger): Promise<void>;
+export interface BuildDeferredIndexesResult {
+    built: string[];
+    failed: string[];
+}
+/**
+ * Build every deferred index on one dedicated connection.
+ *
+ * The connection is taken straight from `pg` rather than from the serving
+ * pool: `CREATE INDEX CONCURRENTLY` must run outside a transaction and must
+ * not inherit a statement timeout, and a concurrent build on a large table
+ * would otherwise hold a serving connection for its whole duration.
+ *
+ * The advisory lock is `pg_try_advisory_lock`, not the blocking form: when a
+ * peer is already building, this instance has nothing to wait for.
+ */
+export declare function buildDeferredIndexes(databaseUrl: string, opts?: {
+    logger?: Logger;
+    indexes?: ReadonlyArray<DeferredIndex>;
+    pg?: typeof import('pg');
+}): Promise<BuildDeferredIndexesResult>;
+//# sourceMappingURL=deferred-indexes.d.ts.map

package/dist/db/migration-test-harness.d.ts

@@ -13,6 +13,11 @@
  * test can neither name the wrong migration nor drift when a file is renamed.
  * It has no fallback to the whole set: an unknown or no-op target throws.
  *
+ * A DATA migration needs the state one step earlier as well, so it can insert
+ * the rows it is supposed to rewrite: `migrateToPreviousMigration()` provides
+ * it, deriving that target from the migration list rather than from a name the
+ * test spells out.
+ *
  * Repo/store tests outside `migrations/` (host roster, artifact store, the repo
  * suites) legitimately want head-of-list schema and use `migrateToLatest()`
  * directly instead.
@@ -38,4 +43,21 @@ export declare function migrationNameFromTestUrl(testUrl: string): string;
  * "the whole migration set ran".
  */
 export declare function migrateToOwnMigration<DB>(db: Kysely<DB>, testUrl: string): Promise<MigrationResultSet>;
+/**
+ * Apply migrations `001..NNN-1` — everything up to, but NOT including, the
+ * migration the calling test file is named after. Pass `import.meta.url`.
+ *
+ * This is the pre-migration state a DATA migration has to be tested from. A
+ * data migration rewrites rows that already exist, so its test has to straddle
+ * it: migrate here, insert the rows an upgraded database actually holds, then
+ * call {@link migrateToOwnMigration} and assert what moved. Going straight to
+ * `migrateToOwnMigration` leaves no window to insert anything, so the
+ * assertions would run against rows the migration never saw — a check that
+ * passes identically with the migration body deleted.
+ *
+ * The target is derived from the migration list, so the caller never names the
+ * previous migration and cannot drift when one is inserted before it. A test
+ * for the very first migration throws, since there is no earlier state.
+ */
+export declare function migrateToPreviousMigration<DB>(db: Kysely<DB>, testUrl: string): Promise<MigrationResultSet>;
 //# sourceMappingURL=migration-test-harness.d.ts.map

package/dist/db/migrations/131_execution_jobs_git_credentials.d.ts

@@ -0,0 +1,30 @@
+import { type Kysely } from 'kysely';
+/**
+ * Add `execution_jobs.git_credentials JSONB NULL` — the `gitCredentials` map the
+ * job's lock entry declared, as server truth the credential relay can read on
+ * the hot path.
+ *
+ * The relay is called on every git network operation, so it must not re-fetch
+ * or re-parse a lock file to learn what a job is allowed to ask for. The
+ * orchestrator persists no per-job lock entry (`execution_jobs` carries no
+ * config column), so the declaration is written at dispatch and read back here.
+ *
+ * Values follow `LockJob.gitCredentials`: a `<name>Secret` field is a secret
+ * NAME in qualified `<context>:<key>` form, while its `<name>Value` sibling
+ * carries material for a credential with no store entry to name. The column
+ * stores whichever the lock declared, verbatim — it is the declaration the
+ * relay compares a request against, not a secret store of its own.
+ *
+ * Nullable, with no default: NULL means "this job declared no git credentials",
+ * which is true of nearly every job and of every row written before this column
+ * existed. A default would have to name a declaration nobody made. The row is
+ * written after the dispatch loop, so NULL also covers "not written yet" — the
+ * relay resolves that ambiguity against the job's dispatch record rather than
+ * reading it as a declaration (`git/job-context.ts`).
+ *
+ * Idempotent: the add is guarded on existence and the drop uses IF EXISTS, so a
+ * re-run is a no-op.
+ */
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=131_execution_jobs_git_credentials.d.ts.map

package/dist/db/migrations/132_execution_runs_trigger_event.d.ts

@@ -0,0 +1,23 @@
+import { type Kysely } from 'kysely';
+/**
+ * Add `execution_runs.trigger_event TEXT NULL` — the event type that started
+ * the run (`push`, `pr:open`, `schedule`, …).
+ *
+ * The tracker has always carried this value in memory and relayed it to the
+ * dashboard, but never persisted it. The git credential relay needs it: it
+ * evaluates a named context's protection rules against the run, and a context
+ * may restrict which trigger types may use it (`triggerTypeFilters`). Without
+ * the recorded value that rule cannot be evaluated at all.
+ *
+ * Nullable, with no default: a row written before this column existed has no
+ * recorded trigger, and no cluster-wide value could stand in for one. A run
+ * whose trigger is unknown fails a `triggerTypeFilters` rule closed, which is
+ * the correct direction — a credential is withheld rather than granted on a
+ * rule nobody could check.
+ *
+ * Idempotent: the add is guarded on existence and the drop uses IF EXISTS, so a
+ * re-run is a no-op.
+ */
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=132_execution_runs_trigger_event.d.ts.map

package/dist/db/migrations/133_dispatch_queue_source_tar_digest.d.ts

@@ -0,0 +1,23 @@
+import { type Kysely } from 'kysely';
+/**
+ * Add `dispatch_queue.source_tar_digest TEXT NULL` — the SHA-256 of the source
+ * tarball's own bytes, so the agent can verify what it downloaded before
+ * extracting it.
+ *
+ * The neighbouring `source_tar_hash` column carries the workflow `contentHash`
+ * despite its name, which is why the agent's restore path verified nothing: it
+ * had no value to compare the bytes against. `deps_hash` next door has always
+ * held its tarball's real digest, and this column is its source-side sibling.
+ *
+ * Nullable, with no default: NULL means "no digest known for this row", which
+ * is true of every row written before the column existed and of any dispatch
+ * whose source came from somewhere other than the content-addressed cache. The
+ * agent treats NULL as "nothing to verify against" and restores unverified,
+ * exactly as it did before — so an in-flight queue survives the upgrade.
+ *
+ * Idempotent: the add is guarded on existence and the drop uses IF EXISTS, so a
+ * re-run is a no-op.
+ */
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=133_dispatch_queue_source_tar_digest.d.ts.map

package/dist/db/migrations/134_dispatch_queue_ownership.d.ts

@@ -0,0 +1,4 @@
+import { type Kysely } from 'kysely';
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=134_dispatch_queue_ownership.d.ts.map

package/dist/db/migrations/135_cluster_settings_retention_days.d.ts

@@ -0,0 +1,4 @@
+import { type Kysely } from 'kysely';
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=135_cluster_settings_retention_days.d.ts.map

package/dist/db/migrations/136_master_key_wrapped_tables_key_version.d.ts

@@ -0,0 +1,4 @@
+import { type Kysely } from 'kysely';
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=136_master_key_wrapped_tables_key_version.d.ts.map

package/dist/db/migrations/137_execution_runs_pr_head_context.d.ts

@@ -0,0 +1,4 @@
+import { type Kysely } from 'kysely';
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=137_execution_runs_pr_head_context.d.ts.map

package/dist/db/migrations/138_execution_runs_subject_trigger_event.d.ts

@@ -0,0 +1,4 @@
+import { type Kysely } from 'kysely';
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=138_execution_runs_subject_trigger_event.d.ts.map

package/dist/db/migrations/139_admin_token_subject.d.ts

@@ -0,0 +1,4 @@
+import { type Kysely } from 'kysely';
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=139_admin_token_subject.d.ts.map

package/dist/db/migrations/140_dispatch_queue_canonical_labels.d.ts

@@ -0,0 +1,54 @@
+import { type Kysely } from 'kysely';
+/**
+ * Fold `dispatch_queue` label arrays to their canonical (trimmed, lowercase)
+ * form.
+ *
+ * Label matching folds case, and every other label store folds on read.
+ * `dispatch_queue` cannot: its comparison happens in SQL — the `@>` containment
+ * prefilter and the `jsonb_array_elements_text` exclude check — so the SQL
+ * filters rows before any JavaScript sees them. A row enqueued before labels
+ * became case-insensitive carries whatever case the workflow author wrote, so
+ * it would never again match a folded agent label set, and no read-side fold
+ * could rescue it because the row is never selected in the first place. This
+ * migration is what makes those rows reachable.
+ *
+ * The fold mirrors `canonicalizeLabel` in `@kici-dev/engine` —
+ * `btrim(lower(...))` against `raw.trim().toLowerCase()` — so a row this
+ * migration rewrites holds the same bytes as the same labels enqueued today.
+ * Lowercasing alone would strand a padded legacy label the same way a
+ * mixed-case one is stranded, because the agent side trims.
+ *
+ * `runs_on_patterns` / `exclude_patterns` are deliberately untouched: they hold
+ * regex SOURCES, which cannot be lowercased without corrupting the pattern.
+ * Those fold via the forced `i` flag applied when they are read.
+ *
+ * The GIN index `idx_dispatch_queue_labels_gin` needs no change — the query
+ * shape is identical, only the values move.
+ *
+ * `COALESCE(jsonb_agg(...), '[]'::jsonb)` is defence in depth against the
+ * `EXISTS` guard below being loosened, and is unreachable as the statement
+ * stands. `jsonb_agg` over zero rows does return NULL, and a NULL would violate
+ * `runs_on_labels NOT NULL` and leave the drain's `jsonb_array_elements_text`
+ * with nothing to walk on `exclude_labels` — but zero rows requires an empty
+ * array, and an empty array can never satisfy a guard that demands an element
+ * differing from its own folded form. Removing the guard, or replacing it with
+ * one that admits an empty array, makes the COALESCE load-bearing immediately,
+ * so it stays.
+ *
+ * Idempotent: each `UPDATE` selects only rows holding an element that is not
+ * already its own canonical form, so a re-run touches nothing.
+ */
+export declare function up(db: Kysely<unknown>): Promise<void>;
+/**
+ * Irreversible by design: the original case is destroyed, so there is nothing
+ * to restore. This is a data migration, not a schema change, so `down` leaves
+ * the schema exactly as `up` found it and the no-op is the honest outcome
+ * rather than a missing implementation.
+ *
+ * Rolling the orchestrator back is briefly worse than never having migrated:
+ * an old orchestrator compares an agent's labels verbatim against rows this
+ * migration canonicalized, so a fleet whose configured labels are not already
+ * lowercase strands those rows until they expire, drain, or are re-enqueued.
+ */
+export declare function down(): Promise<void>;
+//# sourceMappingURL=140_dispatch_queue_canonical_labels.d.ts.map

package/dist/db/migrations/141_event_log_shed.d.ts

@@ -0,0 +1,15 @@
+import { type Kysely } from 'kysely';
+/**
+ * Extend the event_log.status CHECK constraint with 'shed' so the orchestrator
+ * can record a breadcrumb for a delivery the ingest admission controller
+ * refused under load. Without the row a shed delivery is indistinguishable
+ * from one that never arrived, because the shed happens before the pipeline
+ * that writes every other status.
+ *
+ * Orchestrator-only: the Platform event_log uses a separate, narrower status set.
+ *
+ * Idempotent: the DROP ... IF EXISTS / re-ADD pair re-runs cleanly.
+ */
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=141_event_log_shed.d.ts.map

package/dist/db/migrator.d.ts

@@ -11,6 +11,31 @@ interface MigrateOptions {
     db: Kysely<any>;
     pool: pg.Pool;
 }
+/**
+ * Build a pool reserved for schema work.
+ *
+ * Migrations run DDL and backfills that legitimately take minutes on a
+ * database holding real history, so they must not inherit the hot path's
+ * `statement_timeout`. pg treats `0` as "no limit". Kysely's `Migrator`
+ * acquires its own connections from whatever pool backs the `Kysely` instance
+ * it is given, so the exemption has to be set on the pool — a `SET` issued on
+ * one client would not reach the connections that run the migrations.
+ *
+ * `max: 2` covers the advisory-lock client plus the one Kysely checks out.
+ */
+export declare function createMigrationPool(databaseUrl: string): pg.Pool;
+/**
+ * Run `fn` against a short-lived timeout-free migration pool, then close it.
+ */
+export declare function withMigrationPool<T>(databaseUrl: string, fn: (opts: MigrateOptions) => Promise<T>): Promise<T>;
+/** True when a driver error is a cancelled statement rather than bad SQL. */
+export declare function isStatementTimeoutError(message: string): boolean;
+/**
+ * Restate a migration failure so the log names the migration that failed and,
+ * on a cancelled statement, the way out. The bare driver message names
+ * neither, which is what left an operator with a boot loop and no next step.
+ */
+export declare function describeMigrationFailure(message: string, migrationName?: string): string;
 interface MigrationStatusEntry {
     name: string;
     status: 'applied' | 'pending';
@@ -28,5 +53,27 @@ export declare function runMigrations(opts: MigrateOptions): Promise<MigrationRe
  * Get migration status (applied/pending) without running anything.
  */
 export declare function getMigrationStatus(opts: MigrateOptions): Promise<MigrationStatusEntry[]>;
+/** What a `migrateTo` run did. */
+export interface MigrateToResult {
+    /** The migration the ledger now sits at. */
+    target: string;
+    /** Migrations applied to reach it (empty when moving backwards). */
+    applied: string[];
+    /** Migrations reverted to reach it (empty when moving forwards). */
+    reverted: string[];
+}
+/**
+ * Migrate the ledger to a named migration, in either direction.
+ *
+ * The point of this is rollback: a previous release's static provider does not
+ * carry the newer migrations' names, so Kysely refuses to start against a
+ * ledger that records them (`corrupted migrations: previously executed
+ * migration <name> is missing`). Reverting to the head that release was
+ * running at is what makes the old binary bootable again.
+ *
+ * It runs under the same advisory lock as {@link runMigrations}, so a peer
+ * cannot be applying migrations while this reverts them.
+ */
+export declare function migrateTo(opts: MigrateOptions, name: string): Promise<MigrateToResult>;
 export {};
 //# sourceMappingURL=migrator.d.ts.map

package/dist/db/notify-listener.d.ts

@@ -0,0 +1,60 @@
+/**
+ * A LISTEN subscription that survives losing its connection.
+ *
+ * A `LISTEN` session is a single checked-out client sitting idle. A Postgres
+ * failover, a restart, or an idle-backend sweep terminates it, and the pool's
+ * own error handler discards the broken connection without re-acquiring — so
+ * the subscription is silently gone while `/health` and `/ready` stay 200. The
+ * process keeps running and never hears another NOTIFY on that channel.
+ *
+ * This wraps the pattern once: acquire, subscribe, `LISTEN`, and on `error` or
+ * `end` release the dead client and reconnect with jittered exponential
+ * backoff until `stop()`. NOTIFY has no durable log, so nothing can be
+ * replayed — instead, after a successful re-`LISTEN` the consumer's
+ * `onReconnect` re-derives whatever it missed from the database, which is
+ * exactly what that consumer already does at cold boot.
+ */
+import type pg from 'pg';
+import { type Logger } from '@kici-dev/shared';
+export interface NotifyListenerOptions {
+    pool: pg.Pool;
+    /** Channel name. Interpolated into `LISTEN`, so it must be an identifier. */
+    channel: string;
+    onNotification: (msg: pg.Notification) => void;
+    /**
+     * Re-derive what the subscription missed while it was disconnected. Awaited
+     * after a successful re-`LISTEN`, never on the first connect — a cold start
+     * has its own load path.
+     */
+    onReconnect?: () => Promise<void> | void;
+    logger?: Logger;
+    /** First backoff step. Doubles up to {@link MAX_BACKOFF_MS}. */
+    baseBackoffMs?: number;
+}
+export declare const MAX_BACKOFF_MS = 30000;
+export declare class NotifyListener {
+    private readonly opts;
+    private client;
+    private stopped;
+    private reconnecting;
+    private timer;
+    private attempt;
+    private readonly logger;
+    private readonly baseBackoffMs;
+    constructor(opts: NotifyListenerOptions);
+    /** Acquire a client and subscribe. Throws if the first connect fails. */
+    start(): Promise<void>;
+    /**
+     * Best-effort `UNLISTEN`, then release. Cancels any pending reconnect, so a
+     * shutdown mid-backoff does not resurrect the subscription.
+     */
+    stop(): Promise<void>;
+    /** True while a live client holds the subscription. */
+    get connected(): boolean;
+    private connect;
+    private scheduleReconnect;
+    /** Exponential backoff with full jitter, capped at {@link MAX_BACKOFF_MS}. */
+    private backoffMs;
+    private reconnect;
+}
+//# sourceMappingURL=notify-listener.d.ts.map

package/dist/db/synthetic-job-ids.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The `execution_jobs.job_id` prefix that marks a PLACEHOLDER row.
+ *
+ * A placeholder stands for a job the dispatch pass registered but did not hand
+ * to the dispatcher — one waiting on a `needs` edge, on a rolling-wave slot, on
+ * an invoke-gate summon, or on a protection-rule hold. It exists so the run is
+ * not considered complete without it (`isRunComplete` iterates only registered
+ * jobs), and it is swapped for the real job id the moment the job actually
+ * dispatches (`dispatchReadyJob` → `findSyntheticJobId` → `addJobsToRun`).
+ *
+ * Lives here, beside the table it describes, because both the writers
+ * (`pipeline/`) and the readers that must exclude these rows from an occupancy
+ * count (`contexts/`) key on it, and neither layer imports the other.
+ */
+export declare const NEEDS_PENDING_JOB_ID_PREFIX = "needs-pending-";
+/**
+ * SQL `LIKE` pattern matching every placeholder `job_id`.
+ *
+ * `_` is a single-character wildcard in `LIKE`, so the literal underscore-free
+ * prefix above needs no escaping — kept as one constant anyway so a caller can
+ * never spell the pattern and the prefix differently.
+ */
+export declare const NEEDS_PENDING_JOB_ID_LIKE = "needs-pending-%";
+//# sourceMappingURL=synthetic-job-ids.d.ts.map