@kici-dev/orchestrator 0.5.0 → 0.6.0

package/dist/events/event-router.d.ts

@@ -5,9 +5,23 @@ import type { LockFile, WorkflowDecision } from '@kici-dev/engine';
 import type { EventStore } from './event-store.js';
 import type { EventCircuitBreaker } from './circuit-breaker.js';
 import type { TrustStore } from './trust-store.js';
-import type { RegistrationIndex } from '../registration/registration-index.js';
+import type { RegisteredWorkflow, RegistrationIndex } from '../registration/registration-index.js';
 import type { EventRouterConfig, StoredEvent } from './types.js';
 import type { ClusterSettingsReader } from '../cluster/cluster-settings-reader.js';
+/**
+ * System events are exempt from the per-source event-storm rate limiter: they
+ * are orchestrator-emitted (never a user `ctx.emit`) with a bounded chain depth,
+ * so they cannot loop. Two families qualify — the `__`-prefixed workflow/
+ * job-complete events, and the reserved `kici.`-prefixed events (today: the
+ * event scaler's scale-up / scale-down), which fire on real scaling demand and
+ * must not be dropped by a 100/min bucket.
+ *
+ * "Never a user `ctx.emit`" is what the exemption rests on, and it is ENFORCED
+ * rather than assumed: both prefixes are refused at the emit path (the SDK
+ * client-side, the orchestrator's `event.emit` handler authoritatively), which
+ * is the same reservation this predicate reads.
+ */
+export declare function isRateExemptEventName(eventName: string): boolean;
 /**
  * Input for emitting an internal event.
  */
