@kici-dev/orchestrator 0.5.0 → 0.6.1

package/dist/pipeline/dispatch-matched-workflow.d.ts

@@ -16,12 +16,14 @@
 import { ExecutionJobStatus, InitFailureCategory, CacheRefScope, HoldScope, TriggerSource } from '@kici-dev/engine';
 import type { LabelMatcher, LockWorkflow, LockJob, ApprovalRequirement, HostTargetSelector, SimulatedEvent, WorkflowDecision, MaterializedJob, ResolvedHostAgent, HostFacts } from '@kici-dev/engine';
 import { type HostRosterStore } from '../agent/host-roster.js';
+import { gatherInvokeResults } from '../orchestrator-core.js';
 import type { WebhookInfo } from '../webhook/handler.js';
 import type { ProviderBundle } from '../provider-registry.js';
 import type { Dispatcher } from '../agent/dispatcher.js';
 import type { QueuedJobInput } from '../queue/job-queue.js';
 import type { TrustResolution } from '../security/trust-resolver.js';
 import type { TrustPolicyOutcome } from '../security/trust-policy-gate.js';
+import type { CreateHeldRunData } from '../contexts/held-runs.js';
 import { type ProcessingDeps } from './processor.js';
 /**
  * Trusted refs (write+ contributor, default-branch) get the org-shared cache
@@ -85,6 +87,21 @@ export interface WorkflowDispatchContext {
         };
     };
     resolvedOrgId: string;
+    /**
+     * Siblings admitted against a context concurrency limit during THIS dispatch
+     * pass, keyed by {@link concurrencyAdmissionKey}.
+     *
+     * The gate's running count counts jobs whose status is already `running`, so
+     * it cannot see anything this pass has only just admitted. Without this tally
+     * every child of a fan-out is evaluated against that one blind value and all
+     * N are admitted against a single slot.
+     *
+     * Created lazily on first use and dropped with the ctx. It is per-pass state,
+     * never persisted and never shared between passes; two concurrent passes
+     * still race, which is accepted — this is a throughput control, not an
+     * isolation boundary.
+     */
+    concurrencyAdmissions?: Map<string, number>;
     workflow: LockWorkflow;
     decision: WorkflowDecision;
     runId: string;
