@kici-dev/orchestrator 0.9.1 → 0.10.0

package/dist/scaler/container-routing.d.ts

@@ -1,23 +1,23 @@
 /**
- * Capability label for hosts that can run containers.
+ * Label for hosts that can run containers.
  *
- * An operator may put this on a pool's label sets and on a container job's
- * `runsOn` to steer container work at hosts with a runtime. KiCI does NOT add
- * it automatically, and does not gate routing on it.
+ * The agent reports it itself at registration when it finds a Docker socket,
+ * alongside `kici:runtime:podman` for a Podman one and the `kici:os:*` /
+ * `kici:arch:*` facts: whether a machine has a container runtime is that
+ * machine's fact, not the orchestrator's. Probing the orchestrator's own
+ * filesystem answers a different question — it was tried, and it stranded
+ * container jobs that had been running fine, because the probe and the job ran
+ * in different places.
  *
- * **Why it is not automatic.** A container job needs a runtime on the host that
- * ends up running it, and the orchestrator does not know that: an agent runs on
- * its own machine, and whether that machine has docker or podman is the agent's
- * fact, not the orchestrator's. Probing the orchestrator's own filesystem
- * answers a different question — it was tried, and it stranded container jobs
- * that had been running fine, because the probe and the job ran in different
- * places.
+ * Routing gates on the reported label (`canAgentRunJob`): a `container:` job
+ * reaches an agent only when that agent was started for it, or reports
+ * `kici:runtime:docker` or `kici:runtime:podman`. For an operator's own agent
+ * the gate applies from the release that reports runtime labels at all; an
+ * older agent reports none, so its silence proves nothing and a job it cannot
+ * run fails on it with a message that names the missing runtime.
  *
- * Doing this properly means the AGENT reporting the capability at registration,
- * alongside the `kici:os:*` / `kici:arch:*` facts it already self-reports. Until
- * then a mis-routed container job fails at the image preflight or a backend's
- * fail-fast, both of which name what is missing — a clear late error, rather
- * than a job that silently matches nothing and never runs.
+ * An operator may still put the label on a pool's label sets and on a container
+ * job's `runsOn` to steer container work at hosts with a runtime.
  */
 export declare const KICI_RUNTIME_DOCKER_LABEL = "kici:runtime:docker";
 //# sourceMappingURL=container-routing.d.ts.map

package/dist/scaler/manager.d.ts

@@ -8,6 +8,7 @@
  */
 import type { ResourceRequest, ScalerCapacitySummary } from '@kici-dev/engine';
 import { ScaleDownReason } from './scaler-events.js';
+import { type ScalerAgentView } from './agent-fit.js';
 import type { ScalerEventEmitterLike } from './event-backend.js';
 import type { ClaimStore, ClaimedCredentials } from './claim-store.js';
 import type { BackendFailureSummary } from './failure-tracker.js';
