@kici-dev/orchestrator 0.15.0 → 0.16.0

package/dist/scaler/manager.d.ts

@@ -7,7 +7,7 @@
  * and manages the agent lifecycle from spawn to destroy.
  */
 import { ScalerVmTracker } from '@kici-dev/engine';
-import type { ResourceRequest, ScalerCapacitySummary, ScalerLiveVm, ScalerVmStopResult } from '@kici-dev/engine';
+import type { ResourceRequest, ScalerCapacitySummary, ScalerLiveVm, ScalerReloadPlan, ScalerVmStopResult } from '@kici-dev/engine';
 import { ScaleDownReason } from './scaler-events.js';
 import { type ScalerAgentView } from './agent-fit.js';
 import type { ScalerEventEmitterLike } from './event-backend.js';
@@ -28,8 +28,10 @@ import type { ClaimStore, ClaimedCredentials } from './claim-store.js';
  */
 export declare const SCALER_SHUTDOWN_GRACE_MS = 15000;
 import type { BackendFailureSummary } from './failure-tracker.js';
-import type { ScalerBackend, ScalerConfig, ScalerEntry, ScaleResult, ScalerEvent, ResourceCap, ValidationResult, ResolvedContainerSpawn } from './types.js';
+import type { ScalerBackend, ScalerConfig, ScalerEntry, ScaleResult, ScalerEvent, ResourceCap, ResolvedContainerSpawn } from './types.js';
 import type { ScalerStateStore, ScalerStateRecovery, ReapCandidate } from './scaler-state-store.js';
+/** The `skipped` reason for a job whose agent is already provisioning or registered. */
+export declare const PROVISION_IN_FLIGHT = "provision-in-flight";
 /**
  * Raised when a registering agent presents a scaler-minted id that the
  * orchestrator cannot back with a spawn record — either because the lookup
@@ -155,6 +157,17 @@ export interface ScalerStatus {
         retiring: boolean;
     }>;
 }
+/**
+ * The outcome of `ScalerManager.reload`: the applied plan, or the errors of a
+ * refused reload that changed nothing.
+ */
+export type ScalerReloadResult = {
+    valid: true;
+    plan: ScalerReloadPlan;
+} | {
+    valid: false;
+    errors: string[];
+};
 /**
  * What the coordinator holding an event agent needs to tear its provision
  * down: enough to emit `kici.scaler.scale-down` with no local backend and no
@@ -334,6 +347,12 @@ export declare class ScalerManager {
     private readonly resolveProvisionBackoff;
     private readonly readJobStatuses?;
     private globalMaxAgents;
+    /**
+     * Each configured scaler's entry as last applied, in `stableJson` form. A
+     * reload compares against it to report which kept scalers it updated; the
+     * backends cannot answer that, since most of them keep no copy of their entry.
+     */
+    private readonly appliedEntries;
     /** Per-scaler resource caps (`{ maxCpu, maxMemoryBytes }`), keyed by scaler name. */
     private readonly resourceCaps;
     /** Per-scaler default resources (used when neither job nor label-set declares them). */
