@kici-dev/orchestrator 0.1.27 → 0.3.0

package/dist/scaler/types.d.ts

@@ -6,7 +6,7 @@
  */
 import { z } from 'zod';
 import { ScalerEventType } from '@kici-dev/engine';
-import type { ResourceRequest, ResourceSpec, ScalerBackendType } from '@kici-dev/engine';
+import type { ResourceRequest, ResourceSpec, ScalerBackendType, ScalerPlatform } from '@kici-dev/engine';
 export type { ResourceRequest, ResourceSpec } from '@kici-dev/engine';
 export { ScalerEventType } from '@kici-dev/engine';
 /**
@@ -73,6 +73,22 @@ export interface NetworkPolicy {
     /** Block all outbound traffic except allowlisted ranges */
     denyAll?: boolean;
 }
+/**
+ * Image pull policy for container-backend agent images.
+ *
+ * - `IfNotPresent` (default): pull only when the image is not already local.
+ *   KiCI agent images are pinned + immutable, so re-pulling on every spawn only
+ *   storms the registry/socket.
+ * - `Always`: re-pull on every spawn. Set this on a label set that tracks a
+ *   moving tag (e.g. `:latest`) or otherwise needs a fresh image each spawn.
+ * - `Never`: never pull; fail if the image is absent.
+ */
+export declare const ImagePullPolicy: z.ZodEnum<{
+    Always: "Always";
+    IfNotPresent: "IfNotPresent";
+    Never: "Never";
+}>;
+export type ImagePullPolicy = z.infer<typeof ImagePullPolicy>;
 /**
  * Configuration for a single label-set mapping within a scaler backend.
  * Maps an exact set of labels to the agent provisioning details.
@@ -82,8 +98,8 @@ export interface LabelSetConfig {
     labels: string[];
     /** Container image (Docker backend) */
     image?: string;
-    /** Image pull policy: Always (default), IfNotPresent, or Never */
-    imagePullPolicy?: 'Always' | 'IfNotPresent' | 'Never';
+    /** Image pull policy: IfNotPresent (default), Always, or Never */
+    imagePullPolicy?: ImagePullPolicy;
     /** Path to agent binary (bare-metal backend) */
     binaryPath?: string;
     /**
@@ -154,7 +170,23 @@ export type ScaleResult = {
 } | {
     action: 'failed';
     error: string;
+}
+/** Scale-up declined without attempting a spawn (e.g. coordinator draining). */
+ | {
+    action: 'skipped';
+    reason: string;
 };
+/**
+ * What triggered a pending-scale re-drive (`Dispatcher.retryPendingScaleRequests`):
+ * the near-zero-latency capacity-freed `hook` fired from `ScalerManager`, or the
+ * leader-gated periodic `sweep` backstop. Used as the `trigger` label on the
+ * `kici_orch_scaler_redispatch_total` counter.
+ */
+export declare const ScalerRedispatchTrigger: z.ZodEnum<{
+    hook: "hook";
+    sweep: "sweep";
+}>;
+export type ScalerRedispatchTrigger = z.infer<typeof ScalerRedispatchTrigger>;
 /**
  * Result of a configuration validation or reload operation.
  */
