@kici-dev/orchestrator 0.17.0 → 0.18.0

package/dist/db/migrations/125_org_trust_directory.d.ts

@@ -1,29 +1,21 @@
 import { type Kysely } from 'kysely';
 /**
- * Create `org_trust_directory` — the orchestrator's cache of the Platform-owned
- * approval directory pushed alongside the policy on `trust_policy.update`:
- * identity links, per-member CI trust levels, and team memberships.
+ * Create `org_trust_directory`: the orchestrator's cache of the Platform-owned approval directory
+ * pushed with the policy on `trust_policy.update` — identity links, per-member CI trust levels
+ * and team memberships.
  *
- * A sibling of `org_trust_policy` rather than more columns on it: the policy is
- * four scalar switches, while these three are structured documents the Platform
- * replaces wholesale on every push — `identity_links` and `team_memberships`
- * are arrays, `member_ci_trust` is a user-id-keyed map — so they are stored as
- * JSONB.
+ * A sibling of `org_trust_policy`, not more columns on it: the policy is scalar switches, while
+ * these are structured documents the Platform replaces wholesale on every push (arrays, and a
+ * user-id-keyed map for `member_ci_trust`), stored as JSONB.
  *
- * Persisting rather than holding them only in memory is what lets
- * `/kici approve` authorize a commenter after a restart. Without a cached
- * directory the orchestrator cannot map a comment author onto a KiCI user at
- * all until the Platform's next push lands, so every approval is refused in the
- * meantime.
+ * Persisting it lets `/kici approve` authorize a commenter after a restart; without it the
+ * orchestrator cannot map a comment author to a KiCI user, and refuses every approval, until the
+ * next Platform push.
  *
- * Wherever a Platform is attached it is the only writer of this row. An
- * independent orchestrator has no Platform, so there the operator writes it
- * through `kici-admin trust-policy directory-set`. The two are mutually
- * exclusive — the admin route refuses the local write on any Platform-attached
- * orchestrator — so a deployment still only ever has one writer, and there is
- * no counterpart to `org_trust_policy.source` to record which it was.
- *
- * Idempotent: guarded by IF NOT EXISTS, so a re-run is a no-op.
+ * A Platform-attached orchestrator's only writer is the Platform; an independent one's is the
+ * operator, via `kici-admin trust-policy directory-set`. The admin route refuses the local write
+ * when a Platform is attached, so there is one writer and no counterpart to
+ * `org_trust_policy.source`. Idempotent (IF NOT EXISTS).
  */
 export declare function up(db: Kysely<unknown>): Promise<void>;
 export declare function down(db: Kysely<unknown>): Promise<void>;

package/dist/db/migrations/126_held_runs_posted_pending_check.d.ts

@@ -3,25 +3,19 @@ import { type Kysely } from 'kysely';
  * Add `held_runs.posted_pending_check boolean` — whether this hold's pending
  * `KiCI Security` check actually reached the provider.
  *
- * `postCheckStatus` CREATES the named check run when it finds none, so
- * terminalizing a check the hold never posted does not close anything: it puts
- * a completed `KiCI Security` run on a commit that had none. Whether a hold
- * posted one was derived from the row's SHAPE, which answers what the code
- * INTENDED — a post that the provider refused, or that no check poster was in
- * reach to attempt, leaves a shape that says "posted" and a commit that has
- * nothing. The column records what happened instead of what was meant.
+ * `postCheckStatus` CREATES the named check run when it finds none, so terminalizing a check
+ * the hold never posted fabricates a completed `KiCI Security` run. The row's SHAPE only says
+ * what the code intended: a refused post, or one no check poster could attempt, still reads
+ * "posted". This column records what happened.
  *
- * Nullable, with no default, and the three values are distinct:
+ * Nullable, no default:
  *
- * - `true` — the post returned successfully. The hold owns the check.
- * - `false` — no post was attempted, or one was attempted and failed. Nothing
- *   to terminalize; a settle would fabricate.
- * - `null` — the row predates this column, so nothing recorded either way. The
- *   shape derivation still answers for it. A `false` DEFAULT would instead
- *   declare every hold pending at deploy time un-posted and strand the checks
- *   they really do have.
+ * - `true` — the post succeeded; the hold owns the check.
+ * - `false` — no post, or a failed one. Nothing to terminalize; a settle would fabricate.
+ * - `null` — the row predates this column; the shape derivation still answers for it. A `false`
+ *   DEFAULT would mark every hold pending at deploy time un-posted and strand its real check.
  *
