@kici-dev/orchestrator 0.0.0 → 0.1.1

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

@@ -0,0 +1,65 @@
+/**
+ * `execution_steps` cold-store adapter (Orchestrator side).
+ *
+ *
+ * Contract:
+ *   - tenant column: `routing_key` (denormalized in migration 006)
+ *   - partition column: `created_at`
+ *   - warm TTL: 30 days (design §5 matrix row 9)
+ *   - 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
+ *     sufficient)
+ *
+ * Order: registered FIRST in the orchestrator cold-store. Within one
+ * cycle the framework iterates adapters in registration order
+ * (steps → jobs → runs); steps go first so the FK chain
+ * (execution_jobs.run_id → execution_runs.run_id) doesn't break when
+ * jobs and runs are archived later.
+ *
+ * Audit emission: orchestrator-side adapters write to `access_log`
+ * (the orchestrator's audit surface; `audit_log` is Platform-side only).
+ * The row uses actor_type='system', actor_id='cold-store-archive:<id>'.
+ */
+import { type Kysely, type Selectable } from 'kysely';
+import { type ChunkCommitMetadata, type ColdStoreTableConfig, type EligiblePartition, type TableAdapter } from '@kici-dev/shared';
+import type { Database, ExecutionStepTable } from '../../db/types.js';
+export type ExecutionStepRow = Selectable<ExecutionStepTable>;
+export interface ExecutionStepsAdapterOptions {
+    overrides?: Partial<ColdStoreTableConfig>;
+}
+export declare class ExecutionStepsAdapter implements TableAdapter<ExecutionStepRow> {
+    private readonly kdb;
+    private readonly instanceId;
+    readonly db: "orchestrator";
+    readonly table = "execution_steps";
+    readonly tenantColumn = "routing_key";
+    readonly partitionColumn = "created_at";
+    readonly config: ColdStoreTableConfig;
+    constructor(kdb: Kysely<Database>, instanceId: string, opts?: ExecutionStepsAdapterOptions);
+    listEligiblePartitions(args: {
+        warmCutoff: Date;
+    }): AsyncIterable<EligiblePartition>;
+    countTenantWarmBytes(args: {
+        tenantId: string;
+        warmCutoff: Date;
+    }): Promise<number>;
+    withPartitionLock<T>(args: {
+        tenantId: string;
+        partitionDate: string;
+    }, fn: () => Promise<T>): Promise<T | null>;
+    selectEligible(args: {
+        tenantId: string;
+        partitionDate: string;
+        limit: number;
+    }): AsyncIterable<ExecutionStepRow>;
+    encodeRow(row: ExecutionStepRow): string;
+    decodeRow(line: string): ExecutionStepRow;
+    rowId(row: ExecutionStepRow): string | number;
+    rowTimestamp(row: ExecutionStepRow): Date | string;
+    markArchivedAndDelete(args: {
+        rowIds: ReadonlyArray<string | number>;
+        chunkMeta: ChunkCommitMetadata;
+    }): Promise<void>;
+}
+//# sourceMappingURL=execution-steps.d.ts.map

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

