@kici-dev/orchestrator 0.16.0 → 0.18.0

package/dist/pipeline/flatten-lock-steps.d.ts

@@ -1,11 +1,9 @@
 import { type LockStep, type LockStepEntry } from '@kici-dev/engine';
 /**
- * Flatten a lock job's `steps` into the flat sequential list the orchestrator
- * iterates by `stepIndex`. A `parallel` group's children are inlined in array
- * order and the group wrapper is dropped (it consumes no flat index). This keeps
- * the orchestrator's enumeration aligned with the agent's `extractAndNormalizeSteps`
- * — the flat-stepIndex invariant: `flattenLockSteps(job.steps)[i]` is the step at
- * agent `stepIndex i`.
+ * Flatten a lock job's `steps` for `stepIndex` iteration: a `parallel` group's
+ * children are inlined in order and the wrapper takes no index. Invariant,
+ * matching the agent's `extractAndNormalizeSteps`:
+ * `flattenLockSteps(job.steps)[i]` is the step at agent `stepIndex i`.
  */
 export declare function flattenLockSteps(steps: readonly LockStepEntry[]): readonly LockStep[];
 //# sourceMappingURL=flatten-lock-steps.d.ts.map

package/dist/pipeline/global-dispatch-identity.d.ts

@@ -10,7 +10,6 @@
  */
 import type { ProviderBundle } from '../provider-registry.js';
 import type { WorkflowRepoProvenance } from '../reporting/execution-tracker.js';
