@kici-dev/orchestrator 0.17.0 → 0.19.0

package/dist/routes/uploads.d.ts

@@ -1,17 +1,13 @@
 /**
- * Test-run upload provisioning.
- *
- * Mints an upload record and a presigned PUT URL + ephemeral X25519 public key
- * for the overlay tarball. The developer encrypts the tarball with the returned
- * public key and PUTs it directly to the object store; a test trigger then
- * references the upload id. It is invoked by the `test.relay.uploads.init`
- * relay handler (a run routed through the Platform) and by the direct
- * test-run routes (`POST /api/v1/test/uploads/init`).
+ * Test-run upload provisioning. The developer encrypts the overlay tarball with
+ * the returned public key and PUTs it directly to the object store; a test
+ * trigger then references the upload id. Called by the
+ * `test.relay.uploads.init` relay handler (Platform-routed runs) and by the
+ * direct `POST /api/v1/test/uploads/init` route.
  */
 import type { Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
 import type { CacheStorage } from '../storage/types.js';
-/** Parameters for {@link initTestUpload}. */
 export interface InitTestUploadParams {
     routingKey: string;
     sha?: string;
@@ -27,14 +23,12 @@ export interface InitTestUploadParams {
 export declare class TestUploadStorageUnavailableError extends Error {
     constructor(message: string);
 }
-/** Result of {@link initTestUpload}. */
 export interface InitTestUploadResult {
     uploadId: string;
     signedUrl: string;
     publicKey: string;
     expiresIn: number;
 }
-/** Dependencies for {@link initTestUpload}. */
 export interface InitTestUploadDeps {
     db: Kysely<Database>;
     cacheStorage?: CacheStorage;

package/dist/routes/webhooks.d.ts

@@ -2,33 +2,11 @@ import { Hono } from 'hono';
 import type { WebhookInfo } from '../webhook/handler.js';
 import type { GenericSourceManager } from '../webhook/generic-sources.js';
 import { WebhookIngestOutcome } from '../pipeline/process-webhook.js';
-/**
- * Dependencies for generic webhook routes.
- */
 export interface GenericWebhookRoutesDeps {
-    /** Generic source manager for source lookup and validation */
     sourceManager: GenericSourceManager;
-    /** Processing callback -- connects to the trigger matching pipeline */
+    /** Hands the delivery to the trigger-matching pipeline. */
     onWebhook: (info: WebhookInfo) => Promise<WebhookIngestOutcome>;
 }
-/**
- * Create generic webhook routes for non-GitHub webhook ingestion.
- *
- * Endpoint: POST /webhook/:orgId/generic/:sourceId
- *
- * Handler flow:
- * 1. Read raw body
- * 2. Look up source from GenericSourceManager
- * 3. Check payload size
- * 4. Rate limit check
- * 5. Verify signature using per-source verification config
- * 6. Extract idempotency key, check dedup
- * 7. Extract event type, check allowed events
- * 8. Normalize and process through pipeline
- * 9. Return response
- *
- * @param deps - Dependencies (source manager, dedup cache, processing callback)
- * @returns Hono app with generic webhook routes
- */
+/** Non-GitHub webhook ingestion: POST /webhook/:orgId/generic/:sourceId. */
 export declare function createGenericWebhookRoutes(deps: GenericWebhookRoutesDeps): Hono;
 //# sourceMappingURL=webhooks.d.ts.map

package/dist/scaler/agent-binary-location.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Where the `kici-agent` binary installed with an orchestrator lives.
+ *
+ * The `kici-admin` npm package ships both the orchestrator and the `kici-agent`
+ * bin, so `npm install -g kici-admin` puts the agent in the runtime's global bin
+ * folder, and a bare-metal scaler whose `binaryPath` names that file upgrades
+ * its agent together with the orchestrator. These helpers find the
+ * file from a path inside the installed package: the service's entry script,
+ * or the running process's own.
+ */
+import type { ScalerEntry } from './types.js';
+/**
+ * The `kici-agent` bin that npm linked for the `kici-admin` package that
+ * contains `entry`, or null when `entry` is not inside a `kici-admin` install.
+ *
+ * - POSIX global install (`<prefix>/lib/node_modules/kici-admin/…`):
+ *   `<prefix>/bin/kici-agent`.
+ * - Windows global install (`<prefix>\node_modules\kici-admin\…`):
+ *   `<prefix>\kici-agent.cmd`.
+ * - POSIX local install (`<dir>/node_modules/kici-admin/…`):
+ *   `<dir>/node_modules/.bin/kici-agent`.
+ */
+export declare function agentBinaryFromEntry(entry: string, windows: boolean): string | null;
+/**
+ * The agent installed with the runtime a service launch command uses: the
+ * first launch token inside a `kici-admin` install decides it.
+ */
+export declare function agentBinaryFromLaunch(launch: {
+    execPath: string;
+    args: string[];
+}, windows: boolean): string | null;
+/** Whether `file` exists and this process may execute it. */
+export declare function isExecutableFile(file: string): boolean;
+/** A version manager's own executable or shim that a `binaryPath` resolves to. */
+export interface VersionManagerExecutable {
+    /** The version manager, e.g. `mise`, or null when the shim names none. */
+    manager: string | null;
+    /** The file the `binaryPath` resolves to. */
+    realpath: string;
+    /** The command that prints the `kici-agent` the shim runs, or null. */
+    whichCommand: string | null;
+}
+/**
+ * The version manager `binaryPath` runs instead of a `kici-agent`, or null.
+ *
+ * A shim is not an agent: a mise shim links to the `mise` executable, a Volta
+ * shim to `volta-shim`, and an asdf or nodenv shim is a script in a `shims`
+ * folder. Each one passes an executable-file check. An alias into a Node.js
+ * install (mise `node/24`) resolves to the real agent and is not reported here.
+ */
+export declare function versionManagerExecutable(binaryPath: string): VersionManagerExecutable | null;
+/** The sentence that tells the operator which path to set instead of a shim. */
+export declare function versionManagerRemedy(vm: VersionManagerExecutable): string;
+/** Why a bare-metal `binaryPath` is a version-manager shim, in operator words. */
+export declare function versionManagerShimMessage(binaryPath: string, vm: VersionManagerExecutable): string;
+/**
+ * One error line per bare-metal `binaryPath` that resolves to a version
+ * manager's executable or shim. The startup tools check adds these to its own
+ * errors: such a file passes the executable check, and no agent would start.
+ */
+export declare function bareMetalVersionManagerErrors(entries: ScalerEntry[]): string[];
+/**
+ * The hint the startup tools check appends when a bare-metal `binaryPath` is
+ * missing, not executable, or a version-manager shim: the agent installed with
+ * this orchestrator's own runtime, when one is on disk. Null when every
+ * `binaryPath` is usable or no such agent exists.
+ *
+ * Candidates, in order: the agent npm linked for the `kici-admin` package the
+ * process runs from (`entryPath`, the service's entry script), then
+ * `kici-agent` beside the running Node.js binary (`execPath`).
+ */
+export declare function bareMetalAgentBinaryHint(entries: ScalerEntry[], opts: {
+    entryPath: string | undefined;
+    execPath: string;
+    windows: boolean;
+}): string | null;
+//# sourceMappingURL=agent-binary-location.d.ts.map

package/dist/scaler/agent-fit.d.ts

@@ -135,8 +135,8 @@ export declare function fitAgentFor(agent: {
     scalerManaged: boolean;
 }, scalerAgentView?: (agentId: string) => ScalerAgentView | undefined): FitAgent;
 /**
- * Whether this agent may run this job. Every dispatch path that hands a
- * queued job to an agent asks this one predicate; labels have already matched.
+ * Whether this agent may run this job, once its labels have matched. Every
+ * dispatch path that hands a queued job to an agent asks this one predicate.
  *
  * In order:
  *

package/dist/scaler/backend-factory.d.ts

@@ -2,10 +2,9 @@
  * The single construction path for scaler backends.
  *
  * Both startup hosts (`orchestrator-core`, `worker-core`) and
- * `ScalerManager.reload` call this, so a backend built by a reload is built
- * exactly the way startup builds one. Host differences (DB-backed vs in-memory
- * IP allocation, event support) arrive as context fields rather than forked
- * code.
+ * `ScalerManager.reload` call this, so a reload builds a backend exactly as
+ * startup does. Host differences (DB-backed vs in-memory IP allocation, event
+ * support) arrive as context fields, not forked code.
  */
 import type { createLogger, ToolRequirement } from '@kici-dev/shared';
 import type { AgentTokenStore } from '../agent/token-store.js';
@@ -22,10 +21,7 @@ export interface IpAllocatorParams {
 export interface BackendFactoryContext {
     /** The whole config — supplies `defaults.resources` and the firecracker network block. */
     scalerConfig: ScalerConfig;
-    /**
-     * Always supplied when available; the event backend's claim store needs it
-     * regardless of the auth mode.
-     */
+    /** Always supplied when available: the event claim store needs it in any auth mode. */
     tokenStore?: AgentTokenStore;
     /** True when `config.agentAuth === 'token'`; gates token injection for the three local backends. */
     injectAgentToken: boolean;
@@ -46,21 +42,17 @@ export interface BackendFactoryContext {
     /** DB-backed on a coordinator, in-memory on a worker. */
     ipAllocator: (params: IpAllocatorParams) => IpAllocator;
     /**
-     * The already-constructed scaler state store. The event backend's claim
-     * store writes its pending-claim rows through it. Absent on the worker,
-     * which has no database — and so no event backend either.
+     * The event backend's claim store writes pending-claim rows through it.
+     * Absent on the worker, which has no database and so no event backend.
      */
     stateStore?: ScalerStateStore;
     /** Absent ⇒ the `event` type is unsupported on this host (worker mode). */
     eventEmitterProvider?: () => ScalerEventEmitterLike;
     /**
-     * Whether an agent id is currently registered on this host.
-     *
-     * The container backend's orphan sweep uses it to tell a running agent that
-     * is doing work from one whose agent never registered. Absent ⇒ the sweep
-     * assumes every running container is registered, which is the fail-safe
-     * direction: it leaves an orphan for the next pass rather than killing a
-     * live agent.
+     * The container orphan sweep uses it to tell a working agent from one that
+     * never registered. Absent ⇒ every running container counts as registered,
+     * the fail-safe direction: an orphan waits for the next pass rather than a
+     * live agent being killed.
      */
     isAgentRegistered?: (agentId: string) => boolean;
     logger: ReturnType<typeof createLogger>;

package/dist/scaler/bare-metal-backend.d.ts

@@ -1,10 +1,9 @@
 /**
- * Bare-metal scaler backend implementation.
- *
- * Manages ephemeral agent processes using child_process.spawn.
+ * Bare-metal scaler backend: ephemeral agent processes via child_process.spawn.
  * On Linux and macOS each agent leads its own process group, which teardown
  * signals; on Windows teardown ends the agent's process tree with taskkill.
- * All agents are single-use: destroyed after job completion.
+ * An agent exits once it is idle past its idle window (a follow-up job that
+ * arrives within the window reuses it), and the backend destroys it on disconnect.
  */
 import { type ToolRequirement } from '@kici-dev/shared';
 import type { AgentTokenStore } from '../agent/token-store.js';
@@ -24,7 +23,7 @@ export interface BareMetalScalerBackendOptions {
      * container mode, which is the only mode with a network boundary.
      */
     hostServices?: string[];
-    /** Token store for creating ephemeral agent auth tokens. Optional -- when undefined, no token is injected. */
+    /** Token store for ephemeral agent auth tokens; when undefined, no token is injected. */
     tokenStore?: AgentTokenStore;
     /** TTL for ephemeral agent tokens in ms. Default: 1 hour. */
     tokenTtlMs?: number;
@@ -41,9 +40,8 @@ export interface BareMetalScalerBackendOptions {
      * (`systemd-run --user --scope --slice=kici-scaler`) and translate the
      * job's effective CPU / memory limits into `CPUQuota=` / `MemoryMax=`
      * properties so the kernel cgroup actually enforces the limits. When
-     * false (the default), bare-metal stays its historical "advisory limits
-     * only" mode — limits drive the scaler's per-machine cap math but no
-     * cgroup is created.
+     * false (the default), limits are advisory only — they drive the scaler's
+     * per-machine cap math but no cgroup is created.
      *
      * Linux-only. On macOS / Windows hosts the option is silently a no-op
      * (`systemd-run` does not exist), with a one-time startup warning.
@@ -126,15 +124,13 @@ export declare class BareMetalScalerBackend implements ScalerBackend {
      * Declare required tools for a bare-metal scaler entry.
      *
      * - Every label set's `binaryPath` must be an executable file on disk.
-     * - If `KICI_SANDBOX=true` will be forwarded to spawned agents (either via
-     *   the orchestrator's `KICI_AGENT_ENV_KICI_SANDBOX=true` env var or via a
-     *   label set's `env.KICI_SANDBOX=true` in scalers.yaml), then `bwrap` must
-     *   be available on PATH so the agent can actually wrap workflow runners.
+     * - If `KICI_SANDBOX=true` is forwarded to spawned agents (via the
+     *   orchestrator's `KICI_AGENT_ENV_KICI_SANDBOX=true` or a label set's
+     *   `env.KICI_SANDBOX=true`), `bwrap` must be on PATH.
      *
-     *   This check runs at orchestrator startup so misconfiguration fails
-     *   fast with a clear error instead of crashing every job at dispatch
-     *   time. On macOS and Windows (where bwrap does not exist) any attempt
-     *   to enable KICI_SANDBOX will be rejected here.
+     *   Checked at orchestrator startup so misconfiguration fails fast instead of
+     *   crashing every job at dispatch. On macOS and Windows (no bwrap) enabling
+     *   KICI_SANDBOX is rejected here.
      */
     static getRequiredTools(entry: ScalerEntry): ToolRequirement[];
     get labelSets(): LabelSetConfig[];
@@ -148,13 +144,9 @@ export declare class BareMetalScalerBackend implements ScalerBackend {
     /**
      * Launch the agent inside the job's own container image.
      *
-     * The bare-metal backend historically only ran a local process, which meant a
-     * job naming its own image could not use this pool at all. With the KiCI
-     * runtime injected, the image needs neither Node nor git, so an arbitrary
-     * customer image can host the agent.
-     *
-     * Split out of `spawn()` because that function is already near the 200-line
-     * ceiling and the two launches share nothing past the env.
+     * With the KiCI runtime injected the image needs neither Node nor git, so an
+     * arbitrary customer image can host the agent. Split out of `spawn()`: the two
+     * launches share nothing past the env.
      */
     private spawnContainerAgent;
     getScalerContext(agentId: string): Record<string, unknown> | undefined;
@@ -162,29 +154,24 @@ export declare class BareMetalScalerBackend implements ScalerBackend {
     /**
      * Force-reclaim a container-mode agent this backend no longer tracks.
      *
-     * `destroy()` opens with an in-memory map lookup, so an orchestrator restart
-     * makes it a silent no-op while the container keeps running. The container
-     * backend's own startup sweep does not cover this one either: it reaps only
-     * containers stamped with its OWN `kici-scaler-name`, and it runs only when a
-     * container scaler is configured, which a bare-metal-only deployment has not.
+     * After an orchestrator restart `destroy()` (an in-memory lookup) is a silent
+     * no-op while the container keeps running, and the container backend's sweep
+     * reaps only its OWN `kici-scaler-name` and runs only with a container scaler
+     * configured.
      *
-     * The host-local evidence is the container itself: `spawnContainerAgent` stamps
-     * `kici-agent-id` and `kici-scaler-name` onto it, and a container listing only
-     * ever names containers on this host. So a coordinator cannot reach a peer's
-     * compute through this path — a wrongly-routed agent id matches nothing.
+     * The evidence is the container itself, stamped with `kici-agent-id` and
+     * `kici-scaler-name`; a container listing names only this host's containers,
+     * so a coordinator cannot reach a peer's compute — a wrongly-routed id matches
+     * nothing.
      *
-     * A process-mode agent is NOT reclaimed here. Its PID lives in the in-memory
-     * entry alone, so a restart leaves no durable, host-local artifact to key off,
-     * and reclaiming it would need a persistence mechanism this backend does not
-     * have. Scanning the process table instead would risk signalling a recycled
-     * PID.
+     * A process-mode agent is NOT reclaimed: its PID lives only in memory, so a
+     * restart leaves no durable host-local artifact, and scanning the process
+     * table would risk signalling a recycled PID.
      *
      * @returns `true` when a container for `managedId` was found and removed.
      */
     reapUnowned(managedId: string): Promise<boolean>;
-    /**
-     * Get the LogCapture for a managed agent (used by ScalerManager for log forwarding).
-     */
+    /** Used by ScalerManager for log forwarding. */
     getLogCapture(managedId: string): LogCapture | undefined;
     shutdownAll(): Promise<void>;
     reload(labelSets: LabelSetConfig[], opts?: {
@@ -196,8 +183,8 @@ export declare class BareMetalScalerBackend implements ScalerBackend {
      *
      * Windows has no process groups to signal and no SIGTERM, and Node.js cannot
      * send a ctrl-C there (`process.kill` terminates the target unconditionally),
-     * so the tree is ended at once with `taskkill /T /F`. The pid is cmd.exe's, which runs the agent's `node` and
-     * everything it started.
+     * so the tree is ended at once with `taskkill /T /F`. The pid is cmd.exe's,
+     * which runs the agent's `node` and everything it started.
      *
      * Nothing runs once Node.js has seen the child exit: libuv then releases its
      * handle on the process, Windows may give the pid to an unrelated process,
@@ -205,10 +192,7 @@ export declare class BareMetalScalerBackend implements ScalerBackend {
      * handle keeps the pid ours.
      */
     private endWindowsTree;
-    /**
-     * Wait for a process to exit within a timeout.
-     * Returns true if the process exited, false if timed out.
-     */
+    /** True if the process exited within `timeoutMs`, false on timeout. */
     private waitForExit;
 }
 //# sourceMappingURL=bare-metal-backend.d.ts.map

package/dist/scaler/claim-store.d.ts

@@ -1,32 +1,24 @@
 /**
  * Pending-claim store for the event scaler backend.
  *
- * When the event backend spawns, it registers a pending claim and emits a
- * scale-up event carrying a single-use `claimCode` (never the token itself).
- * The provisioning workflow forwards that code to the instance it boots, and the
- * agent exchanges it — over the `scaler.claim-credentials` RPC — for a freshly
- * minted ephemeral agent token it then registers with. The claim code is the
- * authorization for that RPC, so the agent can redeem it before it authenticates
- * or registers; a workflow can also redeem the code itself and deliver the token.
- * The token is therefore minted lazily (only when a real provision claims it) and
- * is single-use: a leaked or replayed claim code mints nothing.
+ * A spawn registers a pending claim and emits a scale-up event carrying a
+ * single-use `claimCode`, never the token. The booted instance (or the workflow
+ * itself) redeems the code over the `scaler.claim-credentials` RPC for a freshly
+ * minted ephemeral agent token. The code is that RPC's authorization, so it is
+ * redeemable before the agent authenticates or registers. The token is minted
+ * lazily and single-use: a leaked or replayed code mints nothing.
  *
- * The claim is persisted in `scaler_pending_claims` rather than held in a
- * per-process map, so a code minted by one coordinator can be redeemed by any
- * other coordinator behind the same shared endpoint. Only the sha256 of the
- * code is stored, so a DB read can never hand back a redeemable secret.
+ * Claims live in `scaler_pending_claims`, not a per-process map, so any
+ * coordinator behind the same shared endpoint can redeem a code. Only the code's
+ * sha256 is stored, so a DB read never hands back a redeemable secret.
  */
 import type { ScalerStateStore } from './scaler-state-store.js';
 /**
- * TTL (seconds) a pending claim code stays redeemable when the scaler entry
- * does not set `claimTtlSeconds`. Long enough for a provisioning workflow to
- * boot an instance, short enough that a leaked code ages out quickly.
+ * Pending claim TTL (seconds) when the scaler entry sets no `claimTtlSeconds`:
+ * long enough to boot an instance, short enough that a leaked code ages out.
  */
 export declare const DEFAULT_CLAIM_TTL_SECONDS = 300;
-/**
- * Function that mints an ephemeral agent token bound to an agent id + labels.
- * Modelled on `AgentTokenStore.createEphemeral(agentId, labels, ttlMs)`.
- */
+/** Mints an ephemeral agent token; modelled on `AgentTokenStore.createEphemeral`. */
 export type CreateEphemeralToken = (agentId: string, labels: string[], ttlMs: number) => Promise<string>;
 /** What the event backend registers when it emits a scale-up. */
 export interface ClaimSpec {
@@ -41,17 +33,13 @@ export interface ClaimSpec {
 }
 /** What a successful claim returns to the provisioning workflow. */
 export interface ClaimedCredentials {
-    /** The freshly minted, single-use-per-claim ephemeral agent token. */
+    /** Minted fresh on each claim. */
     agentToken: string;
-    /** Agent id the instance must register with. */
     agentId: string;
-    /** Orchestrator WS URL to connect back to. */
     orchestratorUrl: string;
-    /** Labels the token authorizes. */
     labels: string[];
 }
 export interface ClaimStoreOptions {
-    /** Mints the ephemeral agent token when a claim is honored. */
     createEphemeral: CreateEphemeralToken;
     /** Shared persistence, so any coordinator can redeem a code. */
     stateStore: ScalerStateStore;
@@ -63,12 +51,10 @@ export interface ClaimStoreOptions {
     scalerName?: string;
     /** Injected clock (epoch ms) — no ambient `Date.now()` so TTLs are testable. */
     now?: () => number;
-    /** Default TTL of a pending claim code (seconds) before it expires. */
+    /** Default pending claim code TTL (seconds). */
     ttlDefaultSec: number;
 }
-/**
- * Shared store of pending provisioning claims, backed by `scaler_pending_claims`.
- */
+/** Shared store of pending provisioning claims, backed by `scaler_pending_claims`. */
 export declare class ClaimStore {
     private readonly createEphemeral;
     private readonly stateStore;
@@ -76,18 +62,11 @@ export declare class ClaimStore {
     private readonly now;
     private ttlDefaultMs;
     constructor(opts: ClaimStoreOptions);
-    /**
-     * Replace the default pending-claim TTL. Called when a config reload changes
-     * the owning scaler's `claimTtlSeconds`, so the new value applies without an
-     * orchestrator restart.
-     */
+    /** Applies a reloaded `claimTtlSeconds` without an orchestrator restart. */
     setDefaultTtlSeconds(seconds: number): void;
     /**
-     * Register a pending claim and return its single-use code. The code is a
-     * 256-bit cryptographically-random token — unguessable, so it can travel in
-     * the (persisted) scale-up event without leaking the agent token. Only the
-     * sha256 of the code is persisted, so a DB read can never hand back a
-     * redeemable secret.
+     * Register a pending claim and return its single-use code: 256 random bits,
+     * so it can travel in the persisted scale-up event without leaking the token.
      */
     register(spec: ClaimSpec): Promise<string>;
     /**
@@ -107,10 +86,8 @@ export declare class ClaimStore {
      */
     invalidate(agentId: string): Promise<void>;
     /**
-     * A redemption-only store never writes a claim row, so it is constructed
-     * without a scaler name. Reaching `register` without one is a wiring bug, not
-     * a runtime condition — fail loudly rather than persisting a row nothing can
-     * attribute.
+     * Reaching `register` on a redemption-only store is a wiring bug: fail loudly
+     * rather than persist a row nothing can attribute.
      */
     private requireScalerName;
 }

package/dist/scaler/config.d.ts

@@ -1,33 +1,23 @@
 /**
- * YAML configuration loading and Zod validation for the scaler module.
- *
- * Handles:
- * - Main YAML config file parsing
- * - scalers.d/ directory merging (alphabetically sorted)
- * - Zod schema validation with type-specific refinements
- * - Memory string parsing (e.g., "2g" -> bytes)
+ * Scaler config loading: the main YAML file plus `scalers.d/` (merged in
+ * alphabetical order), validated by Zod with type-specific refinements.
  */
 import { z } from 'zod';
 import type { ScalerConfig } from './types.js';
 /**
- * Default cap on concurrent `backend.spawn` operations per backend when a
- * scaler entry does not set `maxConcurrentSpawns`. Bounds the provisioning rate
- * (image pull + create + start) so a burst of queued jobs cannot storm the
- * container socket / registry.
+ * Default per-backend `maxConcurrentSpawns`. Bounds the provisioning rate (image
+ * pull + create + start) so a burst of queued jobs cannot storm the container
+ * socket / registry.
  */
 export declare const DEFAULT_MAX_CONCURRENT_SPAWNS = 8;
 /**
- * Zod schema for network policy configuration on a label set.
- * Controls RFC1918 and internet access for spawned agents.
+ * A label set's RFC1918 and internet access for spawned agents.
  */
 export declare const networkPolicySchema: z.ZodOptional<z.ZodObject<{
     allowlist: z.ZodOptional<z.ZodArray<z.ZodString>>;
     denyAll: z.ZodDefault<z.ZodBoolean>;
     hostAccess: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>>;
-/**
- * Zod schema for a label-set configuration entry.
- */
 export declare const labelSetConfigSchema: z.ZodObject<{
     labels: z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<import("@kici-dev/engine").CanonicalLabel[], string[]>>;
     image: z.ZodOptional<z.ZodString>;
@@ -66,7 +56,6 @@ export declare const labelSetConfigSchema: z.ZodObject<{
     overlayDriveSizeMib: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
 /**
- * Zod schema for Firecracker network configuration.
  * Global across all Firecracker scalers on the orchestrator.
  */
 export declare const firecrackerNetworkSchema: z.ZodObject<{
@@ -77,10 +66,6 @@ export declare const firecrackerNetworkSchema: z.ZodObject<{
     table: z.ZodDefault<z.ZodString>;
     autoProvisionHost: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
-/**
- * Zod schema for the complete scaler configuration file.
- * Validates version, global limits, defaults, and scaler entries.
- */
 export declare const scalerFileSchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
     globalMaxAgents: z.ZodDefault<z.ZodNumber>;
@@ -233,28 +218,16 @@ export declare const scalerFileSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 /**
- * Parse a memory string with unit suffix to bytes.
- *
- * Supported formats:
- * - "512m" or "512M" -> 536870912 (512 * 1024^2)
- * - "2g" or "2G" -> 2147483648 (2 * 1024^3)
- * - "1024k" or "1024K" -> 1048576 (1024 * 1024)
+ * Parse a memory string to bytes, with binary units: "512m" -> 512 * 1024^2,
+ * "2G" -> 2 * 1024^3, "1024k" -> 1024 * 1024 (suffix case-insensitive).
  *
  * @throws Error if the format is invalid
  */
 export declare function parseMemoryString(memory: string): number;
 /**
- * Load and validate the scaler configuration from YAML files.
- *
- * 1. Reads the main config file
- * 2. If scalersDirPath provided, reads all *.yaml and *.yml files
- *    from the directory (sorted alphabetically) and merges their
- *    scalers arrays into the main config
- * 3. Validates the merged config through Zod schema
+ * Load the main YAML config, append the `scalers` arrays of every `*.yaml` /
+ * `*.yml` in `scalersDirPath` (alphabetical order), and validate the result.
  *
- * @param configPath - Path to the main scaler YAML config file
- * @param scalersDirPath - Optional path to scalers.d/ directory for additional scaler definitions
- * @returns Validated ScalerConfig
  * @throws ZodError if validation fails
  */
 export declare function loadScalerConfig(configPath: string, scalersDirPath?: string): Promise<ScalerConfig>;