@@ -184,7 +216,8 @@ export interface ScalerBackend {
      * True for bare-metal and Firecracker (local processes / local VMs) and for
      * container backends using a local runtime socket; false when the backend
      * provisions elsewhere (remote container runtime, future cloud backends).
-     * Drives the static spawning-host display on the diagnostics page.
+     * Drives the static spawning-host display on the dashboard Infrastructure
+     * page.
      */
     readonly spawnsOnLocalHost: boolean;
     /** Current count of agents managed by this backend (including spawning) */
@@ -205,7 +238,14 @@ export interface ScalerBackend {
      * @returns The managed agent tracking object
      * @throws If the label set is not supported by this backend
      */
-    spawn(labelSet: string[], agentId: string, orchestratorUrl: string, onEvent?: ScalerEventCallback, effectiveLimits?: EffectiveLimits, spawnContext?: SpawnContext): Promise<ManagedAgent>;
+    spawn(labelSet: string[], agentId: string, orchestratorUrl: string, onEvent?: ScalerEventCallback, effectiveLimits?: EffectiveLimits, spawnContext?: SpawnContext, 
+    /**
+     * Optional abort signal from the ScalerManager spawn-timeout wrapper. When
+     * aborted, backends thread it into any long-running provisioning I/O
+     * (container-runtime requests, HTTP calls) so a hung provision cancels
+     * instead of pinning the per-backend spawn-semaphore slot.
+     */
+    signal?: AbortSignal): Promise<ManagedAgent>;
     /**
      * Destroy a specific managed agent.
      * Docker: docker rm -f; Bare-metal: SIGTERM -> SIGKILL
@@ -224,6 +264,14 @@ export interface ScalerBackend {
      * Used by the orchestrator to enrich job.context before forwarding to Platform.
      */
     getScalerContext?(agentId: string): Record<string, unknown> | undefined;
+    /**
+     * Provision or heal this backend's host prerequisites before it spawns.
+     * Called once by ScalerManager during startup. Optional — only backends with
+     * host-side setup (Firecracker's bridge) implement it; container/bare-metal
+     * omit it. May throw; the manager catches per-backend and degrades that
+     * scaler rather than aborting orchestrator startup.
+     */
+    ensureHostReady?(): Promise<void>;
     /**
      * Reload configuration (called on SIGHUP).
      * Returns validation errors if new config is invalid.
@@ -250,6 +298,12 @@ export interface FirecrackerNetworkConfig {
     netmask?: string;
     /** nft table name for this coordinator's host bridge @default 'kici' */
     table?: string;
+    /**
+     * When true (default), the orchestrator verifies and provisions this host
+     * bridge on startup (self-heal), so a fresh Firecracker host needs no manual
+     * `kici-admin firecracker provision`. @default true
+     */
+    autoProvisionHost?: boolean;
 }
 /**
  * Parsed and validated scaler configuration from YAML.
@@ -293,8 +347,15 @@ export interface ScalerEntry {
     name: string;
     /** Backend type */
     type: Exclude<ScalerBackendType, 'kubernetes'>;
-    /** Maximum concurrent agents for this scaler */
+    /** Maximum concurrent agents for this scaler (population cap) */
     maxAgents: number;
+    /**
+     * Maximum concurrent `backend.spawn` operations for this scaler
+     * (provisioning-rate throttle). Orthogonal to `maxAgents`: excess in-cap
+     * spawns queue and drain at this rate rather than storming the socket.
+     * Defaults to `DEFAULT_MAX_CONCURRENT_SPAWNS` at config-load.
+     */
+    maxConcurrentSpawns: number;
     /** Label-set to image/binary mappings */
     labelSets: LabelSetConfig[];
     /** Container runtime host (e.g. 'tcp://192.168.1.10:2376'). Works for both Docker and Podman remote. */
@@ -319,6 +380,14 @@ export interface ScalerEntry {
      * `labelSets`. Default: `[]` (no gating).
      */
     mandatoryLabels?: string[];
+    /**
+     * Structured platform of this pool's agents. When set, the auto-injected
+     * `kici:os:*` / `kici:arch:*` labels AND the mandatory platform taint both
+     * derive from this single field. Optional: when omitted, bare-metal pools
+     * derive the platform from the host OS/arch, and container / firecracker
+     * pools default to linux.
+     */
+    readonly platform?: ScalerPlatform;
     /**
      * Agent roles this scaler handles. scaler-entry level, not per-label-set.
      * - undefined (not set): handles all job types including build and init (backward compat,)

package/dist/secrets/backend-registry.d.ts

@@ -18,7 +18,26 @@ export declare class BackendRegistry {
     private readonly db;
     private readonly masterKey;
     private readonly logger?;
-    constructor(db: Kysely<any>, masterKey: Buffer, logger?: Logger | undefined);
+    private readonly oldMasterKey?;
+    constructor(db: Kysely<any>, masterKey: Buffer, logger?: Logger | undefined, oldMasterKey?: Buffer | undefined);
+    /**
+     * Decrypt a backend config with the current master key, falling back to the
+     * old key during a rotation grace window. Same dual-key pattern as
+     * PgSecretStore.decryptWithFallback / ephemeral-keys.decryptPrivateKey. The
+     * AAD stays `row.name` — ciphertext remains bound to its logical backend.
+     * Never called for sentinel rows (config_encrypted = '').
+     */
+    private decryptConfigWithFallback;
+    /** Loud, recovery-pointing error for a backend stranded by key rotation. */
+    private strandedError;
+    /**
+     * Re-seal a backend config that decrypted only under the old key back under
+     * the current master key. Runs at load time while KICI_SECRET_KEY_OLD is
+     * still configured, healing deployments that rotated before backend configs
+     * were part of the rotation sweep. The concurrent-rotation guard
+     * (`config_key_version` match) keeps a racing rotation from being clobbered.
+     */
+    private selfHealStrandedRow;
     /**
      * Register a new backend. Encrypts config and stores in DB.
      */
@@ -64,5 +83,17 @@ export declare class BackendRegistry {
      * Update sync status for a backend.
      */
     updateSyncStatus(name: string, scopeCount: number, error?: string): Promise<void>;
+    /**
+     * Re-encrypt every non-sentinel backend config under the current master key
+     * at max(config_key_version)+1. Same transactional skip-and-count shape as
+     * SharedConfigStore.rotateKey — an undecryptable row is counted and left in
+     * place (never aborts the sweep); recovery guidance lives in strandedError.
+     * Sentinel rows (config_encrypted = '') are excluded from the candidate set
+     * and never counted.
+     */
+    rotateKey(): Promise<{
+        reEncrypted: number;
+        skipped: number;
+    }>;
 }
 //# sourceMappingURL=backend-registry.d.ts.map

package/dist/secrets/dashboard-encryption-key.d.ts

@@ -0,0 +1,48 @@
+import { type JWK } from 'jose';
+import type { DashboardEncryptionKeyRepo } from '../db/repos/dashboard-encryption-keys-repo.js';
+export interface GeneratedDashboardEncryptionKey {
+    kid: string;
+    publicJwk: JWK;
+    /** AES-256-GCM-wrapped DER private key (master-key wrapped). */
+    encryptedPrivateKey: string;
+    /** DER-SPKI public key Buffer (for callers that need the raw bytes). */
+    publicKeyDer: Buffer;
+}
+/**
+ * Generate a fresh X25519 dashboard-encryption key: the OKP public JWK
+ * (`use:'enc'`, `kid` = RFC 7638 thumbprint) plus the master-key-wrapped
+ * private half.
+ */
+export declare function generateDashboardEncryptionKey(secretKey: string): Promise<GeneratedDashboardEncryptionKey>;
+export interface ReconcileDashboardEncryptionKeyDeps {
+    repo: Pick<DashboardEncryptionKeyRepo, 'getActiveRow' | 'upsertActive' | 'getByKid'>;
+    isLeader: () => boolean;
+    /** The orchestrator master key (`KICI_SECRET_KEY`), for db-custody wrapping. */
+    secretKey: string | undefined;
+    /** Called once when a NEW kid is first activated (audit log, system actor). */
+    audit: (info: {
+        kid: string;
+    }) => Promise<void> | void;
+}
+/** The resolved active dashboard-encryption key + a per-request decrypt closure. */
+export interface ResolvedDashboardEncryptionKey {
+    activeKid: string;
+    publicJwk: JWK;
+    /**
+     * Unwrap the DER private key for a given `kid` — the active key OR a
+     * rotated-out one whose row is still on record. The lookup is
+     * status-agnostic, so a revoked key that has left the published JWKS still
+     * decrypts; null means the kid is unknown (never minted, or its row was
+     * deleted). Reads the wrapped private half from the DB each call, so
+     * rotation is picked up without a restart.
+     */
+    decryptPrivateKeyDer: (kid: string) => Promise<Buffer | null>;
+}
+/**
+ * Ensure exactly one `active` dashboard-encryption key exists and return the
+ * resolved key + decrypt closure, or null when not yet ready (non-leader before
+ * the leader has generated it). Requires `KICI_SECRET_KEY` (throws otherwise —
+ * the private key is master-key wrapped, same posture as db-custody signing).
+ */
+export declare function reconcileDashboardEncryptionKey(deps: ReconcileDashboardEncryptionKeyDeps): Promise<ResolvedDashboardEncryptionKey | null>;
+//# sourceMappingURL=dashboard-encryption-key.d.ts.map

package/dist/secrets/ephemeral-keys.d.ts

@@ -46,4 +46,20 @@ export declare function decryptSecretOutput(envelope: {
     agentPublicKey: string;
     encrypted: string;
 }, runPrivateKeyDer: Buffer): string;
+/**
+ * Decrypt a browser-sealed dashboard write.
+ *
+ * Under the `encrypted` dashboard-write posture the browser seals the value to
+ * the orchestrator's published X25519 encryption key using the SAME
+ * ECDH → HKDF → AES-256-GCM envelope the agent uses for run secret outputs,
+ * but with the `kici-dashboard-sealed-write` HKDF info string.
+ *
+ * @param envelope - `{ ephemeralPublicKey: base64 DER-SPKI, encrypted: base64 IV||tag||ct }`
+ * @param encryptionPrivateKeyDer - DER-encoded orchestrator X25519 private key
+ * @returns Decrypted plaintext string
+ */
+export declare function decryptDashboardSealedWrite(envelope: {
+    ephemeralPublicKey: string;
+    encrypted: string;
+}, encryptionPrivateKeyDer: Buffer): string;
 //# sourceMappingURL=ephemeral-keys.d.ts.map

package/dist/secrets/pg-secret-store.d.ts

@@ -19,6 +19,16 @@ export declare class SecretScopeNotFoundError extends Error {
     readonly scope: string;
     constructor(scope: string);
 }
+/**
+ * Thrown by `renameScope` when the destination scope already holds secret rows
+ * or context bindings. Renaming onto it would merge two scopes rather than move
+ * one. The admin HTTP route maps it to a 409; the dashboard rename handler
+ * relays its message as the operation's error text.
+ */
+export declare class SecretScopeExistsError extends Error {
+    readonly scope: string;
+    constructor(scope: string);
+}
 /**
  * PostgreSQL secret store with AES-256-GCM encryption.
  * Uses scoped_secrets table keyed by (org_id, scope, key).

package/dist/secrets/rbac.d.ts

@@ -13,7 +13,11 @@ export type Role = 'owner' | 'admin' | 'auditor';
 /**
  * Permissions for the secrets management admin API.
  */
-export type Permission = 'context.create' | 'context.read' | 'context.update' | 'context.delete' | 'secret.read' | 'secret.write' | 'secret.delete' | 'secret.reveal' | 'audit.read' | 'token.manage' | 'key.rotate' | 'run.read' | 'run.cancel' | 'event_log.read' | 'event_log.read_payload' | 'access_log.read' | 'scheduled_job.trigger' | 'attestation.retry' | 'event_dlq.read' | 'event_dlq.manage';
+export type Permission = 'context.create' | 'context.read' | 'context.update' | 'context.delete' | 'secret.read' | 'secret.write' | 'secret.delete' | 'secret.reveal' | 'audit.read' | 'token.manage' | 'key.rotate' | 'run.read' | 'run.cancel' | 'event_log.read' | 'event_log.read_payload' | 'access_log.read' | 'scheduled_job.trigger' | 'attestation.retry' | 'event_dlq.read' | 'event_dlq.manage' | 'orchestrator.drain'
+/** Read the org-wide CI trust policy that gates fork / unknown / workflow-change PRs. */
+ | 'ci_trust.read'
+/** Modify org-wide trust policies (independent mode only — Platform-attached PATCH refuses). */
+ | 'ci_trust.admin';
 /**
  * Error thrown when a role lacks the required permission.
  */

package/dist/secrets/routing-key-scope.d.ts

@@ -17,6 +17,12 @@
  * access is denied, or `null` to let the handler continue. The middleware
  * mounted in each admin route file is responsible for calling
  * `c.set('routingKey', tokenInfo.routingKey)` so these helpers can read it.
+ *
+ * NOT a scope name. `requested` must be a routing key (`<provider>:<id>`) read
+ * from a row or an explicit request field. Secret scope names live in a
+ * different namespace — a path whose `:` is reserved as the backend qualifier —
+ * and must never be passed here. Secret routes have no per-routing-key slice;
+ * they use `requireUnscopedToken` instead.
  */
 import type { Context } from 'hono';
 /**

package/dist/secrets/scope-routing.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Backend-qualified scope routing.
+ *
+ * A secret scope travels over the wire in *qualified* form -- `<backend>:<path>`
+ * -- while every `SecretStore` implementation is addressed with the bare
+ * `<path>`. This module owns the single split between the two forms so the two
+ * write planes (the dashboard WebSocket handler and the HTTP admin API) can
+ * never drift apart on where the qualifier is stripped.
+ *
+ * The registered-backend map IS the whitelist: a head before the first `:` is a
+ * backend qualifier only when it names a registered backend. Anything else --
+ * an unregistered head, a leading `:`, no `:` at all -- stays whole and is
+ * routed to the default store, where the ordinary scope-name validation
+ * rejects it if it is malformed. That is what keeps routing keys
+ * (`<provider>:<id>`) out of the secret-scope namespace: `github:42` names no
+ * backend, so it stays whole and is rejected as a scope path.
+ */
+/**
+ * The subset of `SecretStore` a scope-taking route or WS handler needs.
+ *
+ * Deliberately narrower than the full `SecretStore` from `@kici-dev/engine`:
+ * routing only needs the scope-addressed methods, so a caller may pass a
+ * partial store (the degraded store below, a unit-test fake) without
+ * implementing value resolution.
+ */
+export interface ScopedSecretStore {
+    listScopes(orgId: string): Promise<string[]>;
+    listKeys(orgId: string, scope: string): Promise<string[]>;
+    setSecret(orgId: string, scope: string, key: string, value: string): Promise<void>;
+    deleteSecret(orgId: string, scope: string, key: string): Promise<void>;
+    createScope?(orgId: string, scope: string): Promise<void>;
+    renameScope?(orgId: string, oldScope: string, newScope: string): Promise<void>;
+    deleteScope?(orgId: string, scope: string): Promise<void>;
+}
+/**
+ * Raised when a secret write is issued against an orchestrator that has no
+ * secret store configured.
+ *
+ * The message is operator-facing: the dashboard write planes relay it verbatim
+ * as the `error` on their response, so it names the deployment condition rather
+ * than the internal cause.
+ */
+export declare class SecretsUnavailableError extends Error {
+    constructor();
+}
+/**
+ * The store an orchestrator serves the dashboard from when it has no secret
+ * store configured.
+ *
+ * The read/write asymmetry is deliberate. `listScopes` / `listKeys` return
+ * empty because "this deployment holds no secrets" is true and complete.
+ * `setSecret` / `deleteSecret` reject, because a write that resolved here would
+ * be discarded while the dashboard reported the secret as stored -- and a
+ * delete that resolved would leave a credential the operator believes is
+ * revoked. The optional scope methods stay unimplemented: the write planes
+ * already refuse a scope operation a store does not support.
+ */
+export declare function createUnavailableSecretStore(): ScopedSecretStore;
+/** Backend name assumed when a wire scope carries no recognised qualifier. */
+export declare const DEFAULT_BACKEND_NAME = "pg";
+/** Outcome of resolving a wire-form scope against the registered backends. */
+export interface ResolvedScope<S> {
+    /** The store the operation must be issued against. */
+    store: S;
+    /** The backend the scope resolved to (the default name when unqualified). */
+    backendName: string;
+    /** The bare scope path to pass to the store -- never carries a qualifier. */
+    path: string;
+    /** True when the wire scope carried a recognised `<backend>:` qualifier. */
+    qualified: boolean;
+}
+/**
+ * The one method of the secret-backend registry that store loading needs.
+ *
+ * Structural on purpose: keeping the concrete registry out of this module lets
+ * both write planes -- and their unit tests -- supply their own loader without
+ * dragging a database-backed registry into a pure routing module.
+ */
+export interface BackendStoreRegistry<S, L> {
+    loadAllStores(auditLogger: L): Promise<Map<string, S>>;
+}
+/**
+ * Load the registered secret backends for one operation.
+ *
+ * Never cache the result: a backend's credentials can rotate, and a backend can
+ * be added or removed, between operations -- a stale store would write to the
+ * wrong place. A registry failure propagates rather than degrading to the
+ * default store, because a misrouted secret write is worse than a failed one.
+ *
+ * The default-backend entry is ALWAYS `defaultStore`, overriding whatever the
+ * registry returned. The registry builds its own `PgSecretStore` for the seeded
+ * `pg` row, and that instance carries none of the orchestrator's configuration:
+ * `customerSecretsEnabled` defaults to true (so it would ignore an operator's
+ * `pgCustomerSecrets: false`), its key version is hardcoded to 1, and it has no
+ * old-master-key fallback (so it cannot decrypt rows written before a
+ * rotation). Overriding only when the registry omitted the entry is dead code
+ * -- the default row is seeded at startup -- and would let `pg:<path>` and
+ * `<path>` behave differently, which is the very defect this routing exists to
+ * fix.
+ *
+ * @param registry - Backend registry, or undefined when none is configured.
+ * @param auditLogger - Audit logger handed to the registry's store factory.
+ * @param defaultStore - Configured store for the default backend.
+ * @param defaultBackendName - Name the default store is registered under.
+ */
+export declare function loadRoutableStores<S, L>(registry: BackendStoreRegistry<S, L> | undefined, auditLogger: L, defaultStore: S, defaultBackendName?: string): Promise<Map<string, S>>;
+/**
+ * Split a wire-form scope into the store that owns it and the bare path.
+ *
+ * Pure: takes the already-loaded store map rather than loading it, so both
+ * planes can unit-test routing without a database.
+ *
+ * @param wireScope - Scope as supplied by the caller, possibly `<backend>:<path>`.
+ * @param stores - Registered backends, keyed by backend name.
+ * @param defaultStore - Store used when the scope carries no recognised qualifier.
+ * @param defaultBackendName - Backend name reported for an unqualified scope.
+ */
+export declare function resolveScope<S>(wireScope: string, stores: Map<string, S>, defaultStore: S, defaultBackendName?: string): ResolvedScope<S>;
+/**
+ * Join a backend name and a bare path back into wire form.
+ *
+ * Used for audit records and cross-backend listings, so an operator reading the
+ * audit log sees the same qualified string the caller sent.
+ */
+export declare function toWireScope(backendName: string, path: string): string;
+//# sourceMappingURL=scope-routing.d.ts.map

package/dist/secrets/secret-resolver.d.ts

@@ -7,7 +7,7 @@
  * 2. Gets bindings for that context
  * 3. Queries ALL registered backend stores for secrets
  * 4. Prefixes each secret's scope with the backend name (e.g., pg:aws/prod)
- * 5. Uses resolveSecretsForContext to match bindings against prefixed secrets
+ * 5. Uses resolveSecretsWithProvenance to match bindings against prefixed secrets
  * 6. Returns a flat decrypted key-value map
  *
  * unreachable backends cause job failure (not silent skip).
@@ -148,18 +148,5 @@ export declare class SecretResolver implements SecretResolverApi {
      * jobs referencing only healthy backends succeed normally.
      */
     private checkScopedFailure;
-    /**
-     * Find the winning secret for a given key, mirroring the engine scope
-     * resolver's host-aware matching and `(host specificity, scope depth)`
-     * precedence so the enriched metadata reports the same secret the flat
-     * resolution selected.
-     */
-    private findWinningSecret;
-    /**
-     * Resolve the effective scope pattern a binding contributes for a host,
-     * applying the host gate and per-child scope templating. Mirrors the engine
-     * scope resolver's `bindingScopeForHost`. Returns `null` to skip the binding.
-     */
-    private bindingScopeForHost;
 }
 //# sourceMappingURL=secret-resolver.d.ts.map

package/dist/secrets/token-manager.d.ts

@@ -16,15 +16,19 @@ export declare class TokenManager {
      * @param label - Human-readable label for this token.
      * @param role - Role to assign (owner, admin, auditor).
      * @param routingKey - Optional routing key scope (null = all).
+     * @param expiresAt - Optional absolute expiry. When omitted the token
+     *   never expires (null); `validate()` already enforces the column.
      * @returns The plaintext token (shown once) and the row ID.
      */
-    generateToken(label: string, role: Role, routingKey?: string | null): Promise<{
+    generateToken(label: string, role: Role, routingKey?: string | null, expiresAt?: Date | null): Promise<{
         token: string;
         id: string;
     }>;
     /**
      * Validate a plaintext token against stored hashes.
      *
+     * On success, fires a non-blocking update to last_used_at.
+     *
      * @param token - The plaintext token to validate.
      * @returns Token info if valid, null if invalid/expired/revoked.
      */

package/dist/security/contributor-cache.d.ts

@@ -5,18 +5,26 @@
  * Uses a 15-minute TTL and 10,000 max entries.
  */
 import type { ContributorResolver, ContributorInfo } from '@kici-dev/engine';
+import type { ClusterSettingsReader } from '../cluster/cluster-settings-reader.js';
 /**
  * Caches ContributorResolver results in an LRU cache.
  *
  * Cache key format: `{provider}:{repoFullName}:{username}`
- * TTL: 15 minutes (configurable for testing).
+ * TTL: cluster-configurable (`cluster_settings.contributor_cache_ttl_ms`,
+ * default 15 minutes). The TTL is resolved at each `set()` and applied
+ * per-entry, so a live override affects newly-cached entries without a restart.
  */
 export declare class ContributorCache {
     private readonly cache;
+    private readonly clusterSettings?;
+    private readonly defaultTtlMs;
     constructor(options?: {
         ttlMs?: number;
         maxEntries?: number;
+        clusterSettings?: ClusterSettingsReader;
     });
+    /** Resolve the fleet-wide contributor-cache TTL (ms), falling back to the config default. */
+    private ttlMs;
     /**
      * Build the cache key from provider, repo, and username.
      */

package/dist/security/trust-policy-gate.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Org trust-policy gate — turns the Platform-owned policy plus three per-PR
+ * signals into exactly one outcome.
+ *
+ * Pure: no I/O, no DB, no clock. The caller supplies the effective policy (see
+ * `resolveEffectivePolicy`) and the signals; enforcement lives in the dispatch
+ * gate.
+ *
+ * Scope: the caller only invokes this for sources whose provider bundle carries
+ * a `ContributorResolver` (GitHub today). Every other source is trusted by
+ * construction and never reaches here.
+ */
+import { z } from 'zod';
+import type { OrchestratorMode, TrustPolicy, TrustTier } from '@kici-dev/engine';
+import { SecurityHoldReason } from '../contexts/held-runs.js';
+import type { StoredTrustPolicy } from './trust-policy-store.js';
+/**
+ * Which arm of the gate is actually in force for an org — the vocabulary the
+ * admin API reports and `kici-admin trust-policy show` renders.
+ *
+ * `policy` means `resolveEffectivePolicy` produced a policy and all three arms
+ * apply; `legacy` means it produced `null`, so only the legacy
+ * workflow-modification rule runs and there are no policy values to report.
+ * Named here, next to the resolver that decides between them, so the route and
+ * the CLI cannot drift apart on a bare string literal.
+ */
+export declare const TrustPolicyEnforcement: z.ZodEnum<{
+    legacy: "legacy";
+    policy: "policy";
+}>;
+export type TrustPolicyEnforcement = z.infer<typeof TrustPolicyEnforcement>;
+/** The per-PR facts the policy is evaluated against. */
+export interface TrustPolicySignals {
+    /** Resolved contributor tier; undefined when trust resolution failed. */
+    tier: TrustTier | undefined;
+    /** The PR's head repo differs from its base repo. */
+    isForkPR: boolean;
+    /** The PR changes `.kici/` workflow definitions. */
+    hasWorkflowModifications: boolean;
+}
+/**
+ * The reasons the ORG TRUST POLICY itself can raise — its three arms.
+ *
+ * `context_trust` is excluded at the type level rather than merely by
+ * convention: that reason belongs to the per-context minimum-trust gate, which
+ * holds an individual job under its real name. Narrowing here is what lets
+ * `SECURITY_HOLD_JOB_IDS` drop its phantom `context_trust` sentinel — a value
+ * that existed only to satisfy a `Record<SecurityHoldReason, ...>` and was never
+ * written to a single row.
+ */
+export type TrustPolicyHoldReason = Exclude<SecurityHoldReason, 'context_trust'>;
+export type TrustPolicyOutcome = {
+    action: 'pass';
+} | {
+    action: 'hold';
+    reason: TrustPolicyHoldReason;
+    message: string;
+    /**
+     * Hours the resulting hold stays approvable, taken from the SAME policy
+     * that produced this verdict. `null` in independent mode, where there is
+     * no upstream policy and therefore no operator-set window.
+     *
+     * Carried on the outcome rather than re-read at the hold site: a second,
+     * independent read bypassed `resolveEffectivePolicy`, so it was both a
+     * TOCTOU (the policy could change between deciding and sizing) and a
+     * divergence — independent mode got the 72h default where the decision
+     * path deliberately has no policy at all.
+     */
+    approvalExpiryHours: number | null;
+} | {
+    action: 'reject';
+    reason: TrustPolicyHoldReason;
+    message: string;
+};
+/**
+ * The policy a Platform-attached orchestrator applies when it has no stored
+ * row. Every arm holds — a hold is recoverable by approval, and these are the
+ * documented org defaults, so an org that never changed its policy gets the
+ * behavior its dashboard shows.
+ *
+ * This is NOT necessarily a brief transient. The Platform sends
+ * `trust_policy.update` only when the org has a `trust_policies` row, and that
+ * row is created lazily on a dashboard read — so an org that has never opened
+ * Settings > CI trust receives no push at all and stays on these values
+ * indefinitely. The expiry is therefore the generous documented default rather
+ * than a short one: a short window would auto-fail legitimate runs.
+ */
+export declare const FAIL_CLOSED_POLICY: TrustPolicy;
+/**
+ * Pick the policy to evaluate. A stored row always wins. Without one, a
+ * Platform-attached orchestrator fails closed (a push is imminent); an
+ * independent orchestrator has no upstream authority at all, so it gets `null`
+ * and the evaluator applies only the legacy rule — which is what keeps this
+ * change from silently gating existing independent deployments on upgrade.
+ *
+ * `PLATFORM_CONNECTED_MODES` is the shared definition of "expects a Platform
+ * push", so a mode added there is fail-closed here without a second edit.
+ */
+export declare function resolveEffectivePolicy(stored: StoredTrustPolicy | null, mode: OrchestratorMode): TrustPolicy | null;
+/**
+ * Evaluate the policy.
+ *
+ * Arms are evaluated in a fixed order — workflow_modification, fork_pr,
+ * unknown_contributor — and then any `reject` beats any `hold`, with the first
+ * arm in that order supplying the reason among equals. That makes a PR tripping
+ * several arms produce one outcome with a stable reason rather than a verdict
+ * that depends on evaluation accident.
+ *
+ * An unresolved tier (`undefined`) counts as `unknown`, never as a pass: a
+ * trust resolution that could not be answered is not evidence of trust.
+ *
+ * A `null` policy applies only the legacy rule (workflow modifications by a
+ * non-trusted contributor hold), reproducing behavior from before the policy was
+ * enforced.
+ */
+export declare function evaluateTrustPolicy(policy: TrustPolicy | null, signals: TrustPolicySignals): TrustPolicyOutcome;
+//# sourceMappingURL=trust-policy-gate.d.ts.map