@kici-dev/orchestrator 0.16.0 → 0.18.0

package/dist/cache/pending-precursor-db-watcher.d.ts

@@ -2,23 +2,20 @@
  * The shared-database channel for pending precursor jobs.
  *
  * The dispatch queue is cluster-wide, so a build / init / dynamic-eval job this
- * coordinator dispatched may be claimed by an agent connected to a sibling
- * coordinator. That agent reports to the sibling; the sibling persists the
- * terminal `job.status` — status plus `execution_jobs.precursor_result` — and
- * relays nothing, because between coordinators the shared row IS the report.
- * The trackers on this coordinator would otherwise wait out their own timeout
- * on a job the fleet already finished.
+ * coordinator dispatched may be claimed by an agent on a sibling coordinator.
+ * The sibling persists the terminal `job.status` (status plus
+ * `execution_jobs.precursor_result`) and relays nothing: between coordinators
+ * the shared row IS the report. Without this, local trackers wait out their own
+ * timeout on a job the fleet already finished.
  *
- * While any tracker awaits a job, this watcher polls the rows for exactly that
- * set and hands each terminal one to `settlePendingPrecursor` — the same
- * function the local agent socket goes through, so the two channels cannot
- * disagree on what "finished" means. A job the socket already settled is no
- * longer tracked and is not queried again; a row that is not yet terminal
- * settles nothing and is re-read on the next tick.
+ * While any tracker awaits a job, this watcher polls exactly those rows and
+ * hands each terminal one to `settlePendingPrecursor`, the same function the
+ * local agent socket uses, so the channels cannot disagree on "finished". A job
+ * the socket settled is no longer tracked; a non-terminal row is re-read next
+ * tick.
  *