@@ -0,0 +1,77 @@
+/**
+ * `secret_audit_log` cold-store adapter (Orchestrator side).
+ *
+ *
+ * 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)
+ *
+ * Synthetic tenant: rows without `routing_key` (e.g. orchestrator-level
+ * key rotations done before any source is bound) collapse to a single
+ * synthetic prefix `__orchestrator__`. Mirrors the same pattern already
+ * used for `event_log` payload keys when the routing key is missing.
+ */
+import { type Kysely, type Selectable } from 'kysely';
+import { type ChunkCommitMetadata, type ColdRetention, type ColdStoreTableConfig, type EligiblePartition, type TableAdapter } from '@kici-dev/shared';
+import type { Database, SecretAuditLogTable } from '../../db/types.js';
+export type SecretAuditLogRow = Selectable<SecretAuditLogTable>;
+export interface SecretAuditLogAdapterOptions {
+    overrides?: Partial<ColdStoreTableConfig>;
+}
+export declare class SecretAuditLogAdapter implements TableAdapter<SecretAuditLogRow> {
+    private readonly kdb;
+    private readonly instanceId;
+    readonly db: "orchestrator";
+    readonly table = "secret_audit_log";
+    readonly tenantColumn = "routing_key";
+    readonly partitionColumn = "timestamp";
+    readonly config: ColdStoreTableConfig;
+    constructor(kdb: Kysely<Database>, instanceId: string, opts?: SecretAuditLogAdapterOptions);
+    listEligiblePartitions(args: {
+        warmCutoff: Date;
+    }): AsyncIterable<EligiblePartition>;
+    countTenantWarmBytes(args: {
+        tenantId: string;
+        warmCutoff: Date;
+    }): Promise<number>;
+    withPartitionLock<T>(args: {
+        tenantId: string;
+        partitionDate: string;
+    }, fn: () => Promise<T>): Promise<T | null>;
+    selectEligible(args: {
+        tenantId: string;
+        partitionDate: string;
+        limit: number;
+    }): AsyncIterable<SecretAuditLogRow>;
+    encodeRow(row: SecretAuditLogRow): string;
+    decodeRow(line: string): SecretAuditLogRow;
+    rowId(row: SecretAuditLogRow): string | number;
+    rowTimestamp(row: SecretAuditLogRow): Date | string;
+    /**
+     * Phase 2 — per-row cold-retention TTL. Sampled `resolve` /
+     * `resolve_named` rows get 180d cold; mutations get `'forever'`. The
+     * denied-outcome override promotes to 730d (forensic).
+     *
+     * `outcome` is a free-form string in PG but the engine helper only
+     * branches on `outcome !== 'allowed'`, so any other value
+     * (`'denied'`, `'error'`, future categories) lands in the forensic
+     * bucket.
+     */
+    coldTtlDays(row: SecretAuditLogRow): ColdRetention;
+    markArchivedAndDelete(args: {
+        rowIds: ReadonlyArray<string | number>;
+        chunkMeta: ChunkCommitMetadata;
+    }): Promise<void>;
+    purgeChunkRecord(args: {
+        tenantId: string;
+        chunkId: string;
+        gzipBytes: number;
+        rowCount: number;
+        bucket: string;
+        maxColdDays: number;
+        objectKey: string;
+    }): Promise<void>;
+}
+//# sourceMappingURL=secret-audit-log.d.ts.map

package/dist/concurrency/dispatch-next-queued.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Slot-release dispatch helpers for the long-poll concurrency protocol.
+ *
+ * When a concurrency-group slot frees (run completed, run cancelled, run
+ * superseded), the orchestrator picks the FIFO-oldest queued row and wakes up
+ * the agent that's parked on its second `waitForConcurrencyAck` call. The
+ * agent then continues with normal step execution against the same WS
+ * connection it received the original dispatch on.
+ *
+ * If the in-memory waiter is missing (orchestrator restart, agent already
+ * disconnected), the dequeued DB row is marked completed so the slot doesn't
+ * get permanently stuck on a phantom holder.
+ */
+import type { AgentRegistry } from '../agent/registry.js';
+import type { ConcurrencyGroupTracker } from './group-tracker.js';
+import type { ConcurrencyQueueManager } from './queue-manager.js';
+import type { ConcurrencyWaiters } from './waiters.js';
+export interface DispatchNextQueuedDeps {
+    /** In-memory tracker — kept in sync with the DB on dequeue. */
+    tracker: ConcurrencyGroupTracker;
+    /** DB-backed queue manager. */
+    queueManager: ConcurrencyQueueManager;
+    /** Agent registry for finding the waiter's WS. */
+    registry: AgentRegistry;
+    /** In-memory waiter map. */
+    waiters: ConcurrencyWaiters;
+    /**
+     * Default max for `acquireSlot` when re-syncing the in-memory tracker after
+     * a dequeue. The runtime concurrency config (per-workflow `max`) is not
+     * available at slot-release time; the dequeued waiter has already been
+     * accounted for under that policy when it was originally enqueued, so any
+     * value `>= 1` is safe here. We pass 1 because the v1 contract documents
+     * single-slot semantics (max>1 is out of scope).
+     */
+    trackerMaxFallback?: number;
+}
+/**
+ * Try to dequeue the next queued entry for `(group, routingKey)` and notify
+ * the waiting agent's WS with `concurrency.ack { action: 'proceed' }`.
+ *
+ * No-op if the queue is empty. When a dequeued waiter is missing or its
+ * agent is gone (orphaned row, agent disconnected), the helper LOOPS to the
+ * next queued row instead of stopping — otherwise a single orphan would
+ * permanently mask all live waiters behind it (orphans sort first by
+ * `created_at ASC`).
+ *
+ * Bounded by a defensive iteration cap so we never accidentally infinite-loop
+ * on a queue manager that returns the same row repeatedly.
+ */
+export declare function tryDispatchNextQueued(deps: DispatchNextQueuedDeps, group: string, routingKey: string): Promise<void>;
+export interface AgentDisconnectDeps {
+    waiters: ConcurrencyWaiters;
+    queueManager: ConcurrencyQueueManager;
+}
+/**
+ * Build the agent-disconnect cleanup callback. Drops every waiter owned by
+ * the disconnecting agent and marks their `concurrency_groups` rows as
+ * cancelled so the queue manager doesn't try to dispatch a phantom run.
+ *
+ * Returns a no-arg-async closure suitable for passing to the agent WS handler.
+ */
+export declare function buildOnConcurrencyAgentDisconnect(deps: AgentDisconnectDeps): (agentId: string) => Promise<void>;
+//# sourceMappingURL=dispatch-next-queued.d.ts.map