@@ -415,6 +434,8 @@ export declare class ScalerManager {
      * else.
      */
     private readonly boundAgents;
+    /** Jobs a `requestScale` call is provisioning right now, before its spawning entry exists. */
+    private readonly jobsBeingProvisioned;
     /**
      * Warm agents whose destroy is issued but has not settled yet.
      *
@@ -518,11 +539,10 @@ export declare class ScalerManager {
      * The pool measures readiness with `AgentRegistry.findAvailable(labels)`, and
      * that query applies the agent's `mandatoryLabels` gate: an agent is dropped
      * unless every label in its gate also appears in the query. A scaler-spawned
-     * agent's gate is `labelSetMandatoryLabels()` for the set it was spawned for,
-     * which unions the configured gate with the pool's platform taints.
-     * `warmPoolQueryLabels` puts the structured taints into the query, so that
-     * part of the gate is satisfied by construction, and the legacy shim derives
-     * from this label set's own labels, so it is satisfied by construction too.
+     * agent's gate is `mandatoryGate()`, which unions the configured gate with
+     * the pool's platform taints. `warmPoolQueryLabels` puts the structured
+     * taints into the query, so that part of the gate is satisfied by
+     * construction.
      *
      * That leaves one residual case: a configured `mandatoryLabels` entry absent
      * from the label set, which `scaler/config.ts` validation already rejects.
@@ -531,10 +551,8 @@ export declare class ScalerManager {
      * that share the cap. A refused pool is inert, exactly as it is before it
      * fills at all — never partially filled.
      *
-     * The gate derives from `declaredLabels` and is compared against
-     * `queryLabels`. Deriving it from `queryLabels` would fold a structured taint
-     * back in as a legacy one; comparing it against `declaredLabels` alone would
-     * refuse every structurally-tainted pool.
+     * The gate is compared against `queryLabels`: comparing it against
+     * `declaredLabels` alone would refuse every structurally-tainted pool.
      */
     private warmPoolLabelSetFillable;
     /**
@@ -669,26 +687,20 @@ export declare class ScalerManager {
     private readonly scalerMandatoryLabels;
     /** Declared structured platform per scaler (undefined = host-derive / linux default). */
     private readonly scalerPlatform;
-    /**
-     * Warn when a pool declares a plain platform-ish label (matched by the legacy
-     * denylist) but omits the structured `platform` field. The denylist is a
-     * migration shim; declaring `platform` is the canonical way to taint a pool.
-     */
-    private warnOnUnstructuredPlatformLabels;
     /**
      * Resolve the pool's platform for label + taint derivation. Precedence:
      *   1. A declared `platform` field always wins (even on a linux host).
      *   2. Otherwise a bare-metal pool derives its platform from the host OS/arch.
      *   3. Otherwise (container / firecracker, undeclared) returns null — those
      *      pools run linux agents and are not auto-tainted; only an explicit
-     *      declared platform or a legacy denylist label taints them.
+     *      declared platform taints them.
      * Returns null when a bare-metal host's OS/arch is not a supported enum value
      * (the caller falls back to the raw host-label derivation for labels).
      */
     private resolveScalerPlatform;
     /**
      * The plain platform-taint tokens (`windows`, `macos`, `arm64`) for a scaler,
-     * derived from the same resolved platform `labelSetMandatoryLabels` gates on.
+     * derived from the same resolved platform `mandatoryGate` gates on.
      *
      * This is the single source for the taint: it feeds the matcher's view of the
      * label sets, the taint gate, the labels the spawned agent registers with, and
@@ -719,21 +731,14 @@ export declare class ScalerManager {
      */
     private warmPoolQueryLabels;
     /**
-     * Taint gate for ONE of a scaler's label sets: the configured
-     * `mandatoryLabels` plus the platform taints derived from the pool's resolved
-     * structured platform, unioned with the legacy plain-label denylist shim read
-     * from THIS label set alone.
-     *
-     * This is the gate every routing and stamping decision uses. Deriving the
-     * legacy shim per label set is what keeps a mixed-platform scaler routable: a
-     * pool declaring `[linux, gpu]` alongside `[macos, xcode]` gates only the
-     * second set on `macos`, where the union would gate both and leave the linux
-     * set unreachable by any sensible job.
+     * Taint gate for a scaler's label sets: the configured `mandatoryLabels` plus
+     * the platform taints derived from the pool's resolved structured platform.
      *
-     * `backend` carries only `type` because the label set is passed in — a caller
-     * that holds one label set never has to reach for the whole backend.
+     * This is the gate every routing and stamping decision uses. `backend`
+     * carries only `type`, so a caller that holds one label set never has to
+     * reach for the whole backend.
      */
-    private labelSetMandatoryLabels;
+    private mandatoryGate;
     /**
      * Build enriched scaler entries with auto-labels injected into each label set.
      * This ensures label matching accounts for auto-injected labels (kici:role:*,
@@ -794,6 +799,10 @@ export declare class ScalerManager {
      * image instead of the pool's fixed agent image.
      */
     containerSpawn?: ResolvedContainerSpawn): Promise<ScaleResult>;
+    /** Whether this coordinator already provisions, or holds an agent bound to, `jobId`. */
+    private hasLocalProvisionFor;
+    /** `requestScale` past its drain and per-job checks: match, reserve, spawn. */
+    private provisionForJob;
     /**
      * Take every reservation one spawn needs, or take none at all.
      *
@@ -1310,7 +1319,12 @@ export declare class ScalerManager {
      * dropped: it stops taking work at once, its idle warm agents are destroyed,
      * its job-bound agents finish, and its backend is torn down when it drains.
      */
-    reload(newConfig: ScalerConfig): Promise<ValidationResult>;
+    reload(newConfig: ScalerConfig): Promise<ScalerReloadResult>;
+    /**
+     * What a validated reload is about to change, per scaler name. Runs before
+     * the commit, while the previous entries and global limits are still in place.
+     */
+    private describeReload;
     /**
      * Return status summary for metrics and health endpoints.
      */

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

