@kici-dev/orchestrator 0.16.0 → 0.18.0

package/dist/pipeline/process-webhook.d.ts

@@ -1,10 +1,6 @@
 /**
- * Webhook processing pipeline.
- *
- * Splits the historic 1339-line `processWebhook` into typed phase helpers so
- * each piece can be reasoned about independently. The main exported function
- * is a narrative orchestrator that threads the typed results through the
- * pipeline:
+ * Webhook processing pipeline. `processWebhook` (called from server.ts / app.ts)
+ * threads typed phase results through:
  *
  *   dedup -> provider -> normalize -> (cross-source dispatch | per-repo path)
  *   per-repo path: extract repo + creds -> trust resolution -> lock file fetch
@@ -12,9 +8,6 @@
  *     -> security hold + workflow modifications -> default-branch registration
  *     -> match triggers -> dispatch matched same-source -> dispatch globals
  *     -> forward traces & event log
- *
- * Internal helpers are pure phase functions returning typed results; the only
- * top-level export is `processWebhook`, callable from server.ts / app.ts.
  */
 import { z } from 'zod';
 import type { LockFile as FullLockFile, SimulatedEvent } from '@kici-dev/engine';
@@ -28,16 +21,15 @@ import { type WorkflowModification } from '../security/workflow-diff.js';
 import type { IdentityLink, PermissionLevel } from '../security/identity-link.js';
 import { type ProcessingDeps } from './processor.js';
 /**
- * Outcome of a single inbound-webhook ingestion. `duplicate` lets a direct-
- * ingress route return `{ duplicate: true }` to GitHub's Recent Deliveries
- * panel; `skipped` covers unknown provider / unknown event / no-repo paths;
+ * Outcome of one inbound-webhook ingestion. `duplicate` lets a direct-ingress
+ * route return `{ duplicate: true }` to GitHub's Recent Deliveries panel;
+ * `skipped` covers unknown provider / unknown event / no-repo paths;
  * `processed` means the pipeline matched and dispatched (or recorded a run).
  *
- * `queued` means the delivery is durably stored and its pipeline will run after
- * the response — the direct-ingress accept path's success outcome. It maps to
- * the same 202 `processed` always did, because from the sender's side both mean
- * "accepted, nothing more to do"; the distinction exists so the accept path can
- * be asserted on directly rather than through the HTTP status.
+ * `queued` (the direct-ingress accept path) means the delivery is durably
+ * stored and its pipeline runs after the response. It maps to the same 202 as
+ * `processed` — to the sender both mean "accepted" — and exists so the accept
+ * path can be asserted on directly rather than through the HTTP status.
  */
 export declare const WebhookIngestOutcome: z.ZodEnum<{
     duplicate: "duplicate";
@@ -50,23 +42,18 @@ export type WebhookIngestOutcome = z.infer<typeof WebhookIngestOutcome>;
 /**
  * Resolve the directory a `/kici approve` comment is authorized against.
  *
- * Two sources, and which one applies is decided by the caller that assembled
- * these deps rather than by the orchestrator's mode:
+ * The deps' assembler, not the orchestrator mode, picks the source:
  *
- * - `server.ts` holds the Platform-pushed directory in memory and refreshes it
- *   on every `trust_policy.update`, so it always supplies both fields. An
- *   in-memory directory therefore wins outright — reading the row instead
- *   would answer from a cache the push has already superseded.
- * - Every other assembly supplies neither. That includes the direct-ingress
- *   pipeline in `app.ts`, which is the only path an independent orchestrator
- *   has, and where the operator's own `kici-admin trust-policy directory-set`
- *   registrations live only in the row. Reading it per command is also what
- *   makes a registration take effect immediately rather than at the next
- *   restart.
+ * - `server.ts` supplies the Platform-pushed in-memory directory (refreshed on
+ *   every `trust_policy.update`), which wins outright — the row would be a
+ *   superseded cache.
+ * - Every other assembly supplies neither, including `app.ts`'s direct-ingress
+ *   pipeline (an independent orchestrator's only path), where
+ *   `kici-admin trust-policy directory-set` registrations live only in the row.
+ *   Reading it per command makes a registration take effect immediately.
  *
- * A failed read degrades to an empty directory: the commenter is not resolved
- * and the command is refused, which is the same fail-closed answer an absent
- * directory already gives.
+ * A failed read degrades to an empty directory, so the command is refused —
+ * the same fail-closed answer as an absent directory.
  */
 export declare function resolveApprovalDirectory(deps: ProcessingDeps, orgId: string): Promise<{
     identityLinks: IdentityLink[];
@@ -77,8 +64,23 @@ interface TrustOutcome {
     /** Default 'base' for PR events; trust resolution may override to 'head'. */
     lockFileSource: 'head' | 'base';
 }
-/** Whether an inbound event name is one of the pull-request events. */
 export declare function isPullRequestEvent(eventName: string): boolean;
+/**
+ * Phase D — Resolve the trust tier from the git ref alone. Every base-repo ref
+ * is trusted (only a write-or-higher contributor can put one there); a fork
+ * head ref is the sole untrusted case and resolves to `unknown`.
+ *
+ * For PR events the tier picks the lock-file source (trusted: head; fork:
+ * base) and the user-cache write scope (`deriveCacheRefScope`: `trusted` is
+ * org-shared, everything else per-run isolated).
+ *
+ * A PR resolves a tier only for a provider with `hasForkModel` (GitHub), whose
+ * fork signal comes from the forge's payload. universal-git's `isForkPR`
+ * compares repo names from fixed keys (`repo.full_name`, falling back to
+ * `full_name`, under `head` and `base`) that many forges omit, and yields
+ * `false` when either is absent — it fails toward trust, so it cannot carry
+ * HEAD-lock selection. Such a PR resolves no tier: base lock, isolated cache.
+ */
 export declare function resolveTrustForPR(args: {
     info: WebhookInfo;
     bundle: ProviderBundle;
@@ -86,50 +88,35 @@ export declare function resolveTrustForPR(args: {
     /** Raw webhook payload — read only to decide whether a push targets the default branch. */
     payload: Record<string, unknown>;
 }): Promise<TrustOutcome>;
-/** What one organization-wide dispatch pass produced. */
 interface GlobalDispatchOutcome {
     matchedCount: number;
     matchedRunIds: string[];
     /** One summary per global decision this pass reached, dispatched or excluded. */
     decisionSummaries: Record<string, unknown>[];
-    /**
-     * The workflow repository of every evaluation round this pass could not
-     * decide. Empty means every round the pass ran reached a verdict.
-     */
+    /** Workflow repo of every round this pass could not decide. */
     roundFailureWorkflowRepos: string[];
     /**
-     * Every workflow repository this pass actually evaluated: it examined that
-     * repository's registrations and reached a real outcome for each of them —
-     * dispatched, filtered out, or excluded by a verdict.
-     *
-     * The pass's POSITIVE signal, and the one a re-run gates its success check
-     * on. An empty `roundFailureWorkflowRepos` cannot carry that meaning: a pass
-     * with no registration index, no pending-eval tracker, or an event the trust
-     * policy held evaluates nothing and reports no failure either, so reading its
-     * silence as a clean verdict is the false assurance the round exists to
-     * remove.
+     * Every workflow repo this pass reached a real outcome for (dispatched,
+     * filtered out, or excluded by a verdict) — the POSITIVE signal a re-run gates
+     * its success check on. An empty `roundFailureWorkflowRepos` cannot carry it:
+     * a pass with no registration index, no pending-eval tracker, or a held event
+     * evaluates nothing and reports no failure either.
      */
     decidedWorkflowRepos: string[];
 }
 interface SecurityState {
     workflowModifications: WorkflowModification[];
     /**
-     * True when this PR changes `.kici/` workflow definitions. Reported, not
-     * enforced: the org trust policy is the fork switch, and it reads the fork
-     * signal and the tier — never this one.
+     * This PR changes `.kici/` workflow definitions. Reported, not enforced: the
+     * fork switch reads the fork signal and the tier, never this.
      */
     hasWorkflowModifications: boolean;
 }
 /**
- * Phase G — On PR events evaluated against the base lock file, detect workflow
- * modifications by diffing base vs. head and post a neutral informational check
- * (on its own dedicated check name).
- *
- * Detection and legibility only: the check tells a reviewer that this PR edits
- * the workflows it would run under. It feeds no policy decision — a PR that
- * edits `.kici/` from the base repo is written by a contributor who could
- * already push to it, and one from a fork is governed by the fork switch
- * whether or not it touches `.kici/`.
+ * Phase G — On PR events evaluated against the base lock file, diff base vs.
+ * head and post a neutral informational check for reviewers. It feeds no policy
+ * decision: a base-repo PR's author could already push `.kici/`, and a fork PR
+ * is governed by the fork switch either way.
  */
 export declare function applyWorkflowModificationsAndSecurityHold(args: {
     info: WebhookInfo;
@@ -145,13 +132,10 @@ export declare function applyWorkflowModificationsAndSecurityHold(args: {
     credentials: Record<string, unknown>;
 }): SecurityState;
 /**
- * A trust-policy verdict plus the fork switch it was decided under.
- *
- * The first arm is the short-circuit: a non-PR event, or a provider with no
- * fork model, decides `pass` before any policy is read, so there is no switch
- * to report. Every other verdict comes from an actual policy and carries it —
- * which is what lets the drop site read `forkSwitch` without a fallback that
- * would have to invent a source it never observed.
+ * A trust-policy verdict plus the fork switch it was decided under. The bare
+ * `pass` arm is the short-circuit (non-PR event, or no fork model) taken before
+ * any policy is read; every other verdict carries its switch, so the drop site
+ * reads `forkSwitch` without inventing a source.
  */
 export type SecurityPolicyDecision = {
     action: 'pass';
@@ -161,21 +145,14 @@ export type SecurityPolicyDecision = {
 /**
  * Evaluate the org trust policy for a PR event.
  *
- * Scoped to providers with a fork model (`bundle.hasForkModel`): a source
- * without one passes regardless of policy. That is not a trust claim about such
- * a source — a PR from a fork-less provider resolves no tier at all. It is that
- * the policy's one condition cannot be established for it: universal-git does
- * compute an `isForkPR`, but from payload keys many forges omit, and it reads
- * `false` when they are absent. Gating on a signal that fails toward trust
+ * A provider without `bundle.hasForkModel` passes regardless of policy. That
+ * is not a trust claim (its PRs resolve no tier); the policy's one condition
+ * cannot be established for it, as universal-git's `isForkPR` reads `false`
+ * when payload keys are absent. Gating on a signal that fails toward trust
  * would be worse than not gating.
  *
- * The policy read has two distinct failure shapes, and they get distinct
- * answers: no stored row is the unconfigured default (`FAIL_CLOSED_POLICY`),
- * while a read that THREW gets `READ_FAILURE_POLICY` — see there for why.
- *
- * The verdict carries the fork switch it was decided under, so the drop site
- * can explain itself. It is absent on the two short-circuit `pass` arms below,
- * which return before any policy is read.
+ * No stored row is the unconfigured default (`FAIL_CLOSED_POLICY`); a read
+ * that THREW gets `READ_FAILURE_POLICY` — see there for why.
  */
 export declare function evaluateSecurityPolicy(args: {
     deps: ProcessingDeps;
@@ -187,10 +164,9 @@ export declare function evaluateSecurityPolicy(args: {
     isForkPR: boolean;
 }): Promise<SecurityPolicyDecision>;
 /**
- * Phase J — After per-repo workflows are dispatched, query the global index
- * for workflows authored in OTHER repos that target this event type via
- * cross-repo `repos` patterns. Same-org scope picks up both same-source and
- * cross-source globals (cross-provider global workflows).
+ * Phase J — Dispatch global workflows authored in OTHER repos that target this
+ * event via `repos` patterns. Same-org scope covers same-source and
+ * cross-provider globals.
  */
 export declare function dispatchGlobalWorkflowsForOtherRepos(args: {
     info: WebhookInfo;
@@ -207,68 +183,57 @@ export declare function dispatchGlobalWorkflowsForOtherRepos(args: {
     /** The event's trust resolution, recorded on each global run. */
     trustResolution: TrustResolution | undefined;
     /**
-     * The event's trust-policy verdict. It applies to each global run exactly as
-     * it applies to the per-repository ones: a `hold` parks the run in the
-     * security queue next to the pull request's own runs.
+     * Applies to each global run as to per-repository ones: a `hold` parks it in
+     * the security queue next to the pull request's own runs.
      */
     securityDecision: TrustPolicyOutcome;
     /**
      * The source `dispatchCredentials` belongs to, when a cross-provider lock-file
-     * fallback made it a different source from `info.routingKey`. Persisted on a
-     * failed round's run row so its re-run can rebuild the same dispatch pair
-     * instead of handing this source's credentials to the inbound source's client.
+     * fallback made it differ from `info.routingKey`. Persisted on a failed
+     * round's run row so its re-run rebuilds the same dispatch pair instead of
+     * handing these credentials to the inbound source's client.
      */
     dispatchRoutingKey?: string;
-    /**
-     * Restrict the pass to global workflows authored in this repository. Set by
-     * the re-run of a failed evaluation round, which re-decides that round alone.
-     */
+    /** Only globals authored in this repo; a failed round's re-run re-decides that round alone. */
     onlyWorkflowRepo?: string;
     /**
-     * Dispatch only the candidates that need the evaluation round. Set by the
-     * re-evaluation of a failed or held round: the workflow repository's other
-     * candidates reached their outcome on the original delivery.
+     * Only candidates that need the round. Set when a failed or held round is
+     * re-evaluated: the repo's other candidates reached their outcome on the
+     * original delivery.
      */
     onlyRoundCandidates?: boolean;
     /**
-     * Set with `onlyRoundCandidates` when the round being re-evaluated is a held
-     * round whose security hold was just approved. That hold also held every
-     * result-aware-only candidate of the repository, so the release dispatches
-     * them. A failed round's re-run leaves it unset: the delivery already
-     * dispatched those candidates.
+     * Set with `onlyRoundCandidates` when a held round's security hold was just
+     * approved: that hold also held the repo's result-aware-only candidates, so
+     * the release dispatches them. A failed round's re-run leaves it unset (the
+     * delivery already dispatched them).
      */
     releasedHold?: boolean;
     /**
-     * Asked once the round has decided, before anything it admitted dispatches.
-     * Resolving false withdraws those verdicts: nothing the round admitted
-     * dispatches, and its workflow repositories are not reported as decided. Set
-     * by the release of a held round, whose run may have been cancelled while
-     * the round ran.
+     * Asked after the round decides, before anything it admitted dispatches.
+     * False withdraws the verdicts: nothing admitted dispatches and its repos are
+     * not reported decided. Set by a held round's release, whose run may have
+     * been cancelled while the round ran.
      */
     admitRoundVerdicts?: () => Promise<boolean>;
     /**
-     * The global registrations to evaluate, in place of the ones the index holds
-     * for this event. Set by the release of a held round, which evaluates the
-     * workflow repository as it was at the commit the hold recorded: the round,
-     * its partition, and the dispatch after it all read these entries.
+     * Registrations to evaluate instead of the index's. Set by a held round's
+     * release, which evaluates the workflow repo at the commit the hold recorded:
+     * the round, its partition and the dispatch all read these.
      */
     registrations?: readonly RegisteredWorkflow[];
 }): Promise<GlobalDispatchOutcome>;
 /**
- * Process a webhook through the complete pipeline, recording a `failed` event-log
- * row for a delivery the pipeline could not finish.
+ * Process a webhook through the complete pipeline, recording a `failed`
+ * event-log row for a delivery it could not finish.
  *
- * The row is the only per-delivery record of such a failure. Nothing the pipeline
- * decides after acknowledgement can reach the sender — `acceptWebhookDelivery`
- * answers 202 and runs this detached — and the dashboard's webhook-activity view
- * counts `event_log.status = 'failed'` for exactly this. Without the write that
- * count is structurally always zero, and a post-acknowledgement failure appears
- * in the orchestrator's own logs and nowhere a customer can see.
+ * That row is the only customer-visible record: `acceptWebhookDelivery` answers
+ * 202 and runs this detached, and the dashboard's webhook-activity view counts
+ * `event_log.status = 'failed'`.
  *
- * Best-effort and non-masking: the write is wrapped, and the original error is
- * rethrown either way. The delivery still reverts to `buffered` for the drain
- * pass to retry, so a redelivery that succeeds writes its own `processed` row
- * beside this one — the two are distinct rows, not a mutation.
+ * Best-effort and non-masking: the original error is rethrown either way. The
+ * delivery reverts to `buffered` for the drain to retry, and a successful
+ * redelivery writes its own `processed` row beside this one.
  */
 export declare function processWebhook(info: WebhookInfo, deps: ProcessingDeps): Promise<WebhookIngestOutcome>;
 export {};