package/dist/concurrency/group-tracker.d.ts

@@ -0,0 +1,51 @@
+/**
+ * In-memory concurrency group tracker.
+ *
+ * Tracks active runs per concurrency group, scoped by routing key
+ * to prevent cross-repo interference. Supports slot acquisition/release
+ * and hydration from DB records on startup.
+ */
+/** Record used to hydrate tracker state from DB on startup. */
+export interface HydrateRecord {
+    groupKey: string;
+    routingKey: string;
+    runId: string;
+}
+export declare class ConcurrencyGroupTracker {
+    /**
+     * Scoped state: "routingKey::groupKey" -> ordered list of active run IDs.
+     * Using an array (not Set) to preserve insertion order for getOldestRun().
+     */
+    private readonly groups;
+    private scopeKey;
+    private getOrCreateGroup;
+    /**
+     * Try to acquire a slot in the concurrency group.
+     * Returns true if under max capacity and the run was added, false otherwise.
+     * Idempotent: re-acquiring an already-active run returns true without double-adding.
+     */
+    acquireSlot(groupKey: string, routingKey: string, runId: string, opts: {
+        max: number;
+    }): boolean;
+    /**
+     * Release a slot in the concurrency group.
+     * No-op if the run ID is not active.
+     */
+    releaseSlot(groupKey: string, routingKey: string, runId: string): void;
+    /**
+     * Get all active run IDs in a concurrency group.
+     * Returns a copy of the array.
+     */
+    getActiveRuns(groupKey: string, routingKey: string): string[];
+    /**
+     * Get the oldest active run in a concurrency group.
+     * Used by cancelInProgress mode to determine which run to cancel.
+     */
+    getOldestRun(groupKey: string, routingKey: string): string | null;
+    /**
+     * Hydrate tracker state from DB records.
+     * Called on orchestrator startup to restore active concurrency groups.
+     */
+    hydrate(records: HydrateRecord[]): void;
+}
+//# sourceMappingURL=group-tracker.d.ts.map

package/dist/concurrency/index.d.ts

@@ -0,0 +1,3 @@
+export { ConcurrencyGroupTracker, type HydrateRecord } from './group-tracker.js';
+export { ConcurrencyQueueManager, type QueuedJob, type EnqueueOptions } from './queue-manager.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/concurrency/queue-manager.d.ts