@@ -34,6 +48,13 @@ export interface EventMatchContext {
     repoIdentifier: string;
     /** Provider-specific credentials captured at registration time */
     providerContext: Record<string, unknown>;
+    /**
+     * The registration's default branch (`null` when it was never captured).
+     * A `__schedule_fire` run executes this branch's lock file, so the dispatch
+     * adapter presents it as that run's branch when a context evaluates branch
+     * restrictions.
+     */
+    defaultBranch: string | null;
 }
 export interface EventRouterOptions {
     db: Kysely<Database>;
@@ -53,6 +74,30 @@ export interface EventRouterOptions {
     registrationIndex: RegistrationIndex;
     /** Stable identifier for this orchestrator process — written into `kici_events.claimed_by` for diagnostics. */
     nodeId: string;
+    /**
+     * Boot latch: resolves once this process can actually dispatch a matched
+     * event.
+     *
+     * `start()` runs its catch-up scan well before the dispatch dependencies are
+     * assembled (the `ProcessingDeps` bag is built at `createApp`), and a restart
+     * with a backlog is exactly when that window is loaded. Without the latch a
+     * backlogged event can spend all `maxDispatchAttempts` (default 5) inside the
+     * window — full-jitter backoff can re-fire almost immediately — and land in
+     * the DLQ, which is terminal loss.
+     *
+     * Consumed two DIFFERENT ways, because the two paths sit on opposite sides of
+     * the caller that resolves it:
+     *
+     * - **Live notification** — awaited inline, before leasing. The handler runs
+     *   off the pg client's event loop, so nothing upstream is blocked.
+     * - **Catch-up** — the scan is SCHEDULED behind the latch, never awaited by
+     *   `start()`. The composition root resolves the latch only after `start()`
+     *   returns, so awaiting inline would be a guaranteed startup deadlock.
+     *
+     * Absent ⇒ no gating, and the catch-up runs inline exactly as before (tests,
+     * and any caller that is ready before `start()`).
+     */
+    dispatchReady?: () => Promise<void>;
 }
 /**
  * EventRouter delivers internal events to matching workflows via PostgreSQL LISTEN/NOTIFY.
@@ -75,6 +120,21 @@ export declare class EventRouter {
     private readonly config;
     private readonly clusterSettings?;
     private readonly onEventMatched;
+    private readonly dispatchReady;
+    /** The deferred catch-up scan, when `start()` scheduled one behind the latch. */
+    private catchUpScan;
+    /**
+     * The catch-up scan ITSELF, set the moment it actually begins.
+     *
+     * Distinct from `catchUpScan`, which is the whole latch-then-scan chain.
+     * `stop()` awaits this one, never the chain: the latch is resolved by the
+     * composition root PAST `start()`, so a bootstrap that fails in between
+     * leaves it pending forever and awaiting the chain would hang shutdown.
+     * Awaiting only a scan that has begun bounds the wait by the scan.
+     */
+    private runningCatchUp;
+    /** Set by `stop()` so a latch that resolves after shutdown starts no scan. */
+    private stopped;
     private readonly registrationIndex;
     private readonly nodeId;
     private client;
@@ -85,6 +145,14 @@ export declare class EventRouter {
      * Runs catch-up on start to process events missed during downtime.
      */
     start(): Promise<void>;
+    /**
+     * The deferred catch-up scan scheduled by `start()` behind the boot latch, or
+     * `null` when the scan ran inline (no latch configured).
+     *
+     * Exposed so a caller can await the scan rather than poll for its effects.
+     * `start()` deliberately does not await it — see the comment there.
+     */
+    get catchUpSettled(): Promise<void> | null;
     /**
      * Stop listening and release the dedicated pg client.
      */
@@ -187,6 +255,24 @@ export declare class EventRouter {
      * so we wrap the stored event's metadata into the expected structure.
      */
     private buildSimulatedEvent;
+    /**
+     * Match a kici event by name against the SOURCE repo's own `kiciEvent({ name })`
+     * subscribers, returning the matched decisions plus the synthetic lock file each
+     * was matched against.
+     *
+     * This reuses the exact match path `processSubscriptions` uses for a custom
+     * event — the `kici_event` index lookup plus `matchAllWorkflows` against a
+     * one-workflow synthetic lock file — but scoped to `sourceRepo` and without the
+     * async event-store round-trip, so an invoke gate can summon the repo's opt-in
+     * workflows synchronously and correlate each spawned run. The match is scoped to
+     * the source repo's own registrations (source == target), so no cross-repo trust
+     * check applies.
+     */
+    matchKiciEventSubscribers(eventName: string, payload: Record<string, unknown>, sourceRepo: string, sourceRoutingKey?: string): Array<{
+        reg: RegisteredWorkflow;
+        lockFile: LockFile;
+        decisions: WorkflowDecision[];
+    }>;
     /**
      * Catch-up: process every unprocessed event missed during downtime.
      *

package/dist/events/types.d.ts

@@ -36,10 +36,8 @@ export interface EventRouterConfig {
      * succeeds, and lands the row in the DLQ when N exceeds
      * `maxDispatchAttempts`.
      *
-     * Only honoured when `KICI_TEST_MODE=1` is set at config-load time —
-     * production deployments never see this knob even if the env var is
-     * planted by accident. Source the value from
-     * `KICI_TEST_EVENT_FAIL_FIRST_N` (a JSON object literal).
+     * Undefined in the shipped orchestrator: only the build-time test double
+     * supplies this map, via the injected fault-injection policy.
      */
     debugFailFirstNAttemptsByEvent?: Record<string, number>;
 }
@@ -73,25 +71,6 @@ export interface StoredEvent {
     dlqAt: Date | null;
     dlqReason: DlqReason | null;
 }
-/**
- * Parse the `KICI_TEST_EVENT_FAIL_FIRST_N` JSON payload, gated by
- * `KICI_TEST_MODE`. Returns the parsed map or `undefined` when:
- *
- * - `testMode` is false (the master switch). The JSON value is ignored
- *   entirely; production deployments never see fault-injection even if
- *   the per-event env var is accidentally planted.
- * - the JSON value is absent / empty.
- * - the JSON value is malformed or carries a wrong-shape entry. We
- *   refuse to fall back to a partial map: a typo on one line silently
- *   skipping that test would be confusing in CI logs.
- *
- * The accepted shape is `{ "<eventName>": <number> }`; non-string keys
- * and non-number values are rejected. The numeric value is the inclusive
- * upper bound of attempts to fail (so `1` fails the first attempt and
- * succeeds on retry; `99` exceeds `maxDispatchAttempts` and lands the
- * row in the DLQ).
- */
-export declare function parseFaultInjectionMap(testMode: boolean, raw: string | undefined): Record<string, number> | undefined;
 /**
  * Default event router configuration.
  */

package/dist/git/credential-broker.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Resolves a git credential reference to material plus the grant it actually
+ * obtained.
+ *
+ * Two axes, deliberately orthogonal:
+ *   - shape  — minted (a GitHub App token) or static (PAT / Basic / SSH)
+ *   - origin — a source credential the orchestrator already holds, a secret
+ *              resolved from the secrets backend, or a secret output inherited
+ *              from an upstream job
+ *
+ * Origin is a reference, not a third backend: all of them feed the same two
+ * shapes.
+ *
+ * The broker reports what it granted and never echoes the request. A static
+ * credential is `{ scoped: false }` because an SSH key or PAT cannot be
+ * narrowed after the fact, and recording a request as if it had been honoured
+ * would be a lie in an audit log.
+ *
+ * Knows nothing about git, clones, or agents.
+ */
+import type { GitCredentialRef, GitCredentialResult, ProviderGitAuth } from '@kici-dev/engine';
+import type { SecretResolverApi } from '../secrets/secret-resolver.js';
+import { type MintedToken } from './installation-token.js';
+/** Injected so tests need no network and so the mint seam stays explicit. */
+type MintFn = (args: {
+    appId: string;
+    privateKey: string;
+    installationId: string;
+    repositories: readonly string[];
+    permissions?: Readonly<Record<string, string>>;
+}) => Promise<MintedToken>;
+/**
+ * Reads one secret output this job inherited from a `needs` upstream. Injected
+ * rather than constructed so the broker needs no database in unit tests, and so
+ * the decryption stays in the one place that already owns it.
+ */
+type SecretOutputFn = (runId: string, jobId: string, key: string) => Promise<string | null>;
+export interface BrokerResolveArgs {
+    orgId: string;
+    repositories: readonly string[];
+    /** Omit for the source credential the orchestrator already holds. */
+    ref?: GitCredentialRef;
+    permissions?: Readonly<Record<string, string>>;
+    runId?: string;
+    jobId?: string;
+}
+export declare class GitCredentialBroker {
+    private readonly secretResolver;
+    private readonly sourceAuth;
+    private readonly mint;
+    private readonly secretOutputs;
+    constructor(deps: {
+        secretResolver: SecretResolverApi;
+        /**
+         * Yields the source credential for a repository — normally
+         * `bundle.cloneTokenProvider.issueGitAuth(...)`. Injected rather than
+         * constructed so there is one source-credential path, not two.
+         */
+        sourceAuth: (repository: string) => Promise<ProviderGitAuth | null>;
+        mint?: MintFn;
+        secretOutputs?: SecretOutputFn;
+    });
+    resolve(args: BrokerResolveArgs): Promise<GitCredentialResult>;
+    /**
+     * The source credential, as a ref. Delegates to the dispatch bundle's
+     * existing `CloneTokenProvider` — the same object that already mints the
+     * clone token today — so there is exactly one source-credential path, not two.
+     *
+     * It arrives as material the orchestrator already holds, so it uses the
+     * `*Value` form: there is no secret-store entry to name.
+     */
+    private sourceRef;
+    /**
+     * Read one `<name>Secret` / `<name>Value` pair.
+     *
+     * `*Value` is material — return it verbatim. `*Secret` is a qualified
+     * `<context>:<secret-name>` reference, so the CONTEXT comes from the
+     * reference itself rather than being inferred, matching
+     * `isQualifiedSecretRef` in `packages/sdk/src/workflow.ts`.
+     */
+    private sourced;
+    /** Route a qualified reference to the store that owns it. */
+    private resolveQualified;
+    /**
+     * Resolve a secret output this job inherited from a `needs` upstream.
+     *
+     * Reads the existing run-scoped store rather than adding a second one: the
+     * value was written by `ctx.setSecretOutput`, is encrypted at rest, and is
+     * deleted when the run completes.
+     */
+    private resolveInherited;
+}
+export {};
+//# sourceMappingURL=credential-broker.d.ts.map

package/dist/git/inherited-secret.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Read a secret output this job inherited from a `needs` upstream.
+ *
+ * Backs the reserved `needs:` context in a qualified credential reference. The
+ * value was written by `ctx.setSecretOutput`, is encrypted at rest in
+ * `run_secret_outputs`, and is deleted when the run completes — so this reads
+ * the store that already exists rather than adding a second one.
+ */
+import type { SecretOutputStore } from '../secrets/secret-output-store.js';
+export interface InheritedSecretDeps {
+    secretOutputStore: SecretOutputStore;
+    /** Upstream job ids for a job, in the same shape the run merge path uses. */
+    upstreamJobIds: (runId: string, jobId: string) => Promise<string[]>;
+    /** The orchestrator's master secret key, as configured. */
+    secretKey: string;
+}
+/**
+ * Build the `secretOutputs` lookup the credential broker takes.
+ *
+ * Returns null when the key was not published by any upstream — the broker
+ * turns that into an actionable error naming `setSecretOutput`.
+ */
+export declare function createInheritedSecretReader(deps: InheritedSecretDeps): (runId: string, jobId: string, key: string) => Promise<string | null>;
+//# sourceMappingURL=inherited-secret.d.ts.map

package/dist/git/installation-token.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Mint a GitHub App installation access token, scoped to one repository and to
+ * an explicit permission set.
+ *
+ * Shared deliberately: both the stored KiCI App and a customer's own App
+ * (supplied through workflow secrets) mint the same way, and duplicating the
+ * JWT dance across two code paths would leave two things to keep in sync as
+ * GitHub evolves. It lives outside `providers/github/` for the same reason —
+ * the workflow-supplied path must not import a provider it is not using.
+ *
+ * Installation tokens expire after one hour and cannot be renewed, so callers
+ * must mint per use rather than caching. The credential helper does exactly
+ * that, which is what makes an arbitrarily long job's `git push` succeed.
+ */
+import { Octokit } from '@octokit/rest';
+/** A freshly minted installation token and what it can actually do. */
+export interface MintedToken {
+    token: string;
+    /** ISO-8601 expiry, or null when the forge reported none. */
+    expiresAt: string | null;
+    /** Permissions GitHub ACTUALLY granted — never an echo of the request. */
+    grantedPermissions: Readonly<Record<string, string>>;
+    repositorySelection: string;
+}
+export interface MintInstallationTokenArgs {
+    appId: string;
+    /** PEM-encoded App private key. */
+    privateKey: string;
+    installationId: string;
+    /** `owner/repo` for every repository the token must cover. Only the repo
+     * half of each reaches the API. At least one. */
+    repositories: readonly string[];
+    permissions?: Readonly<Record<string, string>>;
+    /** Seam for tests; production callers omit it. */
+    octokitFactory?: (appId: string, privateKey: string) => Octokit;
+}
+export declare function mintInstallationToken(args: MintInstallationTokenArgs): Promise<MintedToken>;
+//# sourceMappingURL=installation-token.d.ts.map

package/dist/git/job-context.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Per-job facts the git credential relay needs, read from server truth.
+ *
+ * The relay never takes the org or the source repository from request params —
+ * an agent could name any repository it liked. Both come from the run row the
+ * orchestrator itself wrote at dispatch.
+ */
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import type { JobCredentialContext } from '../ws/git-credential-relay.js';
+/** Build the `jobContext` lookup the git credential handler takes. */
+export declare function createJobCredentialContextReader(db: Kysely<Database>): (runId: string) => Promise<JobCredentialContext | null>;
+//# sourceMappingURL=job-context.d.ts.map