@kici-dev/orchestrator 0.16.0 → 0.18.0

package/dist/audit/sampling-rate-limiter.d.ts

@@ -1,38 +1,26 @@
 /**
- * In-memory rate limiter shared by AccessLogWriter and AuditLogger to enforce
- * the per-action / per-actor caps defined in the engine's
- * `POLICY_BY_ACTION` table (one row per minute per actor for diagnostics-class
- * reads).
+ * In-memory rate limiter shared by AccessLogWriter and AuditLogger, enforcing
+ * the engine's `POLICY_BY_ACTION` per-action / per-actor caps (one row per
+ * minute per actor for diagnostics-class reads).
  *
- * Implementation: a single Map keyed by `${action}:${actorKey}` whose value
- * is the last permit timestamp. The token bucket is implicit — a permit is
- * granted iff `now - last >= floor(60_000 / perMinutePerActor)`. On each
- * permit() call we lazily prune entries older than 5 minutes so memory
- * stays bounded for long-lived orchestrators.
+ * One Map of `${action}:${actorKey}` → last permit timestamp; a permit is
+ * granted iff `now - last >= floor(60_000 / perMinutePerActor)`. permit()
+ * lazily prunes entries older than 5 minutes so memory stays bounded.
  *
- * Thread-safety: Node's single-threaded event loop guarantees the
- * read-then-write below is atomic per call. No locking needed.
+ * The single-threaded event loop makes each read-then-write atomic; no locking.
  */
 import type { AccessLogAction, AccessLogRateLimiter } from '@kici-dev/engine';