@@ -0,0 +1,68 @@
+/**
+ * DB-backed concurrency queue manager.
+ *
+ * Persists queued jobs to the concurrency_groups table and dequeues
+ * the oldest queued job when a slot opens. Works with ConcurrencyGroupTracker
+ * for slot-based coordination.
+ */
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+/** A queued job returned from dequeue operations. */
+export interface QueuedJob {
+    id: string;
+    groupKey: string;
+    routingKey: string;
+    runId: string;
+    jobId: string;
+}
+/** Options for enqueueing a job. */
+export interface EnqueueOptions {
+    groupKey: string;
+    routingKey: string;
+    runId: string;
+    jobId: string;
+}
+export declare class ConcurrencyQueueManager {
+    private readonly db;
+    constructor(db: Kysely<Database>);
+    /**
+     * Enqueue a job that is waiting for a concurrency slot.
+     * Inserts a row with status='queued' into concurrency_groups.
+     */
+    enqueue(opts: EnqueueOptions): Promise<void>;
+    /**
+     * Record an active slot in the DB for persistence across restarts.
+     */
+    recordActive(opts: EnqueueOptions): Promise<void>;
+    /**
+     * Dequeue the oldest queued job for a concurrency group.
+     * Returns null if no queued jobs exist.
+     */
+    dequeueNext(groupKey: string, routingKey: string): Promise<QueuedJob | null>;
+    /**
+     * Cancel all queued entries for a run.
+     * Marks them as 'cancelled' with a completion timestamp.
+     */
+    cancelQueued(runId: string): Promise<void>;
+    /**
+     * Mark a concurrency group entry as completed.
+     * Called when a job finishes (success/failed/cancelled).
+     */
+    markCompleted(runId: string, groupKey: string, routingKey: string): Promise<void>;
+    /**
+     * Handle job completion: mark completed and return next queued job if any.
+     * This is the main coordination point: when a slot opens, the next
+     * queued job should be dispatched.
+     */
+    onJobComplete(groupKey: string, routingKey: string, runId: string): Promise<QueuedJob | null>;
+    /**
+     * Load all active entries from DB for hydrating the in-memory tracker.
+     * Called on orchestrator startup.
+     */
+    loadActiveEntries(): Promise<Array<{
+        groupKey: string;
+        routingKey: string;
+        runId: string;
+    }>>;
+}
+//# sourceMappingURL=queue-manager.d.ts.map

package/dist/concurrency/waiters.d.ts

@@ -0,0 +1,58 @@
+/**
+ * In-memory waiter registry for the long-poll concurrency protocol.
+ *
+ * When the orchestrator acks a `concurrency.report` with `{ action: 'wait' }`,
+ * the agent stays connected on the same WS waiting for an unsolicited follow-up
+ * `concurrency.ack`. This module tracks which agent is parked on which queued
+ * run so that, when a slot frees, we can find the right WS to wake up.
+ *
+ * The store is keyed on `(groupKey, routingKey)` tuples and preserves FIFO
+ * order within each scope (the same ordering invariant the queue manager uses
+ * in `concurrency_groups.created_at`).
+ *
+ * State is in-memory only — orchestrator restarts drop all WS connections
+ * anyway, so a queued waiter that survived a restart would have no agent to
+ * notify. The slot-release helper handles the missing-waiter case by marking
+ * the just-dequeued entry completed (effectively cancelling it).
+ */
+export interface WaiterEntry {
+    /** The run id queued behind a held slot. */
+    runId: string;
+    /** The job id the agent is parked on. */
+    jobId: string;
+    /** The agent id holding the WS connection. */
+    agentId: string;
+}
+export declare class ConcurrencyWaiters {
+    /** Scoped state: `${routingKey}\0${groupKey}` -> ordered FIFO of waiters. */
+    private readonly waiters;
+    private scopeKey;
+    /**
+     * Register a waiter for the given (group, routingKey). FIFO order is
+     * preserved across multiple registrations.
+     */
+    register(groupKey: string, routingKey: string, entry: WaiterEntry): void;
+    /**
+     * Pop the FIFO-first waiter whose runId matches the given runId. Returns
+     * undefined if no waiter for that runId is registered (e.g. after an
+     * orchestrator restart, or because the WS already disconnected and called
+     * dropForAgent).
+     *
+     * Matches by runId (not "shift the head") because the queue-manager's
+     * `dequeueNext()` may pick a specific row; the in-memory tracker has to
+     * follow the DB's verdict, not the in-memory FIFO head independently.
+     */
+    popByRunId(groupKey: string, routingKey: string, runId: string): WaiterEntry | undefined;
+    /**
+     * Drop all waiters owned by the given agent. Returns the dropped entries so
+     * the caller can `cancelQueued(runId)` the matching DB rows and emit failure
+     * events.
+     *
+     * Called from the agent-handler `onClose` so a disconnect doesn't leave a
+     * queued row dangling forever.
+     */
+    dropForAgent(agentId: string): WaiterEntry[];
+    /** Number of registered waiters. Test-only. */
+    size(): number;
+}
+//# sourceMappingURL=waiters.d.ts.map