@@ -374,6 +375,14 @@ export declare class ScalerManager {
      * dispatch has not yet arrived.
      */
     private readonly warmAgents;
+    /**
+     * Registered agents this instance started for a specific queued job, keyed
+     * by agent id. The spawning entry that carries the binding is deleted at
+     * registration, so this is where {@link agentView} reads it: the agent always
+     * runs its own job, and an agent started inside a job's image runs nothing
+     * else.
+     */
+    private readonly boundAgents;
     /**
      * Warm agents whose destroy is issued but has not settled yet.
      *
@@ -497,25 +506,25 @@ export declare class ScalerManager {
      */
     private warmPoolLabelSetFillable;
     /**
-     * Whether this scaler pre-spawned (warm-filled) the agent, i.e. whether
-     * {@link canPrespawnedAgentServe} can ever answer false for it. A caller that
-     * picks one agent at a time uses this to decide whether the suitability check
-     * is worth carrying at all.
+     * Whether this scaler pre-spawned (warm-filled) the agent.
      */
     isPrespawnedAgent(agentId: string): boolean;
     /**
-     * Whether a pre-spawned (warm) agent can serve this job.
+     * What this scaler knows about an agent it started, for `canAgentRunJob`,
+     * or undefined for an agent it did not start.
+     */
+    agentView(agentId: string): ScalerAgentView | undefined;
+    /**
+     * Whether a pre-spawned (warm) agent's shape fits the shape a job declares.
      *
      * A warm agent is generic by construction: it was started before the job
-     * existed, at the pool's declared shape and running the pool's agent image.
-     * Both are applied when the agent starts and cannot be changed afterwards —
-     * nothing in the agent reads a job's `resources`, and an already-running
-     * container cannot become a different image. So a job that needs something
-     * else must get its own agent instead of silently running with the pool's.
+     * existed, at the pool's declared shape. The shape is applied when the agent
+     * starts and cannot be changed afterwards — nothing in the agent reads a
+     * job's `resources`. So a job that needs another shape must get its own
+     * agent instead of silently running with the pool's.
      *
-     * Returns true for any agent this scaler did not pre-spawn: a job-bound or
-     * static agent is not this predicate's business. {@link isPrespawnedAgent}
-     * answers that half on its own.
+     * Returns true for any agent this scaler did not pre-spawn: a job-bound agent
+     * was started at its job's shape.
      *
      * Only the fields the job actually declares are compared. `resolveEffective`
      * layers a job's declaration over the label set and the scaler defaults field
@@ -536,10 +545,7 @@ export declare class ScalerManager {
      * them apart, so a job matched on `requests` alone can still land on an agent
      * capped somewhere else entirely.
      */
-    canPrespawnedAgentServe(agentId: string, job: {
-        resources?: ResourceRequest;
-        hasOwnContainerImage: boolean;
-    }): boolean;
+    private prespawnedShapeFits;
     /**
      * Whether one side (`requests` or `limits`) of a job's declared shape leaves
      * the agent's resolved side unchanged.

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

@@ -22,7 +22,7 @@ export interface ContextSecretResolverDeps {
     logger: Logger;
 }
 /**
- * Build a `SecretResolver` over the org's contexts, bindings, and registered
+ * Build a `SecretResolver` over the org's context bindings and registered
  * secret backends. The `pg` backend decrypts through the master key; external
  * backends (Vault) return plaintext, so their decrypt is identity.
  */

package/dist/secrets/index.d.ts

@@ -11,7 +11,7 @@ export { secretOutputAad, sealSecretOutput, unsealSecretOutput } from './secret-
 export { rotateMasterKeyWrappedTables, selfHealStrandedDashboardKey, selfHealStrandedSigningKey, strandedKeyError, type MasterKeyRotationResult, type SweepResult, } from './master-key-rotation.js';
 export { encrypt, decrypt, deriveKey, generateMasterKey, type EncryptedValue, } from '@kici-dev/shared';
 export { VaultSecretStore, type VaultConfig } from './vault-secret-store.js';
-export { SecretResolver, type SecretResolverDeps, type ResolvedSecretMeta, type ContextStoreLike, type BindingStoreLike, type SecretStoreLike, } from './secret-resolver.js';
+export { SecretResolver, type SecretResolverDeps, type ResolvedSecretMeta, type MatchedContextRef, type BindingStoreLike, type SecretStoreLike, } from './secret-resolver.js';
 export { BackendSyncManager } from './backend-sync.js';
 export { RbacEnforcer, PermissionDeniedError, type Role, type Permission } from './rbac.js';
 export { TokenManager } from './token-manager.js';

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

@@ -8,8 +8,8 @@
  * `docs/user/container-jobs.md` do, so a bound-only rule would refuse every
  * documented use.
  *
- * Resolving outside the bindings is not the same as resolving with no
- * authorization. Three independent checks stand between a job and the value,
+ * Resolving outside the job's `contexts:` list is not the same as resolving with
+ * no authorization. Three independent checks stand between a job and the value,
  * and this module is where all three run:
  *
  *   1. the reserved namespace is refused — a job may never name the
@@ -20,6 +20,14 @@
  *      the branch restriction, `minimumTrust`, concurrency, reviewers and wait
  *      timers the operator configured on `prod` apply to a `prod:` reference.
  *
+ * 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 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
  * refs come from the lock by construction.
@@ -27,7 +35,7 @@
  * Callers use this instead of `SecretResolverApi.resolveNamedInternal`, which
  * is the system-scoped direct lookup and applies none of the above.
  */
-import type { TrustTier } from '@kici-dev/engine';
+import { type TrustTier } from '@kici-dev/engine';
 import type { ContextStore } from '../contexts/context-store.js';
 import { type JobDispatchContext } from '../contexts/protection/pipeline.js';
 import type { SecretResolverApi } from './secret-resolver.js';
@@ -37,6 +45,15 @@ import type { SecretResolverApi } from './secret-resolver.js';
  * its `customer_id`, so a job can never legitimately present this value.
  */
 export declare const RESERVED_ORG_ID = "__system__";
+/**
+ * A refusal this module decides — a reserved namespace, an untrusted tier, a
+ * context that does not exist or does not admit the run, a secret that is not
+ * there. Distinct from a store or resolver failure, which propagates as-is, so
+ * a caller can tell "this job may not have it" from "we could not look".
+ */
+export declare class JobSecretRefusedError extends Error {
+    constructor(message: string);
+}
 /**
  * Refuse a reference into the orchestrator's own reserved namespace.
  *
@@ -64,6 +81,11 @@ export interface ResolveJobQualifiedSecretArgs {
     /** The dispatch facts the protection rules evaluate against, from server truth. */
     dispatchCtx: JobDispatchContext;
     trustTier: TrustTier | undefined;
+    /**
+     * Ids of contexts whose protection rules already admitted this job. Their
+     * rules are not re-run; the namespace and trust-tier refusals still apply.
+     */
+    admittedContextIds?: ReadonlySet<string>;
 }
 /**
  * Resolve one `<context>:<key>` reference on behalf of a running job.

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

@@ -0,0 +1,36 @@
+import type { ResolvedMasterKeys } from './config.js';
+/** The job-config fields that carry secret material. */
+export declare const SEALED_JOB_CONFIG_KEYS: readonly ['secrets', 'namespacedSecrets', 'installEnvSecrets', 'containerRegistryAuth', 'npmRegistries', 'orchestratorPrivateKey'];
+/** The key version every seal is written at. The AAD, not the version, binds a value. */
+export declare const JOB_SECRETS_KEY_VERSION = 1;
+/**
+ * Thrown when a sealed value cannot be opened: it was sealed with a master key
+ * this orchestrator does not hold. During a rolling key rotation that is a
+ * coordinator not yet restarted with the new key; the message names the fix.
+ */
+export declare class JobSecretsUnsealError extends Error {
+    constructor(runId: string, cause: string);
+}
+/**
+ * Register the master keys the stores seal with. `null` keeps the fields in
+ * plaintext and logs the one warning that names the setting.
+ */
+export declare function configureJobSecretSealing(keys: ResolvedMasterKeys | null): void;
+/** The AAD a stored job's sealed secrets are bound to. */
+export declare function jobSecretsAad(runId: string): string;
+/** Seal `value` for `runId`; `null` when no master key is configured. */
+export declare function sealJobSecretValue(runId: string, value: unknown): string | null;
+/** Open a value {@link sealJobSecretValue} sealed, with the old key as fallback. */
+export declare function unsealJobSecretValue(runId: string, sealed: string): unknown;
+/**
+ * Split a job config into what is stored in the plain column and the sealed
+ * secret fields. With nothing to seal, or no master key, the config is
+ * returned as is and `sealed` is null.
+ */
+export declare function sealJobConfig(runId: string, jobConfig: Record<string, unknown>): {
+    jobConfig: Record<string, unknown>;
+    sealed: string | null;
+};
+/** The job config with its sealed secret fields merged back. A null `sealed` returns it as is. */
+export declare function unsealJobConfig(runId: string, jobConfig: Record<string, unknown>, sealed: string | null | undefined): Record<string, unknown>;
+//# sourceMappingURL=job-secret-seal.d.ts.map

