@kici-dev/orchestrator 0.17.0 → 0.19.0

package/dist/metrics/agent-metrics-aggregator.d.ts

@@ -1,34 +1,21 @@
 /**
- * In-memory aggregator for agent-pushed metrics.
- *
- * Agents push their OTel metrics snapshots via the WS `agent.metrics` message.
- * This aggregator stores the latest snapshot per agent and produces a
- * cardinality-bounded view by **collapsing all agents within the same
- * scaler pool into one series per (metric, labels, scaler)**. The
- * `agent_id` label is intentionally NOT emitted — including it would
- * make Mimir cardinality grow with the number of agents that have ever
- * existed (every ephemeral firecracker microVM minted a fresh ID), which
- * is unbounded. The caller-side dashboard filters by `scaler` instead,
- * which has a fixed enum of values (`stateful`, plus every
- * `ScalerBackendType`).
+ * In-memory aggregator for the OTel snapshots agents push via the WS `agent.metrics` message.
+ * Keeps the latest snapshot per agent and **collapses each scaler pool into one series per
+ * (metric, labels, scaler)**. `agent_id` is NOT emitted: every ephemeral firecracker microVM
+ * mints a fresh ID, so Mimir cardinality would grow without bound. Dashboards filter by
+ * `scaler` instead, a fixed enum (`stateful` plus every `ScalerBackendType`).
  *
  * Aggregation rules per metric kind:
  *   - counter / upDownCounter / gauge → SUM across agents in the pool
  *   - histogram → bucket-by-bucket SUM, plus summed `_count` / `_sum`
  *
- * Trade-off: counter rates are approximate during agent churn. If
- * agent A reports `100` at t1 and disconnects, then agent B starts
- * fresh at `0` for t2, the combined series steps 100 → 0 — which
- * Prometheus interprets as a reset and `rate()` handles correctly.
- * Over a longer window though (e.g. a day with many ephemeral agents
- * appearing + disappearing), the integrated count can under-count.
- * The orchestrator-side counters (`kici_orch_*`) are the canonical
- * source for absolute totals; the agent counters here are for live
- * "what's happening right now" panels.
+ * Trade-off: counter rates are approximate during agent churn. A series stepping 100 → 0
+ * when one agent leaves and a fresh one starts is a reset `rate()` handles, but over a long
+ * window with many ephemeral agents the integrated count can under-count. `kici_orch_*`
+ * counters are the canonical absolute totals; these feed live "right now" panels.
  *
- * Cleanup: after an agent disconnects, its snapshot is retained for one
- * configurable retention period (default 30s, ~2x scrape interval) so
- * Prometheus can scrape it at least once before it disappears.
+ * A disconnected agent's snapshot is kept for one retention period (default 30s, ~2x scrape
+ * interval) so Prometheus scrapes it at least once.
  */
 /** Shape of a single metric data point pushed by the agent. */
 export interface MetricSnapshot {
@@ -47,68 +34,38 @@ export declare class AgentMetricsAggregator {
     private store;
     private defaultRetentionMs;
     /**
-     * Optional lookup: agentId → scaler backend type (e.g. `container`,
-     * `firecracker`, `bare-metal`). Returning null marks the agent as
-     * static / stateful — we then stamp the `scaler` label as `'stateful'`.
-     * Wired from ScalerManager.getBackendType in production. Tests can
-     * leave it undefined; in that case the `scaler` label is omitted.
+     * agentId → scaler backend type (e.g. `container`, `firecracker`, `bare-metal`); null
+     * stamps `scaler="stateful"`. Wired from ScalerManager.getBackendType; when undefined
+     * (tests), the `scaler` label is omitted.
      */
     private readonly getScalerForAgent?;
     constructor(opts?: {
         retentionMs?: number;
         getScalerForAgent?: (agentId: string) => string | null;
     });
-    /**
-     * Resolve the `scaler` label for one agentId. Centralized so both the
-     * structured snapshot (Mimir push) and the Prometheus text
-     * exporter (HTTP /metrics) stamp identical values.
-     */
+    /** Shared so the Mimir push and the HTTP /metrics exporter stamp identical values. */
     private resolveScalerLabel;
-    /** Store or replace metrics for an agent. */
     update(agentId: string, metrics: MetricSnapshot[]): void;
-    /** Mark an agent as disconnected (start the retention countdown). */
+    /** Starts the retention countdown. */
     markDisconnected(agentId: string): void;
     /** Remove entries where disconnectedAt + retentionMs < now. */
     cleanup(retentionMs?: number): void;
-    /**
-     * Build a stable string key for grouping metrics across agents. The
-     * key encodes the metric name plus every label except `agent_id`
-     * (which is dropped) and including the resolved `scaler`. Sorted so
-     * insertion order can't sneak into the key.
-     */
+    /** Grouping key: the name plus every label except `agent_id`, sorted so order is irrelevant. */
     private groupKey;
     /**
-     * Walk every stored snapshot and bucket points into per-(metric, labels)
-     * groups, summing counter / gauge values and merging histogram buckets
-     * across all agents in each bucket. The bucketing key includes the
-     * `scaler` label and excludes `agent_id`, so the output is one series
-     * per (metric, labels-except-agent_id, scaler) combination.
-     *
-     * Returns one MetricSnapshot per group so both `getStructuredSnapshot`
-     * and `getPrometheusText` can iterate the same shape.
+     * One summed MetricSnapshot per (metric, labels-except-agent_id, scaler), the shape both
+     * `getStructuredSnapshot` and `getPrometheusText` iterate.
      */
     private aggregateAcrossAgents;
     /**
-     * Produce a structured snapshot of all stored agent metrics in the
-     * `OrchMetrics['metrics']` wire shape — same format the orchestrator's
-     * own `MetricsReporter` produces from its OTel exporter. Used by the
-     * Platform-bound Mimir push pipeline so agent metrics land in Mimir
-     * per-org alongside `kici_orch_*` .
-     *
-     * Output is **already aggregated across agents per scaler** — see the
-     * class docstring for the cardinality rationale and counter trade-off.
-     *
-     * Runs `cleanup()` first so disconnected agents past their retention
-     * window stop being emitted.
+     * Agent metrics in the `OrchMetrics['metrics']` wire shape (as `MetricsReporter` produces),
+     * for the Platform-bound Mimir push, so they land per-org alongside `kici_orch_*`. Already
+     * aggregated per scaler (see the class docstring). Runs `cleanup()` first.
      */
     getStructuredSnapshot(): MetricSnapshot[];
     /**
-     * Produce Prometheus exposition text for all stored agent metrics,
-     * aggregated across agents per scaler. See `getStructuredSnapshot` for
-     * the aggregation rules. Runs auto-cleanup before generating output.
-     *
-     * Groups metrics by name and emits `# TYPE` directives so Prometheus
-     * correctly interprets histograms, counters, and gauges.
+     * Prometheus exposition text, aggregated per scaler, with one `# TYPE` directive per name.
+     * Runs `cleanup()` first.
      */
     getPrometheusText(): string;
     private formatHistogram;

package/dist/metrics/metrics-reporter.d.ts

@@ -1,9 +1,6 @@
 /**
- * Periodic metrics reporter that collects OTel metrics and pushes them
- * to the Platform via WebSocket as `orch.metrics` messages.
- *
- * The Platform aggregates these metrics from all orchestrators and exposes
- * them on its `/metrics` endpoint for Prometheus scraping.
+ * Pushes OTel metrics to the Platform over WebSocket as `orch.metrics` messages; the Platform
+ * aggregates all orchestrators and exposes them on `/metrics` for Prometheus.
  */
 import type { OrchMetrics } from '@kici-dev/engine';
 import type { AgentMetricsAggregator } from './agent-metrics-aggregator.js';
@@ -19,22 +16,16 @@ export declare class MetricsReporter {
          * If provided, the reporter concatenates the aggregator's structured
          * snapshot onto its own snapshot before sending — so agent metrics
          * (`kici_agent_*`) land in Mimir per-org alongside `kici_orch_*`.
-         * Each agent metric carries an `agent_id` label injected by the
-         * aggregator. See the metrics enforcement plan.
+         * The aggregator sums each agent metric across agents and drops the
+         * `agent_id` label.
          */
         agentMetricsAggregator?: AgentMetricsAggregator;
     });
-    /** Start periodic metric collection and push. */
     start(): void;
-    /** Stop the periodic reporter. */
     stop(): void;
-    /** Collect current metrics and send as orch.metrics message. */
     collectAndSend(): Promise<void>;
-    /** Collect a snapshot of all current OTel metrics. */
     collectSnapshot(): Promise<OrchMetrics['metrics']>;
-    /** Map OTel DataPointType to wire format type string. */
     private mapDataPointType;
-    /** Extract string labels from OTel Attributes. */
     private extractLabels;
 }
 //# sourceMappingURL=metrics-reporter.d.ts.map