- * Idempotent: a re-run on a DB that already has the column is a no-op.
+ * Idempotent.
  */
 export declare function up(db: Kysely<unknown>): Promise<void>;
 export declare function down(db: Kysely<unknown>): Promise<void>;

package/dist/db/migrations/127_org_trust_policy_approval_expiry_seconds.d.ts

@@ -2,24 +2,16 @@ import { type Kysely } from 'kysely';
 /**
  * Add `org_trust_policy.approval_expiry_seconds` (nullable INTEGER).
  *
- * The authoritative security-hold window, at the granularity the existing
- * `approval_expiry_hours` cannot express. Nullable rather than NOT NULL with a
- * default, and deliberately NOT backfilled: NULL means "no seconds value was
- * ever written", and every reader falls back to `approval_expiry_hours * 3600`
- * for such a row. A backfill would have to guess, and a NOT NULL default would
- * make a row written by an older build — which does not know the column —
- * silently claim the default window instead of the hours the operator set.
+ * The authoritative security-hold window, finer than `approval_expiry_hours` can express.
+ * Nullable and deliberately NOT backfilled: NULL means "no seconds value written", and readers
+ * fall back to `approval_expiry_hours * 3600`. A backfill would guess, and a NOT NULL default
+ * would make a row written by an older build silently claim the default window instead of the
+ * operator's hours. `contexts.hold_expiry_seconds` uses the same shape for the same reason.
  *
- * The same shape `contexts.hold_expiry_seconds` already uses for the same
- * reason: "null = unset, the default window applies".
+ * `approval_expiry_hours` stays: it is the only window an older peer reads and what a partial
+ * write supplies, and dropping it (NOT NULL, no default) would break a rollback outright.
  *
- * `approval_expiry_hours` is kept. It is not dead — it is still the only window
- * an older peer can read, and it is still what a partial write supplies — so
- * dropping it would be a destructive schema change against a protected surface
- * and would break a rollback outright (the column is NOT NULL with no default).
- *
- * Idempotent: guarded on column existence; a re-run on a DB that already has
- * the column is a no-op.
+ * Idempotent: guarded on column existence.
  */
 export declare function up(db: Kysely<unknown>): Promise<void>;
 export declare function down(db: Kysely<unknown>): Promise<void>;

package/dist/db/migrations/128_execution_runs_global_eval_round.d.ts

@@ -4,19 +4,14 @@ import { type Kysely } from 'kysely';
  * the structural marker for a run row that records a global evaluation round
  * rather than a workflow.
  *
- * The re-run path must recognise such a run: re-running it re-executes the
- * evaluation, not a workflow. The only discriminator available to it otherwise
- * is the round job's `__globaleval__` name prefix, which a customer workflow
- * may carry — a name a customer chooses cannot decide which code path a re-run
- * takes. A column stamped where the round failure is recorded is
+ * Re-running such a run re-executes the evaluation, not a workflow. The only
+ * other discriminator is the round job's `__globaleval__` name prefix, which a
+ * customer workflow may carry, so a customer-chosen name would pick the re-run
+ * code path; a column stamped where the round failure is recorded is
  * collision-proof.
  *
- * `NOT NULL DEFAULT false` because the question has exactly two answers: every
- * pre-existing row is an ordinary run, and there is no third "unknown" reading
- * a null would carry.
- *
- * Idempotent: the add is guarded on existence and the drop uses IF EXISTS, so a
- * re-run is a no-op.
+ * `NOT NULL DEFAULT false`: every pre-existing row is an ordinary run, and no
+ * third "unknown" answer exists for a null to carry. Idempotent.
  */
 export declare function up(db: Kysely<unknown>): Promise<void>;
 export declare function down(db: Kysely<unknown>): Promise<void>;

package/dist/db/migrations/129_execution_runs_dispatch_routing_key.d.ts

@@ -3,18 +3,15 @@ import { type Kysely } from 'kysely';
  * Add `execution_runs.dispatch_routing_key TEXT NULL` — the source whose
  * credentials a run's `provider_context` actually holds.
  *
- * `routing_key` records the source the event ARRIVED on. For a cross-provider
- * global workflow those are two different sources: the lock file resolves
- * through another source's bundle, and `provider_context` is written from that
- * source's credentials. Anything that pairs the inbound routing key with the
- * stored context therefore hands one source's credentials to another source's
- * API client — the re-run of a failed evaluation round did exactly that, and
- * the resulting fetch either fails or reads the wrong tree.
+ * `routing_key` is the source the event ARRIVED on. For a cross-provider global
+ * workflow the lock file resolves through another source's bundle, whose
+ * credentials fill `provider_context`. Pairing the inbound routing key with that
+ * context hands one source's credentials to another's API client (as the re-run
+ * of a failed evaluation round did): the fetch fails or reads the wrong tree.
  *