- * Only builds, inits and dynamic evals ride this channel. A pre-run global
- * eval round is not a run and writes no `execution_jobs` row, so it has no
- * shared row to read; its own wait ceiling still bounds it.
+ * Only builds, inits and dynamic evals ride this channel. A pre-run global eval
+ * round writes no `execution_jobs` row; its own wait ceiling bounds it.
  */
 import { type Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
@@ -26,10 +23,8 @@ import type { PendingBuildTracker } from './pending-builds.js';
 import type { PendingDynamicTracker } from './pending-dynamics.js';
 import type { PendingInitTracker } from './pending-inits.js';
 /**
- * How often the tracked rows are re-read while anything is pending.
- *
- * The interval is the latency a cross-coordinator build adds before the
- * awaiting pipeline dispatches its real jobs, so it is short; the query is one
+ * Re-read interval while anything is pending. Short, because it is the latency
+ * a cross-coordinator build adds before real jobs dispatch; the query is one
  * primary-key lookup per tracked job and runs only while a tracker is
  * non-empty, so an idle coordinator pays nothing.
  */
@@ -40,15 +35,14 @@ export interface PendingPrecursorDbWatcherDeps {
     pendingInits?: Pick<PendingInitTracker, 'has' | 'resolve' | 'reject' | 'trackedJobIds'>;
     pendingDynamics?: Pick<PendingDynamicTracker, 'has' | 'resolve' | 'reject' | 'trackedJobIds'>;
     /**
-     * Keeps this coordinator's in-memory job status in step with the row it
-     * settled from. The agent frame that would have done so went to the sibling,
-     * and without it the run's completion check on this coordinator reads the
-     * job as still pending forever.
+     * Syncs this coordinator's in-memory job status with the settled row; the
+     * agent frame went to the sibling, and without this the run's completion
+     * check here reads the job as pending forever.
      */
     executionTracker?: {
         updateInMemoryJob(runId: string, jobId: string, status: string): void;
     };
-    /** Poll interval. Defaults to {@link DEFAULT_PRECURSOR_DB_POLL_MS}. */
+    /** Defaults to {@link DEFAULT_PRECURSOR_DB_POLL_MS}. */
     intervalMs?: number;
 }
 export declare class PendingPrecursorDbWatcher {
@@ -57,10 +51,9 @@ export declare class PendingPrecursorDbWatcher {
     private timer;
     private tickInFlight;
     /**
-     * Terminal rows that carried nothing the settle function could act on —
-     * a `success` with no precursor marker, which a coordinator that predates
-     * `precursor_result` writes. Logged once per job, not once per tick; the
-     * waiter's own timeout still bounds it.
+     * Terminal rows with nothing to settle on — a `success` with no precursor
+     * marker, which a coordinator that predates `precursor_result` writes. Logged
+     * once per job, not per tick; the waiter's own timeout bounds it.
      */
     private readonly warnedNoPayload;
     constructor(deps: PendingPrecursorDbWatcherDeps);
@@ -69,10 +62,9 @@ export declare class PendingPrecursorDbWatcher {
     /** The job ids any tracker currently awaits, de-duplicated. */
     private trackedJobIds;
     /**
-     * One pass: read the terminal rows for every tracked job and settle them.
-     * Returns how many entries settled. Never throws — a read fault costs one
-     * tick, and the next one re-reads the same set. Single-flight, so a slow
-     * read cannot stack ticks.
+     * Settle every tracked job's terminal row; returns how many settled. Never
+     * throws — a read fault costs one tick. Single-flight, so a slow read cannot
+     * stack ticks.
      */
     tick(): Promise<number>;
 }

package/dist/cache/pending-tracker.d.ts

@@ -1,16 +1,10 @@
 /**
- * Generic pending-job tracker for coordinating two-phase orchestrator pipelines
- * (build-then-execute, init-then-execute, dynamic-eval-then-execute).
+ * Pending-job tracker for two-phase pipelines (build / init / dynamic eval,
+ * then execute): a deferred Promise per precursor jobId that resolves with a
+ * typed payload, or rejects on failure / disconnect.
  *
- * The orchestrator dispatches a precursor job (build / init / dynamic eval) and
- * needs to wait for the agent to report completion before continuing. This
- * tracker exposes a deferred Promise per jobId that resolves with a typed
- * payload (or rejects on failure / disconnect).
- *
- * Usage:
- * - dispatcher calls track(jobId), awaits the returned promise
- * - terminal-status handler calls resolve(jobId, value) or reject(jobId, err)
- * - cleanup(jobId) is invoked on agent disconnect to reject with a fixed error
+ * The dispatcher awaits track(jobId); the terminal-status handler calls
+ * resolve or reject; cleanup(jobId) rejects with a fixed error on disconnect.
  */
 export interface PendingTrackerOptions<T> {
     /** Logger prefix, e.g. 'pending-builds'. */
@@ -19,11 +13,7 @@ export interface PendingTrackerOptions<T> {
     itemLabel: string;
     /** Error message used when cleanup() rejects a pending entry on disconnect. */
     disconnectError: string;
-    /**
-     * Optional extractor that derives extra structured log fields from the
-     * resolved value (e.g. `jobCount` for dynamic-eval results). The returned
-     * keys are merged into the `resolve` log line for telemetry / debugging.
-     */
+    /** Extra fields for the `resolve` log line (e.g. dynamic-eval `jobCount`). */
     extractResolveMeta?: (value: T) => Record<string, unknown>;
 }
 export declare class PendingTracker<T> {
@@ -32,43 +22,25 @@ export declare class PendingTracker<T> {
     private readonly opts;
     constructor(opts: PendingTrackerOptions<T>);
     /**
-     * Register a pending job and return a promise that resolves when the agent
-     * reports completion (or rejects on failure / disconnect).
-     *
-     * Each call creates a new Promise. If track() is called for the same jobId
-     * twice, the previous Promise's callbacks are replaced -- the previous
-     * caller's Promise will never settle (orphaned). Callers (e.g. BuildCoordinator)
-     * are responsible for coalescing duplicate work upstream.
+     * A second track() for the same jobId replaces the callbacks, orphaning the
+     * first caller's Promise forever. Callers (e.g. BuildCoordinator) coalesce
+     * duplicate work upstream.
      */
     track(jobId: string): Promise<T>;
-    /**
-     * Resolve a pending entry (agent reported success).
-     */
+    /** Agent reported success. */
     resolve(jobId: string, value: T): void;
-    /**
-     * Reject a pending entry (agent reported failure).
-     */
+    /** Agent reported failure. */
     reject(jobId: string, error: Error): void;
-    /**
-     * Clean up on agent disconnect. Rejects with the configured disconnect error.
-     */
+    /** On agent disconnect: rejects with the configured disconnect error. */
     cleanup(jobId: string): void;
-    /**
-     * Check if an entry is pending for a given jobId.
-     */
     has(jobId: string): boolean;
-    /**
-     * Number of pending entries (for metrics / debugging).
-     */
+    /** For metrics / debugging. */
     get size(): number;
     /**
-     * The job ids currently awaited, for the shared-database channel.
-     *
-     * The local agent socket is one of two channels that settle an entry. A job
-     * this coordinator dispatched may be claimed from the shared queue by an
-     * agent connected to a sibling coordinator, whose terminal frame never
-     * reaches this process — the sibling writes it to `execution_jobs` instead.
-     * `PendingPrecursorDbWatcher` polls those rows for exactly this set.
+     * The awaited job ids, for the shared-database channel. A sibling
+     * coordinator's agent may claim the job from the shared queue; its terminal
+     * frame never reaches this process but lands in `execution_jobs`, which
+     * `PendingPrecursorDbWatcher` polls for exactly this set.
      */
     trackedJobIds(): string[];
 }

package/dist/cache/precursor-result.d.ts

@@ -1,18 +1,14 @@
 /**
- * Settling a pending precursor job — build, init, dynamic eval, global eval
- * round — from a terminal `job.status`, whichever channel delivered it.
+ * Settles a pending precursor job (build, init, dynamic eval, global eval
+ * round) from a terminal `job.status`, via either channel:
  *
- * Two channels feed the pending trackers:
+ * - **The local agent socket:** `app.ts` hands the frame here.
+ * - **The shared database:** the dispatch queue is cluster-wide, so an agent
+ *   on a sibling coordinator may claim the job; the sibling persists the frame
+ *   to `execution_jobs` and `PendingPrecursorDbWatcher` hands it here in the
+ *   same shape.
  *
- * - **The local agent socket.** The agent that ran the job reports to the
- *   coordinator it is connected to, and `app.ts` hands the frame here.
- * - **The shared database.** The dispatch queue is cluster-wide, so a job this
- *   coordinator dispatched may be claimed by an agent connected to a sibling
- *   coordinator. That sibling's frame never reaches this process; the sibling
- *   persists it to `execution_jobs` instead, and `PendingPrecursorDbWatcher`
- *   reads the row back and hands it here in the same shape.
- *
- * One function settles both so the two channels cannot drift on what counts as
+ * One function settles both so the channels cannot drift on what counts as
  * "the build finished" or "the init returned its result".
  */
 import type { LockJob } from '@kici-dev/engine';
@@ -21,14 +17,11 @@ import type { PendingDynamicTracker } from './pending-dynamics.js';
 import { type PendingGlobalEvalTracker } from './pending-global-evals.js';
 import type { InitResult, PendingInitTracker } from './pending-inits.js';
 /**
- * The part of a precursor job's terminal `job.status.data` that the awaiting
- * coordinator needs, persisted to `execution_jobs.precursor_result` so a
- * sibling coordinator can read it back.
- *
- * Only the markers and their payloads are kept. The build marker is a flag —
- * the build's artifacts live in the shared source and dependency caches, keyed
- * by content hash, so the waiter re-reads them from there. The init and
- * dynamic-eval markers carry their results, because nothing else does.
+ * The part of a precursor's terminal `job.status.data` the awaiting coordinator
+ * needs, persisted to `execution_jobs.precursor_result` for siblings. The build
+ * marker is a flag (its output lives in the content-hashed source and
+ * dependency caches); the init and dynamic-eval markers carry their results,
+ * because nothing else does.
  */
 export interface PrecursorResult {
     buildComplete?: true;
@@ -37,10 +30,7 @@ export interface PrecursorResult {
     dynamicComplete?: true;
     dynamicJobs?: LockJob[];
 }
-/**
- * Pull the precursor payload out of a terminal `job.status.data`, or `null`
- * when the frame carries no precursor marker (an ordinary job).
- */
+/** `null` when the frame carries no precursor marker (an ordinary job). */
 export declare function extractPrecursorResult(data: Record<string, unknown> | undefined): PrecursorResult | null;
 /** The settle-side surface of a tracker: membership plus the two ways to settle. */
 type Settleable<T> = Pick<T, Extract<keyof T, 'has' | 'resolve' | 'reject'>>;
@@ -56,12 +46,9 @@ export interface PrecursorJobStatus {
     data?: Record<string, unknown>;
 }
 /**
- * Resolve or reject whichever tracker awaits `jobId`, from a terminal status.
- *
- * Returns true when an entry settled. A status for a job nobody awaits, or a
- * non-terminal status, settles nothing and returns false — the caller may log
- * that, but must not treat it as an error: the local channel sees every job's
- * frames, precursor or not.
+ * Resolve or reject whichever tracker awaits `jobId`; true when one settled.
+ * False (an unawaited job, a non-terminal status) is not an error: the local
+ * channel sees every job's frames, precursor or not.
  */
 export declare function settlePendingPrecursor(trackers: PendingPrecursorTrackers, { jobId, state, data }: PrecursorJobStatus): boolean;
 export {};

package/dist/cache/source-cache.d.ts

@@ -1,57 +1,40 @@
 /**
- * Source-tarball cache layer wrapping CacheStorage.
- *
- * Stores customer-workflow source tarballs — the `.kici/` directory minus
- * `node_modules/`, packed by the agent's build job via `source-packer.ts` —
- * under the tarball's OWN content hash, with a small pointer resolving an org's
- * workflow `contentHash` to that hash. Tarballs are platform-independent: raw
- * TypeScript source is identical across architectures. Refreshes TTL on reads
- * (touch-on-read) so actively used sources stay in cache longer.
+ * Source-tarball cache over CacheStorage: the `.kici/` directory minus
+ * `node_modules/` (packed by the agent's build job via `source-packer.ts`),
+ * stored under the tarball's OWN content hash, with a pointer resolving an
+ * org's workflow `contentHash` to it. Tarballs are platform-independent (raw
+ * TypeScript source). Reads touch the TTL so active sources stay cached.
  *
  * Keys: `source/v2/{orgId}/{sourceTarDigest}.tar.gz` (immutable) and
- * `source/v2/{orgId}/{contentHash}.hash` (the pointer) — the shape `dep-cache.ts`
- * already uses, for the same reasons — content addressing and org scoping.
- *
- * **Content addressing** makes a mismatched pair unrepresentable. At
- * `source/{contentHash}.tar.gz` the object's key was derived from something
- * other than its bytes, so nothing a reader fetched could be verified against
- * anything, and the agent restored whatever the signed URL returned.
+ * `source/v2/{orgId}/{contentHash}.hash` (the pointer) — the `dep-cache.ts`
+ * shape, for the same reasons:
  *
- * **Org scoping** makes the key a tenant's key. `contentHash` alone is a
- * property of a `.kici/` tree, so two repositories scaffolded from the same
- * `kici init` template — or a fork and its upstream — produced one object, and
- * whichever built first won for the life of that object. On an orchestrator
- * serving more than one org that is a cross-tenant read of `.kici/` contents.
- * The org is the tenant boundary and the segment the user cache already scopes
- * by; inside one org, sharing a key now means the two trees are byte-identical,
- * so a monorepo or a same-org fork keeps its warm cache and pays nothing.
+ * - **Content addressing** makes a mismatched pair unrepresentable: a key not
+ *   derived from the bytes lets nothing a reader fetches be verified.
+ * - **Org scoping** makes the key a tenant's key. `contentHash` alone is a
+ *   property of a `.kici/` tree, so two repositories from the same `kici init`
+ *   template, or a fork and its upstream, would share one object — a
+ *   cross-tenant read on a multi-org orchestrator. The org is the tenant
+ *   boundary the user cache scopes by too; within one org a shared key means
+ *   byte-identical trees, so a monorepo or same-org fork keeps its warm cache.
  *
- * Legacy `source/{contentHash}.tar.gz` objects are **not read**. Only a
- * `compileSchemaVersion: 5` lock can name one, and that `contentHash` covers
- * the workflow entry file alone rather than the tree the tarball holds — the
- * defect this layout closes — so serving it would serve the bug. For a v6 lock
- * the fallback is unreachable anyway, since the schema bump moves every hash.
- * Old objects are orphaned. The cache TTL is enforced lazily on access, so
- * nothing here removes them.
+ * Retired `source/{contentHash}.tar.gz` objects are **not read**: only a
+ * `compileSchemaVersion: 5` lock names one, and its `contentHash` covers the
+ * entry file alone rather than the packed tree, so serving it would serve the
+ * bug. A v6 lock cannot reach it (the bump moves every hash). The lazy TTL never
+ * removes them (docs/operator/orchestrator/storage-layout.md § "Retired layouts").
  */
 import type { CacheStorage } from '../storage/types.js';
 /**
- * Cache key for a source tarball, addressed by the tarball's OWN content hash:
- * `source/v2/{orgId}/{sourceTarDigest}.tar.gz`.
- *
- * Naming the object by its own hash means every pair a reader can observe is
- * self-consistent, and the bytes at a given key can never change after a URL is
- * signed for it.
+ * Named by its own hash, so every pair a reader observes is self-consistent and
+ * the bytes at a key never change after a URL is signed for it.
  */
 export declare function sourceTarballKey(orgId: string, sourceTarDigest: string): string;
 /**
- * Cache key for the pointer that resolves a workflow `contentHash` to the
- * content hash of the tarball built from it: `source/v2/{orgId}/{contentHash}.hash`.
- *
- * This is the one mutable object in the scheme. A concurrent write replaces a
- * pointer wholesale — there is no half-written window — so the worst a racing
- * pair of builders can do is leave whichever pointer landed last, and both
- * tarballs stay valid and fetchable.
+ * The pointer from a workflow `contentHash` to its tarball's hash: the one
+ * mutable object. A write replaces it wholesale (no half-written window), so
+ * racing builders at worst leave the last-landed pointer, and both tarballs
+ * stay valid and fetchable.
  */
 export declare function sourcePointerKey(orgId: string, contentHash: string): string;
 export declare class SourceCache {
@@ -59,25 +42,18 @@ export declare class SourceCache {
     constructor(options: {
         storage: CacheStorage;
     });
-    /** The single place the pointer indirection is read. */
+    /** Resolves the pointer indirection (`getUrlAndDigest` reads it inline to touch it). */
     private resolvePointer;
     /**
-     * Whether a source tarball for this org's `contentHash` exists.
-     *
-     * Both halves must be present: a pointer whose tarball has aged out is a
-     * miss, not a hit, or the caller skips a rebuild and dispatches a URL that
-     * 404s on the agent.
+     * Both halves must exist: a pointer whose tarball aged out is a miss, or the
+     * caller skips a rebuild and dispatches a URL that 404s on the agent.
      */
     has(orgId: string, contentHash: string): Promise<boolean>;
     get(orgId: string, contentHash: string): Promise<Buffer | null>;
     /**
-     * A pre-signed download URL and the tarball's own digest.
-     *
-     * The pointer is resolved FIRST: it names the content hash, which is also the
-     * tarball's key, so the url and the digest returned here are read from a
-     * single source of truth and cannot disagree. Returns null on a miss —
-     * including a pointer with no tarball behind it, which is unverifiable and so
-     * is deliberately not served.
+     * A pre-signed download URL and the tarball's own digest. The pointer is
+     * resolved FIRST and names both, so url and digest cannot disagree. Null on a
+     * miss, including a pointer with no tarball (unverifiable, so not served).
      */
     getUrlAndDigest(orgId: string, contentHash: string): Promise<{
         url: string;
@@ -85,24 +61,19 @@ export declare class SourceCache {
     } | null>;
     getUrl(orgId: string, contentHash: string): Promise<string | null>;
     /**
-     * A pre-signed upload URL for direct agent-to-storage upload.
-     *
-     * Takes the tarball's OWN digest, not the workflow `contentHash`: the agent
-     * computes it before asking for a URL, and the object is named by it.
+     * A pre-signed agent-to-storage upload URL, keyed by the tarball's OWN digest
+     * (which the agent computes first), not the workflow `contentHash`.
      */
     getUploadUrl(orgId: string, sourceTarDigest: string): Promise<string>;
     /**
-     * Publish the pointer that makes an uploaded tarball discoverable by
-     * `contentHash`. Called only after the agent confirms its upload completed —
-     * publishing before the bytes land would let a reader follow the pointer to a
-     * missing object.
+     * Publish the pointer to an uploaded tarball. Called only after the agent
+     * confirms the upload, or a reader could follow it to a missing object.
      */
     publishPointer(orgId: string, contentHash: string, sourceTarDigest: string): Promise<void>;
     /** Store a tarball and the pointer that names it. */
     store(orgId: string, contentHash: string, tarball: Buffer | string): Promise<void>;
     /** SHA-256 of a tarball's bytes. The agent computes the same value. */
     static computeDigest(data: Buffer): string;
-    /** Remove a source tarball and its pointer. */
     remove(orgId: string, contentHash: string): Promise<boolean>;
 }
 //# sourceMappingURL=source-cache.d.ts.map

package/dist/cache/user-cache.d.ts

@@ -1,22 +1,21 @@
 import type { CacheRefScope } from '@kici-dev/engine';
 import type { CacheStorage } from '../storage/types.js';
 /**
- * Cluster-wide default quota: 5 GiB. Serves as the fallback when an org has no
- * per-org override in `org_settings.user_cache_quota_bytes`. The cluster-wide
- * value is itself operator-configurable via KICI_USER_CACHE_QUOTA_BYTES.
+ * Cluster-wide default quota: 5 GiB, used when an org has no
+ * `org_settings.user_cache_quota_bytes` override. Operator-configurable via
+ * KICI_USER_CACHE_QUOTA_BYTES.
  */
 export declare const DEFAULT_USER_CACHE_QUOTA_BYTES: number;
 /**
- * Cluster-wide default entry TTL: 7 days. Fallback when an org has no per-org
- * override in `org_settings.user_cache_ttl_ms`. The cluster-wide value is
- * operator-configurable via KICI_USER_CACHE_TTL_MS.
+ * Cluster-wide default entry TTL: 7 days, used when an org has no
+ * `org_settings.user_cache_ttl_ms` override. Operator-configurable via
+ * KICI_USER_CACHE_TTL_MS.
  */
 export declare const DEFAULT_USER_CACHE_TTL_MS: number;
 /**
- * Per-org override of the cache quota + TTL, read from `org_settings` at
- * operation time. A field left `undefined` means "no per-org override" — the
- * cluster-wide default applies. Injected into `UserCache` so the cache stays
- * decoupled from the DB layer (and unit-testable with a stub reader).
+ * Per-org quota + TTL override, read from `org_settings` at operation time; an
+ * `undefined` field means the cluster-wide default applies. Injected so the
+ * cache stays decoupled from the DB layer (and unit-testable with a stub).
  */
 export interface UserCacheOrgLimits {
     quotaBytes?: number;
@@ -47,11 +46,11 @@ export interface UserCacheBeginSaveResult {
 }
 export declare class UserCache {
     private readonly storage;
-    /** Cluster-wide default quota (the `KICI_USER_CACHE_QUOTA_BYTES` value). */
+    /** `KICI_USER_CACHE_QUOTA_BYTES`. */
     private readonly defaultQuotaBytes;
-    /** Cluster-wide default TTL (the `KICI_USER_CACHE_TTL_MS` value). */
+    /** `KICI_USER_CACHE_TTL_MS`. */
     private readonly defaultTtlMs;
-    /** Optional per-org override reader; absent = always use the cluster defaults. */
+    /** Absent = always use the cluster defaults. */
     private readonly orgLimitsReader?;
     constructor(opts: {
         storage: CacheStorage;
@@ -59,14 +58,13 @@ export declare class UserCache {
         quotaBytes?: number;
         /** Cluster-wide default TTL (env-var default). */
         ttlMs?: number;
-        /** Per-org override reader (org_settings). When unset, defaults apply. */
+        /** Per-org override reader (org_settings). */
         orgLimitsReader?: UserCacheOrgLimitsReader;
     });
     /**
-     * Resolve the effective quota + TTL for an org: the per-org override from
-     * `org_settings` when present, otherwise the cluster-wide default. A reader
-     * failure falls back to the defaults (logged) — the cache must never fail a
-     * restore/save because the settings lookup hiccupped.
+     * Per-org override when present, else the cluster default. A reader failure
+     * falls back to the defaults (logged): a settings-lookup hiccup must never
+     * fail a restore/save.
      */
     private resolveLimits;
     /** Restore: try the exact key across read prefixes, then restoreKeys prefix scan (newest wins). */
@@ -91,13 +89,11 @@ export declare class UserCache {
     }): Promise<void>;
     private readHash;
     /**
-     * Evict least-recently-used entries for the org until total tarball size <= the per-org quota.
-     *
-     * An in-flight `.tmp-` upload is never a candidate. A presigned PUT carries
-     * no metadata, so it would rank oldest and be reclaimed first — freeing
-     * nothing, since it has no `.size` — and the concurrent commit would then
-     * fail on its copy to the final key. Retired un-discriminated entries stay
-     * in the set: they hold accounted bytes and are evictable like any other.
+     * Evict the org's LRU entries until total tarball size <= the per-org quota.
+     * An in-flight `.tmp-` upload is never a candidate: with no metadata it would
+     * rank oldest and be reclaimed first, freeing nothing (no `.size`) and failing
+     * the concurrent commit's copy. Retired un-discriminated entries stay
+     * candidates: they hold accounted bytes.
      */
     private enforceQuota;
 }

package/dist/cancel/cancel-held-run.d.ts

@@ -1,14 +1,12 @@
 /**
  * Cancel a run that sits `held` behind an approval request.
  *
- * A held run has no job and no dispatch yet: what it has is a pending
- * `held_runs` row, the pending `KiCI Security` check a security hold posted,
- * and the stored dispatch context an approve would replay. Cancelling it has to
- * settle all three, or a later approve still finds its hold pending, replays
- * the stored dispatch, and closes the check as approved for a run that was
- * cancelled. So a cancel withdraws the approval request through the path a
- * reject takes: each pending hold of the run is flipped `rejected` with the
- * cancel reason, then handed to the workflow-hold rejection
+ * A held run has no job or dispatch yet, only a pending `held_runs` row, the
+ * pending `KiCI Security` check a security hold posted, and the stored dispatch
+ * context an approve would replay. A cancel must settle all three, or a later
+ * approve replays the dispatch and closes the check as approved for a
+ * cancelled run. So a cancel takes the reject path: each pending hold flips
+ * `rejected` with the cancel reason, then goes to the workflow-hold rejection
  * (`rejectWorkflow`), which cancels the run, completes the checks the held
  * dispatch posted, settles the security check, and drops the stored context.
  */
@@ -40,10 +38,10 @@ export interface RejectHeldWorkflowOptions {
 /** Options for {@link cancelHeldRunWithReason}. */
 export interface CancelHeldRunOptions {
     /**
-     * False when the caller ends the run itself — a cancel of a run that is not
-     * `held`, whose jobs are cancelled next. The holds are still rejected and
-     * the checks settled, but no held-run terminal write is attempted: it would
-     * match no row and only report a missing held run. Defaults to true.
+     * False when the caller ends the run itself (a non-`held` run whose jobs are
+     * cancelled next). Holds are still rejected and checks settled, but no
+     * held-run terminal write is attempted: it would match no row and only report
+     * a missing held run. Defaults to true.
      */
     terminalWrite?: boolean;
 }
@@ -59,10 +57,9 @@ export interface CancelHeldRunDeps {
 }
 /**
  * Withdraw every pending approval request of a held run and cancel the run.
- * Returns {@link HeldRunWithdrawal.Withdrawn} when this call withdrew the run.
- * Otherwise a decision reached every hold first — an approve, a reject or an
- * expiry, which the result names — the call writes nothing, and the caller
- * refuses the cancel.
+ * Returns {@link HeldRunWithdrawal.Withdrawn} when this call withdrew the run;
+ * otherwise a decision (named by the result) reached every hold first, the
+ * call writes nothing, and the caller refuses the cancel.
  */
 export declare function cancelHeldRunWithReason(deps: CancelHeldRunDeps, runId: string, reason: string, opts?: CancelHeldRunOptions): Promise<HeldRunWithdrawal>;
 //# sourceMappingURL=cancel-held-run.d.ts.map

package/dist/cancel/cancel-route-answer.d.ts

@@ -1,7 +1,6 @@
 /**
  * The admin cancel route's answer for a cancel that did not find the run
- * already terminal. Kept apart from the route so the mapping is testable
- * without assembling the whole app.
+ * terminal; apart from the route so it is testable without the whole app.
  */
 import { ExecutionRunStatus } from '@kici-dev/engine';
 import { type CancelRunResult } from './cancel-run.js';