@@ -106,6 +123,79 @@ export interface WorkflowDispatchContext {
     triggeredByAgentLabel?: string | null;
     /** True only when invoked from the cross-source dispatch shell. */
     crossSource: boolean;
+    /**
+     * Trigger-event string for the run's `triggerEvent`, stated explicitly rather
+     * than derived from `event.type`.
+     *
+     * The internal-event adapter needs this because a user `kiciEvent()` renders
+     * two different values: `jobConfig.event.type` is the literal `kici_event`,
+     * while the run carries the raw event name. `event.type` carries the former,
+     * so the latter has to be stated.
+     *
+     * Absent ⇒ the value derived from the event, unchanged for the webhook,
+     * CLI-remote-run and resume callers.
+     */
+    triggerEventOverride?: string;
+    /**
+     * The exact `jobConfig.event` envelope to ship, stated explicitly instead of
+     * spreading the `SimulatedEvent` this dispatch matched against.
+     *
+     * Same reason as `triggerEventOverride`: the matcher's event shape and the
+     * shape user code observes are not the same object. `SimulatedEvent` requires
+     * `targetBranch` and carries `changedFiles`; the envelope omits both. An
+     * internally triggered run genuinely has no changed files, and its branch is
+     * provenance the orchestrator evaluates (the trigger matcher and the context
+     * branch gate) rather than a field user code asked for — the envelope becomes
+     * `RuleContext.event` on the agent and the `event` half of
+     * `buildConcurrencyGroupContext`, so publishing the branch would silently
+     * re-key the documented `ctx.event.targetBranch ?? 'default'` concurrency
+     * group of every existing internal workflow.
+     *
+     * Absent ⇒ the envelope derived from the event, unchanged for the webhook,
+     * CLI-remote-run and resume callers.
+     */
+    eventEnvelopeOverride?: Record<string, unknown>;
+    /**
+     * Chain depth to stamp on the started run. A run summoned by an invoke gate
+     * carries its summoner's depth + 1, which is what bounds the chain-depth
+     * circuit breaker. Absent ⇒ 0, the column default (a webhook-triggered run
+     * starts a chain).
+     *
+     * Threading this is load-bearing: the breaker fails OPEN if the value is
+     * lost, so an unbounded summon recursion would go undetected. It is stamped
+     * as soon as the run row exists, because `releaseInvokeGate` reads the column
+     * back at gate-release time — which happens inside this same dispatch.
+     */
+    chainDepth?: number;
+    /**
+     * Marks a run dispatched by a failure-lifecycle trigger, so its own
+     * completion is excluded from batch accumulation and a broken notifier
+     * cannot re-trigger itself (`EventRouter.isFailureLifecycleRun`).
+     *
+     * Persisted as a field INSIDE the `trigger_decision` JSON blob, merged onto
+     * the decision summary rather than replacing it.
+     */
+    dispatchedByFailureLifecycle?: boolean;
+    /**
+     * Marks a run the orchestrator triggered itself — a schedule fire, a
+     * workflow/job completion, a failure batch, a user `kiciEvent()`, or an
+     * invoke-gate summon — as opposed to one a provider webhook triggered.
+     *
+     * Read by the context branch gate, and by nothing else. Such a run usually
+     * carries a real branch in `event.targetBranch` — a schedule fire presents
+     * its registration's default branch, every other internal trigger inherits
+     * the branch of the run that emitted its event — and the gate matches it like
+     * any other run's. The flag singles out the runs whose `targetBranch` is
+     * EMPTY: a failure batch or a scaler event (many runs behind it, or none), a
+     * registration whose default branch has never been captured, an emitting run
+     * that is gone. The gate rejects those naming that cause, instead of quoting
+     * an empty value as though it were a branch name. It does NOT weaken the
+     * gate — a run with no branch cannot satisfy a restriction, `*` included.
+     *
+     * Absent ⇒ webhook-triggered, unchanged for the webhook, CLI-remote-run and
+     * resume callers.
+     */
+    internallyTriggered?: boolean;
     /**
      * Outcome of the org trust-policy gate for this PR event. `pass` dispatches
      * normally; `hold` parks the run in the security queue; `reject` fails it
@@ -137,6 +227,19 @@ export interface WorkflowDispatchContext {
      * explicitly rather than leave it `pending` forever.
      */
     runRegisteredBeforeDispatch?: boolean;
+    /**
+     * Set once `setupDispatchContext` has posted this dispatch's queued
+     * `kici/<workflow>` check and one `kici/<workflow>/job/<name>` per static job.
+     *
+     * Those checks go up BEFORE anything decides whether the run will start, so
+     * every exit after setup owes them a conclusion. The named early exits each
+     * complete their own; a THROW does not, and nothing else can — the workflow
+     * check keys off a run whose jobs never registered, and the stale sweep only
+     * touches check runs already `in_progress`. Left alone they stay `queued`
+     * forever, which on a pull request is a check that never finishes and a
+     * branch-protection blocker.
+     */
+    pendingChecksPosted?: boolean;
     /** Composite dedup key `${info.deliveryId}:${reg.id}` (cross-source only). */
     crossSourceDeliveryId?: string;
     /**
@@ -193,6 +296,14 @@ export interface WorkflowDispatchContext {
      */
     dispatchInputs?: Record<string, unknown>;
 }
+/**
+ * The minimal slice of a dispatch context the needs catch-up + ready-recompute
+ * helpers read. Both the per-repository `WorkflowDispatchContext` and the
+ * global-workflow dispatch path (which builds its own inputs and never
+ * constructs a full `WorkflowDispatchContext`) can drive the needs scheduler
+ * through this narrow shape.
+ */
+export type NeedsSchedulingContext = Pick<WorkflowDispatchContext, 'deps' | 'runId'>;
 /**
  * Build the dispatch-envelope event, carrying the orchestrator's already-fetched
  * changed-files list + status from `eventWithFiles` as a fast-path (the agent
@@ -229,8 +340,6 @@ export interface DispatchMatchedWorkflowOptions {
      * so secrets resolve directly and the dispatch flows into job dispatch.
      */
     skipInstallProtectionGate?: boolean;