@@ -68,6 +68,11 @@ export interface ScalerCapSlot {
      * in that window reads the same pre-spawn count and admits.
      */
     reserve(snapshot: SpawningAgentSnapshot): Promise<void>;
+    /**
+     * Whether this scaler already holds a spawn row bound to `jobId` on any
+     * coordinator. Read inside the same locked transaction as the claim.
+     */
+    hasProvisionForJob(jobId: string): Promise<boolean>;
 }
 /** A row the event-provision reaper may need to tear down. */
 export interface ReapCandidate {

package/dist/scaler/types.d.ts

@@ -144,11 +144,8 @@ export interface LabelSetConfig {
     /** Path to agent binary (bare-metal backend) */
     binaryPath?: string;
     /**
-     * Per-label-set resource request and limit (override scaler defaults).
-     * After config-load normalization the internal representation is always nested:
+     * Per-label-set resource request and limit (override scaler defaults):
      * `{ requests?: { cpus, memory }, limits?: { cpus, memory } }`.
-     * The legacy flat shorthand (`{ cpus, memory }`) is accepted at config-load
-     * and treated as `limits` (with `requests` auto-mirrored).
      */
     resources?: ResourceRequest;
     /**

package/dist/secrets/job-secret-gate.d.ts

@@ -22,11 +22,8 @@
  *
  * The value is then read through the secret-scope bindings of the context row
  * those rules ran against — for a name a glob context matches, the glob row —
- * the way a job's bound context secrets resolve. One deprecated fallback remains
- * (removal planned for v1.0.0): when the row matched by the exact name is not a
- * glob context and no scope bound to it carries the key, the scope named after
- * the context is read instead, and a deprecation warning is logged. A
- * glob-matched row never reads a same-named scope.
+ * the way a job's bound context secrets resolve. A key no bound scope carries is
+ * refused: the scope named after the context is never read.
  *
  * The lock declaration is the fourth check and lives at the callers: the relay
  * pins the wire ref to `execution_jobs.git_credentials`, and container-registry

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

@@ -138,10 +138,8 @@ export declare class SecretResolver implements SecretResolverApi {
      * A JOB-ORIGINATED reference goes through `resolveJobQualifiedSecret`
      * (`secrets/job-secret-gate.ts`) instead, which runs the named context's
      * protection rules and the trust-tier strip, then reads the value through
-     * that context's bindings with `resolveForContext`. It calls this method in
-     * one deprecated case only, after its own checks pass: a non-glob context
-     * matched by its exact name, whose bound scopes do not carry the key, reads
-     * the scope named after the context (removal planned for v1.0.0). The `Internal` suffix marks the
+     * that context's bindings with `resolveForContext`, and never calls this
+     * method. The `Internal` suffix marks the
      * boundary: a warning in a doc comment is not one, but a name shows up in a
      * grep of callers.
      *

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

@@ -64,10 +64,6 @@ export type TrustPolicyOutcome = {
      * divergence between deciding and sizing. `null` means "no window came
      * with this verdict", and the hold site falls back to
      * `DEFAULT_APPROVAL_EXPIRY_SECONDS`.
-     *
-     * Seconds, not hours, because this is what the hold site actually needs:
-     * an hours-only window cannot express the sub-hour hold the policy may now
-     * carry, and rounding it here would silently lengthen it.
      */
     approvalExpirySeconds: number | null;
 } | {

package/dist/server.d.ts

@@ -1,26 +1,15 @@
 /**
- * Platform-connected entry point for the customer orchestrator.
+ * Platform-connected orchestrator entry point. 'platform' mode takes webhooks
+ * only via the Platform WS relay; 'hybrid' also serves the direct HTTP endpoint.
  *
- * Operates in 'platform' or 'hybrid' mode:
- * - platform: receives webhooks ONLY via Platform WS relay
- * - hybrid: receives webhooks via both WS relay and direct HTTP endpoint
- *
- * Both modes connect a PlatformClient to the Platform relay and run an agent WS server.
- *
- * Startup sequence (the same one the Platform follows):
- * config -> DB -> migrations -> provider registry -> dispatcher -> PlatformClient -> app -> HTTP -> heartbeat
- *
- * Graceful shutdown in reverse order:
- * Platform client -> agent WS -> heartbeat -> HTTP -> DB
+ * Startup: config -> DB -> migrations -> provider registry -> dispatcher ->
+ * PlatformClient -> app -> HTTP -> heartbeat. Shutdown runs in reverse.
  */
 import '@kici-dev/shared/load-service-env-file';
 import type { OrchestratorFaultInjection } from './fault-injection-types.js';
 /**
- * Boot the Platform-connected orchestrator. Factored out of the module entry so
- * both this file's production entry (which passes no fault injection) and the
- * test-only `server-test.ts` entry (which passes an injected fault-injection
- * policy) run the identical bootstrap through one code path. Exported solely for
- * that single test-only caller; nothing else imports it.
+ * Boot the Platform-connected orchestrator. Exported only so the test-only
+ * `server-test.ts` entry runs the identical bootstrap with a fault-injection policy.
  */
 export declare function runServer(opts?: {
     faultInjection?: OrchestratorFaultInjection;