@kici-dev/orchestrator 0.5.0 → 0.6.0

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

@@ -0,0 +1,164 @@
+/**
+ * Invoke-gate executor.
+ *
+ * An invoke gate is a standard job whose only novel attribute is `invoke`: it
+ * never dispatches steps to an agent. When the gate becomes ready the
+ * orchestrator emits the gate's kici event at the source repo, matches the
+ * repo's opt-in subscribers, dispatches each as a normal in-repo run, and
+ * tracks each spawned run as a **proxy job** in the gate's own run.
+ *
+ * Correlation is a synchronous in-process match-and-dispatch — one orchestrator
+ * serves one org, so the executor matches + dispatches through an injected
+ * `summon` callback and gets the spawned run ids back directly. It ALSO persists
+ * `summoned_by_run_id` / `summoned_by_proxy_job` on each spawned run so proxy
+ * completion still resolves if the run finalizes on another HA instance.
+ *
+ * The gate itself is the aggregating graph node: downstream `needs` edges point
+ * at the gate, and its proxies are its fan-out children (`base_job_name` = the
+ * gate name). A zero-subscriber emit fails the gate by default; `optional: true`
+ * makes it a green skip.
+ */
+import { ExecutionJobStatus } from '@kici-dev/engine';
+import type { LockInvoke, LockJob } from '@kici-dev/engine';
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import type { ExecutionTracker } from '../reporting/execution-tracker.js';
+/**
+ * The invoke parameters carried from a gate's lock job to its (possibly deferred)
+ * execution. Persisted on the pending job context so a gate released later — or
+ * after a crash-recovery restore — still summons instead of reaching an agent.
+ */
+export interface InvokeGateParams {
+    event: string;
+    payload?: Record<string, unknown>;
+    /** Require-by-default: false fails the gate on zero subscribers. */
+    optional: boolean;
+    /** Fan-out concurrency width applied to the gate's proxy children. */
+    maxParallel?: number;
+    /** Fan-out fail-fast policy applied to the gate's proxy children. */
+    failFast?: boolean;
+    /** The gate's own wall-clock timeout in ms (orchestrator-swept). */
+    timeoutMs?: number;
+}
+/** Extract the invoke parameters from a lock job, or undefined when it is not a gate. */
+export declare function invokeParamsFromLockJob(lockJob: Pick<LockJob, 'invoke' | 'maxParallel' | 'failFast' | 'timeout'> & {
+    invoke?: LockInvoke;
+}): InvokeGateParams | undefined;
+/** True when a lock job is an invoke gate (carries an `invoke` action). */
+export declare function isInvokeGate(lockJob: Pick<LockJob, 'invoke'>): boolean;
+/**
+ * A summon that was REFUSED, as opposed to one that matched nothing.
+ *
+ * The two are not the same verdict and must never render the same. A gate
+ * carrying `optional: true` treats zero summoned runs as a green skip, so a
+ * refusal returned as `[]` would report success for work that was declined.
+ * Throwing this makes the confusion unrepresentable: {@link runInvokeGate}
+ * fails the gate job with the reason, whatever order its own checks run in.
+ */
+export declare class SummonRefusedError extends Error {
+    constructor(reason: string);
+}
+/** One source-repo run summoned by an invoke gate. */
+export interface SummonedRun {
+    /** The spawned run's id. */
+    runId: string;
+    /** The source repo the run belongs to (`owner/repo`). */
+    repo: string;
+    /** The subscribing workflow's name. */
+    workflow: string;
+}
+/** Arguments to the injected `summon` callback. */
+export interface SummonArgs {
+    event: string;
+    payload?: Record<string, unknown>;
+    sourceRepo: string;
+    /** The chain depth to stamp on the summoned runs (already incremented). */
+    chainDepth: number;
+    /** The summoning gate's run id — tag each spawned run so its proxy resolves. */
+    summonedByRunId: string;
+}
+/** Dependencies for {@link runInvokeGate}. */
+export interface InvokeGateDeps {
+    db: Kysely<Database>;
+    /** Insert the proxy rows + mark the gate terminal on a zero-match emit. */
+    executionTracker: Pick<ExecutionTracker, 'addJobsToRun' | 'onJobStatus' | 'reconcileSummonedRunIfTerminal'>;
+    /**
+     * Match the source repo's subscribers to `event`, dispatch each as a normal
+     * in-repo run, and return the spawned run ids. Implemented at the composition
+     * root, where it reuses the orchestrator's event match + trust-policy path.
+     *
+     * An empty array means the event matched no subscriber — a real outcome a
+     * gate may declare `optional`. A REFUSAL raises
+     * {@link SummonRefusedError} instead, so the two can never be read as the
+     * same thing.
+     */
+    summon: (args: SummonArgs) => Promise<SummonedRun[]>;
+    /** Max chain depth allowed for a summon (the circuit breaker's bound). */
+    maxChainDepth: number;
+}
+/** Arguments identifying the gate to run. */
+export interface RunInvokeGateArgs {
+    runId: string;
+    gateJobId: string;
+    gateJobName: string;
+    event: string;
+    payload?: Record<string, unknown>;
+    /** When true, a zero-subscriber emit succeeds; when false it fails the gate. */
+    optional: boolean;
+    sourceRepo: string;
+    chainDepth: number;
+    /** Fan-out concurrency width stamped on the proxy children (`maxParallel`). */
+    maxParallel?: number;
+    /** Fan-out fail-fast policy stamped on the proxy children (`failFast`). */
+    failFast?: boolean;
+}
+/**
+ * Aggregate an invoke gate's status from its proxies' terminal statuses. The
+ * gate stays open (`allTerminal: false`) until every proxy is terminal; then it
+ * is `failed` if any proxy is a failure, else `success`. Pure — the tracker's
+ * aggregation hook drives the DB reads and the gate transition.
+ */
+export declare function aggregateGateStatus(proxyStatuses: readonly string[]): {
+    allTerminal: boolean;
+    status?: ExecutionJobStatus;
+};
+/**
+ * The message a gate naming a reserved event fails with.
+ *
+ * Exported so the gate executor and its test state the same string, and so the
+ * SDK-side error can be compared against it.
+ */
+export declare function reservedEventMessage(event: string, prefix: string): string;
+/** The message a require-by-default gate fails with when nothing subscribes. */
+export declare function zeroSubscriberMessage(sourceRepo: string, event: string): string;
+/**
+ * The proxy job name for a summoned run — the gate name, a `repo:workflow`
+ * variant, and the summoned run id. The run id makes the name **unique per run**:
+ * two summoned runs with the same `repo`+`workflow` (duplicate registrations)
+ * would otherwise share one `job_name`, so the mirror's `job_name` lookup would
+ * resolve one proxy and leave the other hanging. The human-readable label for the
+ * graph is carried separately in `variant_label` (`repo:workflow`).
+ */
+export declare function proxyJobName(gateJobName: string, run: SummonedRun): string;
+/**
+ * Run an invoke gate: summon the source repo's subscribers and create one proxy
+ * child per spawned run. A zero-subscriber emit terminalizes the gate — failed
+ * by default, success under `optional`. When the chain-depth bound is reached
+ * the gate fails without summoning, so an invoke chain cannot loop.
+ */
+export declare function runInvokeGate(deps: InvokeGateDeps, args: RunInvokeGateArgs): Promise<void>;
+/** Dependencies for {@link releaseInvokeGate}. */
+export interface ReleaseInvokeGateDeps {
+    db: Kysely<Database>;
+    executionTracker: ExecutionTracker;
+    invokeGateDeps: InvokeGateDeps;
+}
+/**
+ * Release a ready invoke gate: swap its synthetic needs-pending row for a real
+ * `gate` job row, then run the gate executor. Reads the summoning run's source
+ * repo and chain depth from `execution_runs` (the chain depth bounds recursion).
+ * Shared by the needs-release path (`dispatchReadyJob`) and the root-gate
+ * post-registration nudge, so both go through one code path.
+ */
+export declare function releaseInvokeGate(deps: ReleaseInvokeGateDeps, runId: string, gateJobName: string, params: InvokeGateParams): Promise<void>;
+//# sourceMappingURL=invoke-gate.d.ts.map

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,9 +21,10 @@ 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-
@@ -45,27 +46,76 @@ export declare const WebhookIngestOutcome: z.ZodEnum<{
     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;
 }
@@ -74,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;
@@ -95,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;
@@ -109,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 {};