- * Nullable, with no default: NULL means "the same source the event arrived on",
- * which is true of every run except a cross-provider dispatch and of every row
- * written before this column existed. A default would have to name a routing
- * key, and there is no cluster-wide one to name.
+ * Nullable, no default: NULL means the arrival source, true of every run except
+ * a cross-provider dispatch and of every older row. There is no cluster-wide
+ * routing key a default could name.
  *
  * Idempotent: the add is guarded on existence and the drop uses IF EXISTS, so a
  * re-run is a no-op.

package/dist/db/migrations/130_scaler_provision_outcomes.d.ts

@@ -2,30 +2,23 @@ import { type Kysely } from 'kysely';
 /**
  * Durable per-provision outcome, keyed by agent id.
  *
- * `scaler_spawning_agents` is deleted the moment a provision is torn down, so
- * its absence cannot tell "this provision was never adopted" from "this
- * provision was adopted and has since been torn down". The stale-spawn prune
- * has to separate exactly those two, because the first is a real external
- * provisioning failure every coordinator must back off on, and the second is a
- * healthy provision that must not be reported at all.
+ * A `scaler_spawning_agents` row is deleted at teardown, so its absence cannot separate "never
+ * adopted" (a real provisioning failure every coordinator must back off on) from "adopted, then
+ * torn down" (healthy; never reported). The stale-spawn prune needs exactly that split.
  *
- * This table carries the positive signal the spawn row cannot: the adoption is
- * written in the same transaction that stamps `adopted_by`, and it outlives the
- * spawn row's delete. Deliberately a separate table rather than a column on
- * `scaler_spawning_agents`: that row's delete is what the per-coordinator
- * provisioning backoff depends on, so it is left exactly as it is.
+ * The adoption is written in the same transaction that stamps `adopted_by` and outlives the
+ * spawn row. A separate table, not a column, because the per-coordinator provisioning backoff
+ * depends on the spawn row's delete.
  *
- * `adopted_*` and `condemned_*` are independent. A provision that was adopted
- * and later condemned by the reaper carries BOTH, and the condemn write never
- * touches the adoption columns — losing the adoption fact would restore the
- * misattribution this table exists to remove.
+ * `adopted_*` and `condemned_*` are independent: a provision adopted and later condemned
+ * carries BOTH, and the condemn write never touches the adoption columns, or the
+ * misattribution returns.
  *
- * Rows are purged by the leader-gated reaper once the spawn row is gone and the
- * retention floor has passed; see `ScalerStateStore.purgeProvisionOutcomes`.
+ * The leader-gated reaper purges rows once the spawn row is gone and the retention floor has
+ * passed (`ScalerStateStore.purgeProvisionOutcomes`).
  *
- * Idempotent: both statements are guarded by IF NOT EXISTS, so a re-run is a
- * no-op — including a re-run over a database that has the table but not the
- * index, which an existence probe over the table alone would skip.
+ * Idempotent: each statement is IF NOT EXISTS, covering a database with the table but not the
+ * index, which a table-existence probe would skip.
  */
 export declare function up(db: Kysely<unknown>): Promise<void>;
 export declare function down(db: Kysely<unknown>): Promise<void>;

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

@@ -1,29 +1,19 @@
 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.
+ * Add `execution_jobs.git_credentials`: the job lock entry's `gitCredentials` map, as server
+ * truth the credential relay reads on the hot path. The relay runs on every git network
+ * operation, so it must not re-parse a lock file, and `execution_jobs` has no config column, so
+ * the declaration is written at dispatch.
  *
- * 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 qualified
+ * `<context>:<key>` secret NAME; a `<name>Value` sibling carries material for a credential with
+ * no store entry. Stored verbatim as the declaration the relay compares requests against, not a
+ * secret store.
  *
- * 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.
+ * Nullable, no default: NULL means "declared no git credentials" (nearly every job, and every
+ * older row); a default would name a declaration nobody made. The row is written after the
+ * dispatch loop, so NULL also covers "not written yet", which the relay resolves against the
+ * job's dispatch record (`git/job-context.ts`). Idempotent.
  */
 export declare function up(db: Kysely<unknown>): Promise<void>;
 export declare function down(db: Kysely<unknown>): Promise<void>;

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

