@kici-dev/orchestrator 0.4.0 → 0.6.0

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

@@ -31,6 +31,19 @@ export interface SchedulerResult {
     action: 'dispatch' | 'skip';
     reason?: string;
 }
+/**
+ * Check if ALL upstreams of a job are satisfied.
+ * Returns { satisfied: true, action: 'dispatch' } when every upstream is
+ * terminal and its status is a member of the edge's run_on set. Returns
+ * { satisfied: true, action: 'skip', reason } when an upstream is terminal but
+ * its status is not in the edge's run_on set. Returns { satisfied: false } when
+ * any upstream is not yet terminal.
+ */
+export declare function checkAllUpstreamsSatisfied(db: Kysely<Database>, runId: string, jobName: string): Promise<{
+    satisfied: boolean;
+    action?: 'dispatch' | 'skip';
+    reason?: string;
+}>;
 /**
  * Insert dependency edges at run start for static-to-static needs.
  *

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

@@ -21,44 +21,101 @@ import type { LockFile as FullLockFile, SimulatedEvent } from '@kici-dev/engine'
 import type { OrchestratorMode } from '@kici-dev/engine';
 import type { WebhookInfo } from '../webhook/handler.js';
 import type { ProviderBundle } from '../provider-registry.js';
-import type { TrustResolution } from '../security/trust-resolver.js';
+import { type TrustResolution } from '../security/trust-resolver.js';
 import { type TrustPolicyOutcome } from '../security/trust-policy-gate.js';
 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;
  * `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.
  */
 export declare const WebhookIngestOutcome: z.ZodEnum<{
     duplicate: "duplicate";
     processed: "processed";
+    queued: "queued";
     shed: "shed";
     skipped: "skipped";
 }>;
 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:
+ *
+ * - `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.
+ *
+ * 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.
+ */
+export declare function resolveApprovalDirectory(deps: ProcessingDeps, orgId: string): Promise<{
+    identityLinks: IdentityLink[];
+    orgMemberPermissions: Map<string, PermissionLevel>;
+}>;
 interface TrustOutcome {
     trustResolution: TrustResolution | undefined;
     /** 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;
 export declare function resolveTrustForPR(args: {
     info: WebhookInfo;
-    deps: ProcessingDeps;
     bundle: ProviderBundle;
     event: SimulatedEvent;
+    /** Raw webhook payload — read only to decide whether a push targets the default branch. */
     payload: Record<string, unknown>;
-    resolvedOrgId: string;
-    repoIdentifier: string;
-    credentials: 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.
+     */
+    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.
+     */
+    decidedWorkflowRepos: string[];
+}
 interface SecurityState {
     workflowModifications: WorkflowModification[];
     /**
-     * True when this PR changes `.kici/` workflow definitions. A *signal*, not a
-     * decision — the trust-policy gate turns it into an outcome, which the
-     * dispatch gate then enforces as a held run or a rejected run.
+     * 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.
      */
     hasWorkflowModifications: boolean;
 }
@@ -67,10 +124,11 @@ interface SecurityState {
  * modifications by diffing base vs. head and post a neutral informational check
  * (on its own dedicated check name).
  *
- * Detection only. Whether a modification gates the run is the org trust policy's
- * call, evaluated in `evaluateSecurityPolicy` and enforced by the dispatch gate
- * — which creates the real `held_runs` row and posts the pending
- * "Held for approval" check, so `/kici approve` / reject / expiry can resolve it.
+ * 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/`.
  */
 export declare function applyWorkflowModificationsAndSecurityHold(args: {
     info: WebhookInfo;
@@ -88,11 +146,17 @@ export declare function applyWorkflowModificationsAndSecurityHold(args: {
 /**
  * Evaluate the org trust policy for a PR event.
  *
- * Scoped to providers with a contributor model — the same condition trust
- * resolution uses. A source without a `ContributorResolver` (generic, local,
- * universal-git) is trusted by construction, so it passes regardless of policy;
- * in particular, universal-git computes an `isForkPR` signal that must NOT gate
- * those sources.
+ * 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
+ * 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.
  */
 export declare function evaluateSecurityPolicy(args: {
     deps: ProcessingDeps;
@@ -102,23 +166,54 @@ export declare function evaluateSecurityPolicy(args: {
     mode: OrchestratorMode;
     trustResolution: TrustResolution | undefined;
     isForkPR: boolean;
-    hasWorkflowModifications: boolean;
 }): Promise<TrustPolicyOutcome>;
 /**
- * Process a webhook through the complete pipeline.
+ * 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).
+ */
+export declare function dispatchGlobalWorkflowsForOtherRepos(args: {
+    info: WebhookInfo;
+    deps: ProcessingDeps;
+    eventWithFiles: SimulatedEvent;
+    resolvedOrgId: string;
+    repoIdentifier: string;
+    ref: string;
+    dispatchBundle: ProviderBundle;
+    dispatchCredentials: Record<string, unknown>;
+    /** The inbound event's own bundle, used to post the globals-skipped check. */
+    bundle: ProviderBundle;
+    credentials: Record<string, unknown>;
+    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.
+     */
+    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.
+     */
+    onlyWorkflowRepo?: string;
+}): Promise<GlobalDispatchOutcome>;
+/**
+ * Process a webhook through the complete pipeline, recording a `failed` event-log
+ * row for a delivery the pipeline 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.
  *
- * Flow:
- *   1. Dedup + provider lookup -> contributor cache invalidation -> normalize
- *   2. Cross-source dispatch (generic webhook fan-out, optional)
- *   3. Extract repo + credentials, handle /kici approval comments
- *   4. Trust resolution for PR events
- *   5. Lock file fetch (with multi-provider fallback)
- *      - No lock file: dispatch global workflows for this event (same org) and return
- *   6. Workflow modification detection + security hold check status
- *   7. Default-branch registration
- *   8. Match triggers + dispatch matched same-source workflows
- *   9. Match + dispatch global workflows for OTHER repos
- *  10. Forward Platform trace + record event log
+ * 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.
  */
 export declare function processWebhook(info: WebhookInfo, deps: ProcessingDeps): Promise<WebhookIngestOutcome>;
 export {};