package/dist/config/encryption.d.ts

@@ -0,0 +1,82 @@
+/** Sentinel value used for redacted fields in display/export. */
+export declare const REDACTED_VALUE = "***REDACTED***";
+/**
+ * Get a value at a nested path in an object.
+ * Returns undefined if the path doesn't exist.
+ *
+ * @param obj - The object to traverse
+ * @param path - Dot-separated path (e.g., 'providers.github.appId')
+ */
+export declare function deepGet(obj: Record<string, unknown>, path: string): unknown;
+/**
+ * Set a value at a nested path in an object.
+ * Creates intermediate objects as needed.
+ *
+ * @param obj - The object to modify (mutated in place)
+ * @param path - Dot-separated path (e.g., 'providers.github.appId')
+ * @param value - The value to set
+ */
+export declare function deepSet(obj: Record<string, unknown>, path: string, value: unknown): void;
+/**
+ * Resolve a glob pattern path to concrete paths in an object.
+ * Supports '*' as a wildcard for array indices or object keys at one level.
+ *
+ * Example: 'providers.github.*.privateKey' on an object where
+ * providers.github is an array of 2 items resolves to:
+ * ['providers.github.0.privateKey', 'providers.github.1.privateKey']
+ *
+ * @param obj - The object to inspect
+ * @param pattern - Dot-separated path with optional '*' wildcards
+ * @returns Array of concrete dot-separated paths that exist in the object
+ */
+export declare function resolveGlobPaths(obj: Record<string, unknown>, pattern: string): string[];
+/**
+ * Encrypt sensitive fields in a config object.
+ *
+ * Traverses each sensitive field path pattern, resolves glob wildcards,
+ * and encrypts string values in place (in the cloned object).
+ *
+ * @param config - The config object to encrypt (not mutated)
+ * @param paths - Array of field path patterns (may contain '*' wildcards)
+ * @param key - 32-byte AES-256 encryption key
+ * @param keyVersion - Master-key generation that encrypted these values.
+ *   Stored alongside the ciphertext so rotation can identify and re-seal rows.
+ * @returns Object with the encrypted config clone and list of actual encrypted paths
+ */
+export declare function encryptConfigFields(config: Record<string, unknown>, paths: string[], key: Buffer, keyVersion: number): {
+    encrypted: Record<string, unknown>;
+    encryptedPaths: string[];
+};
+/**
+ * Decrypt sensitive fields in a config object.
+ *
+ * Uses the encrypted_paths array (stored alongside the config in the DB)
+ * to know exactly which paths need decryption.
+ *
+ * Accepts an optional `oldKey` so rows encrypted under a previous master-key
+ * generation continue to decrypt during the rotation grace window — matches
+ * `PgSecretStore.decryptWithFallback`.
+ *
+ * @param config - The config object with encrypted fields (not mutated)
+ * @param encryptedPaths - Array of concrete paths that contain encrypted values
+ * @param key - Current 32-byte AES-256 encryption key
+ * @param keyVersion - Generation stored alongside the row (carried into
+ *   `EncryptedValue.keyVersion` so the crypto layer can surface key-mismatch
+ *   telemetry; the AAD fully binds the ciphertext).
+ * @param oldKey - Optional previous generation key, tried when the current
+ *   key fails (undefined/null means no fallback).
+ * @returns Decrypted config clone
+ */
+export declare function decryptConfigFields(config: Record<string, unknown>, encryptedPaths: string[], key: Buffer, keyVersion: number, oldKey?: Buffer | null): Record<string, unknown>;
+/**
+ * Redact sensitive fields in a config object for safe display.
+ *
+ * Replaces values at encrypted paths with '***REDACTED***'.
+ * Used for CLI export and diff operations.
+ *
+ * @param config - The config object to redact (not mutated)
+ * @param encryptedPaths - Array of concrete paths to redact
+ * @returns Redacted config clone
+ */
+export declare function redactConfigFields(config: Record<string, unknown>, encryptedPaths: string[]): Record<string, unknown>;
+//# sourceMappingURL=encryption.d.ts.map

package/dist/config/env-overlay.d.ts