@@ -1,22 +1,12 @@
 import { type Kysely } from 'kysely';
 /**
- * Add `execution_runs.trigger_event TEXT NULL` — the event type that started
- * the run (`push`, `pr:open`, `schedule`, …).
+ * Add `execution_runs.trigger_event`: the event type that started the run (`push`, `pr:open`,
+ * `schedule`, …). The git credential relay evaluates a context's `triggerTypeFilters` against it,
+ * which needs the persisted value, not the tracker's in-memory copy.
  *
- * 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.
+ * Nullable, no default: an older row has no recorded trigger and no cluster-wide value can stand
+ * in. An unknown trigger fails a `triggerTypeFilters` rule closed, withholding the credential.
+ * Idempotent.
  */
 export declare function up(db: Kysely<unknown>): Promise<void>;
 export declare function down(db: Kysely<unknown>): Promise<void>;

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

@@ -4,16 +4,13 @@ import { type Kysely } from 'kysely';
  * 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.
+ * Despite its name, `source_tar_hash` carries the workflow `contentHash`, so the
+ * agent had no digest to check the bytes against. This is the source-side
+ * sibling of `deps_hash`, which holds its tarball's real digest.
  *
- * 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.
+ * Nullable, no default: NULL means no digest is known (every older row, and any
+ * source not from the content-addressed cache). The agent then restores
+ * unverified, 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.

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

@@ -1,54 +1,36 @@
 import { type Kysely } from 'kysely';
 /**
- * Fold `dispatch_queue` label arrays to their canonical (trimmed, lowercase)
- * form.
+ * 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.
+ * Every other label store folds on read, but `dispatch_queue` compares in SQL (the `@>`
+ * prefilter and the `jsonb_array_elements_text` exclude check), filtering rows before any
+ * JavaScript sees them. A row enqueued before labels became case-insensitive would never match
+ * a folded agent label set again, and is never selected for a read-side fold to rescue.
  *
- * 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.
+ * The fold mirrors `canonicalizeLabel` in `@kici-dev/engine` (`btrim(lower(...))` against
+ * `raw.trim().toLowerCase()`), so a rewritten row holds the same bytes as labels enqueued today.
+ * Lowercasing alone would strand a padded legacy label, 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.
+ * `runs_on_patterns` / `exclude_patterns` stay untouched: they hold regex SOURCES that
+ * lowercasing would corrupt, and fold via the forced `i` flag on read. The GIN index
+ * `idx_dispatch_queue_labels_gin` needs no change: only the values move.
  *
- * 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 unreachable as written and is defence in depth
+ * against the `EXISTS` guard being loosened. `jsonb_agg` over zero rows returns NULL, which would
+ * violate `runs_on_labels NOT NULL` and leave the drain nothing to walk on `exclude_labels`; zero
+ * rows needs an empty array, which the guard (an element differing from its folded form) never
+ * admits. A guard that admits an empty array makes the COALESCE load-bearing.
  *
- * `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.
+ * Idempotent: each `UPDATE` selects only rows with a non-canonical element.
  */
 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.
+ * Irreversible by design: the original case is destroyed. As a data migration, `up` changed no
+ * schema, so the no-op is the honest `down`.
  *
- * 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.
+ * Rolling the orchestrator back is briefly worse than never migrating: an old orchestrator
+ * compares agent labels verbatim against canonicalized rows, so a fleet with non-lowercase
+ * labels 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/143_execution_jobs_precursor_result.d.ts