-/** The workflow repository of a run whose workflow is defined in another repository. */
 export interface GlobalDispatchIdentity {
     /** `owner/repo` that defines the workflow. */
     readonly workflowRepoIdentifier: string;
@@ -24,7 +23,6 @@ export interface GlobalDispatchIdentity {
     readonly workflowProviderContext: Record<string, unknown>;
     /** The workflow repository's provider bundle (may differ from the inbound one). */
     readonly workflowBundle: ProviderBundle | undefined;
-    /** Credentials minted for the workflow repository. */
     readonly workflowCredentials: Record<string, unknown>;
 }
 interface IdentityCtx {
@@ -54,19 +52,16 @@ export declare function policyRoutingKey(ctx: {
 /** Provenance recorded on the run row; `undefined` for a same-repo run. */
 export declare function workflowRepoProvenance(ctx: IdentityCtx): WorkflowRepoProvenance | undefined;
 /**
- * The dual-checkout job-config fields of a dispatch, with the workflow
- * repository's clone URL built by its own provider bundle. Empty for a
- * same-repository dispatch. Throws when the workflow bundle cannot build a
- * clone URL: a global job without a workflow-repository URL cannot run.
+ * The dual-checkout job-config fields, with the workflow repository's clone URL
+ * built by its own provider bundle. Empty for a same-repository dispatch. Throws
+ * when that bundle cannot build a clone URL.
  */
 export declare function globalJobConfigFor(ctx: IdentityCtx): Record<string, unknown>;
 /** Job-config fields the agent uses for the dual checkout. */
 export declare function globalJobConfigFields(ctx: IdentityCtx, workflowRepoUrl: string): Record<string, unknown>;
 /**
- * The part of a {@link GlobalDispatchIdentity} a held run stores: everything
- * but the live provider bundle and the minted credentials, both of which a
- * resume re-derives from `workflowRoutingKey`. The commit, branch and provider
- * context are the ones captured when the run was held, so a resumed run
+ * The part of a {@link GlobalDispatchIdentity} a held run stores; a resume
+ * re-derives bundle and credentials from `workflowRoutingKey`. A resumed run
  * executes the workflow commit it was held at, not the live registration's.
  */
 export type SerializableGlobalDispatchIdentity = Omit<GlobalDispatchIdentity, 'workflowBundle' | 'workflowCredentials'>;

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

@@ -1,20 +1,17 @@
 /**
  * Tier-2 global eval round — orchestrator side.
  *
- * A global workflow can declare a `filter` predicate and `DynamicJobFn`
- * generators, neither of which the orchestrator may run: author code never
- * returns to this process. So the candidates that need either one are grouped by
- * the workflow repo they live in and handed to ONE pre-run job per
- * (event × workflow repo × registered SHA). That job checks out the workflow
- * repo and the source repo once, runs every candidate's filter and then its
- * generators, and reports a verdict per candidate.
+ * The orchestrator never runs author code, so global candidates with a `filter`
+ * or `DynamicJobFn` generators go to ONE pre-run job per
+ * (event × workflow repo × registered SHA). That job checks out both repos once,
+ * runs each candidate's filter then its generators, and reports a verdict per
+ * candidate.
  *
- * The round precedes any run row by design: its whole purpose is to decide which
- * global workflows produce a run at all, so creating one up-front would defeat
- * it.
+ * The round precedes any run row by design: it decides which global workflows
+ * produce a run at all.
  *
- * This module owns the partition, the grouping, and the dispatch-and-await. The
- * caller decides what to do with the verdicts.
+ * This module owns the partition, the grouping, and the dispatch-and-await; the
+ * caller acts on the verdicts.
  */
 import type { GlobalEvalCandidateResult, LockJobOrFactory, LockWorkflow, SimulatedEvent, WorkflowDecision } from '@kici-dev/engine';
 import { type GlobalEvalRoundCache } from '../cache/global-eval-round-cache.js';
@@ -55,27 +52,21 @@ export interface GlobalEvalCandidate {
     reg: RegisteredWorkflow;
     lockEntry: LockWorkflow;
     /**
-     * The trigger-match decision this candidate came from, carried so the round's
-     * verdict can be appended to its trace. Optional because the round itself
-     * never reads it — only the caller that explains an exclusion does.
+     * The trigger-match decision, carried so the verdict can be appended to its
+     * trace. Optional: only the caller that explains an exclusion reads it.
      */
     decision?: WorkflowDecision;
 }
 /**
- * Stable identity for one candidate across a round's results.
- *
- * The registration id alone is unique, but the workflow name is appended so a
- * lookup reads honestly at the call site and a malformed registration with a
- * blank id still separates two workflows.
+ * Stable identity for one candidate across a round's results. The workflow name
+ * is appended so a malformed registration with a blank id still separates two
+ * workflows.
  */
 export declare function candidateKey(candidate: GlobalEvalCandidate): string;
 /**
  * True for a `DynamicJobFn` entry the pre-run round runs: a generator with no
- * upstream `needs`.
- *
- * A result-aware generator (`resultAware`, or any declared `needs`) reads its
- * upstreams' outputs, which do not exist before the run starts. It runs on the
- * run's deferred path instead, once those upstreams complete.
+ * upstream `needs`. A result-aware generator (`resultAware`, or any `needs`)
+ * reads upstream outputs that do not exist yet, so it runs on the deferred path.
  */
 export declare function isRoundGenerator(job: LockJobOrFactory): boolean;
 /** True for a `DynamicJobFn` entry that runs on the deferred path, never in the round. */
@@ -83,29 +74,21 @@ export declare function isDeferredGenerator(job: LockJobOrFactory): boolean;
 /** True when the workflow carries at least one generator the round must NOT run. */
 export declare function hasDeferredGenerator(lockEntry: LockWorkflow): boolean;
 /**
- * Split matched global candidates into those that can dispatch straight away and
- * those that must go through an eval round first.
+ * Split matched global candidates into immediate dispatch and eval-round.
  *
- * A candidate needs the round when it declares a `filter` (only the agent may
- * run the predicate), carries a needs-free `DynamicJobFn` (only the agent may
- * run the generator, and it depends on nothing the run produces), or matched
- * with deferred `paths` (only the agent's clone holds the diff). Everything
- * else — static jobs, and result-aware generators the run evaluates later — is
- * handed to the dispatch pipeline as declared, so routing it through a round
- * would add a job dispatch and an agent round trip for nothing.
+ * A candidate needs the round when it declares a `filter`, carries a needs-free
+ * `DynamicJobFn` (only the agent may run either), or matched with deferred
+ * `paths` (only the agent's clone holds the diff). Static jobs and result-aware
+ * generators dispatch as declared; a round would add a dispatch for nothing.
  */
 export declare function partitionCandidates(candidates: readonly GlobalEvalCandidate[]): {
     immediate: GlobalEvalCandidate[];
     needsRound: GlobalEvalCandidate[];
 };
 /**
- * Group by workflow repo, routing key, and registered SHA.
- *
- * All three parts are load-bearing. The repo identifier and the SHA together pin
- * the exact tree the round checks out, so two registrations of one repo at
- * different commits can never share a checkout; the routing key pins which
- * provider bundle mints the clone credentials, so two providers owning the same
- * repo path stay separate.
+ * Group by workflow repo, routing key, and registered SHA. Repo and SHA pin the
+ * tree the round checks out; the routing key pins the provider bundle that mints
+ * clone credentials, so two providers owning one repo path stay separate.
  */
 export declare function groupCandidates(candidates: readonly GlobalEvalCandidate[]): Map<string, GlobalEvalCandidate[]>;
 /** Minimal dispatcher surface the round needs (the real one is the job dispatcher). */
@@ -114,16 +97,12 @@ export interface GlobalEvalDispatcher {
         status: string;
         jobId: string;
     }>;
-    /**
-     * Take a still-queued round job out of the queue when nobody is waiting for
-     * it any more. Optional so a test double can omit it.
-     */
+    /** Drop a still-queued round job nobody waits for. Optional for test doubles. */
     cancelQueuedJob?(jobId: string, reason: string): Promise<void>;
 }
 /**
- * Minimal provider-registry surface: resolving the bundle that owns a routing
- * key. The round needs it because the workflow repo and the event's source repo
- * can live behind different providers.
+ * Resolves the bundle owning a routing key: the workflow repo and the event's
+ * source repo can live behind different providers.
  */
 export interface GlobalEvalProviderRegistry {
     getByRoutingKey(routingKey: string): ProviderBundle | undefined;
@@ -145,30 +124,18 @@ export interface GlobalEvalAgentRegistry {
 }
 /**
  * First agent release whose job runner understands a `globalEvalRound`
- * dispatch.
- *
- * Below it the agent has no round branch at all: the job falls through to the
- * standard executor, whose `jobConfig` carries no `source.file`, so it either
- * fails outright or reports success without the `globalEvalComplete` the
- * orchestrator is waiting for. Either way the round never settles.
+ * dispatch. An older agent runs it through the standard executor, which fails
+ * or succeeds without sending `globalEvalComplete`, so the round never settles.
  *
- * Customers upgrade their orchestrator and their agents on their own schedule,
- * so an orchestrator ahead of its fleet is
- * a supported state and not an error — but it is one this module has to
- * recognise, because the damage is not confined to the new feature. A global
- * workflow that merely *contains* a generator now routes through the round, so
- * an unrecognised round means static jobs that ran yesterday stop running.
+ * An orchestrator ahead of its fleet is a supported state, but this module must
+ * recognise it: a global workflow that merely *contains* a generator routes
+ * through the round, so its static jobs would stop running too.
  */
 export declare const MIN_GLOBAL_EVAL_AGENT_VERSION = "0.5.0";
 export interface GlobalEvalRoundDeps {
     dispatcher: GlobalEvalDispatcher;
     pendingGlobalEvals: PendingGlobalEvalTracker;
-    /**
-     * Required, unlike the three optional deps below: it is what resolves the
-     * WORKFLOW repo's own provider bundle. Omitting it would leave the round with
-     * no clone URL for the workflow repo at all, so it is not a dep that can
-     * degrade quietly.
-     */
+    /** Required: without it the round has no clone URL for the WORKFLOW repo. */
     providerRegistry: GlobalEvalProviderRegistry;
     clusterSettings?: ClusterSettingsReader;
     globalEvalCache?: GlobalEvalRoundCache;
@@ -201,99 +168,58 @@ export interface GlobalEvalRoundArgs {
 /**
  * Why a fleet cannot decide a round, or `null` when it might.
  *
- * Only ONE state is refused: every registered init-runner reports a version, and
- * every one of them is below the minimum. Everything else returns `null`.
+ * Refuses only when every registered init-runner reports a readable version
+ * below the minimum. An empty fleet is not refused (the queue's unroutable
+ * handling covers it), nor is a fleet with even ONE unreadable version: refusing
+ * suppresses every global workflow for the delivery, so it must rest on proof.
  *
- * An empty fleet is not refused — nothing is registered yet, an agent may
- * register a second from now, and the queue's own unroutable handling already
- * covers a round nobody picks up.
- *
- * A fleet containing even ONE agent whose version cannot be read is not refused
- * either, and the bar is deliberately that strict rather than "all unknown".
- * Refusing suppresses every global workflow for the delivery — the exact damage
- * this function exists to prevent — so it must rest on proof, not on ignorance
- * about part of the fleet. Getting it wrong in the other direction merely costs
- * a slow failure with a less useful message.
- *
- * Refusing here rather than at dispatch is deliberate. A too-old fleet does not
- * clear within a retry, so dispatching would spend two full wait ceilings of
- * inline webhook latency to reach the same verdict — and reach it with a
- * timeout message that says nothing about agent versions.
+ * Refusing before dispatch saves two full wait ceilings of inline webhook
+ * latency and yields a message that names agent versions.
  */
 export declare function unsupportedFleetReason(agentRegistry?: GlobalEvalAgentRegistry): string | null;
 /**
  * Narrow one wire verdict into a value the dispatch path can trust.
  *
- * The round-result schema proves only "array of objects with string keys" — its
- * `jobs` entries are a deliberate unvalidated pass-through of `LockJob`, whose
- * single source of truth is a TypeScript interface with no Zod mirror. So every
- * field is re-checked here rather than dereferenced: `run` is compared, not
- * coerced, and a generated job missing a usable `name` makes the whole candidate
- * indeterminate rather than being dropped silently. Fail-closed is the right
- * direction — a generator whose output we cannot read is a generator whose
- * verdict we cannot act on, and half-dispatching its jobs would be worse than
- * reporting that we could not decide.
+ * The round-result schema passes `jobs` through unvalidated (`LockJob` has no
+ * Zod mirror), so every field is re-checked: `run` is compared, not coerced, and
+ * a generated job without a usable `name` makes the whole candidate
+ * indeterminate. Fail-closed: half-dispatching unreadable output is worse.
  */
 export declare function narrowVerdict(raw: unknown, workflowName: string): GlobalEvalCandidateResult;
 /**
- * Cap on the joined reason string a decided-nothing round reports.
- *
- * The reasons are authored by an agent running author code, so their combined
- * length is unbounded — and this string travels verbatim into the commit
- * check's `output.summary`, which GitHub caps at 65535 characters. An overflow
- * is rejected with a 422 that the best-effort post swallows, so the check
- * disappears in exactly the case it exists for. Realistic reasons are one short
- * sentence each; this bound makes that structural instead of lucky.
+ * Cap on the joined reason string a decided-nothing round reports. Reasons come
+ * from author code, unbounded, and land in the commit check's `output.summary`,
+ * which GitHub caps at 65535 characters; an overflow 422 is swallowed by the
+ * best-effort post, so the check would vanish.
  */
 export declare const MAX_ROUND_REASON_CHARS = 4000;
 /**
  * Truncate `text` to at most `max` UTF-16 code units, marking that it was cut.
  *
- * Two edges the naive slice gets wrong, both of which matter because the result
- * is posted to an API with a hard character limit:
- *
- * - A `max` smaller than the marker would make `max - marker.length` negative,
- *   and appending the marker to an empty slice then returns a string LONGER
- *   than `max`. Such a `max` cannot carry both content and a marker, so the
- *   marker itself is truncated instead.
- * - Slicing at an arbitrary index can cut a surrogate pair in half, leaving a
- *   lone surrogate that is not valid text. The cut backs off by one unit when
- *   it lands between the halves of a pair.
+ * - A `max` no larger than the marker returns the truncated marker, never a
+ *   string longer than `max`.
+ * - The cut backs off one unit rather than split a surrogate pair.
  */
 export declare function truncateReasonText(text: string, max: number): string;
 /**
- * One round that produced no verdicts after every attempt, described well enough
- * for the caller to record it.
- *
- * There is exactly one of these per failed round — never one per candidate. The
- * round exists to collapse N candidate workflows into a single pre-run job, so
- * fanning its failure back out into N run rows and N checks would undo the fan-out
- * reduction the whole design is for. `workflowNames` is what makes the single
- * record honest: it names every workflow the failure suppressed.
+ * One round that produced no verdicts after every attempt. Exactly one per
+ * failed round, never one per candidate (the round exists to collapse N
+ * workflows into one job); `workflowNames` names every suppressed workflow.
  */
 export interface GlobalEvalRoundFailure {
     /** The last attempt's round-job run id — what an errored run row is written under. */
     runId: string;
-    /** Repo the suppressed workflows are authored in. */
     workflowRepoIdentifier: string;
     /** Every candidate workflow this round suppressed. */
     workflowNames: string[];
     /** The last attempt's error. */
     error: string;
-    /** How many attempts were made before giving up. `0` ⇒ never dispatched. */
+    /** `0` ⇒ never dispatched. */
     attempts: number;
     /**
-     * True when the round itself completed and decided some candidates, leaving
-     * only {@link workflowNames} undecided.
-     *
-     * Recorded as its own record rather than folded into a total failure because
-     * the two read differently to an author: a total failure means nothing from
-     * this repo ran, a partial one means their workflow specifically could not be
-     * decided while its neighbours ran fine. Without it, whether a broken filter
-     * is visible at all depends on how many unrelated global workflows happen to
-     * share a workflow repo — a per-candidate budget breach in a group of one
-     * produces a check, and the identical fault in a group of two produces
-     * nothing.
+     * True when the round completed but left only {@link workflowNames}
+     * undecided. Kept distinct from a total failure so a broken filter surfaces
+     * whether or not other global workflows share its workflow repo.
      */
     partial?: boolean;
 }
@@ -308,29 +234,17 @@ export interface GlobalEvalRoundsOutcome {
  * Run every eval round the candidate set needs and return one verdict per
  * candidate, plus one failure record per round that produced none.
  *
- * Rounds run one group at a time: a group is one dual checkout on one agent, and
- * a push touching several workflow repos is the uncommon case. A group whose
- * round fails marks only its own candidates indeterminate — one unreachable
- * workflow repo must not suppress the workflows living in another.
- *
- * The failures are returned rather than recorded here: this module owns the
- * partition, the grouping, and the dispatch-and-await, and has neither a
- * database handle nor the inbound provider bundle a commit check must be posted
- * through.
+ * Groups run sequentially (several workflow repos per push is uncommon). A
+ * failed group marks only its own candidates indeterminate. Failures are
+ * returned, not recorded: this module has no database handle nor the inbound
+ * bundle a commit check posts through.
  */
 export declare function runGlobalEvalRounds(args: GlobalEvalRoundArgs): Promise<GlobalEvalRoundsOutcome>;
 /**
- * Meter candidates a round never got to decide on.
- *
- * The caller's fail-closed paths — no pending-eval tracker, so a round could
- * never settle — return before {@link runGlobalEvalRounds} is reached, and they
- * suppress EVERY global workflow for that delivery. That is this subsystem's
- * most severe outcome, and without this call it appeared in none of its
- * metrics: one `logger.warn` was the whole record.
- *
- * Counted as `indeterminate` because that is exactly what happened — nothing
- * evaluated the workflows — which also keeps `candidates` equal to the sum of
- * the verdicts on every path.
+ * Meter candidates a round never got to decide on: the caller's fail-closed
+ * paths (no pending-eval tracker) return before {@link runGlobalEvalRounds} and
+ * suppress EVERY global workflow for the delivery. Counted `indeterminate`,
+ * which keeps `candidates` equal to the sum of the verdicts on every path.
  */
 export declare function recordUnrunCandidates(count: number): void;
 //# sourceMappingURL=global-eval-round.d.ts.map

package/dist/pipeline/global-round-hold.d.ts

@@ -10,9 +10,8 @@ export interface HoldGlobalEvalRoundsArgs {
     info: WebhookInfo;
     deps: ProcessingDeps;
     event: SimulatedEvent;
-    /** The candidates that needed the round. */
     candidates: readonly GlobalEvalCandidate[];
-    /** The source repository the event came from. */
+    /** The source repository. */
     repoIdentifier: string;
     /** The event's commit SHA. */
     ref: string;
@@ -30,12 +29,11 @@ export interface HoldGlobalEvalRoundsArgs {
     }>;
 }
 /**
- * Hold the evaluation round of every workflow repository among `candidates`.
- * Returns the id of each held run, in workflow-repository order.
+ * Hold the round of every workflow repository among `candidates`; returns the
+ * held run ids in workflow-repository order.
  *
- * One run per workflow repository, not per registered SHA: the release
- * re-evaluates a whole workflow repository, so two rows for one repository would
- * dispatch its workflows twice.
+ * One run per workflow repository, not per SHA: the release re-evaluates the
+ * whole repository, so two rows would dispatch its workflows twice.
  */
 export declare function holdGlobalEvalRounds(args: HoldGlobalEvalRoundsArgs): Promise<string[]>;
 //# sourceMappingURL=global-round-hold.d.ts.map

package/dist/pipeline/held-context-data.d.ts

@@ -88,11 +88,9 @@ interface LogFields {
 }
 /**
  * Resolve the merged variables and secrets of `entries`, then the container
- * registry credentials, writing each onto `into` as soon as it resolves. A
- * context that has no scope binding is named in a warning log line.
- *
- * Writing progressively keeps what already resolved when a later step throws,
- * which is what the dispatch path's catch relies on.
+ * registry credentials, writing each onto `into` as soon as it resolves, so the
+ * dispatch path's catch keeps what resolved before a later step throws. A
+ * context with no scope binding is named in a warning log line.
  */
 export declare function resolveContextJobData(args: {
     deps: ContextDataDeps;
@@ -127,9 +125,8 @@ export declare function withoutContextData(jobInput: QueuedJobInput, runWideFlat
  * The job's own contexts are not re-gated: it passed their rules, or its hold
  * was released. Throws when the record is malformed, the stores are
  * unavailable, a bound context is gone or replaced, or a lookup fails, so the
- * caller fails the job rather than dispatching it without the secrets it was
- * bound to. A registry-auth refusal leaves the job without registry
- * credentials, as dispatch does.
+ * caller fails the job rather than dispatching it without its bound secrets.
+ * A registry-auth refusal only drops registry credentials, as dispatch does.
  */
 export declare function resolveReleasedJobInput(args: {
     jobInput: QueuedJobInput;

package/dist/pipeline/held-round-registrations.d.ts

@@ -14,18 +14,15 @@ export interface HeldRoundRow {
 export declare function heldRoundWorkflowsOf(triggerDecision: string | null): string[] | undefined;
 /**
  * The workflow repository's organization-wide registrations for the held
- * event, as they were at the held commit.
+ * event, as they were at the held commit: every live registration of a covered
+ * workflow, one per source, as the pass the round was held from evaluates them.
  *
- * Throws, naming the workflow repository and the workflows, when the release
- * cannot run what the approver approved: the repository registers nothing any
- * more, its lock file at the held commit cannot be read, a workflow the round
- * covered has no live, enabled registration that still subscribes to the event,
- * or the lock file at the held commit does not define it as an
- * organization-wide workflow for the event. The release then fails the held run
- * with that reason and dispatches nothing — never a partial round.
- *
- * Every live registration of a covered workflow is returned, one per source
- * that registers it, as the pass the round was held from evaluates them.
+ * Throws, naming the repository and the workflows, when the release cannot run
+ * what the approver approved: the repository registers nothing any more, its
+ * lock file at the held commit cannot be read, a covered workflow has no live,
+ * enabled registration still subscribed to the event, or the held commit's
+ * lock file does not define it as organization-wide for the event. The release
+ * then fails the held run and dispatches nothing — never a partial round.
  *
  * The covered set is the one the hold recorded. A row held before that record
  * existed falls back to the held commit's round-shaped workflows, which cannot

package/dist/pipeline/install-gate.d.ts

@@ -2,17 +2,14 @@
  * The workflow install gate: the protection rules of every context a
  * workflow's `registries:` / `installEnv:` references name.
  *
- * Every context is evaluated before the gate decides, with the combination rule
- * the job-level multi-context gate uses: a reject from any context rejects,
- * whatever the others say. When none rejects and at least one holds, the gate
- * raises ONE hold whose requirement aggregates every context's rules, most
- * restrictive wins (`aggregateProtectionParams`): the reviewers of every held
- * context must approve, the longest wait timer applies. That hold records which
- * contexts held — its approval covers them — and which were admitted.
+ * Every context is evaluated before deciding, as on the job-level gate: any
+ * reject rejects. Otherwise any hold raises ONE hold aggregating every context's
+ * rules, most restrictive wins (`aggregateProtectionParams`: every held
+ * context's reviewers approve, the longest wait timer applies), and records
+ * which contexts held (covered by its approval) and which were admitted.
  *
  * The release gates again every context the approval did not cover, and
- * refuses when any recorded context now matches a different row than the one
- * the hold was raised against.
+ * refuses when a recorded context now matches a different row.
  */
 import { z } from 'zod';
 import type { ProtectionGateResult } from '@kici-dev/engine';
@@ -26,10 +23,7 @@ export declare const InstallGateContextSchema: z.ZodObject<{
     id: z.ZodString;
 }, z.core.$strip>;
 export type InstallGateContext = z.infer<typeof InstallGateContextSchema>;
-/**
- * What an install-gate hold records about its contexts. Stored with the held
- * dispatch, so the release knows which contexts the approval covers.
- */
+/** Stored with the held dispatch, so the release knows which contexts the approval covers. */
 export declare const InstallGateRecordSchema: z.ZodObject<{
     held: z.ZodArray<z.ZodObject<{
         name: z.ZodString;
@@ -67,24 +61,20 @@ interface GateInputs {
     protectionContext: JobDispatchContext;
 }
 /**
- * Evaluate every referenced context's rules and decide the install gate.
- *
- * Reject wins over hold, as on the job-level gate. A hold aggregates the rules
- * of every context, so its requirement is at least as strict as each held
- * context's own, and its record lists which contexts held and which passed.
+ * Evaluate every referenced context's rules and decide the install gate. Reject
+ * wins over hold; a hold's aggregated requirement is at least as strict as each
+ * held context's own.
  */
 export declare function gateInstall(inputs: GateInputs): Promise<InstallGateOutcome>;
 /**
  * Decide the install gate for a dispatch resumed from a released hold.
  *
- * The contexts the hold recorded as held are covered by its approval and are
- * not gated again: their reviewer and wait-timer rules are stateless and would
- * hold the approved run once more. Every other context is gated again, and any
- * verdict but pass rejects — a release never raises a second hold. A context
- * the hold recorded must still match the row it matched then.
+ * Held contexts are covered by the approval and skip the gate: their reviewer
+ * and wait-timer rules are stateless and would hold the approved run again.
+ * Every other context is gated, and any verdict but pass rejects. A recorded
+ * context must still match its recorded row.
  *
- * `releasedHold` comes from stored JSON, so it is parsed here: an absent or
- * malformed record covers no context, and every context is gated again.
+ * `releasedHold` is stored JSON: absent or malformed, it covers no context.
  */
 export declare function gateReleasedInstall(inputs: GateInputs & {
     releasedHold: unknown;

package/dist/pipeline/install-secrets-resolver.d.ts

@@ -7,31 +7,26 @@
  * `<context>:<secret-name>` syntax. The resolver:
  *
  *   1. Parses every qualified ref and groups by context name.
- *   2. Runs the install gate (`install-gate.ts`): every referenced context's
- *      protection rules (branch / trust / concurrency / reviewer / wait-timer)
- *      are evaluated before it decides. Any `reject` fails the whole workflow
- *      dispatch with a clear reason; otherwise any hold returns ONE structured
- *      `hold` decision, aggregated across the contexts, so the caller can
- *      pause the workflow dispatch as a workflow-scoped held run and resume it
- *      when the gate clears. The hold records which contexts held and which
- *      passed. On the resume path the caller sets `skipProtectionGate` and
- *      hands back that record: the contexts that held are covered by the
- *      approval, every other context is gated again, and a context that now
- *      matches a different row is refused.
+ *   2. Runs the install gate (`install-gate.ts`) over every referenced
+ *      context's protection rules. Any `reject` fails the whole workflow
+ *      dispatch; otherwise any hold returns ONE aggregated `hold` decision,
+ *      recording which contexts held and which passed, so the caller can park a
+ *      workflow-scoped held run. On resume the caller sets
+ *      `skipProtectionGate` and hands back that record: held contexts are
+ *      covered by the approval, every other context is gated again, and a
+ *      context that now matches a different row is refused.
  *   3. Resolves secrets per context via `secretResolver.resolveForContext`
- *      against the row step 2 gated (which writes its own audit log lines),
- *      so a context whose name is a glob pattern delivers its own bindings.
- *   4. Validates each registry URL scheme: HTTPS always allowed; `http://`
- *      allowed only for loopback / `*.local` hosts OR when the org operator
- *      has flipped `org_settings.allow_http_npm_registries=true`.
+ *      (which writes its own audit lines) against the row step 2 gated, so a
+ *      glob-pattern context delivers its own bindings.
+ *   4. Validates each registry URL scheme: HTTPS always; `http://` only for
+ *      loopback / `*.local` hosts or when
+ *      `org_settings.allow_http_npm_registries=true`.
  *   5. Strips the resolved auth entirely when the contributor-trust tier is
- *      not `trusted` (defense in depth: even if a misconfigured context
- *      lets an unknown contributor through the protection-pipeline trust
- *      gate, this strip ensures fork PRs never see registry tokens — the
- *      install fails naturally because the deps are unreachable).
+ *      not `trusted`: defense in depth, so fork PRs never see registry tokens
+ *      even through a misconfigured context; the install then fails on
+ *      unreachable deps.
  *
- * Pure helper: no imports of the dispatch giant. Tested in isolation in
- * `install-secrets-resolver.test.ts`.
+ * Pure helper: no imports of the dispatch giant.
  */
 import type { ApproverClause, LockRegistry } from '@kici-dev/engine';
 import type { TrustResolution } from '../security/trust-resolver.js';
@@ -56,16 +51,14 @@ export interface ResolveInstallSecretsArgs {
     secretResolver: SecretResolverApi | undefined;
     protectionContext: JobDispatchContext;
     /**
-     * Resume path: the dispatch continues past a released install-gate hold. The
-     * gate runs only for the contexts `releasedHold` does not cover. The
-     * untrusted-contributor strip still runs first.
+     * Resume path past a released install-gate hold: the gate runs only for
+     * contexts `releasedHold` does not cover. The untrusted strip still runs first.
      */
     skipProtectionGate?: boolean;
     /**
-     * Resume path: what the released hold recorded (`hold` decision's
-     * `record`). Its held contexts are covered by the approval; every recorded
-     * context must still match the same row. Read as stored JSON: absent or
-     * malformed, it covers no context.
+     * Resume path: the released hold's `record`. Its held contexts are covered by
+     * the approval; every recorded context must still match the same row. Absent
+     * or malformed stored JSON covers no context.
      */
     releasedHold?: InstallGateRecord;
 }
@@ -112,11 +105,8 @@ export declare function validateRegistryUrlScheme(url: string, allowHttp: boolea
     reason: string;
 };
 /**
- * The held-run `hold_type` for a gate outcome — the gate's own `holdType` when
- * it set one, otherwise the `HoldType` member its action implies. Column and
- * gate share one vocabulary, so nothing is translated here.
- *
- * Exported for tests.
+ * The held-run `hold_type`: the gate's own `holdType`, else the `HoldType` its
+ * action implies. Column and gate share one vocabulary. Exported for tests.
  */
 export declare function resolveHoldType(action: 'hold' | 'wait' | 'queue', raw: string | undefined): string;
 export declare function resolveInstallSecrets(args: ResolveInstallSecretsArgs): Promise<ResolveInstallSecretsResult>;