@kici-dev/orchestrator 0.16.0 → 0.18.0

package/dist/pipeline/sandbox-allowlist-reader.d.ts

@@ -11,21 +11,17 @@ export interface SandboxAllowList {
 }
 export interface SandboxAllowListReader {
     /**
-     * Read the org's escape-hatch allow-list. Never throws; on a DB error (or no
-     * DB handle) it degrades to the safe deny-all default `{ capabilities: [],
-     * allowHostNetwork: false }` so a sick DB denies escalation rather than
-     * blocking dispatch.
+     * Never throws: a DB error or no DB handle degrades to deny-all, so a sick DB
+     * denies escalation rather than blocking dispatch.
      */
     read(orgId: string): Promise<SandboxAllowList>;
 }
 /**
- * Reader for the per-org container-sandbox escape-hatch allow-list. Read once per
- * matched-workflow dispatch (not per request), against a single indexed row, so
- * it is intentionally **uncached**: this is a security control, and an operator's
- * `sandbox-allowlist` change must take effect on the very next dispatch (a cache
- * would leave the old policy in force for its TTL — a stale-deny or stale-allow
- * window on a privilege boundary). The trivial per-dispatch query is the right
- * trade for always-fresh enforcement.
+ * Reader for the per-org container-sandbox escape-hatch allow-list, read once per
+ * matched-workflow dispatch against one indexed row. Intentionally **uncached**:
+ * a security control, so an operator's `sandbox-allowlist` change must apply on
+ * the very next dispatch; a cache TTL would open a stale-deny or stale-allow
+ * window on a privilege boundary.
  */
 export declare function createSandboxAllowListReader(deps: {
     db?: Kysely<Database>;

package/dist/pipeline/security-hold-check.d.ts

@@ -3,10 +3,7 @@ import type { Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
 /** Resolve the check poster of the provider bundle a routing key is served by. */
 export type ResolveCheckStatusPoster = (routingKey: string) => CheckStatusPoster | undefined;
-/**
- * The `held_runs` columns this module reads. A full `HeldRun` row satisfies it,
- * so every caller passes the row it already loaded rather than a projection.
- */
+/** The `held_runs` columns this module reads; a full `HeldRun` row satisfies it. */
 export interface SecurityCheckHold {
     id: string;
     org_id: string;
@@ -16,9 +13,8 @@ export interface SecurityCheckHold {
     hold_type: string;
     approval_requirement: unknown;
     /**
-     * Whether the pending post reached the provider. Required rather than
-     * optional so a query that projects columns by name cannot omit it and fall
-     * back to the shape derivation without the compiler saying so.
+     * Whether the pending post reached the provider. Required, so a projecting
+     * query cannot silently omit it and fall back to the shape derivation.
      */
     posted_pending_check: boolean | null;
 }
@@ -62,22 +58,16 @@ export interface SettleSecurityCheckResult {
  * Whether this hold put a pending `KiCI Security` check on its commit, and so
  * has one to terminalize when it ends.
  *
- * `posted_pending_check` is the answer whenever the row carries one: it is
- * written `true` only after the provider accepted the post, so it records what
- * HAPPENED. Everything below records what the code INTENDED, which is a
- * different question and answers the wrong way twice — a post the provider
- * refused, and a hold reached with no check poster in `ctx.bundle`, both leave
- * a shape that says "posted" and a commit that has nothing. Terminalizing then
- * CREATES the check run, so the mirror of the stuck-check leak is a fabricated
- * failing check on a pull request.
- *
- * The shape derivation stays for `null` — a row written before the column
- * existed, for which no fact was recorded and an inference is all there is.
+ * `posted_pending_check` wins whenever set: it is written `true` only after the
+ * provider accepted the post, so it records what HAPPENED. The shape derivation
+ * below records what the code INTENDED, and is wrong for a refused post and for
+ * a hold with no check poster in `ctx.bundle` — terminalizing those CREATES a
+ * fabricated failing check on a pull request. The derivation serves only
+ * `null` (a row older than the column).
  *
- * Three sites post that pending status, and the derivation is read off them
- * rather than off the queue type — which cannot make the distinction, because a
- * workflow install gate whose context protection rule is security-typed carries
- * `queue_type = 'security'` and posts nothing at all.
+ * Three sites post the pending status, and the derivation reads them, not the
+ * queue type: an install gate with a security-typed context protection rule
+ * carries `queue_type = 'security'` and posts nothing.
  *
  * | Hold | Written by | Posts pending? | Recognised here by |
  * |---|---|---|---|
@@ -90,11 +80,11 @@ export interface SettleSecurityCheckResult {
  * | wait-timer / concurrency hold | the per-env gate | no | none of the above matches |
  * | step approval | `StepApprovalBridge.request` | no | step scope |
  *
- * `approval_requirement` is what `createHold` writes and `create` does not, so
- * it identifies exactly the rows `holdJobForApproval` wrote through the
- * approval path — the site whose post is guarded by `if (hold && …)`. The two
- * other `createHold` callers are excluded above it: the install gate by its job
- * id, the step bridge by its scope.
+ * `approval_requirement` is written by `createHold` and not by `create`, so it
+ * identifies exactly the rows `holdJobForApproval` wrote through the approval
+ * path (whose post is guarded by `if (hold && …)`). The other `createHold`
+ * callers are excluded before it: the install gate by job id, the step bridge
+ * by scope.
  */
 export declare function postedPendingSecurityCheck(hold: SecurityCheckHold): boolean;
 /**
@@ -102,28 +92,22 @@ export declare function postedPendingSecurityCheck(hold: SecurityCheckHold): boo
  * families use: `cancelled` for a rejection, `timed_out` for an elapsed window,
  * `success` for an approval.
  *
- * The subject follows the hold's scope on every outcome, because the same event
- * means different things at each: a workflow-scoped hold owns the whole run,
- * while a job-scoped one owns one job and says nothing about the run's other
- * jobs — including a step-approval hold that is still pending, which a run-wide
- * "no longer waiting for approval" would contradict.
+ * The subject follows the hold's scope: a workflow-scoped hold owns the whole
+ * run, a job-scoped one owns one job and says nothing about the others (a
+ * still-pending step-approval hold would contradict a run-wide "no longer
+ * waiting for approval").
  *
- * `actor` names whoever ended the hold, on an approve and on a reject alike.
- * Only an expiry has none: nobody answered, which is what expiry means. A
- * rejecter whose surface already writes its own attribution into `reason` (the
- * `/kici reject` handler builds "Rejected by alice via /kici reject") passes no
- * `actor`, so the sentence lands once rather than twice.
+ * `actor` names whoever ended the hold (none on expiry). A surface that already
+ * writes its attribution into `reason` (`/kici reject`: "Rejected by alice via
+ * /kici reject") passes no `actor`, so the sentence lands once.
  *
- * **`actor` is a display name, and it is published verbatim on a public commit
- * check.** It must never be an opaque identity-provider subject id: a surface
- * that holds one — the dashboard / CLI / MCP applier, which decides by KiCI
- * user id — resolves it against the org's identity directory first and passes
- * nothing when that resolves to no single name. Omitting the attribution reads
- * as "an approver"; leaking the subject reads as `Approved by
- * 8f3a-…-uuid`, on a pull request anyone can open.
+ * **`actor` is a display name, published verbatim on a public commit check.**
+ * Never an opaque identity-provider subject id: a surface holding one (the
+ * dashboard / CLI / MCP applier) resolves it against the org's identity
+ * directory first and passes nothing when no single name results — "an
+ * approver", never `Approved by 8f3a-…-uuid` on a public pull request.
  *
- * `reason` is normalized to end in terminal punctuation — a rejecter's own
- * sentence carries none, and without one it runs straight into what follows.
+ * `reason` is normalized to end in terminal punctuation.
  */
 export declare function buildHoldEndedSummary(args: {
     outcome: HoldOutcome;
@@ -133,12 +117,11 @@ export declare function buildHoldEndedSummary(args: {
     via?: string | undefined;
 }): string;
 /**
- * Terminalize the `KiCI Security` check of a hold that just ended, choosing the
- * conclusion, title and summary from {@link HoldOutcome}.
- *
- * The single entry point for every surface that ends a hold — the `/kici`
- * comment handler, the dashboard / CLI / MCP applier, and the stale detector's
- * approval-window sweep — so those surfaces cannot render one event three ways.
+ * Terminalize the `KiCI Security` check of an ended hold, with conclusion, title
+ * and summary from {@link HoldOutcome}. The single entry point for every surface
+ * that ends a hold (the `/kici` comment handler, the dashboard / CLI / MCP
+ * applier, the stale detector's approval-window sweep), so they cannot render
+ * one event three ways.
  */
 export declare function settleSecurityCheckForOutcome(args: {
     db: Kysely<Database> | undefined;
@@ -155,15 +138,10 @@ export declare function settleSecurityCheckForOutcome(args: {
  * The dashboard / CLI / MCP applier's entry point into
  * {@link settleSecurityCheckForOutcome}.
  *
- * That applier decides by KiCI user id, so the only actor it holds is an opaque
- * identity-provider subject — and this summary is published verbatim on a public
- * commit check. `resolveDisplayName` maps the subject onto the account name the
- * org's identity directory links it to; when it names none, the attribution is
- * DROPPED rather than falling back to the subject. So an approve reads
- * "Approved by an approver" at worst, never "Approved by 8f3a-…-uuid".
- *
- * Separate from its caller so the resolve-or-drop step is a unit under test
- * rather than a line in the composition root.
+ * The applier holds only an opaque identity-provider subject, and the summary is
+ * public. `resolveDisplayName` maps it to the org identity directory's linked
+ * account name; when none, the attribution is DROPPED, never the subject. A
+ * separate function so the resolve-or-drop step is unit-tested.
  */
 export declare function settleSecurityCheckForDecision(args: {
     db: Kysely<Database> | undefined;
@@ -180,23 +158,22 @@ export declare function settleSecurityCheckForDecision(args: {
  * Terminalize the `KiCI Security` check of a hold that just ended, under a
  * caller-supplied status and copy.
  *
- * Used directly where one summary has to reach BOTH check families — a rejected
- * workflow-scoped hold reports the same sentence on `KiCI Security` and on the
- * `kici/…` runs of the same event, and that sameness is asserted rather than
- * assumed. Everything else goes through {@link settleSecurityCheckForOutcome}.
+ * Used directly where one summary must reach BOTH check families (a rejected
+ * workflow-scoped hold reports the same, asserted sentence on `KiCI Security`
+ * and the event's `kici/…` runs); everything else goes through
+ * {@link settleSecurityCheckForOutcome}.
  *
- * Call it AFTER the hold's own row has left `pending` (every caller does: the
- * applier flips inside `recordAndReject` / `recordAndRelease`, the comment
- * handler inside `reject` / `approveByQueueType`) — and, on an approve, BEFORE
- * the resume, so a replayed dispatch that holds again overwrites this terminal
- * status with its own pending one rather than the other way round. The ending
- * hold's own id is excluded from the contention query regardless, so a sweep
- * that has not yet flipped its batch can name it in `excludeHoldIds`.
+ * Call it AFTER the hold's row has left `pending` (the applier flips inside
+ * `recordAndReject` / `recordAndRelease`, the comment handler inside `reject` /
+ * `approveByQueueType`) and, on an approve, BEFORE the resume, so a replayed
+ * dispatch that holds again overwrites this terminal status with its pending
+ * one, not the reverse. The ending hold's id is always excluded from the
+ * contention query; a sweep that has not flipped its batch yet names the rest
+ * in `excludeHoldIds`.
  *
- * Never throws: terminalizing a check run is a reporting courtesy on a path
- * whose real job is to terminalize the hold, and a provider error must not stop
- * that. The returned `posted` is what a caller binds its own suppression to —
- * it says a check was written, not merely that a delegate resolved.
+ * Never throws: a provider error must not stop the hold's terminalization.
+ * Callers bind suppression to the returned `posted` (a check was written, not
+ * merely a delegate resolved).
  */
 export declare function settleSecurityHoldCheck(args: {
     db: Kysely<Database> | undefined;
@@ -207,10 +184,9 @@ export declare function settleSecurityHoldCheck(args: {
     summary: string;
     excludeHoldIds?: readonly string[] | undefined;
     /**
-     * Commits this caller already wrote in the same pass. A sweep that ends
-     * several holds on one commit shares one check run between them, and every
-     * hold in it carries the same conclusion and summary — so the second write
-     * would be a byte-identical provider round-trip.
+     * Commits this caller already wrote in the same pass: a sweep's holds on one
+     * commit share one check run and identical copy, so a second write is a
+     * byte-identical round-trip.
      */
     skipCommits?: ReadonlySet<string> | undefined;
 }): Promise<SettleSecurityCheckResult>;

package/dist/pipeline/test-pipeline.d.ts

@@ -2,12 +2,12 @@
  * Test-trigger adapter for CLI-initiated runs (`kici run`).
  *
  * Resolves the lock file, matched decisions, and fixture-specific concerns
- * (inline-vs-provider lock, decision selection, fixture-payload storage, the
+ * (inline-vs-provider lock, fixture-payload storage, the
  * `allow_local_execution` context gate, CLI-secret overlay, in-memory
  * test-run marking), then dispatches each matched workflow through the SAME
- * shared core as webhooks (`dispatchMatchedWorkflow`). The test path is a thin
- * adapter — needs-DAG scheduling, `expansionMap` fan-out edges, `runsOnAll`
- * host fan-out, and deferred init/dynamic dispatch all come from the core.
+ * core as webhooks (`dispatchMatchedWorkflow`), which supplies needs-DAG
+ * scheduling, `expansionMap` fan-out edges, `runsOnAll` host fan-out, and
+ * deferred init/dynamic dispatch.
  *
  * Differences from a webhook run:
  * - the synthetic event is injected directly (no provider normalization/dedup);
@@ -24,13 +24,8 @@
 import { type ProcessingDeps } from './processor.js';
 import { type ActorPrincipal } from '@kici-dev/engine';
 import type { CheckMode, HostTargetSelector } from '@kici-dev/engine';
-/**
- * Input for a test trigger request.
- */
 export interface TestTriggerInput {
-    /** Unique fixture identifier from the CLI. */
     fixtureId: string;
-    /** The simulated event to inject into the pipeline. */
     event: {
         type: string;
         action?: string;
@@ -41,15 +36,15 @@ export interface TestTriggerInput {
     };
     /** Routing key for provider lookup and lock file fetch. */
     routingKey: string;
-    /** Reference to uploaded tarball (optional). */
+    /** Uploaded tarball reference. */
     uploadId?: string;
-    /** Fixture secret context mappings (optional). */
+    /** Fixture secret context mappings `{ contextName: envName }`. */
     secrets?: Record<string, string>;
     /** Base64 X25519+AES-GCM blob of the developer's local secrets ({flat, contexts}). */
     encryptedSecrets?: string;
     /** Base64 ephemeral CLI public key that encrypted `encryptedSecrets`. */
     encryptedSecretsKey?: string;
-    /** Direct workflow run -- bypass triggers (optional). */
+    /** Direct workflow run, bypassing triggers. */
     workflowName?: string;
     /** Resolved overlay metadata for tarball download + decryption. */
     resolvedOverlay?: {
@@ -57,17 +52,13 @@ export interface TestTriggerInput {
         cliPublicKey: string;
         orchestratorPrivateKey: string;
     };
-    /** Request trace ID from the HTTP request. */
+    /** Trace ID of the HTTP request. */
     requestId: string;
     /**
-     * The principal that initiated this run, relayed by the Platform on
-     * `test.relay.trigger` (where the wire schema has always required it).
-     *
-     * Required rather than optional: the relay handler is the only production
-     * caller, so there is no path that legitimately lacks an actor, and an
-     * optional field would let a future caller silently drop attribution — which
-     * is exactly how `execution_runs.triggered_by` stayed NULL for every remote
-     * test run while the column claimed to hold the initiator.
+     * The initiating principal: the one the Platform relays on
+     * `test.relay.trigger`, or the admin token's service account on the direct
+     * test-run routes. Required so no caller can silently leave
+     * `execution_runs.triggered_by` NULL.
      */
     actor: ActorPrincipal;
     /** JSON-stringified lock file content for local repos with no remote. */
@@ -75,39 +66,26 @@ export interface TestTriggerInput {
     /** When true, repo has no remote -- skip provider lookup, skip clone. */
     fullRepo?: boolean;
     /**
-     * Run mode for idempotent steps (`apply` | `check` | `check-fail-on-drift`).
-     * Threaded onto each dispatched job's config and persisted on the run.
-     * Omitted means `apply`.
+     * Run mode for idempotent steps, set on each job's config and persisted on
+     * the run. Omitted means `apply`.
      */
     checkMode?: CheckMode;
-    /**
-     * Runtime host narrowing from `kici run --target`. Threaded onto the dispatch
-     * context, where it post-filters each runsOnAll job's matched roster.
-     */
+    /** `kici run --target`: post-filters each runsOnAll job's matched roster. */
     target?: HostTargetSelector;
     /**
-     * Raw operator-supplied `kici run --input KEY=VALUE` pairs (not coerced /
-     * defaulted). Validated + coerced + defaulted here against the matched
-     * workflow's lock dispatch descriptor before dispatch.
+     * Raw `kici run --input KEY=VALUE` pairs, validated, coerced and defaulted
+     * here against the matched workflow's lock dispatch descriptor.
      */
     dispatchInputs?: Record<string, string>;
 }
-/**
- * Result of processing a test trigger.
- */
 interface TestTriggerResult {
-    /** Unique run identifier. */
     runId: string;
-    /** Whether the test trigger was accepted or rejected. */
     status: 'accepted' | 'rejected';
-    /** Reason for rejection (if rejected). */
     reason?: string;
-    /** Dispatched job IDs. */
     jobIds: string[];
     /**
-     * User-visible warnings on an accepted run — today, one per job whose bound
-     * test-run context(s) were unavailable (non-test or unconfigured) and
-     * skipped. Printed by the CLI on acceptance.
+     * Warnings the CLI prints on acceptance: one per job whose bound test-run
+     * contexts were unavailable (non-test or unconfigured) and skipped.
      */
     warnings?: string[];
 }
@@ -121,11 +99,8 @@ export declare function repoIdentityFromInlineInput(input: TestTriggerInput): {
     provider: string;
 };
 /**
- * Process a test trigger through the shared dispatch core.
- *
- * Resolves the lock file + matched decisions + fixture concerns, then builds a
- * `WorkflowDispatchContext` per matched workflow and calls
- * `dispatchMatchedWorkflow` — the same core the webhook path uses.
+ * Process a test trigger through the shared dispatch core: one
+ * `WorkflowDispatchContext` per matched workflow, into `dispatchMatchedWorkflow`.
  */
 export declare function processTestTrigger(input: TestTriggerInput, deps: ProcessingDeps): Promise<TestTriggerResult>;
 export {};

package/dist/pipeline/unbound-job-context.d.ts

@@ -1,20 +1,17 @@
 /**
- * The dispatch-time warning for a job context that has no scope binding.
+ * The dispatch-time warning for a job context with no scope binding.
  *
- * A job receives a context's secrets only through the context's scope
- * bindings, so a context with none delivers no secret, and nothing fails until
- * a step reads one. This names each such context in the orchestrator log when
- * the job's context data resolves. Advisory only: it runs after resolution, a
- * failed lookup logs nothing, and the dispatch proceeds unchanged.
+ * Secrets reach a job only through scope bindings, so an unbound context
+ * delivers none and nothing fails until a step reads one. Advisory only: it runs
+ * after resolution, a failed lookup logs nothing, and dispatch is unchanged.
  */
 import type { Context } from '@kici-dev/engine';
 import type { SecretResolverApi } from '../secrets/secret-resolver.js';
 /** The warning line's message; the structured fields carry the identities. */
 export declare const UNBOUND_JOB_CONTEXT_MESSAGE = "Job binds a context that has no scope binding; it receives no secrets from it";
 /**
- * Warn once for every context in `entries` that resolved no secret and has no
- * scope binding. A context that resolved at least one secret is skipped without
- * a lookup, so a bound context costs nothing here.
+ * Warn once per context that resolved no secret and has no scope binding; one
+ * that resolved a secret is skipped without a lookup.
  */
 export declare function warnUnboundJobContexts(args: {
     secretResolver: SecretResolverApi | undefined;

package/dist/pipeline/undispatched-hold-checks.d.ts

@@ -5,13 +5,11 @@ import type { CheckRunReporter } from '../reporting/check-run-reporter.js';
 /**
  * Complete the check runs of `runId`'s stored workflow dispatch, if it has one.
  *
- * A run with no pending workflow context never held at workflow scope (or its
- * context was already consumed by a resume), so there is nothing to close and
- * this is a no-op. Call it BEFORE `deletePendingWorkflowContext` — the context
- * is the only place the check-run names can still be derived from.
+ * A no-op without a pending workflow context. Call it BEFORE
+ * `deletePendingWorkflowContext`: the context is the only source of the
+ * check-run names.
  *
- * Never throws: closing a check run is a reporting courtesy on a path whose real
- * job is to terminalize the run, and a provider error must not stop that.
+ * Never throws: a provider error must not stop the caller terminalizing the run.
  */
 export declare function completeUndispatchedHoldChecks(args: {
     db: Kysely<Database> | undefined;

package/dist/pipeline/wave-scheduler.d.ts

@@ -1,18 +1,15 @@
 /**
  * Rolling-wave scheduler for bounded fan-out (`maxParallel` / `failFast`).
  *
- * Sibling of the needs-scheduler (`needs-scheduler.ts`): both fire on a job
- * reaching terminal state and decide what to do with held downstream/sibling
- * jobs. The needs-scheduler releases jobs whose `needs` edges are now satisfied;
- * the wave-scheduler releases the next `wave_gated` sibling of a fan-out base
- * whenever an in-flight slot frees up (or, under `failFast`, skips the held
- * remainder on the first child failure).
+ * Like `needs-scheduler.ts`, it fires when a job reaches a terminal state: it
+ * releases the next `wave_gated` sibling of a fan-out base when an in-flight
+ * slot frees up, or, under `failFast`, skips the held remainder on the first
+ * child failure.
  *
- * Pure DB — no in-memory state. Every decision is a fresh query against
- * `execution_jobs` keyed by `(run_id, base_job_name)`, so the scheduler needs
- * zero recovery code on orchestrator restart. The caller performs the DB write
- * (clear `wave_gated` / mark skipped) and the dispatch (`onJobReady`), keeping
- * this module a pure decision function.
+ * Pure DB, no in-memory state: every decision is a fresh query on
+ * `execution_jobs` keyed by `(run_id, base_job_name)`, so a restart needs no
+ * recovery code. The caller performs the DB write (clear `wave_gated` / mark
+ * skipped) and the dispatch (`onJobReady`).
  */
 import type { Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
@@ -38,23 +35,19 @@ export type WaveResult = {
     action: 'noop';
 };
 /**
- * Decide what happens after a fan-out child of `baseJobName` reaches terminal.
- *
- * The wave policy (`maxParallel` / `failFast`) is read from the base group's
- * own rows — every child of a bounded wave carries the same stamped
- * `wave_max_parallel` / `wave_fail_fast`, so the just-completed child's slot
- * being re-inserted without the policy on release does not break the chain
- * (the still-held siblings carry it). If no sibling carries a policy, this is
- * not a bounded wave → `noop`.
+ * The wave policy is read from the base group's rows: every child of a bounded
+ * wave carries the same `wave_max_parallel` / `wave_fail_fast`, so a slot
+ * re-inserted without the policy on release does not break the chain (the
+ * still-held siblings carry it). No sibling with a policy means no bounded
+ * wave → `noop`.
  *
  * - `failFast` + a child failure → `skip-remaining` every still-held sibling.
  * - in-flight count `< maxParallel` AND a held sibling exists → `release` the
  *   next held sibling (lowest `variant_label`).
  * - otherwise → `noop`.
  *
- * "In-flight" = a non-terminal, non-`wave_gated` child (it has been dispatched
- * and not yet completed). The just-completed child is terminal, so it does not
- * count against the window — its slot is the one we are filling.
+ * "In-flight" = a non-terminal, non-`wave_gated` child. The just-completed
+ * child is terminal, so its slot is the one being filled.
  */
 export declare function evaluateWave(db: Kysely<Database>, evaluation: WaveEvaluation): Promise<WaveResult>;
 //# sourceMappingURL=wave-scheduler.d.ts.map

package/dist/pipeline/webhook-payload-store.d.ts

@@ -1,16 +1,9 @@
 import type { LogStorage } from '../reporting/log-storage.js';
-/**
- * Object-storage key holding the webhook payload for a run. Shared by the
- * writers and by the re-run path that copies a payload forward, so the layout
- * is stated once.
- */
+/** Object-storage key of a run's webhook payload, shared by the writers and the re-run copy. */
 export declare function webhookPayloadPath(runId: string): string;
 /**
- * Store a run's triggering webhook payload, best-effort.
- *
- * A failure is logged and swallowed: the payload is a debugging aid, and losing
- * it must never cost the run that was about to execute. A no-op when the
- * orchestrator has no object storage configured.
+ * Best-effort: a failure is logged and swallowed, because losing a debugging
+ * aid must never cost the run. A no-op without object storage.
  */
 export declare function storeWebhookPayload(args: {
     logStorage: LogStorage | undefined;

package/dist/pipeline/workflow-lock-at-sha.d.ts

@@ -1,22 +1,18 @@
 /**
- * Load a workflow repository's lock entries as they were at a recorded commit.
- *
- * An organization-wide run records the commit of the repository that defines
- * its workflow (`execution_runs.workflow_sha`). Two paths act on such a run
- * later, after that repository may have moved on: the re-run of a finished
- * global run, and the release of a held evaluation round. Both must run the
- * workflow version the run was created against, never the registration's
- * current one. This module is the one place that resolves it.
+ * Load a workflow repository's lock entries at the commit an organization-wide
+ * run recorded (`execution_runs.workflow_sha`). The re-run of a finished global
+ * run and the release of a held evaluation round act after that repository may
+ * have moved on, and must run the version the run was created against, never
+ * the registration's current one. This module is the one place that resolves it.
  */
 import type { LockFile, LockWorkflow } from '@kici-dev/engine';
 import type { ProviderRegistry } from '../provider-registry.js';
 import type { RegisteredWorkflow } from '../registration/registration-index.js';
 import { type DepCacheKey } from '@kici-dev/shared';
 /**
- * Whether a lock entry is an organization-wide workflow: a trigger carries
- * `repos:`. The re-run and the held-round release both judge a workflow by its
- * entry at the recorded commit through this one rule, never by the current
- * registration.
+ * A lock entry is organization-wide when a trigger carries `repos:`. The re-run
+ * and the held-round release judge a workflow by its entry at the recorded
+ * commit through this one rule, never by the current registration.
  */
 export declare function isOrganizationWideEntry(entry: LockWorkflow): boolean;
 /**
@@ -37,14 +33,12 @@ export interface WorkflowLockEntryAtSha {
     depCacheKey: DepCacheKey;
 }
 /**
- * The lock entries of `registrations` at `sha`, keyed by workflow name.
- *
- * Every registration must belong to the same workflow repository. When each
- * registration is already at `sha`, its stored lock entry is that version and
- * nothing is fetched. Otherwise the lock file is fetched at `sha` through the
- * registration's own provider bundle, with the registration's provider context
- * — the same fetcher a per-repository re-run reads its own lock file with. A
- * workflow the lock file at `sha` does not define is absent from the result.
+ * The lock entries of `registrations` at `sha`, keyed by workflow name. Every
+ * registration must belong to one workflow repository. When each is already at
+ * `sha`, its stored lock entry is that version and nothing is fetched; otherwise
+ * the lock file is fetched at `sha` through the registration's own bundle and
+ * provider context, the fetcher a per-repository re-run uses. A workflow the
+ * lock file at `sha` does not define is absent from the result.
  *
  * Throws, naming the workflow repository, when the lock file cannot be read:
  * the caller refuses rather than falling back to any other version.

package/dist/policy/dashboard-write-policy.d.ts

@@ -106,7 +106,7 @@ export declare function assertDashboardWriteAllowed(db: Kysely<Database>, custom
  * Merge `updates` into the persisted policy and persist the result.
  * Unknown keys in `updates` are rejected at the Zod schema layer
  * before this function runs (kici-admin already validates). Any
- * operation explicitly set to `true` is normalized away — the
+ * operation explicitly set to `'permissive'` is normalized away — the
  * permissive default lives in the absence of the key, keeping the
  * JSONB shape minimal.
  *

package/dist/provider-registry.d.ts

@@ -81,12 +81,6 @@ export interface ProviderBundle {
  */
 export declare class ProviderRegistry {
     private readonly bundles;
-    /**
-     * Register a provider bundle by routing key.
-     *
-     * Each routing key gets its own bundle with per-app credentials.
-     * Routing keys have the format "{provider}:{id}" (e.g., "github:12345").
-     */
     registerByRoutingKey(routingKey: string, bundle: ProviderBundle): void;
     /**
      * Register the provider-wide default bundle for `type`, stored under the
@@ -104,9 +98,6 @@ export declare class ProviderRegistry {
      */
     hasExact(routingKey: string): boolean;
     /**
-     * Get the provider bundle by routing key.
-     * Routing keys have the format "{provider}:{id}" (e.g., "github:12345").
-     *
      * A key with no bundle of its own falls back only to its type's default
      * bundle (`{type}:default`, e.g. `generic:default`, which stands in for every
      * plain generic source). It never falls back to another key's bundle: that
@@ -115,30 +106,20 @@ export declare class ProviderRegistry {
      */
     getByRoutingKey(routingKey: string): ProviderBundle | undefined;
     /**
-     * Get just the normalizer for a routing key.
      * Convenience method for webhook handling.
      */
     getNormalizerByRoutingKey(routingKey: string): WebhookNormalizer | undefined;
-    /**
-     * Iterate over all registered bundles.
-     */
     getAll(): IterableIterator<[string, ProviderBundle]>;
-    /**
-     * Get all registered routing keys.
-     */
     getRoutingKeys(): string[];
     /**
-     * Remove a routing key and its bundle.
      * Used during config reload when apps are removed.
      */
     unregister(routingKey: string): boolean;
     /**
-     * Check if a routing key is for a generic webhook source.
      * Generic routing keys have the format "generic:{orgId}:{sourceId}".
      */
     static isGenericRoutingKey(routingKey: string): boolean;
     /**
-     * Remove all registered bundles.
      * Used during full config rebuild on reload.
      */
     clear(): void;