@@ -1,25 +1,16 @@
 import { type Kysely } from 'kysely';
 /**
- * Add `execution_jobs.precursor_result JSONB NULL` — the payload a precursor
- * job (source-pack build, init, dynamic eval) reports on its terminal
- * `job.status`, persisted so a coordinator other than the one whose agent ran
- * the job can read it back.
+ * Add `execution_jobs.precursor_result`: the payload a precursor job (source-pack build, init,
+ * dynamic eval) reports on its terminal `job.status`, readable by any coordinator.
  *
- * The dispatch queue is cluster-wide: a job one coordinator dispatched may be
- * claimed by an agent connected to a sibling coordinator. The sibling receives
- * the agent's terminal frame; the coordinator awaiting the job never does. The
- * shared row is the channel between them, and until this column existed the
- * row carried the status but not the result — a build's `buildComplete`
- * marker, an init's resolved fields, a dynamic eval's generated jobs — so the
- * awaiting coordinator waited out its build timeout on a build that had
- * succeeded.
+ * The dispatch queue is cluster-wide, so an agent on a sibling coordinator may run the job and
+ * receive its terminal frame, which the awaiting coordinator never sees. The shared row is their
+ * channel; without the result (a build's `buildComplete` marker, an init's resolved fields, a
+ * dynamic eval's generated jobs) the awaiting coordinator waited out its build timeout on a
+ * successful build.
  *
- * Nullable, with no default: NULL means "this job reported no precursor
- * payload", which is true of every ordinary job and of every row written
- * before this column existed.
- *
- * Idempotent: the add is guarded on existence and the drop uses IF EXISTS, so a
- * re-run is a no-op.
+ * Nullable, no default: NULL means "no precursor payload" (every ordinary job and older row).
+ * Idempotent.
  */
 export declare function up(db: Kysely<unknown>): Promise<void>;
 export declare function down(db: Kysely<unknown>): Promise<void>;

package/dist/db/migrations/144_execution_runs_registration_window.d.ts

@@ -3,29 +3,21 @@ import { type Kysely } from 'kysely';
  * Add `execution_runs.registration_window_instance_id TEXT NULL` — the
  * coordinator whose dispatch pipeline still has jobs to register for this run.
  *
- * A run is registered before all of its jobs exist: with its source-pack build
- * job alone, or with no jobs at all ahead of its dispatch loop, and the real
- * jobs land only once the build finishes or every dispatch has returned. The
- * coordinator running that pipeline holds an in-memory token that keeps its
- * own completion check from finalizing the run on the jobs registered so far.
+ * A run is registered before all its jobs exist (with only its source-pack build job, or none
+ * ahead of its dispatch loop). The coordinator running that pipeline holds an in-memory token
+ * that stops its own completion check from finalizing the run early.
  *
- * The dispatch queue is cluster-wide, so a job may be claimed by an agent
- * connected to a sibling coordinator, and that sibling rehydrates the run from
- * the database when the agent reports on it. The sibling has no token, so
- * once the jobs it knows about are terminal it finalizes the run — on a build
- * job alone, that is a green run in which nothing ran. This column is the
- * token's durable form: the owner writes its instance id when it takes its
- * first token and clears it when it drops its last, and every finalization
- * path defers while the column names a live sibling.
+ * A sibling coordinator whose agent claims one of the jobs rehydrates the run from the DB with
+ * no token, and would finalize it once its known jobs are terminal: on a build job alone, a
+ * green run in which nothing ran. This column is the token's durable form: the owner writes
+ * its instance id on its first token and clears it on its last, and every finalization path
+ * defers while it names a live sibling.
  *
- * Nullable, with no default: NULL means "no coordinator has a registration
- * window open", which is true of every run whose owner released its window
- * and of every row written before this column existed. A dead holder's id
- * reads as no window at all — liveness comes from `cluster_instances`, the
- * same way the dispatch plane reads `dispatch_queue.owner_instance_id`.
+ * Nullable, no default: NULL means no registration window is open (including older rows). A
+ * dead holder's id reads as no window; liveness comes from `cluster_instances`, as for
+ * `dispatch_queue.owner_instance_id`.
  *
- * Idempotent: the add is guarded on existence and the drop uses IF EXISTS, so a
- * re-run is a no-op.
+ * Idempotent: the add is guarded on existence and the drop uses IF EXISTS.
  */
 export declare function up(db: Kysely<unknown>): Promise<void>;
 export declare function down(db: Kysely<unknown>): Promise<void>;

package/dist/db/migrations/147_sealed_job_secrets.d.ts

@@ -1,15 +1,11 @@
 import { type Kysely } from 'kysely';
 /**
- * Hold the secret fields of a stored job encrypted under the orchestrator
- * master key, beside the plain JSON column that keeps every other field.
+ * `sealed_secrets` holds a stored job's secret fields under the orchestrator master key, beside
+ * the plain JSON column (`dispatch_queue.job_config`, `pending_job_contexts.job_input`,
+ * `pending_workflow_contexts.context`) that keeps every other field.
  *
- * Adds a nullable `sealed_secrets text` column to the three tables a job waits
- * in: `dispatch_queue` (its `job_config`), `pending_job_contexts` (its
- * `job_input`), and `pending_workflow_contexts` (its `context`).
- *
- * Nullable and unbackfilled: NULL on every row written before this column
- * existed, and on every row an orchestrator without a master key writes. Such
- * a row keeps its secret fields in the plain column and reads back unchanged.
+ * Nullable and unbackfilled: NULL on older rows and on rows an orchestrator without a master
+ * key writes; such a row keeps its secrets in the plain column and reads back unchanged.
  *
  * Idempotent: each column is added only when missing.
  */

