@kici-dev/orchestrator 0.16.0 → 0.18.0

package/dist/routes/provenance-oidc.d.ts

@@ -19,9 +19,9 @@ export interface ProvenanceOidcRoutesDeps {
     /** Whether orchestrator-owned signing is configured. */
     enabled: boolean;
     /**
-     * Dashboard-encryption key repo. When present, the JWKS additionally serves
-     * the non-revoked X25519 `use:'enc'` key(s) for browser-sealed dashboard
-     * writes (the Verified tier's trust root). Independent of provenance signing.
+     * When present, the JWKS also serves the non-revoked X25519 `use:'enc'` key(s)
+     * for browser-sealed dashboard writes (the Verified tier's trust root).
+     * Independent of provenance signing.
      */
     dashboardEncryptionRepo?: Pick<DashboardEncryptionKeyRepo, 'listNonRevoked'>;
 }

package/dist/routes/test-direct.d.ts

@@ -0,0 +1,46 @@
+import type { Kysely } from 'kysely';
+import { OrchestratorMode } from '@kici-dev/engine';
+import type { Database } from '../db/types.js';
+import type { RbacEnforcer } from '../secrets/rbac.js';
+import { type TestRelayHandlerDeps } from '../ws/test-relay-handlers.js';
+import type { AuthTokenValidator } from './admin-auth.js';
+import { type TokenCaller } from './caller-identity.js';
+type TestDirectEnv = {
+    Variables: {
+        caller: TokenCaller;
+    };
+};
+/** Answer for a Platform-connected orchestrator that has no org yet. */
+export declare const NO_PLATFORM_ORG_MESSAGE = "This orchestrator has not received its organization from the KiCI Platform yet, so it cannot choose where to run the test. Retry when the orchestrator is connected.";
+export interface TestDirectRouteDeps {
+    tokenManager: AuthTokenValidator;
+    rbac: RbacEnforcer;
+    mode: OrchestratorMode;
+    /** The org a connected orchestrator learned from the Platform; read per request. */
+    platformOrgId: () => string | null | undefined;
+    db: Kysely<Database>;
+    /** Builds the relay handlers' deps for one request (minus org, routing key and source). */
+    relayDeps: () => Omit<TestRelayHandlerDeps, 'orgId' | 'routingKey' | 'accessLogSource'>;
+}
+/**
+ * The org a direct test run belongs to: the default org on an independent
+ * orchestrator, the Platform-assigned org otherwise (null until it is known).
+ */
+export declare function directOrgId(mode: OrchestratorMode, platformOrgId: string | null | undefined): string | null;
+/**
+ * Build the route deps, or null when admin auth is not configured: without a
+ * token store there is no credential to authenticate a developer with.
+ */
+export declare function testDirectRouteDeps(input: {
+    adminDeps?: {
+        tokenManager: AuthTokenValidator;
+        rbac: RbacEnforcer;
+    };
+}, rest: Omit<TestDirectRouteDeps, 'tokenManager' | 'rbac'>): TestDirectRouteDeps | null;
+/**
+ * Build the direct test-run router: the routes under `/api/v1/test`, each
+ * behind admin-token authentication that refuses a routing-key-scoped token.
+ */
+export declare function createTestDirectRoutes(deps: TestDirectRouteDeps): import("hono").Hono<TestDirectEnv, import("hono/types").BlankSchema, "/">;
+export {};
+//# sourceMappingURL=test-direct.d.ts.map

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. This is invoked by the Platform-first
- * `test.relay.uploads.init` relay handler — the developer never reaches the
- * orchestrator's HTTP API directly.
+ * 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;
@@ -19,21 +15,20 @@ export interface InitTestUploadParams {
     compressedSize?: number;
     /** PAT/actor identity that owns this upload, written to `test_uploads.created_by`. */
     createdBy?: string | null;
-    /**
-     * When true, presign with the host-facing internal endpoint. When false (the
-     * Platform-relayed path), presign with the external/dev-reachable endpoint so
-     * a developer on a different network can PUT directly to the object store.
-     */
-    internal?: boolean;
 }
-/** Result of {@link initTestUpload}. */
+/**
+ * The orchestrator has no object storage, so it cannot mint an upload URL.
+ * Callers answer it as "service unavailable" with the message as-is.
+ */
+export declare class TestUploadStorageUnavailableError extends Error {
+    constructor(message: string);
+}
 export interface InitTestUploadResult {
     uploadId: string;
     signedUrl: string;
     publicKey: string;
     expiresIn: number;
 }
-/** Dependencies for {@link initTestUpload}. */
 export interface InitTestUploadDeps {
     db: Kysely<Database>;
     cacheStorage?: CacheStorage;
@@ -41,8 +36,8 @@ export interface InitTestUploadDeps {
 /**
  * Mint an upload record and return a presigned PUT URL + ephemeral X25519
  * public key. The encryption keypair is generated per upload; the private key
- * is stored orchestrator-side for post-PUT decryption. The `internal` flag
- * selects the host-facing vs the external/dev-reachable presign endpoint.
+ * is stored orchestrator-side for post-PUT decryption. The URL is the
+ * developer-facing one (`CacheStorage.getInternalUploadUrl`).
  */
 export declare function initTestUpload(deps: InitTestUploadDeps, params: InitTestUploadParams): Promise<InitTestUploadResult>;
 //# sourceMappingURL=uploads.d.ts.map

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,7 +1,5 @@
 /**
- * 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.
@@ -24,7 +22,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 +39,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 +123,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 +143,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 +153,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 +182,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 +191,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;
 }