@@ -0,0 +1,45 @@
+/**
+ * KICI_ environment variable to config path mapping and overlay.
+ *
+ * Converts KICI_-prefixed env vars to nested config paths and applies
+ * them as overrides on top of a config object.
+ *
+ * Multi-app env var convention:
+ * - App name in YAML: `main-org` -> env segment: `MAIN_ORG` (hyphen to underscore, uppercased)
+ * - Example: KICI_PROVIDERS_GITHUB_MAIN_ORG_APP_ID -> providers.github[name=main-org].appId
+ */
+/**
+ * Convert a KICI_ env var key to a config path array.
+ * Returns null for non-KICI_ keys or unknown mappings.
+ *
+ * Handles two patterns:
+ * 1. Direct mappings (KICI_DATABASE_URL -> ['database', 'url'])
+ * 2. Multi-app GitHub provider (KICI_PROVIDERS_GITHUB_<NAME>_<FIELD> ->
+ *    ['providers', 'github', '<name-lowered>', '<camelField>'])
+ */
+export declare function envKeyToConfigPath(key: string): string[] | null;
+/**
+ * Apply KICI_ env var overrides onto a config object.
+ * Iterates all env vars, maps KICI_ ones to paths, and deep-sets values.
+ *
+ * @param config - Base config object (cloned, not mutated)
+ * @param env - Process environment
+ * @returns New config object with env overrides applied
+ */
+export declare function applyEnvOverrides(config: Record<string, unknown>, env: NodeJS.ProcessEnv): Record<string, unknown>;
+/**
+ * Deep merge two objects. Objects merge recursively, arrays replace,
+ * undefined/null values in source do NOT override target.
+ */
+export declare function deepMerge(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Set a value at a nested path in an object.
+ * Creates intermediate objects as needed.
+ */
+export declare function deepSetByPath(obj: Record<string, unknown>, path: string[], value: unknown): void;
+/**
+ * Get a value at a nested path in an object.
+ * Returns undefined if path doesn't exist.
+ */
+export declare function deepGetByPath(obj: Record<string, unknown>, path: string[]): unknown;
+//# sourceMappingURL=env-overlay.d.ts.map

package/dist/config/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Barrel export for the orchestrator config module.
+ *
+ * Re-exports all types, schemas, and loader functions.
+ */
+export type { LocalConfig, SharedConfig, AppConfig, ConfigVersion } from './types.js';
+export { localConfigSchema, sharedConfigSchema, appConfigSchema } from './schema.js';
+export type { LocalConfigSchemaType, SharedConfigSchemaType, AppConfigSchemaType, } from './schema.js';
+export { loadLocalConfig, SENSITIVE_FIELD_PATHS } from './loader.js';
+export { SharedConfigStore, type ConfigVersionMeta } from './shared-store.js';
+export { encryptConfigFields, decryptConfigFields, redactConfigFields, resolveGlobPaths, deepGet, deepSet, REDACTED_VALUE, } from './encryption.js';
+export { envKeyToConfigPath, applyEnvOverrides, deepMerge, deepSetByPath, deepGetByPath, } from './env-overlay.js';
+export { resolveLocalConfig, resolveFullConfig, getDefaults, type LocalPhaseResult, } from './resolver.js';
+export { ConfigReloader } from './reload.js';
+export type { ConfigReloaderDeps, ReloadResult, ReloadOptions, ReloadSource } from './reload.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/config/loader.d.ts

@@ -0,0 +1,26 @@
+/**
+ * YAML configuration file loader for the orchestrator.
+ *
+ * Reads the local YAML config file from a configurable path with fallback:
+ * 1. Explicit configPath argument
+ * 2. KICI_CONFIG environment variable
+ * 3. /etc/kici/orchestrator.yaml default
+ *
+ * When no YAML file is found and no explicit path was given,
+ * returns an empty config (YAML is optional -- env-only mode).
+ */
+import type { LocalConfig } from './types.js';
+/**
+ * Shared config field paths that contain sensitive values.
+ * Used by SharedConfigStore for encryption before DB storage.
+ */
+export declare const SENSITIVE_FIELD_PATHS: readonly ["platform.token", "secrets.key", "secrets.bootstrapAdminToken", "cluster.joinToken"];
+/**
+ * Load and validate the local orchestrator YAML configuration.
+ *
+ * @param configPath - Explicit path to the config file (highest precedence)
+ * @returns Validated LocalConfig
+ * @throws Error if explicit path doesn't exist, or if validation fails
+ */
+export declare function loadLocalConfig(configPath?: string): Promise<LocalConfig>;
+//# sourceMappingURL=loader.d.ts.map

package/dist/config/reload.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Hot-reload infrastructure for orchestrator configuration.
+ *
+ * ConfigReloader handles SIGHUP, HTTP endpoint, and programmatic reload triggers
+ * with debounce, mutex serialization, validation-before-swap, drain mode,
+ * and Prometheus metrics.
+ *
+ * Safety guarantees:
+ * - Concurrent reloads serialized via mutex (no partial state)
+ * - Validation before swap (old config preserved on failure)
+ * - Restart-required fields detected but not applied (database.url, server.port)
+ * - Drain mode for zero-disruption reload
+ */
+import type { Logger } from '@kici-dev/shared';
+import type { AppConfig, SharedConfig } from './types.js';
+import type { SharedConfigStore } from './shared-store.js';
+/**
+ * Source of a reload trigger.
+ */
+export type ReloadSource = 'sighup' | 'http' | 'cluster' | 'cli';
+/**
+ * Result of a reload operation.
+ */
+export interface ReloadResult {
+    success: boolean;
+    version?: number;
+    errors?: string[];
+    /** Fields that changed but need restart to apply */
+    restartRequired?: string[];
+    /** Fields that were hot-reloaded */
+    fieldsChanged?: string[];
+}
+/**
+ * Options for executeReload.
+ */
+export interface ReloadOptions {
+    /** Whether to drain in-flight work before reloading */
+    drain?: boolean;
+    /** Reload trigger source for metrics */
+    source: ReloadSource;
+}
+/**
+ * Dependencies injected into ConfigReloader.
+ */
+export interface ConfigReloaderDeps {
+    /** Load local config from YAML + env */
+    resolveLocalConfig: () => Promise<{
+        local: Record<string, unknown>;
+    }>;
+    /** Merge all layers into AppConfig */
+    resolveFullConfig: (local: Record<string, unknown>, dbConfig: SharedConfig | null) => AppConfig;
+    /** Shared config store (null if no DB config) */
+    sharedStore: SharedConfigStore | null;
+    /** Called after successful reload when provider config changed */
+    onProviderChange?: (newConfig: AppConfig, oldConfig: AppConfig) => Promise<void>;
+    /** Called to reload scaler configuration */
+    onScalerReload?: () => Promise<void>;
+    /** Called when Platform connection settings changed */
+    onPlatformReconnect?: (newConfig: AppConfig) => Promise<void>;
+    /** Atomic swap callback -- replaces the config reference */
+    onConfigApplied?: (newConfig: AppConfig) => void;
+    /** Start draining in-flight work */
+    startDrain?: () => Promise<void>;
+    /** Stop drain and resume accepting work */
+    stopDrain?: () => void;
+    logger: Logger;
+}
+/**
+ * ConfigReloader manages hot-reload of orchestrator configuration.
+ *
+ * Handles SIGHUP signals, HTTP-triggered reloads, and cluster-triggered reloads
+ * with debounce, mutex, validation-before-swap, and Prometheus metrics.
+ */
+export declare class ConfigReloader {
+    private currentConfig;
+    private reloading;
+    private debounceTimer;
+    private currentVersion;
+    private readonly deps;
+    /** Debounce interval in milliseconds */
+    static DEBOUNCE_MS: number;
+    constructor(initialConfig: AppConfig, deps: ConfigReloaderDeps);
+    /**
+     * Trigger a reload (debounced).
+     * Multiple rapid triggers will be collapsed into a single reload.
+     */
+    triggerReload(source: ReloadSource, opts?: {
+        drain?: boolean;
+    }): void;
+    /**
+     * Execute reload immediately (no debounce).
+     * Used by tests and direct API calls that need synchronous results.
+     */
+    executeReload(opts: ReloadOptions): Promise<ReloadResult>;
+    /**
+     * Get the current effective config.
+     */
+    getCurrentConfig(): AppConfig;
+    /**
+     * Get the current shared config version.
+     */
+    getCurrentVersion(): number;
+    /**
+     * Install SIGHUP handler for signal-triggered reload.
+     * SIGHUP triggers unified reload of both orchestrator config AND scaler config.
+     */
+    installSignalHandler(): void;
+    /**
+     * Clean up timers and resources.
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=reload.d.ts.map