-    /** The released held-run id being resumed (for logging / correlation). */
-    reuseHeldRunId?: string;
     /**
      * The run id whose `held` execution_runs row should be reused (flipped to
      * pending) instead of inserting a fresh row.
@@ -312,6 +421,16 @@ interface JobEnvData {
     jobEnv?: Record<string, string>;
     jobSecrets?: Record<string, string>;
     jobNamespacedSecrets?: Record<string, Record<string, string>>;
+    /**
+     * Registry credentials for this job's container image, resolved from the
+     * secret NAMES the lock carries. Lifted to a top-level dispatch field (and
+     * stripped from jobConfig) before the message reaches the agent.
+     */
+    containerRegistryAuth?: {
+        username: string;
+        password: string;
+        serveraddress: string;
+    };
     held?: boolean;
     /**
      * Pending approval hold for this job, set when a context policy or
@@ -320,6 +439,13 @@ interface JobEnvData {
      * can re-dispatch after approval.
      */
     approvalHold?: PendingApprovalHold;
+    /**
+     * A non-reviewer hold (security / wait-timer / concurrency-queue) decided by a
+     * context's protection rules. Carried rather than written on the spot so
+     * `holdJobForApproval` can create the row and the job's resume path in ONE
+     * transaction — the reviewer branch uses `approvalHold` for the same purpose.
+     */
+    nonApprovalHold?: CreateHeldRunData;
     rejected?: boolean;
     rejectReason?: string;
     pendingInit?: boolean;
@@ -350,27 +476,14 @@ interface JobEnvEvalResult {
     runContextName: string | undefined;
     runContextId: string | undefined;
 }