package/dist/secrets/master-key-rotation.d.ts

@@ -1,7 +1,7 @@
 /**
- * Master-key rotation sweeps for the four wrapped stores `rotate-key` did not
+ * Master-key rotation sweeps for the wrapped stores `rotate-key` did not
  * cover: the provenance signing key, the dashboard-encryption key, run
- * ephemeral keys, and stored secret outputs.
+ * ephemeral keys, stored secret outputs, and the sealed secrets of stored jobs.
  *
  * Each sweep runs in its own transaction with the same skip-and-count
  * discipline as `BackendRegistry.rotateKey` — a row neither key opens is
@@ -26,10 +26,14 @@ export interface MasterKeyRotationResult {
     dashboardKeys: SweepResult;
     ephemeralKeys: SweepResult;
     secretOutputs: SweepResult;
+    /** `sealed_secrets` of `dispatch_queue`, `pending_job_contexts` and `pending_workflow_contexts`. */
+    jobSecrets: SweepResult;
 }
 type Warn = (message: string, meta: Record<string, unknown>) => void;
+/** Rows of `dispatch_queue` one rotation transaction re-seals. */
+export declare const JOB_SECRETS_SWEEP_BATCH = 500;
 /**
- * Run all four sweeps, each in its own transaction so a bug in one cannot roll
+ * Run all the sweeps, each in its own transaction so a bug in one cannot roll
  * back a good rotation of another. Order is least-to-most volume, so the
  * singleton key tables — the two whose loss brings the orchestrator down — move
  * first.

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

@@ -2,9 +2,10 @@
  * Secret resolver for dispatch-time secret resolution.
  *
  * Uses context bindings + scope resolver to match secrets from multiple backends.
- * When a job dispatches with a context name, the resolver:
- * 1. Looks up the context by name
- * 2. Gets bindings for that context
+ * When a job dispatches through a context, the resolver:
+ * 1. Takes the context row the dispatch path already matched (a fixed context
+ *    by exact name, or a glob context whose pattern matched the declared name)
+ * 2. Gets bindings for that row
  * 3. Queries ALL registered backend stores for secrets
  * 4. Prefixes each secret's scope with the backend name (e.g., pg:aws/prod)
  * 5. Uses resolveSecretsWithProvenance to match bindings against prefixed secrets
@@ -19,14 +20,23 @@ import { type ContextBinding, type HostFacts, type ScopedSecret } from '@kici-de
 import type { Logger } from '@kici-dev/shared';
 import type { AuditLogger } from './audit-logger.js';
 /**
- * Minimal context store interface (subset needed by resolver).
+ * The context a job's secrets resolve through.
+ *
+ * `id` is the row the dispatch path matched — which, for a glob context, is not
+ * the row whose name equals the declared one — so the resolver reads that row's
+ * bindings and never matches a name again: a second match could land on a
+ * different row than the one the caller's protection rules and held-run
+ * checks ran against. `name` is the name the job declared; it labels the audit
+ * entry and keys per-context namespacing.
  */
