@kici-dev/orchestrator 0.11.0 → 0.13.0

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

@@ -34,10 +34,10 @@ export interface ClusterIdentityDeps {
  * `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, the `kici-admin cluster reconcile-identity` CLI, and the staging
- * deploy's self-heal step) 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".
+ * 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".
  */
 export declare const DEFAULT_CACHE_STORAGE_S3_PREFIX = "";
 /**

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

@@ -0,0 +1,45 @@
+import type { Kysely } from 'kysely';
+import { type Logger } from '@kici-dev/shared';
+import type { Database } from '../db/types.js';
+import { PeerCredentialStore } from './peer-credentials.js';
+/** What one reconciliation did. */
+export declare enum CoordinatorCredentialOutcome {
+    Valid = "valid",
+    Issued = "issued",
+    Replaced = "replaced",
+    Revoked = "revoked",
+    Failed = "failed"
+}
+/** Why a new credential was issued, recorded on the issue log line. */
+export declare enum CredentialIssueReason {
+    NoCredential = "no-credential",
+    Expired = "expired",
+    FileMissing = "credential-file-missing",
+    FileMismatch = "credential-file-mismatch"
+}
+export declare const COORDINATOR_CREDENTIAL_REVOKED_MESSAGE = "Peer credential for this coordinator was revoked; not issuing a new one";
+export type CoordinatorCredentialStore = Pick<PeerCredentialStore, 'save' | 'findUnrevokedByInstanceId' | 'findLatestRevokedByInstanceId' | 'retireSelfIssued'>;
+export interface EnsureCoordinatorCredentialOptions {
+    store: CoordinatorCredentialStore;
+    /** Absolute path of the credential file, with `~` already expanded. */
+    credentialFile: string;
+    instanceId: string;
+    /** Whether an instance has a live `cluster_instances` heartbeat. */
+    isInstanceLive: (instanceId: string) => Promise<boolean>;
+    logger?: Logger;
+    now?: () => Date;
+}
+/**
+ * Make sure this coordinator holds a credential its peers accept, issuing one
+ * when it has none. Never throws: a failure is logged and reported as `Failed`.
+ */
+export declare function ensureCoordinatorCredential(opts: EnsureCoordinatorCredentialOptions): Promise<CoordinatorCredentialOutcome>;
+/** The `selfIssue` callback the coordinator's `PeerAuthCoordinator` runs. */
+export declare function coordinatorSelfIssuer(opts: {
+    db: Kysely<Database>;
+    credentialFile: string;
+    instanceId: string;
+    agentMaxReconnectDelayMs: number;
+    clusterInstanceHeartbeatMs: number;
+}): () => Promise<CoordinatorCredentialOutcome>;
+//# sourceMappingURL=coordinator-credential.d.ts.map

package/dist/cluster/coordinator.d.ts

@@ -334,9 +334,25 @@ export declare class RunCoordinator {
      * The run-cancel path needs this for a job this coordinator never routed:
      * the Platform picks any pool member to receive `run.cancel.request`, and only
      * the coordinator holding the agent's socket can put a cancel frame on it.
-     * {@link RunCoordinator.cancelRun} covers rerouted jobs and is unchanged.
+     * `force` rides on the message, so a force cancel stays forced on the peer.
+     * {@link RunCoordinator.cancelRun} covers rerouted jobs.
      */
-    cancelJobOnPeer(peerId: string, runId: string, jobId: string, reason: string): boolean;
+    cancelJobOnPeer(peerId: string, runId: string, jobId: string, reason: string, force?: boolean): boolean;
+    /**
+     * Send a fire-and-forget message to a peer. The outbound client carries it
+     * when connected; otherwise the peer's own connection to this process does.
+     * The outbound client is down while it reconnects, and for good on a
+     * coordinator whose credential an operator revoked.
+     * `PeerClient.send` returns false only when it sent nothing, so the fallback
+     * never delivers a message twice.
+     */
+    private sendToPeer;
+    /**
+     * The link a reroute uses, chosen before sending. A reroute is never retried
+     * over the second link: `false` from a connected client is a NAK or an ack
+     * timeout, and resending would deliver the job twice.
+     */
+    private rerouteTransport;
     /**
      * Local fallback for a re-dispatch: dispatch the job on this coordinator under
      * the existing jobId. Returns true when the local dispatcher accepts it.

package/dist/cluster/index.d.ts

@@ -9,6 +9,7 @@ export type { PeerInfo, PeerAgentInfo, PeerRegistryOptions } from './peer-regist
 export { PeerClient } from './peer-client.js';
 export type { PeerClientOptions } from './peer-client.js';
 export { PeerAuthCoordinator } from './peer-auth-coordinator.js';
+export { coordinatorSelfIssuer } from './coordinator-credential.js';
 export type { AuthDecision, RejectionAction } from './peer-auth-coordinator.js';
 export { createPeerHandler } from './peer-handler.js';
 export type { PeerHandlerDeps } from './peer-handler.js';

package/dist/cluster/instance-heartbeat.d.ts

@@ -1,4 +1,4 @@
-import type { Kysely } from 'kysely';
+import { type Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
 /** Default interval between `cluster_instances` heartbeat writes. */
 export declare const DEFAULT_INSTANCE_HEARTBEAT_MS = 10000;
@@ -23,6 +23,11 @@ export declare const DEFAULT_RECOVERY_GRACE_MS = 120000;
  * recovery machinery would have given it to reconnect.
  */
 export declare function instanceLivenessGraceMs(gracePeriodMs: number, heartbeatMs?: number): number;
+/**
+ * Whether `instanceId` has a `cluster_instances` heartbeat inside `graceMs`:
+ * the same liveness the dispatch plane's ownership predicate reads.
+ */
+export declare function isInstanceLive(db: Kysely<Database>, instanceId: string, graceMs: number): Promise<boolean>;
 export interface InstanceHeartbeatOptions {
     db: Kysely<Database>;
     instanceId: string;

package/dist/cluster/join-token.d.ts

@@ -18,6 +18,8 @@ import { Kysely } from 'kysely';
  * and a stray log line would break the contract).
  */
 export declare function silenceJoinTokenLogger(): void;
+export declare const TOKEN_ALREADY_USED_MESSAGE = "Join token has already been used. Create a new token with: kici-admin peer create-token";
+export declare const TOKEN_EXPIRED_MESSAGE = "Join token has expired. Create a new token with: kici-admin peer create-token";
 interface TokenRouting {
     orgId: string;
     routingKey: string;
@@ -79,8 +81,8 @@ export declare class JoinTokenManager {
 /**
  * Build a JoinTokenManager backed by its own connection pool to the given
  * orchestrator database URL. Mirrors `createPeerCredentialStoreFromUrl`;
- * consumed by E2E tests that need to exercise token validation/reuse against
- * the real cluster DB.
+ * used by tests that need to exercise token validation/reuse against a real
+ * cluster DB.
  */
 export declare function createJoinTokenManagerFromUrl(databaseUrl: string, opts?: {
     maxConnections?: number;

package/dist/cluster/leader-gated-scheduler.d.ts

@@ -23,7 +23,8 @@ export interface LeaderGatedSchedulerOptions {
 /**
  * Raft-leader-only periodic scheduler. Encapsulates the become -> (optional async setup) ->
  * start-interval / lose -> stop lifecycle that the orchestrator's leader-gated schedulers share.
- * The interval runs only while this node is the leader.
+ * The interval runs only while this node is the leader. `stop()` is final: no
+ * later leadership change starts another tenure.
  */
 export declare class LeaderGatedScheduler {
     private readonly opts;
@@ -39,6 +40,11 @@ export declare class LeaderGatedScheduler {
      * would leak a timer running tick() while no longer leader.
      */
     private generation;
+    /**
+     * Set by {@link stop}: the owning process is shutting down, so no later
+     * leadership change starts another tenure.
+     */
+    private stopped;
     constructor(opts: LeaderGatedSchedulerOptions);
     get isLeader(): boolean;
     onBecomeLeader(): Promise<void>;

package/dist/cluster/peer-auth-coordinator.d.ts

@@ -1,4 +1,5 @@
 import { type CredentialFileData } from './peer-credentials.js';
+import { CoordinatorCredentialOutcome } from './coordinator-credential.js';
 export type AuthDecision = {
     mode: 'credential';
     credential: CredentialFileData;
@@ -15,6 +16,11 @@ export declare class PeerAuthCoordinator {
     private readonly instanceId;
     private readonly joinToken?;
     private readonly joinWaitTimeoutMs;
+    private readonly selfIssue?;
+    /** The issuance in progress; concurrent sibling clients share it. */
+    private selfIssueInFlight;
+    /** An operator revoked this coordinator's credential: never issue again in this process. */
+    private selfIssueRevoked;
     /** Promise-chain mutex tail; every file op awaits the prior one. */
     private lock;
     /** Set while one peer-client is mid token-join; siblings await it. */
@@ -24,11 +30,18 @@ export declare class PeerAuthCoordinator {
         instanceId: string;
         joinToken?: string;
         joinWaitTimeoutMs?: number;
+        /**
+         * Issues this coordinator its own credential when a decision finds no
+         * credential and no join token. Only a coordinator wires it.
+         */
+        selfIssue?: () => Promise<CoordinatorCredentialOutcome>;
     });
     /** Run `fn` exclusively against the credential file. */
     private withLock;
     private readValidCredential;
     decideAuth(): Promise<AuthDecision>;
+    /** Run the issuer under the mutex, once for every concurrent caller. */
+    private runSelfIssue;
     private makeComplete;
     private awaitInFlightJoin;
     reportRejection(provedCredential: string | null, reason: string): Promise<RejectionAction>;

package/dist/cluster/peer-client.d.ts

@@ -13,6 +13,8 @@
 import { type PeerHeartbeat, type PeerToPeerMessage, type JobReroute, type JobProgress, type JobProgressAck, type PeerJobCancel, type PeerLogChunk, type PeerCacheUploadRequest, type PeerCacheUploadResponse, type PeerConfigReload, type PeerConfigReloadResponse, type PeerClusterSettingsRequest, type PeerClusterSettingsResponse, type PeerLogsCollectRequest, type PeerLeaving, type PeerAgentTokenRevoke, type RaftVoteRequest, type RaftVoteResponse, type RaftAppendEntries } from '@kici-dev/engine';
 import type { PeerRegistry } from './peer-registry.js';
 import type { PeerAuthCoordinator } from './peer-auth-coordinator.js';
+/** Logged when this instance has neither a credential file nor a join token. */
+export declare const NO_AUTH_METHOD_MESSAGE = "No peer auth method: this instance has no credential file and no join token";
 type PeerConnectionState = 'disconnected' | 'connecting' | 'handshaking' | 'authenticating' | 'connected';
 export interface PeerClientOptions {
     /** WebSocket URL of the remote peer orchestrator. */
@@ -108,6 +110,8 @@ export declare class PeerClient {
     private heartbeatTimer;
     private reconnectTimer;
     private reconnectAttempts;
+    /** Whether this client already warned that it has no auth method; re-armed by an accepted auth. */
+    private noAuthWarned;
     private intentionalDisconnect;
     private _targetInstanceId;
     private sessionKey;

package/dist/cluster/peer-credentials.d.ts

@@ -1,4 +1,15 @@
 import { Kysely } from 'kysely';
+/** How a credential row was issued, recorded in `peer_credentials.metadata.issuance`. */
+export declare enum PeerCredentialIssuance {
+    /** A coordinator issued the credential to itself (`coordinator-credential.ts`). */
+    Self = "self"
+}
+/**
+ * `metadata` key set when a coordinator retires the self-issued credential its
+ * previous run left behind. An operator revoke never sets it, which is how a
+ * retirement is told apart from a revoke.
+ */
+export declare const RETIRED_BY_INSTANCE_KEY = "retiredByInstance";
 /**
  * A peer credential record stored in the coordinator's database.
  */
@@ -14,6 +25,7 @@ export interface PeerCredential {
     lastValidatedBy: string | null;
     expiresAt: Date;
     revokedAt: Date | null;
+    metadata: Record<string, unknown>;
 }
 /**
  * Data persisted in this orchestrator's local credential file
@@ -55,6 +67,7 @@ export declare class PeerCredentialStore {
         routingKeys: string[];
         sourceTokenHash?: string;
         expiryDays?: number;
+        metadata?: Record<string, unknown>;
     }): Promise<{
         revokedCount: number;
     }>;
@@ -66,6 +79,24 @@ export declare class PeerCredentialStore {
      * Find a non-revoked, non-expired credential by instance ID.
      */
     findByInstanceId(instanceId: string): Promise<PeerCredential | null>;
+    /**
+     * The credential row for `instanceId` that nobody revoked, expired or not.
+     * `peer_credentials_active_uniq` allows at most one.
+     */
+    findUnrevokedByInstanceId(instanceId: string): Promise<PeerCredential | null>;
+    /** The most recently revoked credential row for `instanceId`, or null. */
+    findLatestRevokedByInstanceId(instanceId: string): Promise<PeerCredential | null>;
+    /**
+     * Revoke `instanceId`'s unrevoked, self-issued row whose hash is
+     * `credentialHash`, recording who retired it. Every condition sits in the
+     * WHERE clause, so a row that changed meanwhile is left alone.
+     * Returns whether a row was retired.
+     */
+    retireSelfIssued(opts: {
+        instanceId: string;
+        credentialHash: string;
+        retiredByInstance: string;
+    }): Promise<boolean>;
     /**
      * Update the last_seen_at timestamp for a credential.
      * Optionally records which coordinator validated it.
@@ -107,7 +138,7 @@ export declare function readCredentialFile(filePath: string): Promise<Credential
  * store plus a disposer that closes the underlying pool. Lets tests
  * exercise the real Kysely-backed store without importing pg/kysely.
  *
- * Intended for e2e coverage of the store's own CRUD methods — production
+ * Intended for tests of the store's own CRUD methods — production
  * code constructs the store with an already-allocated Kysely instance
  * shared with the orchestrator.
  */

package/dist/cluster/raft-state.d.ts

@@ -28,6 +28,12 @@ export declare class RaftStateStore {
      * Upsert full Raft state into the DB.
      */
     save(state: RaftPersistentState): Promise<void>;
+    /**
+     * Upsert full Raft state unless the stored term is newer. A coordinator that
+     * leaves the cluster saves through this: the row is shared, and the remaining
+     * coordinators may already have elected a leader in a newer term.
+     */
+    saveUnlessNewerTerm(state: RaftPersistentState): Promise<void>;
     /**
      * Update just the leader and term fields (lightweight update for heartbeat acceptance).
      */

package/dist/cluster/raft.d.ts

@@ -4,12 +4,16 @@
  * Implements only leader election (no log replication) for cluster coordination.
  * State machine: follower -> candidate -> leader. State is persisted to Postgres
  * via RaftStateStore for crash recovery. Election timeout is 5-10s with randomized
- * jitter (WAN-appropriate per research). Leader sends heartbeats every 2s.
+ * jitter (WAN-appropriate). Leader sends heartbeats every 2s.
  *
  * Dormant mode: When peerRegistry has 0 connected peers, the node self-elects
  * immediately (single-orchestrator deployment). If peers connect later, normal
  * election resumes.
  *
+ * `stop()` takes the node out of every election until the next `start()`: it
+ * ends the node's leadership and ignores every election input afterwards, so a
+ * process that is shutting down cannot be elected again.
+ *
  * Raft heartbeat (raft.append.entries every 2s) is separate from peer inventory
  * heartbeat (peer.heartbeat every 30s). Raft heartbeat is purely for leader
  * liveness detection.
@@ -47,6 +51,13 @@ export declare class RaftNode {
     private votedFor;
     private leaderId;
     private role;
+    /**
+     * Set by {@link stop}. A stopped node takes no further part in any election:
+     * it belongs to a process that is shutting down, and an election would restart
+     * the leader-only services the shutdown is stopping and write Raft state to a
+     * database that is being closed.
+     */
+    private stopped;
     private electionTimer;
     private leaderHeartbeatTimer;
     /** Votes received during the current election as candidate. */
@@ -65,7 +76,10 @@ export declare class RaftNode {
      */
     start(): Promise<void>;
     /**
-     * Stop the Raft node. Clears all timers and persists state.
+     * Stop the Raft node. Clears its timers, ends its leadership (so the
+     * leader-only services stop with it), and persists its state. Every election
+     * input after this is ignored until the next {@link start}. A second call does
+     * nothing.
      */
     stop(): Promise<void>;
     /** Whether this node is the current leader. */

package/dist/cold-store/load-access-log-range.d.ts

@@ -1,11 +1,11 @@
 /**
- * Read-through helper for `access_log` (Orchestrator) — Phase D.
+ * Read-through helper for `access_log` (Orchestrator).
  *
  * Unlike `audit_log` and `secret_audit_log`, the `access_log` callers
  * (dashboard "Data access" tab, admin HTTP route, `kici-admin
  * access-log list` CLI) all use the same cursor-based pagination
- * already implemented by `AccessLogWriter.query()`. Phase D's design
- * §7 row 11 classifies access_log as "paginated/transparent" — there
+ * already implemented by `AccessLogWriter.query()`. access_log is
+ * "paginated/transparent" — there
  * is NO `--include-archived` flag. The helper merges cold rows
  * automatically when pagination crosses the warm cutoff or the caller
  * supplies a `from` timestamp older than warm.

package/dist/cold-store/load-event-log-range.d.ts

@@ -1,5 +1,5 @@
 /**
- * Read-through helper for `event_log` (Orchestrator) — Phase E.
+ * Read-through helper for `event_log` (Orchestrator).
  *
  * Mirrors the Platform-side `load-event-log-range.ts`. Tenant column is
  * `routing_key` (NOT NULL on this side) so cold-store partitioning

package/dist/cold-store/load-secret-audit-log-range.d.ts

@@ -1,7 +1,7 @@
 /**
- * Read-through helper for `secret_audit_log` (Orchestrator) — Phase D.
+ * Read-through helper for `secret_audit_log` (Orchestrator).
  *
- * Mirrors the Phase B/C reader pattern. Wraps `AuditLogger.query()`'s
+ * Mirrors the execution-table reader pattern. Wraps `AuditLogger.query()`'s
  * existing offset/limit shape; cold-store rows are fetched only when
  * `includeArchived === true`.
  *

package/dist/cold-store/orchestrator-cold-store.d.ts

@@ -1,10 +1,9 @@
 /**
  * Orchestrator-side cold-store.
  *
- * Extends BaseColdStore with orchestrator-specific table adapters.
- * Phase A registered no adapters; Phase C added execution_runs /
- * execution_jobs / execution_steps. Phase D adds secret_audit_log
- * and access_log.
+ * Extends BaseColdStore with orchestrator-specific table adapters:
+ * execution_runs / execution_jobs / execution_steps, secret_audit_log,
+ * access_log and event_log.
  */
 import { type Kysely } from 'kysely';
 import { BaseColdStore, type BaseColdStoreDeps, type ColdStoreConfig, type PurgeableChunk } from '@kici-dev/shared';
@@ -17,7 +16,7 @@ export declare class OrchestratorColdStore extends BaseColdStore {
     private readonly kdb;
     constructor(deps: OrchestratorColdStoreDeps);
     /**
-     * Phase 2 — query the orchestrator's `cold_store_chunks` table for
+     * Query the orchestrator's `cold_store_chunks` table for
      * chunks past their per-row cold-retention horizon. See the matching
      * Platform-side method for the full rationale.
      */
@@ -27,7 +26,7 @@ export declare class OrchestratorColdStore extends BaseColdStore {
         limit: number;
     }): Promise<PurgeableChunk[]>;
     /**
-     * Phase 2 — per-chunk advisory lock keyed on
+     * Per-chunk advisory lock keyed on
      * `hashtext('cold-store-purge|orchestrator|<table>|<chunkId>')`.
      */
     protected withPurgeLock<T>(args: {
@@ -37,10 +36,9 @@ export declare class OrchestratorColdStore extends BaseColdStore {
 }
 /**
  * Build the orchestrator cold-store config from env vars. Reads
- * `KICI_COLD_STORE_*` vars mirrored with the Platform side. YAML
- * integration (per the design doc) lands in a follow-up commit that
- * wires the `coldStore` section of the orchestrator config schema;
- * Phase A ships the env-var path only.
+ * `KICI_COLD_STORE_*` vars mirrored with the Platform side. The
+ * orchestrator config schema has no `coldStore` section, so env vars are
+ * the only input.
  */
 export declare function readOrchestratorColdStoreConfig(env?: NodeJS.ProcessEnv): ColdStoreConfig;
 /**
@@ -50,7 +48,7 @@ export declare function readOrchestratorColdStoreConfig(env?: NodeJS.ProcessEnv)
  */
 export declare function createColdStoreArchiveHandler(instanceId: string, kdb: Kysely<Database>): () => Promise<void>;
 /**
- * Phase 2 — build the cold-store-purge scheduled-job handler. Same
+ * Build the cold-store-purge scheduled-job handler. Same
  * env-var re-read pattern as the archive handler so SIGHUP picks up
  * config changes mid-run.
  */

package/dist/cold-store/tables/access-log.d.ts

@@ -5,7 +5,7 @@
  * Contract:
  *   - tenant column: `org_id` (NULL → synthetic `__orchestrator__`)
  *   - partition column: `created_at`
- *   - warm TTL: 30 days (design §5 matrix row 11)
+ *   - warm TTL: 30 days
  *
  * Replaces the previous 90-day `expires_at`-based hard delete (removed
  * by migration 007). Rows older than 30 days now live in S3
@@ -57,7 +57,7 @@ export declare class AccessLogAdapter implements TableAdapter<AccessLogColdStore
     rowId(row: AccessLogColdStoreRow): string | number;
     rowTimestamp(row: AccessLogColdStoreRow): Date | string;
     /**
-     * Phase 2 — per-row cold-retention TTL. Mirrors the warm-side override
+     * Per-row cold-retention TTL. Mirrors the warm-side override
      * layering: outcome=denied/error → 730d (forensic), platform_operator →
      * `'forever'` (compliance), otherwise per-action map. The framework
      * groups rows by `coldDaysToBucket(coldTtlDays(row))` at archive time.

package/dist/cold-store/tables/event-log.d.ts

@@ -1,25 +1,19 @@
 /**
- * `event_log` cold-store adapter (Orchestrator side) —.
- *
- *  §2 row 6
- * and §10.
+ * `event_log` cold-store adapter (Orchestrator side).
  *
  * Contract:
  *   - tenant column: `routing_key` (NOT NULL on this side — no
  *     synthetic-tenant fallback like access_log / secret_audit_log)
  *   - partition column: `received_at`
- *   - warm TTL: 30 days (replaces the previous 30-day hard delete in
- *     `packages/orchestrator/src/webhook/event-log.ts:cleanup` +
- *     `packages/orchestrator/src/queue/cleanup.ts:runCleanup` step 4)
+ *   - warm TTL: 30 days (rows are archived, not hard-deleted)
  *
  * Per-row payload retention: rows on this table carry a `payload_key`
  * pointing at a gzipped webhook body in object storage (LogStorage).
  * Cold-store packages the row metadata — including `payload_key` —
  * but does NOT touch the body the key points to. The body remains in
  * S3 indefinitely so the dashboard delivery-detail page resolves
- * payload reads identically for hot and cold rows. The pre-Phase-E
- * cleanup that deleted both the row and the payload blob in
- * lock-step is retired.
+ * payload reads identically for hot and cold rows. Nothing deletes the
+ * row and the payload blob in lock-step.
  *
  * Recursive write: archiving event_log rows writes one access_log
  * audit row per chunk (the orchestrator's audit surface). The new

package/dist/cold-store/tables/execution-jobs.d.ts

@@ -5,7 +5,7 @@
  * Contract:
  *   - tenant column: `routing_key` (denormalized in migration 006)
  *   - partition column: `created_at`
- *   - warm TTL: 30 days (design §5 matrix row 8)
+ *   - warm TTL: 30 days
  *   - eligibility: terminal job status AND no live steps remain for this
  *     (run, job)
  *

package/dist/cold-store/tables/execution-runs.d.ts

@@ -5,7 +5,7 @@
  * Contract:
  *   - tenant column: `routing_key`
  *   - partition column: `created_at`
- *   - warm TTL: 30 days (design §5 matrix row 7)
+ *   - warm TTL: 30 days
  *   - eligibility: terminal run status AND no live jobs reference this run
  *
  * Order: registered LAST in the orchestrator cold-store. Within one
@@ -51,17 +51,17 @@ export declare class ExecutionRunsAdapter implements TableAdapter<ExecutionRunRo
     rowId(row: ExecutionRunRow): string | number;
     rowTimestamp(row: ExecutionRunRow): Date | string;
     /**
-     * Phase F — natural-key extractor used by `replayRow` so callers
+     * Natural-key extractor used by `replayRow` so callers
      * (the rerun pipeline) can locate the chunk holding a given UUID
      * `run_id` without knowing the internal SERIAL `id` returned by
      * `rowId()`.
      */
     replayLookupKey(row: ExecutionRunRow): string;
     /**
-     * Phase F — replay a chunk's `execution_runs` rows back into
+     * Replay a chunk's `execution_runs` rows back into
      * Orchestrator PG. Mirrors the Platform-side replayInsert; the
      * audit row goes to `access_log` (not `audit_log`) because the
-     * orchestrator's audit surface is access_log per design §8.
+     * orchestrator's audit surface is access_log.
      *
      * Idempotent on duplicate replays via `ON CONFLICT (run_id) DO
      * NOTHING`. Decrements `cold_store_chunk_counts` (floored at 0).

package/dist/cold-store/tables/execution-steps.d.ts

@@ -5,7 +5,7 @@
  * Contract:
  *   - tenant column: `routing_key` (denormalized in migration 006)
  *   - partition column: `created_at`
- *   - warm TTL: 30 days (design §5 matrix row 9)
+ *   - warm TTL: 30 days
  *   - eligibility: created_at < cutoff (steps are append-only and have no
  *     terminal-status predicate — there is no UPDATE statement against
  *     `execution_steps` in the orchestrator codebase, so age alone is

package/dist/cold-store/tables/secret-audit-log.d.ts

@@ -5,8 +5,8 @@
  * Contract:
  *   - tenant column: `routing_key` (NULL → synthetic `__orchestrator__`)
  *   - partition column: `timestamp`
- *   - warm TTL: 90 days (longer window than other audit tables — design
- *     §5 matrix row 10. Volume is low, forensic value is high)
+ *   - warm TTL: 90 days (longer window than other audit tables — volume is
+ *     low, forensic value is high)
  *
  * Synthetic tenant: rows without `routing_key` (e.g. orchestrator-level
  * key rotations done before any source is bound) collapse to a single
@@ -51,7 +51,7 @@ export declare class SecretAuditLogAdapter implements TableAdapter<SecretAuditLo
     rowId(row: SecretAuditLogRow): string | number;
     rowTimestamp(row: SecretAuditLogRow): Date | string;
     /**
-     * Phase 2 — per-row cold-retention TTL. Sampled `resolve` /
+     * Per-row cold-retention TTL. Sampled `resolve` /
      * `resolve_named` rows get 180d cold; mutations get `'forever'`. The
      * denied-outcome override promotes to 730d (forensic).
      *

package/dist/config.d.ts

@@ -15,6 +15,8 @@
  * and PgSecretStore, not through config. See SourceStore and SourceManager.
  */
 import { z } from 'zod';
+/** How long the database pool waits for a connection when `KICI_DB_POOL_ACQUIRE_TIMEOUT_MS` is unset. */
+export declare const DB_POOL_ACQUIRE_TIMEOUT_DEFAULT_MS = 5000;
 /**
  * Default for `sealed_secrets_retry_backoff_ms`: how long a coordinator stops
  * offering a queued job it put back because it could not open its seal. The
@@ -145,6 +147,7 @@ declare const configSchema: z.ZodObject<{
     reconnectReplayWindowHours: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     cacheBuildTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     cacheMaxTarballBytes: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    cacheUploadSettleTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     userCacheQuotaBytes: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     userCacheTtlMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     artifactQuotaBytes: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
@@ -355,6 +358,7 @@ export declare const packagingConfigSchema: z.ZodObject<{
     reconnectReplayWindowHours: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     cacheBuildTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     cacheMaxTarballBytes: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    cacheUploadSettleTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     userCacheQuotaBytes: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     userCacheTtlMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     artifactQuotaBytes: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
@@ -484,7 +488,7 @@ export type AppConfig = z.infer<typeof configSchema> & {
 };
 /**
  * Env-var definition for the orchestrator. Exported so the docs generator and
- * the deploy-stg pre-validator can re-parse without going through process.env.
+ * config pre-validation can re-parse without going through process.env.
  *
  * Note: passes the inner `baseSchema` (a ZodObject) so describe() can walk
  * `.shape`, but uses the outer `configSchema` (with .superRefine) as the parser
@@ -589,6 +593,7 @@ export declare const envDef: import("@kici-dev/shared/env").DefineEnvResult<{
     reconnectReplayWindowHours: number;
     cacheBuildTimeoutMs: number;
     cacheMaxTarballBytes: number;
+    cacheUploadSettleTimeoutMs: number;
     userCacheQuotaBytes: number;
     userCacheTtlMs: number;
     artifactQuotaBytes: number;

package/dist/contexts/held-runs.d.ts

@@ -321,8 +321,8 @@ export declare class HeldRunStore {
 /**
  * Build a HeldRunStore backed by its own connection pool to the given
  * orchestrator database URL. Mirrors `createPeerCredentialStoreFromUrl` /
- * `createJoinTokenManagerFromUrl`; consumed by E2E tests that exercise the
- * PR-scoped hold selection against the real deployed orchestrator DB.
+ * `createJoinTokenManagerFromUrl`; used by tests that exercise the PR-scoped
+ * hold selection against a real orchestrator DB.
  */
 export declare function createHeldRunStoreFromUrl(databaseUrl: string, opts?: {
     maxConnections?: number;

package/dist/dashboard/attestation-filters.d.ts

@@ -5,7 +5,7 @@ import type { Database } from '../db/types.js';
  * The org-wide attestations base query: joins `attestations` to `execution_jobs`
  * (for the job name) and `execution_runs` (for repository / workflow context).
  *
- * `attestations.run_id` / `job_id` are TEXT (P1.5 schema) while the
+ * `attestations.run_id` / `job_id` are TEXT while the
  * `execution_*` keys are `uuid`; Postgres won't compare `uuid = text` implicitly,
  * so the join casts the uuid side to text — mirroring `resolveAttestationsForRun`.
  * The `execution_runs` join is a LEFT join so a row with no matching run still