-interface DispatchedJob {
-    jobId: string;
-    jobName: string;
-    runsOnLabels?: string[];
-    matrixValues?: Record<string, unknown>;
-    baseJobName?: string;
-    variantKind?: string;
-    variantLabel?: string;
-    /** Held by the rolling-wave gate (a fan-out child beyond maxParallel). */
-    waveGated?: boolean;
-    /** The base's wave width, stamped on every child of a bounded wave. */
-    waveMaxParallel?: number;
-    /** The base's failFast policy, stamped on every child of a bounded wave. */
-    waveFailFast?: boolean;
-    /** Ordered bound-context names persisted on the job row (multi-env jobs). */
-    contexts?: string[];
-    /** Bound contexts skipped on a test run (non-test / unconfigured). */
-    skippedContexts?: string[];
-    /** User-visible warning naming the skipped test-run contexts. */
-    envWarning?: string;
-}
+/**
+ * Synthetic job-id prefix every needs-gate site stamps on a job it holds back.
+ * The release path (`dispatchReadyJob` → `findSyntheticJobId` → `addJobsToRun`)
+ * keys on it, so it is load-bearing rather than cosmetic — which is what makes
+ * it a sound way to recover the gated set without threading a parallel list
+ * through both the single-orchestrator and cluster dispatch paths.
+ */
+export declare const NEEDS_PENDING_JOB_ID_PREFIX = "needs-pending-";
 interface RejectedJob {
     jobId: string;
     jobName: string;
@@ -384,6 +497,32 @@ interface RejectedJob {
      */
     terminalStatus?: ExecutionJobStatus;
 }
+/**
+ * Whether this dispatch must run a `__build__` job before its real jobs.
+ *
+ * Either cache missing is a reason to build. The two are keyed on different
+ * things — the source cache on the workflow source's contentHash, the dep cache
+ * on the lockfile hash — so they miss independently, and a dependency bump is
+ * exactly the case that leaves the source warm and the deps cold. Gating only on
+ * the source miss made that state permanent: no build job ran, so nothing ever
+ * uploaded the dep tarball, so every agent fell back to installing from the
+ * registry on every job — and an agent with no route to that registry (a
+ * cloud-hosted one-shot agent, an air-gapped runner) could not run the job at
+ * all. The `__build__` job already carries `buildSourceNeeded` /
+ * `buildDepsNeeded` separately and the agent already honors both, so a
+ * deps-only build was implemented and simply unreachable.
+ *
+ * A hash is required alongside its miss: with no hash there is no cache key to
+ * write, so building would produce an artifact nothing could ever look up.
+ */
+export declare function buildIsNeeded(args: {
+    /** False when there is nothing to cache into (no bundle, no coordinator, …). */
+    cacheInfraAvailable: boolean;
+    sourceHit: boolean;
+    contentHash: string | undefined;
+    depHit: boolean;
+    lockfileHash: string | undefined;
+}): boolean;
 /**
  * Build the QueuedJobInput for a synthetic `__bringup__` job: the orchestrator
  * dispatches one per declared-but-un-agented `includeUninitialized` child to an
@@ -435,6 +574,28 @@ export declare function runsOnSelectorsForLockJob(lockJob: {
     runsOn?: readonly LabelMatcher[];
     excludeLabels?: readonly LabelMatcher[];
 }): JobRoutingSelectors;
+/**
+ * Runtime facts a job's own shape demands of the host that runs it.
+ *
+ * Only a `container.dockerfile` job gets one. Building shells out to a
+ * `docker` / `podman` CLI, so a host without one cannot run the job at all, and
+ * the agent self-reports `kici:runtime:container-build` when it has one.
+ *
+ * A job that names a finalized `image` deliberately gets NOTHING added. Adding
+ * an implicit requirement to jobs that already work is how container jobs were
+ * stranded once before: they had been running fine, and a routing gate the
+ * orchestrator could not actually evaluate made them match nothing. A dockerfile
+ * job is new, so requiring the fact strands no existing workflow — and an agent
+ * old enough not to report the fact is an agent that cannot build anyway.
+ *
+ * Applied when matching REGISTERED agents (the dispatcher), and deliberately
+ * NOT when consulting the scaler. A scaler backend is chosen by exact label-set
+ * containment, so a required label the operator never wrote in a pool's label
+ * set matches no backend at all — the job would be stranded `queued-no-backend`
+ * rather than spawned. The pool's hosts are the operator's to describe; what an
+ * agent can actually do is known only once it registers and says so.
+ */
+export declare function requiredRuntimeLabelsFor(container: unknown): string[];
 /**
  * Resolve a generated job's single bare-`agentId` `runsOn` into a host pin.
  *
@@ -502,6 +663,19 @@ export declare function findInvalidApprovalTimeout(workflow: LockWorkflow): {
  * no host facts to scope by.
  */
 export declare function hostCtxFromMat(mat: MaterializedJob): HostFacts | undefined;
+/**
+ * Key for the in-pass admission tally.
+ *
+ * The org id is part of the key so the tally inherits the cross-tenant scoping
+ * the running-count query already enforces on `execution_runs.customer_id`: a
+ * context name shared across tenants must not leak concurrency between them.
+ * One dispatch pass carries a single `resolvedOrgId`, so the org component is a
+ * standing invariant rather than a live discriminator — it is here so a future
+ * pass dispatching for more than one org cannot silently merge two orgs'
+ * tallies. `JSON.stringify` over the pair is used rather than string
+ * concatenation so no separator character can make two different pairs collide.
+ */
+export declare function concurrencyAdmissionKey(orgId: string, concurrencyGroup: string): string;
 /**
  * Phase D — evaluate static jobs' context data, queue deferred-init jobs
  * for jobs with dynamic fields, and pick the first `runContextName` for
@@ -512,6 +686,85 @@ export declare function evaluateJobContexts(args: {
     setup: DispatchSetup;
     buildPrep: BuildPrepResult;
 }): Promise<JobEnvEvalResult>;
+/**
+ * Refuse a Dockerfile build on an untrusted ref, unless the org opted in.
+ *
+ * A job may build its container image from a Dockerfile in the repository. That
+ * build runs arbitrary `RUN` commands on the agent host's daemon, OUTSIDE the
+ * hardened posture the job's own steps get — `docker build` cannot be
+ * capability-restricted the way a container run can. So an untrusted ref (a fork
+ * PR, an unresolved contributor, or an internally-triggered run without a
+ * trusted emitter — the same classification the user-cache write scope uses)
+ * reaches it only where the operator said so.
+ *
+ * "Without a trusted emitter" covers both halves of the internal case: a
+ * `kiciEvent()` subscriber that inherited a `known` / `unknown` tier, and one
+ * that inherited nothing at all (no emitting run, no persisted tier, a lookup
+ * that failed) — the strict fallback, which is not an "untrusted emitter".
+ *
+ * Enforced here, at dispatch, and nowhere else: the agent applies only what
+ * dispatch authorized, exactly as it does for the sandbox capability grant. Deny
+ * is loud and total — the build never starts.
+ */
+export declare function resolveWorkflowDockerfileBuilds(workflow: LockWorkflow, opts: {
+    scope: CacheRefScope;
+    allowUntrusted: boolean;
+}): {
+    allowed: true;
+} | {
+    denied: {
+        reason: string;
+    };
+};
+/**
+ * Post the pending `KiCI Security` status, and record on every hold that gates
+ * this commit's check that the commit now carries it.
+ *
+ * The record is what a settle reads to decide whether a hold has a check to
+ * terminalize. Deriving that from the row's shape instead answers what the code
+ * INTENDED, and `postCheckStatus` CREATES the named run when it finds none — so
+ * a post the provider refused left a shape saying "posted" and a settle that
+ * put a completed `KiCI Security` run on a commit which never had one.
+ *
+ * `heldRunIds` is plural because the commit carries ONE check run: a job held on
+ * two independent requirements has both of them gating it, and marking only the
+ * one whose summary was rendered would let the first to end resolve a check the
+ * other is still gating.
+ *
+ * Awaited, where the post used to be fire-and-forget: the record can only be
+ * written once the provider has accepted, and a record racing the settle is a
+ * record the settle may not see. A failed post is still swallowed — the dispatch
+ * loop is never blocked by a provider error — but the round-trip is now
+ * serial and inside the per-job loop, so N held jobs cost N of them.
+ *
+ * On success and then a failed record the commit keeps a pending check the
+ * settle will decline to close. That is the residue the fire-and-forget post
+ * could already leave, now narrowed to whatever can fail between the accepted
+ * post and ONE statement. The record is therefore retried
+ * {@link PENDING_CHECK_MARK_ATTEMPTS} times before it is given up on, which
+ * closes the half of that window the doc above names as reachable without a
+ * process dying — a lost connection, a statement timeout, a deadlock. What is
+ * left is a process death inside the retry window, and nothing in reach closes
+ * that: a sweeper would have to ask the provider whether the check exists, and
+ * `CheckStatusPoster` has no read method. Adding one means a new method on a
+ * compat-protected engine interface, every implementation and every hand-built
+ * bundle, to recover a window measured in milliseconds — against a recovery
+ * that already exists, since pushing a new commit re-posts. A sweeper without
+ * that read could only guess, and a wrong guess FABRICATES a check, which is
+ * the worse direction either way: a fabricated failing check on a pull request
+ * is worse than a stuck one.
+ *
+ * The record is one statement over every id, never one per id. A partial mark
+ * would leave an unmarked hold uncounted by the contention query, so the first
+ * hold to end would terminalize the shared check while the other still gates
+ * the job — a fabricated PASSING check, the worse direction, and reachable
+ * without any process dying. See `markPendingCheckPosted`.
+ */
+/**
+ * How many times {@link postPendingHoldCheck} tries to record an accepted post
+ * on the hold rows before giving up and leaving the check unclosable.
+ */
+export declare const PENDING_CHECK_MARK_ATTEMPTS = 3;
 /**
  * Open the needs gate for any job whose upstreams already reached terminal
  * before this run's edges existed.
@@ -543,8 +796,12 @@ export declare function evaluateJobContexts(args: {
  * bypass the `maxParallel` window.
  */
 export declare function catchUpNeedsGatedJobs(args: {
-    ctx: WorkflowDispatchContext;
-    dispatchedJobs: readonly DispatchedJob[];
+    ctx: NeedsSchedulingContext;
+    dispatchedJobs: readonly {
+        jobId: string;
+        jobName: string;
+        waveGated?: boolean;
+    }[];
 }): Promise<void>;
 /** Why an init result must not lead to a dispatch. */
 export declare enum InitDispatchSuppression {
@@ -562,10 +819,24 @@ export declare enum InitDispatchSuppression {
  * predates the filter reports no verdict at all — reading that absence as
  * "suppress" would silently stop every dispatch it handles.
  *
- * `Gated` is belt-and-braces. `evaluateJobContexts` gives a rejected or held job
- * no init job in the first place, so this is unreachable today; if it ever
- * becomes reachable, dispatching would mean going straight past a protection
- * rule or an approval hold, which is the one outcome worth a redundant check.
+ * `Gated` covers a job that is already rejected or held. Its two halves now have
+ * very different reachability, and saying so is the point of this paragraph:
+ *
+ * - **rejected** is live and load-bearing. The flow-back consumes it (that is
+ *   the `suppression === Gated && jobEnvData.rejected` branch) to stop a job its
+ *   context rules rejected from dispatching.
+ * - **held** is NOT consumed here any more. A held job deliberately DOES get an
+ *   init job — nothing else can resolve a dynamic value, so suppressing the
+ *   round would make the job undispatchable rather than merely gated. The
+ *   flow-back handles it after resolution instead, routing it to
+ *   `holdExecutionAfterInit` so the hold and its resolved dispatch context are
+ *   stored together.
+ *
+ * So do not read this as a guarantee that a held job cannot dispatch: that
+ * guarantee lives at the call site's `jobEnvData.held` branch, and — for the
+ * needs-scheduler and cluster paths, which reach a job by other routes — in
+ * `dispatchReadyJob`'s pending-hold check and the cluster path's own
+ * `holdJobForApproval` call.
  *
  * Exported for its own test: inline, the second branch could not be exercised at
  * all, and an untestable security check is one nobody can prove still works.
@@ -615,7 +886,8 @@ export declare function partitionGeneratedConfigsByPin(configs: readonly Generat
  * `evaluateDownstreams` already claimed is not returned here and cannot be
  * dispatched twice.
  */
-export declare function recomputeAndApplyReady(ctx: WorkflowDispatchContext, jobNames: readonly string[]): Promise<void>;
+export declare function recomputeAndApplyReady(ctx: NeedsSchedulingContext, jobNames: readonly string[]): Promise<void>;
+export { gatherInvokeResults };
 /**
  * Dispatch a single matched workflow.
  *
@@ -632,5 +904,4 @@ export declare function recomputeAndApplyReady(ctx: WorkflowDispatchContext, job
  *   J. deferred dynamic dispatch (fire-and-forget per dynamic entry)
  */
 export declare function dispatchMatchedWorkflow(ctx: WorkflowDispatchContext, opts?: DispatchMatchedWorkflowOptions): Promise<DispatchMatchedWorkflowResult>;
-export {};
 //# sourceMappingURL=dispatch-matched-workflow.d.ts.map

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

@@ -192,6 +192,20 @@ export interface GlobalEvalRoundArgs {
  * timeout message that says nothing about 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.
+ */
+export declare function narrowVerdict(raw: unknown, workflowName: string): GlobalEvalCandidateResult;
 /**
  * Cap on the joined reason string a decided-nothing round reports.
  *

package/dist/pipeline/internal-event-pipeline.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Adapter that dispatches an internally-triggered workflow through the SHARED
+ * pipeline (`dispatchMatchedWorkflow`) instead of a bespoke path.
+ *
+ * The bespoke path it replaces resolved no bound contexts, so no context vars,
+ * no scoped secrets and none of the context's protection rules reached an
+ * internally-triggered job; it also dropped every non-static job on the floor.
+ * Routing through the one pipeline is what keeps a fourth such gap from
+ * appearing.
+ */
+import { z } from 'zod';
+import type { LockFile, WorkflowDecision } from '@kici-dev/engine';
+import { type ProcessingDeps } from './processor.js';
+import type { ProviderBundle } from '../provider-registry.js';
+/**
+ * The LIFECYCLE event names the orchestrator emits to itself. They are
+ * `__`-prefixed so they can never collide with a user `kiciEvent()` name, and
+ * each one maps onto a canonical trigger-event type (`__schedule_fire` is the
+ * one that is not a plain de-prefixing).
+ *
+ * NOT the whole set of orchestrator-minted events — the scaler manager mints two
+ * more under the other reserved prefix. NOT the trusted set either: two of these
+ * four are caused by a run and inherit its tier — `ORCHESTRATOR_MINTED_TRUSTED_EVENT_NAMES`
+ * is what the trust classification reads.
+ *
+ * Enumerated so this module compares against a checked value rather than a bare
+ * literal. It is NOT yet the single source: `cron/cron-scheduler.ts`,
+ * `events/event-emitter.ts` and `events/event-router.ts` still spell the same
+ * names inline, and converging them is a sweep this module's blast radius does
+ * not cover. The names are a protocol between those emitters, the router and
+ * this adapter, so a typo in any one of them silently stops matching.
+ */
+export declare const InternalSystemEventName: z.ZodEnum<{
+    __job_complete: "__job_complete";
+    __schedule_fire: "__schedule_fire";
+    __workflow_complete: "__workflow_complete";
+    __workflows_failed_batch: "__workflows_failed_batch";
+}>;
+/**
+ * Context for dispatching one internally-triggered workflow.
+ *
+ * Declared here rather than in `orchestrator-core.ts` because the adapter is
+ * the consumer that defines the shape; the composition root imports it.
+ */
+export interface InternalEventDispatchContext {
+    event: {
+        id: string;
+        eventName: string;
+        payload?: Record<string, unknown>;
+    };
+    routingKey: string;
+    repoIdentifier: string;
+    providerContext: Record<string, unknown>;
+    providerType: 'github' | undefined;
+    /**
+     * Provider bundle for the acting repository, resolved by the composition root
+     * from the live registry.
+     *
+     * Required, not derived here: every dispatch site builds its clone URL as
+     * `bundle?.repoUrlBuilder?.buildCloneUrl(repoIdentifier) ?? ''`, and nothing
+     * downstream resolves a bundle from `deps.providerRegistry`. Passing
+     * `undefined` therefore dispatches every job with an empty repo URL AND
+     * classifies the run as a local-working-tree dispatch (the source-pack build
+     * and the source-cache probe both gate on `!!ctx.bundle`), so no source
+     * tarball is produced and the agent falls through to cloning `''`. It also
+     * carries the clone-token provider and the check-status poster.
+     *
+     * Legitimately `undefined` when the event carries no routing key, or when the
+     * registry has no bundle for it — the same state the pre-pipeline path
+     * rendered as an empty repo URL.
+     */
+    bundle: ProviderBundle | undefined;
+    cronCommitSha: string;
+    /**
+     * The default branch of the registration this event dispatches, or `null`
+     * when it was never captured.
+     *
+     * A `__schedule_fire` run executes the default branch's lock file, so that
+     * branch IS the run's branch — which is what a context's branch restrictions
+     * evaluate. `null` presents no branch and the gate then rejects with its
+     * named-cause verdict; nothing substitutes a value, because a branch nobody
+     * proved is worse than an honest refusal.
+     */
+    registrationDefaultBranch: string | null;
+    /**
+     * The run that summoned this one through an invoke gate, when there is one.
+     *
+     * Set ONLY by the invoke-gate summon path, whose event id is synthesized and
+     * therefore matches no `kici_events` row. Stating the emitting run directly
+     * is what lets a summoned run inherit its summoner's trust tier — the same
+     * inheritance every other user `kiciEvent()` subscriber gets — instead of
+     * always falling back to isolated on a lookup that cannot succeed.
+     */
+    summonedByRunId?: string;
+    /**
+     * Chain depth to stamp on the started run. A webhook-triggered run leaves this
+     * unset (0); a run summoned by an invoke gate carries its summoner's depth + 1
+     * so the chain-depth circuit breaker bounds recursion when it fires its own
+     * gate.
+     */
+    chainDepth?: number;
+}
+/**
+ * The two identities an internal event renders into, which are NOT the same
+ * value for a user `kiciEvent()`:
+ *
+ * - `jobConfigType` is what workflows observe as `ctx.event.type` and what the
+ *   trigger matcher matched against — the literal `kici_event` for a custom
+ *   event.
+ * - `triggerEvent` is what the run carries and forwards to the Platform — the
+ *   actual event name, so the dashboard can say which event fired.
+ *
+ * A system (`__`-prefixed) event renders both from its de-prefixed name, with
+ * `__schedule_fire` collapsing onto `schedule`.
+ */
+export declare function deriveInternalEventIdentity(eventName: string): {
+    jobConfigType: string;
+    triggerEvent: string;
+};
+/**
+ * True when every tier the schema admits carries a rank.
+ *
+ * The `Record<TrustTier, number>` above already fails the build on an unranked
+ * tier, so this can only ever be false if the two drift through a cast. It is
+ * exported so a test asserts it against the live `TrustTierSchema.options`
+ * rather than against a transcription of it — the check has to read the schema
+ * to be worth having.
+ */
+export declare function trustTierRanksCoverEverySchemaTier(): boolean;
+/**
+ * Dispatch one matched workflow for an internal event through the shared
+ * pipeline. Returns the spawned-run summary the bespoke path returned, or
+ * `null` when the decision names a workflow the lock file does not carry.
+ */
+export declare function dispatchInternalEventViaPipeline(decision: WorkflowDecision, lockFile: LockFile, ctx: InternalEventDispatchContext, deps: ProcessingDeps): Promise<{
+    runId: string;
+    repo: string;
+    workflow: string;
+} | null>;
+//# sourceMappingURL=internal-event-pipeline.d.ts.map