package/dist/db/migrations/148_cluster_settings_sealed_secrets_retry_backoff_ms.d.ts

@@ -1,20 +1,14 @@
 import { type Kysely } from 'kysely';
 /**
- * Add `cluster_settings.sealed_secrets_retry_backoff_ms` (nullable bigint).
+ * How long a coordinator leaves a queued job alone after failing to open its sealed secrets
+ * (sealed under a master key it does not hold). During a rolling key rotation a coordinator
+ * holding the key can take the job in that window; each later re-claim spends a dispatch
+ * attempt, so a job no coordinator can open still fails.
  *
- * How long a coordinator leaves a queued job alone after it claimed the job and
- * could not open its sealed secrets: the job was sealed with a master key this
- * coordinator does not hold. During a rolling key rotation a coordinator that
- * holds the key can take the job in that window; after it, this coordinator can
- * claim the job again, and each claim spends another dispatch attempt, so a job
- * no coordinator can open still fails.
+ * On `cluster_settings` because every coordinator drains the same queue. NULL ⇒ the
+ * orchestrator's configured default.
  *
- * Cluster-global (every coordinator drains the same queue), so it lives on
- * `cluster_settings` rather than `org_settings`. NULL ⇒ the orchestrator's own
- * configured default applies.
- *
- * Idempotent: guarded on column existence; a re-run on a DB that already has the
- * column is a no-op.
+ * Idempotent: guarded on column existence.
  */
 export declare function up(db: Kysely<unknown>): Promise<void>;
 export declare function down(db: Kysely<unknown>): Promise<void>;

package/dist/db/migrations/150_execution_runs_status_epoch.d.ts

@@ -1,17 +1,12 @@
 import { type Kysely } from 'kysely';
 /**
- * Add `execution_runs.status_epoch` (integer, NOT NULL, default 0).
+ * Add `execution_runs.status_epoch`: the run's status generation. The tracker raises it each time
+ * a run leaves a terminal status (it failed before an already-dispatched job reported in, and
+ * continues). Every `execution.status` frame carries it, so the Platform keeps a finished run
+ * finished against a late non-terminal frame and still follows a real reopen.
  *
- * The run's status generation. It starts at 0, and the tracker raises it each
- * time a run leaves a terminal status: a run failed before a job it had already
- * dispatched reported in, and the run continues. Every `execution.status` frame
- * carries it, so the Platform can keep a finished run finished against a
- * non-terminal frame that arrives late, and still follow a real reopen.
- *
- * A constant default adds the column without rewriting the table, and every
- * existing row reads 0: none of them was reopened under this counter.
- *
- * Idempotent: guarded on the column's existence, so re-running is a no-op.
+ * The constant default 0 adds the column without a table rewrite; no existing row was reopened
+ * under this counter. Idempotent.
  */
 export declare function up(db: Kysely<unknown>): Promise<void>;
 export declare function down(db: Kysely<unknown>): Promise<void>;

package/dist/db/migrations/152_org_settings_cache_upload_settle_timeout.d.ts

@@ -1,14 +1,11 @@
 import { type Kysely } from 'kysely';
 /**
- * Add `org_settings.cache_upload_settle_timeout_ms BIGINT` (nullable).
+ * Per-org bound on how long a build job's `job.status success` waits for the cache publish
+ * (object metadata plus pointer) its agent reported just before it. NULL ⇒ cluster default
+ * (`KICI_CACHE_UPLOAD_SETTLE_TIMEOUT_MS`, 10s); 0 turns the wait off. Set via
+ * `kici-admin org-settings cache-upload-settle`.
  *
- * Per-org bound on how long a build job's `job.status success` waits for the
- * cache publish (object metadata plus pointer) its agent reported just before
- * it. NULL falls back to the cluster default
- * (`KICI_CACHE_UPLOAD_SETTLE_TIMEOUT_MS`, 10s); 0 turns the wait off. Operators
- * tune it via `kici-admin org-settings cache-upload-settle`.
- *
- * Idempotent: a re-run on a DB that already has the column is a no-op.
+ * Idempotent.
  */
 export declare function up(db: Kysely<unknown>): Promise<void>;
 export declare function down(db: Kysely<unknown>): Promise<void>;