-/**
- * Implementation of `AccessLogRateLimiter` (engine interface). Constructed
- * once per orchestrator process and injected into both
- * `AccessLogWriter` and `AuditLogger`.
- */
+/** One per orchestrator process, injected into `AccessLogWriter` and `AuditLogger`. */
 export declare class SamplingRateLimiter implements AccessLogRateLimiter {
     private readonly buckets;
     private readonly now;
     private lastPruneAt;
-    /**
-     * @param now  Time source override (test seam). Defaults to `Date.now`.
-     */
+    /** @param now  Time source (test seam). */
     constructor(now?: () => number);
     permit(action: AccessLogAction, actorKey: string, perMinute: number): boolean;
     /**
-     * Drop entries older than PRUNE_TTL_MS. Called opportunistically from
-     * `permit()` so memory stays bounded without a background timer. With the
-     * 1-row/min/actor cap the map is naturally tiny (it grows by one entry
-     * per active actor and prunes after five minutes of silence).
+     * Called from `permit()`, so no background timer is needed. The map holds
+     * one entry per active actor, pruned after five minutes of silence.
      */
     private maybePrune;
     /** Test-only: introspect the bucket size. */

package/dist/cache/agent-job-failed-error.d.ts

@@ -1,9 +1,8 @@
 import type { InitFailure } from '@kici-dev/engine';
 /**
  * Reject reason for a pending init / dynamic-eval job the agent reported as
- * failed. Carries the optional structured initFailure the agent attached to
- * job.status.data so the orchestrator catch can record the correct category
- * instead of collapsing everything to a string.
+ * failed. Carries the agent's optional structured `job.status.data` initFailure
+ * so the catch records the correct category, not just a string.
  */
 export declare class AgentJobFailedError extends Error {
     readonly initFailure?: InitFailure | undefined;

package/dist/cache/build-coordinator.d.ts

@@ -1,13 +1,7 @@
 /**
- * Build coordinator for coalescing concurrent build requests.
- *
- * Ensures only one build runs per content hash. Subsequent requests
- * for the same hash coalesce on the same Promise, avoiding duplicate
- * compilation work.
- *
- * On success: all waiters resolve.
- * On failure: all waiters reject with the build error.
- * On timeout: all waiters reject with a timeout error.
+ * Coalesces concurrent build requests: one build per content hash, and later
+ * requests for the hash share its Promise. Every waiter resolves on success
+ * and rejects with the build error or the timeout error otherwise.
  */
 export declare class BuildCoordinator {
     private readonly inFlight;
@@ -15,28 +9,11 @@ export declare class BuildCoordinator {
     constructor(options?: {
         timeoutMs?: number;
     });
-    /**
-     * Ensure a build is running for the given content hash.
-     *
-     * If already in-flight, returns the existing promise (coalescing).
-     * If not, calls triggerBuild() and tracks the promise.
-     *
-     * @param contentHash - The content hash identifying the bundle to build
-     * @param triggerBuild - Async function that performs the actual build
-     */
+    /** Return the in-flight build for `contentHash`, or start one via triggerBuild. */
     ensureBuild(contentHash: string, triggerBuild: () => Promise<void>): Promise<void>;
-    /**
-     * Check if a build is currently in-flight for a content hash.
-     */
     isBuilding(contentHash: string): boolean;
-    /**
-     * Get the number of in-flight builds (for metrics/debugging).
-     */
+    /** For metrics / debugging. */
     getInFlightCount(): number;
-    /**
-     * Run triggerBuild with a timeout. Rejects with a descriptive
-     * error if the build exceeds timeoutMs.
-     */
     private runWithTimeout;
 }
 //# sourceMappingURL=build-coordinator.d.ts.map

package/dist/cache/cache-upload-settle.d.ts

@@ -1,16 +1,16 @@
 /**
- * Holding a build job's success until the cache publish its agent reported
- * just before it has finished.
+ * Holds a build job's success until the cache publish its agent reported just
+ * before it has finished.
  *
- * A build agent sends `cache.upload.complete` and then, moments later, the
- * build's terminal `job.status success`. The agent WebSocket handler runs
- * frames concurrently, so without this record the success can release the
- * jobs that wait on the build while the pointer naming the uploaded tarball is
- * still being written — and they dispatch without the cache URL.
+ * A build agent sends `cache.upload.complete`, then moments later the terminal
+ * `job.status success`. The agent WebSocket handler runs frames concurrently, so
+ * without this record the success can release the jobs waiting on the build while
+ * the pointer naming the uploaded tarball is still being written, and they
+ * dispatch without the cache URL.
  *
- * The upload frame registers here before its first `await`. Frames enter the
- * handler in wire order, so the registration is in place by the time the
- * success frame is handled. The success then waits, bounded by the org's
+ * The upload frame registers here before its first `await`; frames enter the
+ * handler in wire order, so the registration exists when the success frame is
+ * handled. The success then waits, bounded by the org's
  * `cache_upload_settle_timeout_ms` (cluster default
  * `KICI_CACHE_UPLOAD_SETTLE_TIMEOUT_MS`).
  */
@@ -37,7 +37,7 @@ export declare class InFlightCacheUploads {
     /** Register one publish for `jobId`; the returned function settles it (idempotent). */
     begin(jobId: string): () => void;
     has(jobId: string): boolean;
-    /** Number of jobs with a publish in flight. */
+    /** Jobs with a publish in flight. */
     get size(): number;
     /**
      * Wait for every publish registered for `jobId` at call time, bounded by

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

@@ -1,10 +1,7 @@
 /**
- * Dependency-specific cache layer wrapping CacheStorage.
- *
- * Stores dependency tarballs under their own content hash, with a small pointer
- * resolving lockfileHash + platform + arch to that hash. Shared CacheStorage
- * backend with SourceCache (same S3 bucket). Refreshes TTL on reads
- * (touch-on-read).
+ * Dependency cache over CacheStorage (the same S3 bucket as SourceCache).
+ * Tarballs live under their own content hash, with a small pointer resolving
+ * lockfileHash + platform + arch to it. Reads refresh TTL (touch-on-read).
  *
  * Keys: `deps/{platform}-{arch}/{depsHash}.tar.gz` (immutable) and
  * `deps/{platform}-{arch}/{lockfileHash}.hash` (the pointer).
@@ -12,17 +9,14 @@
 import type { CacheStorage } from '../storage/types.js';
 import type { ClusterSettingsReader } from '../cluster/cluster-settings-reader.js';
 /**
- * Cache key for a dependency tarball, addressed by the tarball's OWN content
- * hash: `deps/{platform}-{arch}/{depsHash}.tar.gz`.
+ * Cache key for a dependency tarball, addressed by its OWN content hash:
+ * `deps/{platform}-{arch}/{depsHash}.tar.gz`.
  *
- * Content-addressing is what makes a mismatched pair unrepresentable. When the
- * tarball lived at a lockfile-derived name, it and its companion `.hash` were
- * two independently-written objects under keys that any two builds sharing a
- * lockfile + platform + arch also share — so concurrent builders could leave the
- * `.tar.gz` from one and the `.hash` from the other, and the reader failed
- * verification durably. 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.
+ * Content-addressing makes a mismatched pair unrepresentable. Under a
+ * lockfile-derived name, concurrent builders sharing lockfile + platform + arch
+ * could leave one's `.tar.gz` and the other's `.hash`, and the reader failed
+ * verification durably. Named by its own hash, every observable pair is
+ * self-consistent and a key's bytes never change after a URL is signed for it.
  */
 export declare function depTarballKey(depsHash: string, platform: string, arch: string): string;
 /**
@@ -30,17 +24,14 @@ export declare function depTarballKey(depsHash: string, platform: string, arch:
  * tarball built from it: `deps/{platform}-{arch}/{lockfileHash}.hash`, or
  * `…/{lockfileHash}-{siblingsDigest}.hash` when the lock carries one.
  *
- * `siblingsDigest` is part of the key because the deps tarball carries in-repo
- * `workspace:` sibling directories WITH their built output, and editing a
- * sibling's source moves no package-manager lock file — so a `lockfileHash`-only
- * key restored the sibling's stale build over the fresh clone on every run. A
- * lock with no in-repo sibling carries no digest and keys exactly as before, so
- * existing pointers stay live.
+ * `siblingsDigest` is keyed because the tarball carries in-repo `workspace:`
+ * siblings WITH their built output, and editing a sibling moves no lock file —
+ * a `lockfileHash`-only key restored a stale sibling build over the fresh clone.
+ * A lock with no in-repo sibling carries no digest, so existing pointers stay live.
  *
- * This is the one mutable object in the scheme. A concurrent write replaces a
- * pointer wholesale — there is no window in which it is half-written — so the
- * worst a racing pair of builders can do is leave whichever pointer landed last,
- * and both tarballs remain valid and fetchable.
+ * The one mutable object in the scheme. A write replaces the pointer wholesale
+ * (never half-written), so racing builders at worst leave whichever landed
+ * last, and both tarballs stay valid and fetchable.
  */
 export declare function depPointerKey(lockfileHash: string, platform: string, arch: string, siblingsDigest?: string): string;
 export declare class DepCache {
@@ -57,59 +48,40 @@ export declare class DepCache {
         clusterSettings?: ClusterSettingsReader;
     });
     /**
-     * Resolve the live dependency-cache entry TTL as a per-operation override
-     * (ms) from `cluster_settings.cache_ttl_days`, falling back to the cluster
-     * default. `undefined` when no reader is wired, so the storage backend uses
-     * its own configured TTL. Passed to read/expiry operations so an operator's
-     * `cache_ttl_days` change takes effect on the next lookup.
+     * Per-operation TTL override (ms) from `cluster_settings.cache_ttl_days`, so
+     * an operator's change takes effect on the next lookup. `undefined` when no
+     * reader is wired, so the backend uses its own configured TTL.
      */
     private resolveTtlMsOverride;
-    /**
-     * Resolve a lockfile to the content hash of the tarball built from it, or
-     * null when no pointer exists. The single place the indirection is read.
-     */
+    /** Lockfile → tarball content hash, or null when no pointer exists. */
     private resolvePointer;
     /**
-     * Check if a dep tarball exists in cache.
-     *
-     * 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.
+     * Both halves must be present: a pointer whose tarball aged out is a miss, or
+     * the caller skips a rebuild and dispatches a URL that 404s.
      */
     has(lockfileHash: string, platform: string, arch: string, siblingsDigest?: string): Promise<boolean>;
-    /**
-     * Get a pre-signed download URL for the dep tarball (for agent delivery).
-     * Refreshes TTL on hit.
-     */
+    /** Pre-signed download URL for agent delivery. Refreshes TTL on hit. */
     getUrl(lockfileHash: string, platform: string, arch: string, siblingsDigest?: string): Promise<string | null>;
     /**
-     * Get a pre-signed download URL and the tarball content hash.
-     *
-     * Returns null on cache miss — including an entry with no pointer, which is
-     * unverifiable and so is deliberately not served.
+     * Pre-signed download URL plus tarball content hash; null on a miss,
+     * including an entry with no pointer (unverifiable, so never served).
      */
     getUrlAndHash(lockfileHash: string, platform: string, arch: string, siblingsDigest?: string): Promise<{
         url: string;
         hash?: string;
     } | null>;
-    /**
-     * Get a pre-signed upload URL for direct agent-to-S3 upload.
-     */
+    /** Pre-signed URL for direct agent-to-S3 upload. */
     getUploadUrl(depsHash: string, platform: string, arch: string): Promise<string>;
     /**
-     * Publish the pointer that makes an uploaded tarball discoverable by lockfile.
-     *
-     * 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.
+     * Make an uploaded tarball discoverable by lockfile. Called only after the
+     * agent confirms its upload, or a reader could follow the pointer to nothing.
      */
     publishPointer(lockfileHash: string, platform: string, arch: string, depsHash: string, siblingsDigest?: string): Promise<void>;
-    /**
-     * Store a dep tarball in cache.
-     * Throws if tarball exceeds max size (per user decision).
-     */
+    /** Throws when the tarball exceeds the max size. */
     store(lockfileHash: string, platform: string, arch: string, tarballData: Buffer): Promise<void>;
     /**
-     * Compute SHA-256 hash of a tarball buffer.
-     * Used by build agents to compute the hash for depsHash protocol field.
+     * Compute SHA-256 hash of a tarball buffer: the `depsHash` that `store()`
+     * keys and logs the tarball under.
      */
     static computeHash(data: Buffer): string;
     /** Remove a dep tarball and its pointer from cache. */

package/dist/cache/dispatch-cache-ref-tracker.d.ts

@@ -1,45 +1,37 @@
 /**
  * Server-side record of the user-cache namespacing for each dispatched job.
  *
- * The user-facing cache is namespaced by `{orgId, repoId, cacheRefScope, runId}`.
- * Those values are decided by the orchestrator at dispatch time (lifted onto the
- * `job.dispatch` message). The agent later sends `cache.user.*` requests that
- * carry ONLY a `jobId` + `key` — never the namespacing — so the WS handler must
- * resolve the namespace from a trusted server-side store keyed by jobId. This
- * tracker is that store: a wire `cache.user.*` message can name a `jobId`, but it
- * can never influence the org/repo/scope the orchestrator resolves for it.
+ * The orchestrator decides `{orgId, repoId, cacheRefScope, runId}` at dispatch
+ * time (lifted onto `job.dispatch`). The agent's `cache.user.*` requests carry
+ * ONLY `jobId` + `key`, so the WS handler resolves the namespace from this
+ * trusted store: a wire message can name a `jobId` but never influence the
+ * org/repo/scope resolved for it.
  *
- * The map is written when a job is dispatched, read on every `cache.user.*`
- * request, and deleted when the job completes or its agent disconnects (mirroring
- * the dispatcher's own per-job cleanup lifecycle) so it cannot leak.
+ * Written at dispatch, read on every `cache.user.*` request, deleted when the
+ * job completes or its agent disconnects (mirroring the dispatcher's per-job
+ * cleanup) so it cannot leak.
  */
 import type { CacheRefScope } from '@kici-dev/engine';
-/** Cache namespacing recorded for a dispatched job. */
 export interface DispatchCacheRef {
     /** Org that owns the run — the per-tenant cache isolation boundary. Absent for sourceless deploys. */
     orgId?: string;
-    /** Repo identifier (e.g. "owner/repo") — second namespacing level. Absent for sourceless deploys. */
+    /** E.g. "owner/repo" — second namespacing level. Absent for sourceless deploys. */
     repoId?: string;
-    /** Write scope: `shared` (trusted ref) or `isolated` (untrusted ref, per-run scope). */
+    /** `shared` (trusted ref) or `isolated` (untrusted ref, per-run scope). */
     cacheRefScope?: CacheRefScope;
-    /** Run id — the per-run isolation namespace for `isolated`-scope writes. */
+    /** The per-run isolation namespace for `isolated`-scope writes. */
     runId: string;
 }
-/**
- * In-memory `jobId -> DispatchCacheRef` map populated at dispatch time and
- * consumed by the agent WS handler to resolve a `UserCacheRef` server-side.
- */
 export declare class DispatchCacheRefTracker {
     private readonly refs;
-    /** Record the cache namespacing for a dispatched job. */
     record(jobId: string, ref: DispatchCacheRef): void;
-    /** Resolve the cache namespacing for a job, or `undefined` if it was never dispatched / already cleaned up. */
+    /** `undefined` if the job was never dispatched or is already cleaned up. */
     get(jobId: string): DispatchCacheRef | undefined;
-    /** Drop a job's recorded ref (on completion or agent disconnect). */
+    /** On completion or agent disconnect. */
     delete(jobId: string): void;
-    /** Drop every recorded ref (test/teardown helper). */
+    /** Test/teardown helper. */
     clear(): void;
-    /** Number of currently-tracked dispatches (leak assertions in tests). */
+    /** For leak assertions in tests. */
     get size(): number;
 }
 //# sourceMappingURL=dispatch-cache-ref-tracker.d.ts.map

package/dist/cache/global-eval-round-cache.d.ts

@@ -3,47 +3,41 @@
  *
  * **This cache only helps webhook redelivery and same-input re-deliveries.** Its
  * key pins the source commit and a digest of the whole round input, and every
- * real push carries a new source SHA — so a developer pushing twice gets two
- * rounds, by design. Read it as a duplicate-delivery guard, never as a
- * steady-state optimization: sizing it up buys nothing, and a hit rate near zero
- * on a healthy cluster is the expected shape, not a defect.
+ * real push carries a new source SHA, so two pushes get two rounds by design. It
+ * is a duplicate-delivery guard, not a steady-state optimization: sizing it up
+ * buys nothing, and a hit rate near zero on a healthy cluster is expected.
  *
- * There is deliberately no TTL. A round verdict is a pure function of its
- * inputs, and {@link globalEvalRoundCacheKey} covers all of them, so an entry
- * cannot go stale within its own key — the same content-addressable argument the
- * lock-file and content caches make for their SHA-keyed entries, without their
- * branch-name escape hatch.
+ * Deliberately no TTL: a round verdict is a pure function of its inputs, and
+ * {@link globalEvalRoundCacheKey} covers all of them, so an entry cannot go stale
+ * within its key — the content-addressable argument of the lock-file and content
+ * caches, without their branch-name escape hatch.
  */
 import type { GlobalEvalRoundResult } from '@kici-dev/engine';
 /**
  * Key one round over **every input its verdict depends on**.
  *
- * The three SHAs are not enough, and the gap is a wrong-answer bug rather than a
- * missed-hit one. `createFilterContext` and `buildGeneratorContext` both receive
- * the whole event, so a filter can branch on `event.type`, `targetBranch`,
- * `changedFiles`, or anything in the raw payload. A push to `main` at commit X
- * and a pull-request synchronize whose head is commit X share all three SHAs and
- * genuinely deserve different verdicts: their events differ, and their
- * changed-file sets are computed over different ranges. Two branches pointing at
- * one commit collide the same way. `workflowRoutingKey` is in the key for the
- * reason `groupCandidates` keeps it in the group key — it selects the provider
+ * The SHAs alone would give wrong answers, not just missed hits.
+ * `createFilterContext` and `buildGeneratorContext` both receive the whole event,
+ * so a filter can branch on `event.type`, `targetBranch`, `changedFiles`, or
+ * anything in the raw payload. A push to `main` at commit X and a pull-request
+ * synchronize whose head is X share every SHA yet deserve different verdicts
+ * (different events, changed files computed over different ranges); two branches
+ * at one commit collide the same way. `workflowRoutingKey` is in the key for the
+ * reason `groupCandidates` keeps it in the group key: it selects the provider
  * bundle that mints the clone credentials.
  *
- * `sourceRepoIdentifier` is its own component, placed next to `sourceSha` so the
- * source repo and its commit stay adjacent. Every event already carries its
- * source repo, so the event digest covers it too — but keying it explicitly
- * makes that coverage structural rather than incidental: an event shape that
+ * `sourceRepoIdentifier` sits next to `sourceSha`. The event digest covers it
+ * too, but keying it explicitly makes that structural: an event shape that
  * stopped carrying the source repo could otherwise collide two repos' rounds.
  *
- * The candidate list and the event are folded in as a SHA-256 digest of their
- * JSON, so the key stays a bounded string no matter how large a payload is. Both
- * are rebuilt by the same code from the same delivery, so a genuine redelivery
- * reproduces the digest; anything else is a miss, which costs a round rather
- * than a wrong verdict.
+ * The candidate list and the event enter as a SHA-256 digest of their JSON, so
+ * the key stays bounded. The same code rebuilds both from the same delivery, so a
+ * genuine redelivery reproduces the digest; anything else is a miss, which costs
+ * a round rather than a wrong verdict.
  *
- * Returns `null` when the inputs cannot be serialized. A round that cannot be
- * keyed is not cached — never keyed on a partial input, which is how a
- * cache starts answering questions it was not asked.
+ * Returns `null` when the inputs cannot be serialized: a round is never keyed on
+ * a partial input, which is how a cache starts answering questions it was not
+ * asked.
  */
 export declare function globalEvalRoundCacheKey(args: {
     workflowRepoIdentifier: string;
@@ -62,18 +56,16 @@ export declare function globalEvalRoundCacheKey(args: {
  * An agent-side budget breach reports `success` with the affected candidates
  * marked indeterminate — the whole round on a round-budget breach, one workflow
  * on a candidate-budget breach. Caching either turns one slow round into a
- * permanently replayed failure for the whole key: a webhook redelivery, which
- * is exactly when an operator is retrying, would be served the stored failure
- * instead of running again, and the round's own retry sits behind this cache
- * read so a stored breach short-circuits that too.
+ * permanently replayed failure for the key: a webhook redelivery (exactly when an
+ * operator retries) would be served the stored failure, and the round's own retry
+ * sits behind this cache read, so it short-circuits too.
  *
- * Requiring EVERY candidate to be decided costs almost no hit rate — an
- * indeterminate verdict is the exceptional path — and buys a guarantee that is
- * easy to state: nothing a redelivery replays was ever undecided.
+ * Requiring EVERY candidate decided costs almost no hit rate (indeterminate is the
+ * exceptional path) and guarantees nothing a redelivery replays was undecided.
  *
- * An empty candidate list is not cacheable either. For a non-empty group it
- * means every candidate is about to be recorded as "no verdict", which is the
- * same failure by another route.
+ * An empty candidate list is not cacheable either: for a non-empty group every
+ * candidate is about to be recorded as "no verdict", the same failure by another
+ * route.
  */
 export declare function isCacheableRoundResult(result: GlobalEvalRoundResult): boolean;
 export declare class GlobalEvalRoundCache {
@@ -85,7 +77,7 @@ export declare class GlobalEvalRoundCache {
     });
     get(key: string): GlobalEvalRoundResult | undefined;
     set(key: string, value: GlobalEvalRoundResult): void;
-    /** Hit/miss counters for metrics and debugging. */
+    /** For metrics and debugging. */
     stats(): {
         hits: number;
         misses: number;

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

@@ -1,10 +1,6 @@
 /**
- * Pending build tracker for coordinating build-then-execute pipeline.
- *
- * The orchestrator dispatches a build job and waits for the build agent to
- * finish before retrieving cache URLs and dispatching execution jobs. The
- * underlying tracker logic lives in `PendingTracker<void>`; this subclass
- * just wires the build-specific logger prefix and disconnect error.
+ * Awaits a build job in the build-then-execute pipeline, before cache URLs are
+ * retrieved and execution jobs dispatched.
  */
 import { PendingTracker } from './pending-tracker.js';
 export declare class PendingBuildTracker extends PendingTracker<void> {

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

@@ -1,11 +1,6 @@
 /**
- * Pending dynamic-eval tracker for coordinating DynamicJobFn evaluation pipeline.
- *
- * The orchestrator dispatches a dynamic eval job for runtime job generation and
- * waits for the agent to evaluate the DynamicJobFn and return the generated
- * `LockJob[]` array. The underlying tracker logic lives in
- * `PendingTracker<LockJob[]>`; this subclass wires the dynamic-eval-specific
- * logger prefix and disconnect error.
+ * Awaits the `LockJob[]` an agent returns after evaluating a DynamicJobFn
+ * (runtime job generation). Logic lives in `PendingTracker`.
  */
 import type { LockJob } from '@kici-dev/engine';
 import { PendingTracker } from './pending-tracker.js';

package/dist/cache/pending-global-evals.d.ts

@@ -1,14 +1,12 @@
 /**
  * Pending tracker for the Tier-2 global eval round.
  *
- * The orchestrator dispatches one round job per (event × workflow repo) and
- * waits for the agent to return a verdict per candidate workflow. The
- * underlying tracker logic lives in `PendingTracker<GlobalEvalRoundResult>`;
- * this subclass wires the round-specific logger prefix and disconnect error.
+ * One round job per (event × workflow repo) returns a verdict per candidate
+ * workflow.
  *
  * Unlike the dynamic-eval and init trackers, this round runs BEFORE any run row
- * exists: its whole purpose is to decide which global workflows produce a run at
- * all, so creating one up-front would defeat it.
+ * exists: its purpose is to decide which global workflows produce a run at all,
+ * so creating one up-front would defeat it.
  */
 import { type GlobalEvalRoundResult } from '@kici-dev/engine';
 import { PendingTracker } from './pending-tracker.js';
@@ -17,12 +15,11 @@ import { PendingTracker } from './pending-tracker.js';
  * the tracker.
  *
  * **This is the one place the round's wire payload is validated.** The status
- * message's `data` field is `z.record(z.string(), z.unknown())`, so nothing
- * upstream checks `globalEvalResult` against its schema — a cast at the message
- * handler would be a type assertion over an arbitrary agent-supplied value, and
- * any agent that owns the round job can send one. Parsing here keeps the
- * "typed but unvalidated" boundary at a single named function instead of spread
- * across every consumer.
+ * message's `data` is `z.record(z.string(), z.unknown())`, so nothing upstream
+ * checks `globalEvalResult` against its schema, and any agent that owns the round
+ * job can send an arbitrary value — a cast at the message handler would be an
+ * unchecked type assertion. Parsing here keeps the "typed but unvalidated"
+ * boundary at one named function instead of every consumer.
  *
  * The parsed value is widened back to {@link GlobalEvalRoundResult}: the schema
  * is deliberately loose about `jobs` (the lock-job shape has no Zod mirror), and

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

@@ -1,11 +1,6 @@
 /**
- * Pending init tracker for coordinating init-then-execute pipeline.
- *
- * The orchestrator dispatches an init job for dynamic context resolution
- * and waits for the agent to return the resolved field values
- * (contextNames, env, concurrencyGroup). The underlying tracker logic lives
- * in `PendingTracker<InitResult>`; this subclass wires the init-specific
- * logger prefix and disconnect error.
+ * Awaits an init job (dynamic context resolution) in the init-then-execute
+ * pipeline until the agent returns the resolved field values.
  */
 import { PendingTracker } from './pending-tracker.js';
 export interface InitResult {
@@ -14,27 +9,21 @@ export interface InitResult {
     env?: Record<string, string>;
     concurrencyGroup?: string;
     /**
-     * Resolved matrix combinations when the target job's matrix is a dynamic
-     * function. The dispatch path re-materializes these into N execution jobs.
+     * Matrix combinations of a dynamic-function matrix, which dispatch
+     * re-materializes into N execution jobs.
      */
     matrixValues?: Array<Record<string, string | undefined>>;
     /**
-     * Verdict of the workflow-level `filter`, reported only when the init job was
-     * asked to evaluate one. `false` means the workflow does not apply to this
-     * event and its job must not be dispatched.
-     *
-     * Optional on purpose: an agent that predates the filter never sends it, so
-     * absence means "no verdict was reported" and dispatch proceeds — only an
-     * explicit `false` suppresses.
+     * The workflow-level `filter` verdict, when asked; `false` suppresses the
+     * job. Optional because an agent predating the filter never sends it: absence
+     * means "no verdict" and dispatch proceeds — only an explicit `false`
+     * suppresses.
      */
     filterPassed?: boolean;
     /**
-     * Verdict on the workflow's deferred `paths`, reported only when the init job
-     * was asked to decide them. `false` means the agent's clone diff matched none
-     * of them and the job must not be dispatched.
-     *
-     * Optional on purpose: an agent that predates deferred paths never sends it,
-     * so absence means "no verdict" and dispatch proceeds.
+     * The deferred `paths` verdict, when asked; `false` (the clone diff matched
+     * none) suppresses the job. Optional because an agent predating deferred
+     * paths never sends it: absence means "no verdict" and dispatch proceeds.
      */
     pathsPassed?: boolean;
 }