@kici-dev/orchestrator 0.17.0 → 0.18.0

package/dist/cluster/cluster-identity.d.ts

@@ -1,10 +1,9 @@
 /**
  * Cluster identity validation for split-brain prevention.
  *
- * In geo-distributed setups, orchestrators may use different connection strings
- * for the same logical DB and S3. URL comparison would falsely flag them as
- * different resources. cluster_id validates that orchestrators share the same
- * logical DB, and the S3 sentinel validates they share the same logical bucket.
+ * Geo-distributed orchestrators may use different connection strings for the same
+ * logical DB and S3, so URL comparison would give false mismatches. cluster_id
+ * proves a shared logical DB; the S3 sentinel proves a shared logical bucket.
  */
 import type { Kysely } from 'kysely';
 interface ClusterIdentityS3Client {
@@ -16,34 +15,27 @@ export interface ClusterIdentityDeps {
     s3Client?: ClusterIdentityS3Client;
     storageBucket?: string;
     /**
-     * Optional storage prefix (mirrors `KICI_STORAGE_PREFIX`). When set, the
-     * sentinel lives under that prefix (`<prefix>/.kici-cluster-id`) so multiple
-     * clusters can share the same physical bucket as long as they use distinct
-     * prefixes. When empty, the sentinel is at the bucket root.
+     * Mirrors `KICI_STORAGE_PREFIX`. When set, the sentinel is
+     * `<prefix>/.kici-cluster-id`, so clusters with distinct prefixes can share one
+     * bucket; when empty, it is at the bucket root.
      */
     storagePrefix?: string;
     /**
-     * Test-only escape hatch — when true, validateS3Sentinel logs a warning and
-     * returns early. Supplied only by the build-time test double's injected
-     * fault-injection policy; the shipped orchestrator always validates.
+     * Test-only: validateS3Sentinel warns and returns early. Only the build-time test
+     * double's fault-injection policy sets it; the shipped orchestrator always validates.
      */
     skipSentinelValidation?: boolean;
 }
 /**
- * Default cache-storage S3 prefix (mirrors the orchestrator config
- * `cacheStorageS3Prefix` default). Empty means the cache blobs and the
- * cluster-identity sentinel live at the bucket root — the bucket already scopes
- * the cluster. Every place that resolves a sentinel prefix (the orchestrator
- * runtime and the `kici-admin cluster reconcile-identity` CLI, including a
- * deploy's pre-start self-heal run of it) MUST fall back to THIS value when no
- * explicit prefix is set, otherwise they compute divergent sentinel keys and
- * crash-loop the orchestrator boot on a spurious "Cluster identity mismatch".
+ * Mirrors the orchestrator config `cacheStorageS3Prefix` default. Empty puts the
+ * cache blobs and the sentinel at the bucket root — the bucket already scopes the
+ * cluster. Every sentinel-prefix resolver (the orchestrator runtime and
+ * `kici-admin cluster reconcile-identity`, including a deploy's pre-start self-heal
+ * run) MUST fall back to THIS value when no prefix is set; divergent sentinel keys
+ * crash-loop the boot on a spurious "Cluster identity mismatch".
  */
 export declare const DEFAULT_CACHE_STORAGE_S3_PREFIX = "";
-/**
- * Build the S3 key for the cluster identity sentinel under an optional prefix.
- * Strips any trailing slash from the prefix so callers can pass either form.
- */
+/** Sentinel S3 key; a trailing slash on the prefix is stripped, so either form works. */
 export declare function clusterSentinelKey(prefix?: string): string;
 export declare class ClusterIdentity {
     private readonly deps;
@@ -51,18 +43,14 @@ export declare class ClusterIdentity {
     /** Read cluster_id from DB. Throws if not found (migration not run). */
     getClusterId(): Promise<string>;
     /**
-     * Validate S3 sentinel file matches DB cluster_id.
-     * - If no S3 configured, skip (filesystem-only deployment).
-     * - If sentinel doesn't exist, write it (first orch to use this bucket).
-     * - If sentinel exists and matches, success.
-     * - If sentinel exists and doesn't match, throw error (different DB/bucket mismatch).
+     * Check the S3 sentinel against the DB cluster_id: skip without S3
+     * (filesystem-only), write it when absent (first orchestrator on this bucket),
+     * throw on mismatch (different DB/bucket).
      */
     validateS3Sentinel(): Promise<void>;
     /**
-     * Validate cluster identity at startup.
-     * Logs cluster_id and instance_id for operational visibility, then runs
-     * S3 sentinel check. Throws on misconfiguration (e.g., different cluster
-     * using same DB/S3).
+     * Logs cluster_id and instance_id, then runs the S3 sentinel check. Throws on
+     * misconfiguration (e.g., a different cluster using the same DB/S3).
      */
     validateAtStartup(instanceId: string): Promise<string>;
 }

package/dist/cluster/cluster-settings-reader.d.ts

@@ -7,52 +7,39 @@ export type ClusterStringColumn = 'dashboard_verified_issuer';
 /** Boolean columns on cluster_settings readable via {@link ClusterSettingsReader}. */
 export type ClusterBooleanColumn = 'global_workflows_enabled';
 /**
- * Ceiling for the three LRU entry-count knobs — `lockfile_cache_max`,
- * `content_cache_max`, and `global_eval_cache_max`.
+ * Boot-safety ceiling for `lockfile_cache_max`, `content_cache_max` and
+ * `global_eval_cache_max`, not a policy preference.
  *
- * This is a boot-safety bound, not a policy preference. The underlying LRU
- * allocates its index arrays eagerly from `max` — several typed arrays plus the
- * TTL and size arrays the caches ask for — so the cost is paid at construction
- * with zero entries cached. Measured on the shipped version: an empty cache at
- * `max` 5,000,000 costs ~191 MB, and at 5,000,000,000 the constructor throws
- * `RangeError: Invalid array length`.
+ * The LRU allocates its index, TTL and size arrays eagerly from `max`, so the
+ * cost is paid with zero entries cached: `max` 5,000,000 costs ~191 MB empty,
+ * and 5,000,000,000 throws `RangeError: Invalid array length`. All three caches
+ * are built inside `bootstrapOrchestrator`, so a bad stored value crashes the
+ * orchestrator before its admin API — the only way `kici-admin cluster-settings`
+ * reaches the value — is listening.
  *
- * That throw is what makes an unbounded knob dangerous rather than merely
- * wasteful. All three caches are built inside `bootstrapOrchestrator`, so a bad
- * stored value crashes the orchestrator before its admin API is listening —
- * and the admin API is the only way `kici-admin cluster-settings` can reach the
- * stored value. The knob would brick the very tool needed to un-brick it.
- *
- * 100,000 is 200x the shipped default of 500 and costs ~4 MB per empty cache,
- * so it is far above any plausible operator setting while keeping boot bounded.
+ * 100,000 is 200x the shipped default of 500 and costs ~4 MB per empty cache.
  */
 export declare const CACHE_MAX_ENTRIES_CEILING = 100000;
 /**
  * Bound a stored entry-count knob to something the LRU constructor survives.
  *
- * Applied at the read site rather than only at the write site, because the
- * write-side validation cannot reach a value that is already in the database —
- * set before the ceiling shipped, or written by any path other than the admin
- * route. Clamping here is what actually guarantees a stored value cannot
- * prevent boot.
+ * Applied at the read site because write-side validation cannot reach a value
+ * already in the database (set before the ceiling shipped, or by a path other
+ * than the admin route).
  *
- * A value that is not a usable positive count (NaN, non-finite, below 1) falls
- * back to the configured default rather than clamping to 1: a 1-entry cache
- * thrashes silently, which is harder to diagnose than ignoring garbage.
- * The fallback is floored and bounded by the ceiling on the same path as the
- * stored value, so neither a fractional nor an above-ceiling configured default
- * can reach the LRU constructor as a non-integer or unclamped max — the
- * constructor rejects both, and either would prevent boot.
+ * A non-usable count (NaN, non-finite, below 1) falls back to the configured
+ * default rather than clamping to 1: a 1-entry cache thrashes silently. The
+ * fallback is floored and clamped on the same path, because the constructor
+ * rejects a non-integer or unclamped max and either would prevent boot.
  */
 export declare function clampCacheMaxEntries(value: number, fallback: number): number;
 /**
- * A knob read that keeps "the operator never set this" separate from "we could
- * not read it".
+ * A knob read that keeps "never set" separate from "could not read".
  *
- * `{ ok: true, value: null }` is a genuine unset — a missing row, a null
- * column, or a cleared (empty) string. `{ ok: false }` means the query failed,
- * so the caller decides: most knobs want their cluster default, but one whose
- * default is a weaker trust tier must hold its last known value instead.
+ * `{ ok: true, value: null }` is a genuine unset (missing row, null column,
+ * cleared string). `{ ok: false }` means the query failed: most knobs want
+ * their cluster default, but one whose default is a weaker trust tier must
+ * hold its last known value instead.
  */
 export type ClusterSettingRead<T> = {
     ok: true;
@@ -62,16 +49,15 @@ export type ClusterSettingRead<T> = {
 };
 /**
  * Reads the single cluster_settings row (id='default') once per short TTL
- * window and serves every fleet-wide knob from that snapshot. `getNumber` and
- * `getString` degrade to the caller's `fallback` (the config.ts cluster
- * default) on no-db / missing row / null column / DB error, so a hot-path read
- * never blocks on a sick DB. {@link ClusterSettingsReader.tryGetString} is the
- * one exception: it reports a failed query as `{ ok: false }` rather than a
- * default, for the caller whose default would be a weaker trust tier.
+ * window and serves every fleet-wide knob from that whole-row snapshot.
+ * `getNumber` and `getString` degrade to the caller's `fallback` (the config.ts
+ * cluster default) on no-db / missing row / null column / DB error, so a
+ * hot-path read never blocks on a sick DB. {@link ClusterSettingsReader.tryGetString}
+ * instead reports a failed query as `{ ok: false }`, for the caller whose
+ * default would be a weaker trust tier.
  *
- * There is exactly one row, so a whole-row cache is strictly simpler than a
- * per-column cache: one DB hit per TTL window serves every column and every
- * read-site.
+ * There is exactly one row, so a whole-row cache is simpler than a per-column
+ * one: one DB hit per TTL window serves every column and every read-site.
  */
 export declare class ClusterSettingsReader {
     private readonly db;
@@ -79,61 +65,48 @@ export declare class ClusterSettingsReader {
     private cache;
     constructor(db: Kysely<Database> | undefined, cacheTtlMs?: number);
     /**
-     * The cached row plus whether it reflects a successful read.
-     *
      * `readable` lives on the cache entry, not around the query, because the
-     * negative cache serves reads 2..N of a TTL window without touching the DB:
-     * deriving "unreadable" from the catch alone would report those reads as a
-     * genuine unset.
+     * negative cache serves reads 2..N of a TTL window without touching the DB;
+     * deriving it from the catch alone would report those reads as a genuine unset.
      */
     private loadSnapshot;
     private loadRow;
     /**
-     * The whole row from one read (undefined when there is no row or the read
-     * failed). For a caller that needs several columns that agree with each
-     * other, such as a value and the row version it belongs to.
+     * The whole row from one read (undefined on no row or a failed read), for a
+     * caller needing columns that agree, such as a value and its row version.
      */
     getRow(): Promise<ClusterSettings | undefined>;
     /** Resolve a fleet-wide numeric knob; `fallback` is the config.ts cluster default. */
     getNumber(column: ClusterNumberColumn, fallback: number): Promise<number>;
     /**
-     * Resolve a fleet-wide text knob; `fallback` is the config.ts cluster default
-     * (which may itself be null). An empty stored string is treated as unset so an
-     * operator clearing the knob via the admin API behaves like a NULL.
+     * `fallback` is the config.ts cluster default (may be null). An empty stored
+     * string is unset, so clearing the knob via the admin API behaves like a NULL.
      */
     getString(column: ClusterStringColumn, fallback: string | null): Promise<string | null>;
     /**
-     * Resolve a fleet-wide text knob without collapsing a read failure into a
-     * default.
-     *
-     * There is deliberately no `fallback` parameter: the point of this variant is
-     * that the caller — not the reader — decides what an unreadable knob means.
-     * An empty stored string is unset, matching {@link getString}.
+     * Resolve a text knob without collapsing a read failure into a default:
+     * deliberately no `fallback`, so the caller decides what an unreadable knob
+     * means. An empty stored string is unset, matching {@link getString}.
      */
     tryGetString(column: ClusterStringColumn): Promise<ClusterSettingRead<string>>;
     /**
-     * Resolve a fleet-wide boolean knob without collapsing a read failure into a
-     * default.
+     * Resolve a boolean knob without collapsing a read failure into a default.
      *
-     * There is deliberately no `getBoolean(column, fallback)` companion. The
-     * security gate that consumes this must tell the reader's outcomes apart
-     * itself: a stored `false` and a NULL both deny today, but they deny for
-     * different reasons, and `{ ok: false }` must deny regardless of what the
-     * configured default happens to be. A convenience wrapper that folded the
-     * failure into the default would be safe only for as long as that default
-     * stayed `false`. A caller that only needs a display value (the dashboard
-     * status badge) folds `{ ok: false }` into the default explicitly at its own
-     * site, where getting it wrong misreports a badge rather than opening a gate.
+     * Deliberately no `getBoolean(column, fallback)` companion: the consuming
+     * security gate must deny on `{ ok: false }` whatever the configured default
+     * is, and a wrapper folding failure into the default is safe only while that
+     * default stays `false`. A display-only caller (the dashboard status badge)
+     * folds `{ ok: false }` into the default at its own site, where a mistake
+     * misreports a badge rather than opening a gate.
      */
     tryGetBoolean(column: ClusterBooleanColumn): Promise<ClusterSettingRead<boolean>>;
     /**
-     * The cluster_settings row version last seen in the cache (0 if never loaded).
+     * The row version last seen in the cache (0 if never loaded).
      *
-     * Synchronous — never awaits a DB read — so the heartbeat timer can read it
-     * safely and advertise it to workers. When the cache is cold or expired it
-     * kicks a non-blocking refresh so the advertised version self-heals within a
-     * cache-TTL window without depending on a `getNumber()` call, then returns
-     * the last-loaded value.
+     * Synchronous, so the heartbeat timer can advertise it to workers. A cold or
+     * expired cache kicks a non-blocking refresh, so the advertised version
+     * self-heals within a TTL window without a `getNumber()` call; this call
+     * returns the last-loaded value.
      */
     getCachedVersion(): number;
 }

package/dist/cluster/coordinator-credential.d.ts

@@ -27,11 +27,10 @@ export declare enum RejectionCorroboration {
     Unreadable = "unreadable"
 }
 /**
- * The `corroborateRejection` callback a coordinator's `PeerAuthCoordinator`
- * runs before it deletes its credential file after a peer rejected it. Any
- * dialled endpoint can send a rejection, so the coordinator's own database
- * decides: an expired or revoked row does not hold the credential, and the file
- * then goes so the self-issue path reconciles.
+ * The `corroborateRejection` callback run before deleting the credential file
+ * after a peer rejected it. Any dialled endpoint can send a rejection, so the
+ * coordinator's own database decides: an expired or revoked row does not hold
+ * the credential, and the file then goes so the self-issue path reconciles.
  */
 export declare function coordinatorRejectionCorroborator(opts: {
     db: Kysely<Database>;