-export interface ContextStoreLike {
-    getByName(orgId: string, name: string): Promise<{
-        id: string;
-        name: string;
-        orgId: string;
-    } | null>;
+export interface MatchedContextRef {
+    id: string;
+    name: string;
+}
+/** The run and job a resolution is recorded against in the secret audit log. */
+export interface SecretResolutionAttribution {
+    runId?: string;
+    jobId?: string;
 }
 /**
  * Minimal binding store interface (subset needed by resolver).
@@ -49,7 +59,6 @@ export interface SecretStoreLike {
  * Dependencies for the SecretResolver.
  */
 export interface SecretResolverDeps {
-    contextStore: ContextStoreLike;
     bindingStore: BindingStoreLike;
     /** Map of backend name to store. Replaces single secretStore. */
     backendStores: Map<string, SecretStoreLike>;
@@ -69,7 +78,7 @@ export interface ResolvedSecretMeta {
  * can flow through `ProcessingDeps.secretResolver`.
  */
 export interface SecretResolverApi {
-    resolveForJob(orgId: string, contextName: string, hostCtx?: HostFacts): Promise<Record<string, string>>;
+    resolveForContext(orgId: string, context: MatchedContextRef, hostCtx?: HostFacts, attribution?: SecretResolutionAttribution): Promise<Record<string, string>>;
     /**
      * System-scoped direct lookup — no context binding, no protection rule, no
      * trust tier. A job-originated reference goes through
@@ -80,7 +89,12 @@ export interface SecretResolverApi {
         runId?: string;
         jobId?: string;
     }): Promise<string | null>;
-    resolveForJobWithMeta(orgId: string, contextName: string, hostCtx?: HostFacts): Promise<Record<string, ResolvedSecretMeta>>;
+    resolveForContextWithMeta(orgId: string, context: MatchedContextRef, hostCtx?: HostFacts): Promise<Record<string, ResolvedSecretMeta>>;
+    /**
+     * How many scope bindings the context row `contextId` has. A context with
+     * none resolves no secret; the dispatch path reads this to say so in its log.
+     */
+    countContextBindings?(contextId: string): Promise<number>;
 }
 /**
  * Resolves secrets for a job by matching context bindings against scoped secrets
@@ -92,7 +106,6 @@ export interface SecretResolverApi {
  * stripping the backend prefix.
  */
 export declare class SecretResolver implements SecretResolverApi {
-    private readonly contextStore;
     private readonly bindingStore;
     private readonly backendStores;
     private readonly auditLogger;
@@ -102,14 +115,16 @@ export declare class SecretResolver implements SecretResolverApi {
      * Resolve secrets for a job dispatch.
      *
      * @param orgId - Organization ID
-     * @param contextName - Context name to resolve secrets for
+     * @param context - The matched context row and the name the job declared
      * @param hostCtx - Optional fan-out child identity for per-host resolution.
      *   When supplied, each binding is gated by its `host_pattern` and its
      *   `scope_pattern` is templated per-child; when omitted, only fleet-wide
      *   (`'**'`) non-templated bindings contribute.
+     * @param attribution - The run and job the audit entry names, when the
+     *   caller resolves on behalf of one.
      * @returns Flat map of decrypted secret key-value pairs
      */
-    resolveForJob(orgId: string, contextName: string, hostCtx?: HostFacts): Promise<Record<string, string>>;
+    resolveForContext(orgId: string, context: MatchedContextRef, hostCtx?: HostFacts, attribution?: SecretResolutionAttribution): Promise<Record<string, string>>;
     /**
      * Resolve a single named secret by (orgId, scope, key), optionally scoped to
      * a specific backend.
@@ -122,18 +137,20 @@ 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 before reaching this method. The
-     * `Internal` suffix is the enforcement: this method's doc comment already
-     * warned that it bypassed context bindings, and three call sites took it
-     * anyway — a warning is not a boundary, but a name shows up in a grep of
-     * callers.
+     * 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
+     * boundary: a warning in a doc comment is not one, but a name shows up in a
+     * grep of callers.
      *
      * When `store` is omitted, backends are tried in Map iteration order (the
      * order they were registered) and the first hit wins. An explicit `store`
      * restricts the lookup to that one backend and returns null on miss.
      *
      * Audit-log: writes one `resolve_named` entry on success. Throws when the
-     * named store is requested but doesn't exist, mirroring `resolveForJob`'s
+     * named store is requested but doesn't exist, mirroring `resolveForContext`'s
      * fail-fast policy — the caller asked for a specific backend and
      * it's gone.
      */
@@ -142,12 +159,14 @@ export declare class SecretResolver implements SecretResolverApi {
         runId?: string;
         jobId?: string;
     }): Promise<string | null>;
+    /** How many scope bindings the context row `contextId` has. */
+    countContextBindings(contextId: string): Promise<number>;
     /**
      * Resolve secrets with metadata (per, for secrets.getMeta).
      *
      * Returns the secret value along with which backend and scope provided it.
      */
-    resolveForJobWithMeta(orgId: string, contextName: string, hostCtx?: HostFacts): Promise<Record<string, ResolvedSecretMeta>>;
+    resolveForContextWithMeta(orgId: string, context: MatchedContextRef, hostCtx?: HostFacts): Promise<Record<string, ResolvedSecretMeta>>;
     /**
      * Collect all secrets from all backend stores, prefixing scopes.
      * Per /: unreachable backends are tracked but not fatal here.