package/dist/metrics/prometheus.d.ts

@@ -59,12 +59,10 @@ interface ScalerUsageRow {
     memBytes: number;
 }
 /**
- * Replace the current scaler-usage breakdown.
- *
- * Called by ScalerManager whenever a reservation lands or releases. Caller is
- * responsible for including a `scaler="__global__"` row for the orchestrator-wide
- * total and one row per active machine pool (with `machinePool` set) reflecting
- * the on-disk ledger snapshot. Per-scaler rows omit `machinePool`.
+ * Called by ScalerManager whenever a reservation lands or releases. The caller
+ * includes a `scaler="__global__"` orchestrator-wide row and one row per active
+ * machine pool (`machinePool` set) from the on-disk ledger snapshot. Per-scaler
+ * rows omit `machinePool`.
  */
 export declare function setScalerUsageBreakdown(rows: ScalerUsageRow[]): void;
 interface WarmPoolGaugeRow {
@@ -77,8 +75,6 @@ interface WarmPoolGaugeRow {
     inFlight: number;
 }
 /**
- * Replace the current warm-pool fill state.
- *
  * Called by ScalerManager after each warm-pool tick and after a config reload,
  * so the gauges follow the pool rather than the scrape.
  */
@@ -161,19 +157,13 @@ export declare function setScalerReapBlocked(blocked: boolean): void;
 /**
  * Merge current per-label counts with explicit `0`s for previously-seen labels
  * whose queue has drained. Mutates `everSeen` to include the current labels.
- *
- * Exported for direct unit testing of the sticky-zero invariant: a label that
- * appears in one snapshot and is absent from the next must report `0` rather
- * than vanish, otherwise the by-label gauge series freezes at its last value.
+ * Exported to unit-test the sticky-zero invariant: a label absent from the next
+ * snapshot must report `0`, or its series freezes at its last value.
  */
 export declare function applyStickyQueueLabels(everSeen: Set<string>, byLabel: Record<string, number>): Record<string, number>;
 /**
- * Update the dispatch-queue depth breakdown used by the Prometheus gauges.
- *
- * Called by the orchestrator's periodic depth refresher after polling the
- * JobQueue. Normalizes the input so the gauge callback can emit explicit
- * zero series for known statuses even when the queue is empty, and keeps
- * emitting `0` for any per-label series whose queue has drained.
+ * Called by the periodic depth refresher after polling the JobQueue. Missing
+ * statuses normalize to `0`, and drained labels keep emitting `0`.
  */
 export declare function setDispatchQueueDepthBreakdown(snapshot: {
     byStatus: Partial<Record<'pending' | 'dispatched', number>>;
@@ -229,14 +219,10 @@ export declare const ingestOverflowReplayedTotal: import("@opentelemetry/api").C
 /** Buffered deliveries permanently dropped. Labels: reason (cap_full|max_attempts|max_age). */
 export declare const ingestOverflowDroppedTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
 /**
- * Replay reservations the admission controller refused. This is the drain's own
- * backpressure signal, kept off `kici_orch_ingest_shed_total` because that one
- * means "a sender was refused" and a background drain deciding not to start is
- * not that.
- *
- * It is also the evidence that the gate can still stop the replayer: a drain
- * that converges proves the mechanism works, while a non-zero count here during
- * that drain proves the reservation is refusable rather than an exempt lane.
+ * Replay reservations the admission controller refused: the drain's own
+ * backpressure signal, kept off `kici_orch_ingest_shed_total`, which means "a
+ * sender was refused". A non-zero count during a converging drain proves the
+ * reservation is refusable rather than an exempt lane.
  *
  * Labels: reason (loop_overload|queue_full).
  */
@@ -337,8 +323,7 @@ export declare const depCacheHitsTotal: import("@opentelemetry/api").Counter<imp
  */
 export declare const depCacheMissesTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
 /**
- * Duration of build agent operations in seconds.
- * Tracks how long it takes to compile a workflow bundle via a build agent.
+ * Duration of compiling a workflow bundle via a build agent.
  * Buckets: 1s to 10min covering fast to slow compilations.
  */
 export declare const buildDurationSeconds: import("@opentelemetry/api").Histogram<import("@opentelemetry/api").Attributes>;
@@ -418,11 +403,9 @@ export declare const staleRunsDetectedTotal: import("@opentelemetry/api").Counte
 export declare const staleDetectionDurationSeconds: import("@opentelemetry/api").Histogram<import("@opentelemetry/api").Attributes>;
 /**
  * Number of webhook-trigger registrations matched when an inbound generic
- * webhook fans out across sources in the same org.
- *
- * Recorded once per inbound webhook on the cross-source dispatch path
- * (including zero-match cases). The label carries the inbound event name
- * (NOT the literal 'generic_webhook').
+ * webhook fans out across sources in the same org. Recorded once per inbound
+ * webhook on the cross-source path, zero matches included; the label carries the
+ * inbound event name (NOT the literal 'generic_webhook').
  *
  * Buckets cover small fan-outs (1-2 typical) through large org-wide fan-outs.
  *
@@ -442,12 +425,10 @@ export declare const crossSourceFanoutSize: import("@opentelemetry/api").Histogr
  */
 export declare const crossSourceErrorsTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
 /**
- * Counter for universal-git source registration errors at orchestrator
- * startup or config reload. A non-zero rate indicates at least one
- * `generic_webhook_sources` row with a non-null `git_config` could not be
- * promoted to a provider bundle — the row stays in the DB but its routing
- * key has no bundle, so webhooks for it will fall through to the generic
- * bundle's payload-only path.
+ * Universal-git source registration errors at startup or config reload: a
+ * `generic_webhook_sources` row with a non-null `git_config` could not become a
+ * provider bundle, so its webhooks fall through to the generic bundle's
+ * payload-only path.
  *
  * Labels:
  * - reason: 'invalid_config' (Zod parse failed) | 'bundle_build' (factory
@@ -470,11 +451,9 @@ export declare const trustMatchRefusedNoIdTotal: import("@opentelemetry/api").Co
  * Candidates handed to a global eval round.
  *
  * Equal to `sum(kici_orch_global_eval_verdicts_total)` by construction: every
- * candidate receives exactly one verdict, including on the fail-closed path
- * where the round never runs. Kept as its own series because it is the natural
- * top-line rate and the denominator the outcome breakdown divides — a
- * divergence between the two would be a bug in the round, never a condition an
- * operator should watch for.
+ * candidate gets exactly one verdict, even on the fail-closed path where the
+ * round never runs. Kept as the top-line rate and the outcome denominator; a
+ * divergence is a bug in the round, not a condition for operators to watch.
  */
 export declare const globalEvalCandidatesTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
 /**
@@ -505,14 +484,12 @@ export declare const globalEvalJobsGenerated: import("@opentelemetry/api").Histo
 /**
  * Global eval round cache lookups by outcome.
  *
- * Three outcomes, not two. An input that cannot be serialized yields no cache
- * key at all, so it never reaches the cache and registers neither a hit nor a
- * miss — counting only hits and misses would drop those lookups from the
- * denominator and make the hit rate read higher than it is.
+ * An unserializable input yields no cache key, so it is neither a hit nor a
+ * miss; counting only those would inflate the hit rate.
  *
  * Expect a hit rate near zero on a healthy cluster: the key covers the whole
- * event, so every real push is a miss by construction. This cache is a
- * redelivery guard, not a steady-state optimization.
+ * event, so every real push misses. This cache is a redelivery guard, not a
+ * steady-state optimization.
  *
  * Labels:
  * - result: hit | miss | unkeyable (the round input could not be serialized)
@@ -544,12 +521,10 @@ export declare function incEventUnmatched(eventName: string, reason: string): vo
 /**
  * Startup catch-up scans that threw. Emits no labels.
  *
- * The scan recovers the internal-event backlog a restart left behind, and it
- * runs behind a boot latch that the composition root resolves after startup
- * continues — so a failure cannot fail the bootstrap and is otherwise invisible
- * until the backlog quietly ages into the DLQ. This counter is what an alert
- * fires on; the accompanying `Deferred catch-up scan failed` log line carries
- * the reason.
+ * The scan recovers the internal-event backlog a restart left behind, behind a
+ * boot latch resolved after startup continues, so a failure cannot fail the
+ * bootstrap and is otherwise invisible until the backlog ages into the DLQ.
+ * Alert on this; the `Deferred catch-up scan failed` log line carries the reason.
  */
 export declare const eventCatchUpFailuresTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
 /**
@@ -567,9 +542,8 @@ export declare const eventAttemptsHistogram: import("@opentelemetry/api").Histog
 /** Set the current DLQ depth gauge. Refreshed by the leader-only retry scanner each tick. */
 export declare function setEventDlqDepth(value: number): void;
 /**
- * Reason values for the `kici_orch_install_secrets_decisions_total` counter.
- * The single source of truth — the resolver and tests both reference these
- * constants, so adding a new reject path requires extending the union here.
+ * Reason values for `kici_orch_install_secrets_decisions_total`, the single
+ * source of truth for the resolver and tests: a new reject path extends it here.
  */
 export declare const InstallSecretsDecisionReason: {
     readonly Ok: 'ok';
@@ -602,16 +576,14 @@ export type InstallSecretsChannel = (typeof InstallSecretsChannel)[keyof typeof
  * - decision: pass | reject | hold
  * - reason: ok (only with `pass`), held (only with `hold`), or one of the reject reasons enumerated in `InstallSecretsDecisionReason`
  *
- * Pass series are emitted exactly once per resolver call that does any work
- * (workflows declaring neither `registries:` nor `installEnv:` are NOT
- * counted — that's the trivial early-return path and dashboard rates would
- * be dominated by it).
+ * Pass series are emitted once per resolver call that does work: workflows
+ * declaring neither `registries:` nor `installEnv:` take the trivial
+ * early-return path and are NOT counted, or they would dominate dashboard rates.
  */
 export declare const installSecretsDecisionsTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
 /**
- * Total registry / installEnv entries that successfully resolved on a
- * passing dispatch. Each entry contributes one increment, so a workflow
- * with two `registries:` rows and one `installEnv:` entry adds three.
+ * Registry / installEnv entries resolved on a passing dispatch, one increment
+ * per entry.
  *
  * Labels:
  * - channel: registries (Option A workflow block) | install_env (Option C committed .npmrc + installEnv:)
@@ -622,9 +594,8 @@ export declare const installSecretsRegistryUsedTotal: import("@opentelemetry/api
 /**
  * Total dispatches where the orchestrator stripped registry tokens because
  * the resolved contributor trust tier was not `trusted` (fork PRs from
- * unknown contributors). Defense-in-depth: even if a misconfigured
- * environment lacks a `minimum_trust` rule, this strip prevents tokens
- * from leaving the orchestrator for those dispatches.
+ * unknown contributors). Defense-in-depth: even when a misconfigured
+ * environment lacks a `minimum_trust` rule, no token leaves the orchestrator.
  *
  * Labels:
  * - trust_tier: unknown (the `trusted` tier does not strip and therefore never fires this counter)
@@ -634,10 +605,9 @@ export declare const installSecretsContributorStrippedTotal: import("@openteleme
  * Dispatches where a job's container-registry credentials were withheld because
  * the contributor tier was not `trusted`.
  *
- * The sibling of `installSecretsContributorStrippedTotal`, for the other class
- * of credential a dispatch resolves orchestrator-side. Counted separately
- * because the two fire on different jobs: install secrets are workflow-level
- * and registry auth is per-job, so one run can strip both, either, or neither.
+ * Sibling of `installSecretsContributorStrippedTotal`, counted separately because
+ * install secrets are workflow-level and registry auth is per-job, so one run
+ * can strip both, either, or neither.
  *
  * Labels:
  * - trust_tier: unknown (the `trusted` tier does not strip and therefore never fires this counter)
@@ -704,14 +674,10 @@ export declare const wsUnsupportedMessageSentTotal: import("@opentelemetry/api")
  */
 export declare const wsNackReceivedTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
 /**
- * Register every queued orchestrator observable gauge on the real meter.
- *
- * Must run AFTER `initTelemetry()` has wired the global MeterProvider —
- * `createApp()` calls it once during bootstrap. Registering the gauges at
- * module-eval time instead would bind them to the no-op provider (the
- * bundler hoists some module init above the entry's `initTelemetry()` call),
- * leaving every `kici_orch_*` gauge absent from the /metrics scrape and the
- * Platform push. Idempotent: repeat calls are no-ops.
+ * Register every queued observable gauge on the real meter. Must run AFTER
+ * `initTelemetry()` (see the lazy-resolution note at the top of this file), or
+ * every `kici_orch_*` gauge is absent from the /metrics scrape and the Platform
+ * push. `createApp()` calls it once during bootstrap; repeat calls are no-ops.
  */
 export declare function registerOrchestratorMetrics(): void;
 /** Record whether the LISTEN subscription on `channel` currently holds a client. */

package/dist/orchestrator-core.d.ts

@@ -6,8 +6,8 @@
  * between the two modes. Mode-specific behavior is injected via the
  * OrchestratorHooks interface.
  *
- * This eliminates ~1300 lines of duplication that previously existed across
- * the two entry points.
+ * This keeps that logic in one place instead of duplicating it across the two
+ * entry points.
  */
 import { type ColdStore } from '@kici-dev/shared';
 import type { AppConfig } from './config.js';
@@ -224,7 +224,7 @@ export interface OrchestratorSubsystems {
      * (orchestrator-side) and the Platform-bound MetricsReporter (which
      * concatenates the agent snapshot before WS push so agent metrics
      * land in Mimir per-org alongside `kici_orch_*`) reference the same
-     * store. the metrics enforcement plan.
+     * store.
      */
     agentMetricsAggregator: AgentMetricsAggregator;
     /**
@@ -261,7 +261,6 @@ export interface OrchestratorSubsystems {
  * Mode-specific hooks injected by each entry point.
  */
 export interface OrchestratorHooks {
-    /** Logger prefix for mode-specific messages */
     logPrefix: string;
     /**
      * Extra ExecutionTracker callbacks (e.g., Platform-mode forwards execution
@@ -314,9 +313,6 @@ export interface OrchestratorHooks {
         /** Called after HTTP server starts (e.g., PlatformClient.connect) */
         onServerStarted?: () => Promise<void>;
     }>;
-    /**
-     * Mode startup log message.
-     */
     startupLogMessage: (port: number) => string;
 }
 /**

package/dist/pipeline/content-filter.d.ts

@@ -1,17 +1,15 @@
 /**
- * Tier-1 declarative content-requirements filter (execution-purity model, Part B).
+ * Tier-1 declarative content-requirements filter (execution-purity model,
+ * Part B). After Tier-0 trigger matching, it fetches the files each candidate's
+ * `requires` names, once per distinct `(repo, sha, path)` via the LRU cache,
+ * evaluates the pure-data requirements with the engine matcher, and drops any
+ * candidate that FAILS or is INDETERMINATE before dispatch. No author code runs:
+ * `requires` is a declarative query, which keeps content filtering inside the
+ * orchestrator under the purity model.
  *
- * After Tier-0 trigger matching selects candidate workflows, this step fetches
- * the source files each candidate's `requires` names — once per distinct
- * `(repo, sha, path)` via the LRU cache — evaluates the (pure DATA) requirements
- * with the engine matcher, and drops any candidate that FAILS or is
- * INDETERMINATE before dispatch. No author code is executed: `requires` is a
- * declarative query the orchestrator interprets, which is what keeps content
- * filtering inside the orchestrator under the purity model.
- *
- * Fail-visible: a dropped candidate (definite negative, oversize/unparseable
- * content, a fetch error, or no fetcher/cache available) is logged with the
- * concrete reason. An indeterminate file NEVER passes silently.
+ * Fail-visible: every drop (definite negative, oversize/unparseable content, a
+ * fetch error, or no fetcher/cache) is logged with its reason. An indeterminate
+ * file NEVER passes silently.
  */
 import type { FileContentsFetcher, LockContentRequirement } from '@kici-dev/engine';
 import type { ContentRequirementsCache } from '../content-requirements-cache.js';
@@ -36,15 +34,12 @@ export interface ContentFilterOptions {
     readonly deliveryId?: string;
 }
 /**
- * One dropped candidate.
- *
- * `indeterminate` separates the two reasons a drop happens, which mean opposite
- * things to a workflow author: a definite content mismatch is the requirement
- * doing its job, while an unreadable file, a fetch error, or a provider with no
- * file-contents fetcher is the requirement never having been evaluated at all.
- * Both drop the candidate — the filter is fail-visible, so an unevaluable file
- * never passes — but a trace that renders the second as "excluded" tells an
- * author their requirement said no when nothing ever read it.
+ * One dropped candidate. `indeterminate` separates the two drop reasons, which
+ * mean opposite things to an author: a definite content mismatch is the
+ * requirement doing its job, while an unreadable file, a fetch error, or a
+ * provider with no file-contents fetcher means it was never evaluated. Both
+ * drop the candidate, but a trace that renders the second as "excluded" tells
+ * an author their requirement said no when nothing ever read it.
  */
 export interface DroppedCandidate {
     readonly name: string;
@@ -57,15 +52,10 @@ export interface ContentFilterResult<C extends ContentFilterCandidate> {
     readonly dropped: DroppedCandidate[];
 }
 /**
- * Filter candidates by their declarative content requirements.
- *
- * Gathers each distinct `(repo, sha, path)` once via the cache, evaluates every
- * candidate's `requires`, and returns the survivors (pass) split from the
- * dropped (fail / indeterminate, each logged with its reason). A candidate with
- * no `requires` always survives without any fetch (the fast path — like an empty
- * `paths` filter). When a candidate has `requires` but no fetcher/cache is
- * available, it is dropped as indeterminate (fail-visible), never dispatched
- * unfiltered.
+ * Filter candidates by their declarative content requirements. A candidate with
+ * no `requires` always survives without any fetch, like an empty `paths`
+ * filter. One with `requires` but no fetcher/cache is dropped as indeterminate,
+ * never dispatched unfiltered.
  */
 export declare function filterByContentRequirements<C extends ContentFilterCandidate>(candidates: readonly C[], event: ContentFilterEvent, opts: ContentFilterOptions): Promise<ContentFilterResult<C>>;
 //# sourceMappingURL=content-filter.d.ts.map

package/dist/pipeline/cross-source-tally.d.ts

@@ -1,8 +1,8 @@
 /**
- * A generic delivery can run both halves — cross-source for other sources'
- * registrations, and the inbound source's own lock when its normalizer reads a
- * repository. The delivery still gets one event-log row: the same-source path
- * writes it, and this wrapper folds the cross-source half into it.
+ * A generic delivery can run both cross-source (other sources' registrations)
+ * and same-source (the inbound lock, when its normalizer reads a repository).
+ * It still gets one event-log row: the same-source path writes it, and this
+ * wrapper folds the cross-source half in.
  */
 import type { ProcessingDeps } from './processor.js';
 export interface CrossSourceTally {
@@ -12,10 +12,9 @@ export interface CrossSourceTally {
     degraded: boolean;
 }
 /**
- * Wrap `deps.eventLog` so whichever row the same-source path records — corrupt
- * lock, missing lock, skip or processed — also counts the cross-source half's
- * dispatched jobs and carries its degraded reason. A reason the same-source
- * path already set wins.
+ * Wrap `deps.eventLog` so any row the same-source path records (corrupt lock,
+ * missing lock, skip, processed) adds the cross-source dispatched jobs and its
+ * degraded reason; a same-source reason wins.
  */
 export declare function withCrossSourceTally(deps: ProcessingDeps, tally: CrossSourceTally): ProcessingDeps;
 //# sourceMappingURL=cross-source-tally.d.ts.map

package/dist/pipeline/decorating-secret-resolver.d.ts

@@ -1,15 +1,11 @@
 /**
  * CLI-secret overlay for `kici run` test dispatch.
  *
- * Wraps the orchestrator's context `SecretResolver` and overlays the
- * developer's CLI-uploaded local secrets on top of the env-resolved secrets,
- * with CLI winning on collision. Passed to the shared dispatch core via
- * `ProcessingDeps.secretResolver`, so the core's secret-resolution path is
- * unchanged and oblivious to "test secrets".
+ * Wraps the context `SecretResolver` and overlays the developer's CLI-uploaded
+ * secrets, passed as `ProcessingDeps.secretResolver` so the dispatch core stays
+ * oblivious to test secrets.
  *
- * Precedence: env-resolved secrets → CLI context for the requested context
- * → CLI flat. The CLI flat overlay is applied last so a CLI flat key always
- * wins.
+ * Precedence, lowest first: env-resolved → CLI context → CLI flat.
  */
 import type { HostFacts } from '@kici-dev/engine';
 import type { MatchedContextRef, ResolvedSecretMeta, SecretResolutionAttribution, SecretResolverApi } from '../secrets/secret-resolver.js';

package/dist/pipeline/degraded-reason.d.ts

@@ -1,8 +1,7 @@
 /**
- * Annotation written to a `processed` event-log row when path filters were
- * evaluated against an unavailable changed-files diff. Reuses the existing
- * free-text field so the outcome is never a silent `processed / matched 0` —
- * no new event-log status enum value is added.
+ * Annotates a `processed` event-log row whose path filters ran against an
+ * unavailable changed-files diff, in the existing free-text field (no new
+ * status enum value), so the outcome is never a silent `processed / matched 0`.
  */
 export declare const DEGRADED_CHANGED_FILES_REASON = "trigger evaluation degraded: changed files unavailable \u2014 path filters matched conservatively";
 //# sourceMappingURL=degraded-reason.d.ts.map