@kici-dev/orchestrator 0.1.26 → 0.2.0

package/dist/storage/blob-routes.d.ts

@@ -11,9 +11,25 @@
  * filesystem backend is active (`deps.fsCache` truthy in app.ts).
  */
 import type { Hono } from 'hono';
+/**
+ * URL prefix for the filesystem-backend blob transfer route. The app-level
+ * webhook body-size cap MUST exempt this prefix: blob PUTs carry internal
+ * artifacts (dependency tarballs up to `cacheMaxTarballBytes`, 500MB by
+ * default), which the S3 backend uploads direct-to-S3 uncapped. Binding them
+ * to the tenant-webhook body limit would 413 legitimate large caches on the
+ * filesystem backend. The PUT route below enforces its own `maxUploadBytes`
+ * bound instead.
+ */
+export declare const CACHE_BLOB_PATH_PREFIX = "/api/v1/cache/blob/";
 export interface FsCacheRouteDeps {
     basePath: string;
     signingSecret: string;
+    /**
+     * Upper bound on a single blob PUT, in bytes. Aligned with the dep-cache's
+     * `cacheMaxTarballBytes` (500MB default) so the filesystem backend accepts
+     * the same artifact sizes the S3 backend does.
+     */
+    maxUploadBytes: number;
 }
 /** Mount filesystem-backend cache routes onto an existing Hono app. */
 export declare function registerBlobRoutes(app: Hono, deps: FsCacheRouteDeps): void;

package/dist/storage/filesystem.d.ts

@@ -51,11 +51,28 @@ export declare class FilesystemCacheStorage implements CacheStorage {
     delete(key: string): Promise<boolean>;
     touch(key: string): Promise<void>;
     getUrl(key: string, ttlMsOverride?: number): Promise<string | null>;
+    presignedGetTtlSeconds(): number;
     getUploadUrl(key: string): Promise<string>;
     getInternalUploadUrl(key: string): Promise<string>;
     initMeta(key: string): Promise<void>;
+    /**
+     * List cache keys under a prefix.
+     *
+     * The prefix is a **key prefix**, not necessarily a directory — `UserCache`'s
+     * `restoreKeys` fallback lists on `${prefix}${seg(restoreKey)}`, a partial
+     * object name. Two shapes, and both must work the way the S3 backend does:
+     *
+     * - trailing `/` — a directory. Walk it directly; this is the hot path.
+     * - no trailing `/` — a partial name. Walk the parent directory and filter by
+     *   the prefix, since the prefix itself may name a file (or nothing at all).
+     *
+     * Reading the prefix as a directory in the second case is what made the
+     * `restoreKeys` fallback silently never hit here (`ENOENT` → `[]`) or throw
+     * (`ENOTDIR`, when a real object carried that exact name).
+     */
     list(subPrefix: string): Promise<string[]>;
     getMetadata(key: string): Promise<CacheMetadata | null>;
+    getObjectSize(key: string): Promise<number | null>;
     copy(srcKey: string, destKey: string): Promise<void>;
     /**
      * Recursively collect data files under `dir`, returning each as a cache key

package/dist/storage/key-discriminator.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Width of the object-key discriminator, in hex characters.
+ *
+ * 32 hex chars is 128 bits, and the width is a security property rather than a
+ * formatting choice: on a case-insensitive namespace the discriminator is the
+ * only thing separating object names chosen by untrusted workflow code. A
+ * narrower value would let that code search case variants for a colliding pair
+ * and land two different payloads on one object.
+ */
+export declare const KEY_DISCRIMINATOR_LENGTH = 32;
+/**
+ * A collision-resistant discriminator for a user-supplied object-key segment.
+ *
+ * Hashes the **exact** name, before any sanitization. Sanitizing is many-to-one
+ * — `seg()` maps both `/` and `_` to `_`, so `a/b` and `a_b` collapse to one
+ * segment — and a case-insensitive backend folds `build` onto `Build`. Hashing
+ * the pre-sanitization name is what keeps each of those pairs two objects.
+ */
+export declare function keyDiscriminator(exact: string): string;
+//# sourceMappingURL=key-discriminator.d.ts.map

package/dist/storage/s3.d.ts

@@ -70,11 +70,13 @@ export declare class S3CacheStorage implements CacheStorage {
     delete(key: string): Promise<boolean>;
     touch(key: string): Promise<void>;
     getUrl(key: string, ttlMsOverride?: number): Promise<string | null>;
+    presignedGetTtlSeconds(): number;
     getUploadUrl(key: string): Promise<string>;
     getInternalUploadUrl(key: string): Promise<string>;
     initMeta(key: string): Promise<void>;
     list(subPrefix: string): Promise<string[]>;
     getMetadata(key: string): Promise<CacheMetadata | null>;
+    getObjectSize(key: string): Promise<number | null>;
     copy(srcKey: string, destKey: string): Promise<void>;
     /** Delete an S3 object. Idempotent (doesn't error if missing). */
     private deleteObject;

package/dist/storage/types.d.ts

@@ -51,6 +51,15 @@ export interface CacheStorage {
      * `ttlMsOverride` applies a per-operation TTL (see `get`).
      */
     getUrl(key: string, ttlMsOverride?: number): Promise<string | null>;
+    /**
+     * The validity window, in seconds, of the pre-signed download URLs this
+     * backend mints via `getUrl` — i.e. how long after minting a `getUrl` link
+     * still authorizes a download before its signature expires. This is the
+     * signature expiry, NOT the artifact-retention TTL; consumers that render a
+     * `getUrl` link (e.g. the dashboard artifacts panel) use it to refresh the
+     * link before it stops working.
+     */
+    presignedGetTtlSeconds(): number;
     /**
      * Generate a pre-signed PUT URL for direct agent upload.
      * Uses the external endpoint (container-routable) when configured.
@@ -86,6 +95,13 @@ export interface CacheStorage {
      * eviction to order candidates by access recency.
      */
     getMetadata(key: string): Promise<CacheMetadata | null>;
+    /**
+     * Byte size of the stored object, or null when the object is missing. A pure
+     * stat — no metadata write and no TTL/last-accessed side effect. Used to
+     * verify an artifact's real size server-side instead of trusting the
+     * agent-declared value.
+     */
+    getObjectSize(key: string): Promise<number | null>;
 }
 import type { SharedS3Config } from '@kici-dev/shared';
 /**

package/dist/webhook/dedup.d.ts

@@ -1,5 +1,6 @@
 import type { Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
+import type { ClusterSettingsReader } from '../cluster/cluster-settings-reader.js';
 /**
  * Delivery ID deduplication cache with dual-layer storage:
  * 1. In-memory Set for hot-path performance (last 10,000 IDs)
@@ -12,7 +13,14 @@ export declare class DedupCache {
     private readonly db;
     private readonly memoryCache;
     private readonly insertionOrder;
-    constructor(db: Kysely<Database>);
+    private readonly clusterSettings?;
+    private readonly defaultTtlMs;
+    constructor(db: Kysely<Database>, opts?: {
+        clusterSettings?: ClusterSettingsReader;
+        defaultTtlMs?: number;
+    });
+    /** Resolve the fleet-wide dedup TTL (ms), falling back to the config default. */
+    private ttlMs;
     /**
      * Check if a delivery ID has already been processed.
      * Checks in-memory cache first (fast path), then DB.

package/dist/webhook/event-log.d.ts

@@ -2,11 +2,18 @@ import { EventLogStatus, EventLogSource } from '@kici-dev/engine';
 import type { Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
 import type { LogStorage } from '../reporting/log-storage.js';
+import type { ClusterSettingsReader } from '../cluster/cluster-settings-reader.js';
 import type { WebhookInfo } from './handler.js';
 /** Configuration for the writer. */
 export interface EventLogWriterOptions {
-    /** Soft cap in bytes for payload upload (default 5 MB). */
+    /**
+     * Cluster-wide fallback soft cap in bytes for payload upload (default 5 MB),
+     * used when no live `cluster_settings.event_log_max_payload_bytes` override
+     * is set. Read per-write through {@link ClusterSettingsReader}.
+     */
     maxPayloadBytes: number;
+    /** Optional fleet-wide settings reader; when present overrides maxPayloadBytes per write. */
+    clusterSettings?: ClusterSettingsReader;
 }
 /**
  * Outcome metadata recorded alongside the delivery row.
@@ -30,7 +37,11 @@ export interface EventLogOutcome {
     ref?: string | null;
     /** First run spawned by this delivery. */
     runId?: string | null;
-    /** Failure reason when status='failed'. */
+    /**
+     * Failure reason when status='failed', or a degraded-evaluation note on a
+     * status='processed' row (e.g. path filters matched conservatively against
+     * an unavailable changed-files diff). Free-text; not tied to a single status.
+     */
     errorMessage?: string | null;
 }
 /**

package/dist/webhook/generic-sources-listener.d.ts

@@ -39,6 +39,7 @@ import type { GenericSourceManager } from './generic-sources.js';
 import type { ProviderRegistry } from '../provider-registry.js';
 import type { AppConfig } from '../config.js';
 import type { SecretResolver } from '../secrets/secret-resolver.js';
+import type { ClusterSettingsReader } from '../cluster/cluster-settings-reader.js';
 export interface GenericSourcesChangeListenerOptions {
     /** Raw pg pool — a dedicated PoolClient is checked out for LISTEN. */
     pool: pg.Pool;
@@ -51,6 +52,9 @@ export interface GenericSourcesChangeListenerOptions {
     /** Required for universal-git source rows; null is acceptable on
      *  peers that cannot serve them. */
     secretResolver: SecretResolver | null;
+    /** Fleet-wide settings reader; threads the live lock-file cap into warm-path
+     *  universal-git fetcher registration. */
+    clusterSettings?: ClusterSettingsReader;
     /** Active scaler backend on this peer. Threaded into the warm-path
      *  registration so a local source added at runtime on a container /
      *  firecracker scaler emits the same reachability warning as a cold-boot one. */

package/dist/webhook/ingest-admission.d.ts

@@ -0,0 +1,140 @@
+import { z } from 'zod';
+import type { LoopLagSource } from './loop-lag-source.js';
+/**
+ * Reasons a webhook-ingest admission is shed by the {@link IngestAdmissionController}.
+ *
+ * - `loop_overload` — the event-loop-lag gate is latched open (p99 delay above
+ *   the shed threshold); admission sheds immediately, DB-free.
+ * - `codel_drop`    — the CoDel controlled-delay queue is standing (minimum
+ *   sojourn stayed above target for a full interval); the head is dropped.
+ * - `queue_full`    — the bounded queue is at capacity, or the caller disallowed
+ *   queueing (the WS relay path) and no slot was immediately available.
+ * - `max_sojourn`   — a waiter exceeded the hard sojourn ceiling (< the Platform
+ *   WS ack timeout) and is dropped so nothing waits past the caller's timeout.
+ */
+export declare const IngestShedReason: z.ZodEnum<{
+    codel_drop: "codel_drop";
+    loop_overload: "loop_overload";
+    max_sojourn: "max_sojourn";
+    queue_full: "queue_full";
+}>;
+export type IngestShedReason = z.infer<typeof IngestShedReason>;
+export type AdmitResult = {
+    admitted: true;
+    release: () => void;
+} | {
+    admitted: false;
+    reason: IngestShedReason;
+};
+/** Per-call admission options. */
+export interface AdmitOptions {
+    /**
+     * When true (HTTP direct ingress), a request that cannot be admitted
+     * immediately is enqueued on the CoDel queue. When false (Platform-WS relay,
+     * whose ack the Platform awaits synchronously with a 5 s budget), no queueing
+     * happens — the request is granted immediately or shed `queue_full` at once.
+     */
+    allowQueue?: boolean;
+}
+export interface IngestAdmissionConfig {
+    maxConcurrency: number;
+    maxQueueDepth: number;
+    codelTargetMs: number;
+    codelIntervalMs: number;
+    queueMaxWaitMs: number;
+    loopLagShedMs: number;
+    loopLagResumeMs: number;
+    loopLagSampleMs: number;
+}
+export interface IngestAdmissionSnapshot {
+    inflight: number;
+    queueDepth: number;
+    sheddingActive: boolean;
+    loopDelayP99Ms: number;
+    loopDelayMaxMs: number;
+}
+export interface IngestAdmissionDeps {
+    config: IngestAdmissionConfig;
+    loopLag: LoopLagSource;
+    /** injectable clock (default Date.now). */
+    now?: () => number;
+    /** durable-buffer seam (default no-op) — a future replay buffer plugs in here. */
+    onShed?: (reason: IngestShedReason, key: string) => void;
+    /** metric hook: shed counter increment (keeps the controller OTel-free). */
+    onShedMetric?: (reason: IngestShedReason) => void;
+    /** metric hook: admitted counter increment. */
+    onAdmitMetric?: () => void;
+    /** metric hook: state gauges refresh. */
+    onStateChange?: (s: IngestAdmissionSnapshot) => void;
+    /** start the real sweep timer (default true; unit tests pass false and drive tickQueue/sampleLoopLag). */
+    startTimer?: boolean;
+}
+/**
+ * Single-process admission controller for the webhook-ingest pipeline. Three
+ * layers evaluated in order on {@link admit}: (1) an event-loop-lag gate (the
+ * DB-free adaptive signal), (2) hard global + per-org caps (memory backstop +
+ * fairness), (3) a CoDel controlled-delay queue (burst absorption without
+ * bufferbloat). Shed is lossy — the caller redelivers.
+ */
+export declare class IngestAdmissionController {
+    private readonly cfg;
+    private readonly loopLag;
+    private readonly now;
+    private readonly onShedSeam;
+    private readonly onShedMetric?;
+    private readonly onAdmitMetric?;
+    private readonly onStateChange?;
+    private globalInflight;
+    private readonly perKeyInflight;
+    private readonly queue;
+    private loopP99;
+    private loopMax;
+    /** Hysteresis latch for the loop-lag gate (open = shedding). */
+    private loopGateOpen;
+    /** CoDel: timestamp the head sojourn first rose above target; undefined when below. */
+    private codelAboveSince;
+    private codelDropping;
+    private readonly sweepTimer;
+    private stopped;
+    constructor(deps: IngestAdmissionDeps);
+    private keyInflight;
+    private incKey;
+    private decKey;
+    isShedding(): boolean;
+    snapshot(): IngestAdmissionSnapshot;
+    private emit;
+    /**
+     * Sample the loop-lag source into the snapshot and update the hysteresis
+     * latch. Called on the sweep interval (production) or directly (tests).
+     */
+    sampleLoopLag(): void;
+    private canAdmit;
+    private makeRelease;
+    private grant;
+    private shed;
+    /**
+     * @param key    fairness key — org id (preferred) or routing key (DB-degraded fallback).
+     * @param orgCap per-key concurrency cap P (from the cached settings reader).
+     */
+    admit(key: string, orgCap: number, opts?: AdmitOptions): Promise<AdmitResult>;
+    /**
+     * Drive the queue: admit admissible waiters (fair skip of maxed keys), sweep
+     * the hard sojourn ceiling, then evaluate CoDel on the head. Called on every
+     * release and on the sweep interval; also test-drivable with the injected clock.
+     */
+    tickQueue(): void;
+    /** Release-driven fair dequeue: admit the first admissible waiter, skip maxed keys. */
+    private admitWaiters;
+    /** Hard sojourn ceiling: shed any waiter that waited past W_max. */
+    private sweepMaxSojourn;
+    /**
+     * CoDel head evaluation. While the head sojourn is below target, reset the
+     * dropping state (a transient burst drains cleanly). Once the head has stayed
+     * at/above target continuously for a full interval, enter the dropping state
+     * and shed the head each sweep until sojourn recovers below target.
+     */
+    private codelEval;
+    /** Stop the sweep timer and drain the queue (every waiter resolves as shed). */
+    stop(): void;
+}
+//# sourceMappingURL=ingest-admission.d.ts.map

package/dist/webhook/ingest-overflow-buffer.d.ts

@@ -0,0 +1,27 @@
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import { type OverflowDelivery } from './ingest-overflow-types.js';
+export interface IngestOverflowBufferDeps {
+    db: Kysely<Database>;
+    /** Buffered-row cap (KICI_INGEST_OVERFLOW_MAX). */
+    maxRows: number;
+}
+/**
+ * Capture side of the durable overflow buffer. On a shed, the ingest path calls
+ * {@link IngestOverflowBuffer.capture} additively (the 429 still stands). At the
+ * row cap, capture drops the delivery from the buffer (never unbounded rows) —
+ * the lossy fallback a retrying sender still covers.
+ */
+export declare class IngestOverflowBuffer {
+    private readonly db;
+    private readonly maxRows;
+    constructor(deps: IngestOverflowBufferDeps);
+    /** Current buffered-row depth. */
+    currentDepth(): Promise<number>;
+    /**
+     * Persist a shed delivery. Returns true when a `buffered` row was inserted,
+     * false when the buffer is at cap (delivery dropped, `cap_full` metric bumped).
+     */
+    capture(d: OverflowDelivery): Promise<boolean>;
+}
+//# sourceMappingURL=ingest-overflow-buffer.d.ts.map

package/dist/webhook/ingest-overflow-replayer.d.ts

@@ -0,0 +1,49 @@
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import { WebhookIngestOutcome } from '../pipeline/process-webhook.js';
+import { type OverflowDelivery } from './ingest-overflow-types.js';
+export type ReinjectFn = (d: OverflowDelivery) => Promise<WebhookIngestOutcome>;
+export interface IngestOverflowReplayerDeps {
+    db: Kysely<Database>;
+    controller: {
+        isShedding(): boolean;
+    };
+    intervalMs: number;
+    batchSize: number;
+    maxAttempts: number;
+}
+/**
+ * Background drain for the durable overflow buffer. A pass runs only while the
+ * admission controller is NOT shedding (replaying into a still-overloaded
+ * orchestrator just re-sheds), claims the oldest `buffered` rows FIFO up to a
+ * bounded batch, and re-injects each through the admission-gated ingest path.
+ * A re-shed or error reverts the row to `buffered` (never lost); past the
+ * max-attempts ceiling it goes `failed`. Successful rows are swept.
+ */
+export declare class IngestOverflowReplayer {
+    private readonly db;
+    private readonly controller;
+    private readonly intervalMs;
+    private readonly batchSize;
+    private readonly maxAttempts;
+    private reinjectDirect;
+    private reinjectRelay;
+    private timer;
+    private running;
+    private stopped;
+    constructor(deps: IngestOverflowReplayerDeps);
+    setReinjectDirect(fn: ReinjectFn): void;
+    setReinjectRelay(fn: ReinjectFn): void;
+    start(): void;
+    stop(): void;
+    /** One drain pass. Test-drivable. */
+    runPass(): Promise<void>;
+    /** Select the oldest buffered rows and claim each via a conditional update. */
+    private claimBatch;
+    private toDelivery;
+    private replayOne;
+    private revertOrFail;
+    private sweepReplayed;
+    private refreshDepthGauge;
+}
+//# sourceMappingURL=ingest-overflow-replayer.d.ts.map

package/dist/webhook/ingest-overflow-types.d.ts

@@ -0,0 +1,73 @@
+import { z } from 'zod';
+import type { WebhookInfo } from './handler.js';
+import type { RelayStartMeta } from './relay-buffer.js';
+/**
+ * Lifecycle of a durably-buffered shed delivery.
+ *
+ * - `buffered`  — captured, awaiting replay.
+ * - `replaying` — claimed by a replay pass (a conditional-update lock so a
+ *   restart / second loop cannot double-claim the same row).
+ * - `replayed`  — successfully re-injected through normal ingest; swept.
+ * - `failed`    — re-shed / errored past the max-attempts ceiling; kept for
+ *   operator inspection with `last_error`.
+ */
+export declare const OverflowStatus: z.ZodEnum<{
+    buffered: "buffered";
+    failed: "failed";
+    replayed: "replayed";
+    replaying: "replaying";
+}>;
+export type OverflowStatus = z.infer<typeof OverflowStatus>;
+/**
+ * Which ingest boundary captured the delivery, and therefore how it is replayed:
+ *
+ * - `direct` — HTTP direct-ingress. The delivery was already signature-verified
+ *   and normalized at ingest; replay re-injects the stored `WebhookInfo` through
+ *   the admission-gated HTTP path (no re-verification).
+ * - `relay`  — Platform-WS relay. The delivery was shed BEFORE signature
+ *   verification; replay MUST re-verify the raw body against the stored headers.
+ */
+export declare const OverflowSourceKind: z.ZodEnum<{
+    direct: "direct";
+    relay: "relay";
+}>;
+export type OverflowSourceKind = z.infer<typeof OverflowSourceKind>;
+/** Reasons a delivery is permanently dropped from the overflow buffer. */
+export declare const OverflowDropReason: z.ZodEnum<{
+    cap_full: "cap_full";
+    max_attempts: "max_attempts";
+}>;
+export type OverflowDropReason = z.infer<typeof OverflowDropReason>;
+/** Verify-input envelope for a `relay`-origin delivery (mirrors RelayStartMeta). */
+export interface OverflowRelayMeta {
+    signatureHeaderName: string | null;
+    signatureHeader: string | null;
+    clientIp: string | null;
+    headers: Record<string, string>;
+    requestId?: string;
+}
+/** A delivery captured for durable overflow replay. */
+export interface OverflowDelivery {
+    deliveryId: string;
+    routingKey: string;
+    sourceKind: OverflowSourceKind;
+    /** Provider type (direct: from WebhookInfo; relay: resolved at replay). */
+    provider: string | null;
+    event: string;
+    action: string | null;
+    /**
+     * Base64 of the raw delivery bytes. For `direct` this is the JSON-serialized
+     * payload; for `relay` it is the verbatim wire body (base64 preserves bytes so
+     * a non-JSON generic payload replays intact and HMAC re-verification matches).
+     */
+    body: string;
+    /** Verify metadata; empty for `direct` (already verified). */
+    meta: OverflowRelayMeta;
+}
+/** Build a capture record from a verified HTTP-direct `WebhookInfo`. */
+export declare function deliveryFromDirect(info: WebhookInfo): OverflowDelivery;
+/** Build a capture record from a pre-verify WS relay `meta` + raw body. */
+export declare function deliveryFromRelay(meta: RelayStartMeta, body: Buffer): OverflowDelivery;
+/** Reconstruct a normalized `WebhookInfo` from a `direct`-origin delivery. */
+export declare function overflowDeliveryToInfo(d: OverflowDelivery): WebhookInfo;
+//# sourceMappingURL=ingest-overflow-types.d.ts.map

package/dist/webhook/loop-lag-source.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Event-loop delay source for the ingest admission controller's adaptive gate.
+ *
+ * The controller reads p99/max loop delay on a short interval to decide whether
+ * to shed. Hiding the real `perf_hooks` primitive behind this interface lets the
+ * gate decision logic and the real sampler be tested separately: the controller
+ * unit tests drive a {@link FakeLoopLagSource} with caller-controlled values, and
+ * {@link RealLoopLagSource} has its own busy-spin detection test.
+ */
+export interface LoopLagSource {
+    /** p99 event-loop delay in ms over the current window. */
+    p99(): number;
+    /** max event-loop delay in ms over the current window. */
+    max(): number;
+    /** reset the window's histogram (start a fresh measurement window). */
+    reset(): void;
+    /** stop the underlying monitor (real source only; no-op on the fake). */
+    stop(): void;
+}
+/** Real source backed by `perf_hooks.monitorEventLoopDelay`. */
+export declare class RealLoopLagSource implements LoopLagSource {
+    private readonly h;
+    constructor(resolutionMs?: number);
+    p99(): number;
+    max(): number;
+    reset(): void;
+    stop(): void;
+}
+/** Deterministic test double returning caller-controlled p99/max values. */
+export declare class FakeLoopLagSource implements LoopLagSource {
+    private _p99;
+    private _max;
+    setP99(v: number): void;
+    setMax(v: number): void;
+    p99(): number;
+    max(): number;
+    reset(): void;
+    stop(): void;
+}
+//# sourceMappingURL=loop-lag-source.d.ts.map

package/dist/webhook/observed-relay-guard.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Client-side half of the `observed`-mode "no relay, ever" guarantee.
+ *
+ * An `observed` orchestrator ingests only its OWN webhooks — providers post
+ * straight to its public URL and nothing transits the hosted Platform. The
+ * Platform never selects an observed connection as a relay target, so a relay
+ * reaching one is a defect somewhere upstream. These handlers make that case
+ * loud and inert instead of silently processing the payload.
+ */
+import { WebhookRelayResult } from '@kici-dev/engine';
+/** Thrown when a Platform relay reaches an observed-mode orchestrator. */
+export declare class ObservedRelayRefusedError extends Error {
+    constructor(routingKey: string);
+}
+/** Reason string returned on both the verify and the refusal paths. */
+export declare const OBSERVED_RELAY_REFUSAL_REASON = "orchestrator is in observed mode and does not accept Platform-relayed webhooks";
+/** Minimal logger surface the guard needs (keeps the module test-friendly). */
+type WarnLogger = {
+    warn: (message: string, meta?: Record<string, unknown>) => void;
+};
+/**
+ * `onVerifyInbound` for observed mode: refuse every relayed webhook at verify
+ * time, so the Platform gets a definitive `rejected_misconfigured` ack instead
+ * of a timeout.
+ */
+export declare function observedRelayVerify(): {
+    result: WebhookRelayResult;
+    reason: string;
+};
+/**
+ * `onWebhookRelay` for observed mode: log loudly and reject so nothing is
+ * processed. Rejecting (rather than returning) keeps the failure visible in the
+ * Platform client's relay error path.
+ */
+export declare function observedRelayReject(logger: WarnLogger, meta: {
+    routingKey: string;
+    deliveryId?: string;
+}): Promise<void>;
+export {};
+//# sourceMappingURL=observed-relay-guard.d.ts.map

package/dist/webhook/org-ingest-cap-reader.d.ts

@@ -0,0 +1,24 @@
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+/** The resolved fairness key + per-key concurrency cap for an ingest admission. */
+export interface AdmissionKey {
+    key: string;
+    orgCap: number;
+}
+export interface OrgIngestCapReader {
+    /**
+     * Resolve the fairness key + per-org cap for a routing key. Never throws; on a
+     * DB error / cold-miss-slow it degrades to `{ key: routingKey, orgCap:
+     * clusterDefault }` (per-routing-key fairness, DB-free) so admission never
+     * blocks on a sick DB.
+     */
+    resolve(routingKey: string): Promise<AdmissionKey>;
+}
+export declare function createOrgIngestCapReader(deps: {
+    db?: Kysely<Database>;
+    clusterDefault: number;
+    orgTtlMs?: number;
+    capTtlMs?: number;
+    maxEntries?: number;
+}): OrgIngestCapReader;
+//# sourceMappingURL=org-ingest-cap-reader.d.ts.map

package/dist/webhook/register-source-bundle.d.ts

@@ -33,6 +33,7 @@
 import type { AppConfig } from '../config.js';
 import type { ProviderRegistry } from '../provider-registry.js';
 import type { SecretResolver } from '../secrets/secret-resolver.js';
+import type { ClusterSettingsReader } from '../cluster/cluster-settings-reader.js';
 import type { GenericWebhookSource } from '../db/types.js';
 export interface RegisterSourceBundleDeps {
     providerRegistry: ProviderRegistry;
@@ -40,6 +41,8 @@ export interface RegisterSourceBundleDeps {
     /** Required for universal-git source rows. Null is allowed; rows that
      *  carry `git_config` will be skipped with a metric bump. */
     secretResolver: SecretResolver | null;
+    /** Fleet-wide settings reader; threads the live lock-file cap into universal-git fetchers. */
+    clusterSettings?: ClusterSettingsReader;
     /** Active scaler backend on this peer. When 'container' or 'firecracker', a
      *  local source registration emits a one-time reachability warning (the repo
      *  must exist inside the agent filesystem, not just on the orchestrator host). */

package/dist/webhook/relay-reinject.d.ts

@@ -0,0 +1,43 @@
+import type { AdmitResult } from './ingest-admission.js';
+import type { WebhookInfo } from './handler.js';
+import { WebhookIngestOutcome } from '../pipeline/process-webhook.js';
+import type { OverflowDelivery } from './ingest-overflow-types.js';
+import type { ReinjectFn } from './ingest-overflow-replayer.js';
+/** Verify outcome shape the reinject cares about (subset of VerifyOutcome). */
+export interface RelayVerifyResult {
+    result: string;
+}
+/**
+ * Collaborator seams for {@link buildRelayReinject}. Injected so the reinject
+ * orchestration + payload parsing can be unit-tested without the DB / secret
+ * store / provider registry. server.ts wires these to the real subsystems.
+ */
+export interface RelayReinjectSeams {
+    /**
+     * Re-admit on the routing key (allowQueue:false — same non-queueing gate the
+     * live relay path uses). A re-shed maps the reinject to `shed` so the replayer
+     * reverts the row to `buffered`.
+     */
+    admit: (routingKey: string) => Promise<AdmitResult>;
+    /** Re-verify the raw body against the stored headers. */
+    verify: (d: OverflowDelivery, body: Buffer) => Promise<RelayVerifyResult>;
+    /** Resolve the provider string for a routing key (bundle → prefix fallback). */
+    resolveProvider: (routingKey: string) => string;
+    /** Process a verified, normalized delivery through the relay ingest pipeline. */
+    process: (info: WebhookInfo) => Promise<WebhookIngestOutcome>;
+}
+/**
+ * Parse a captured relay body into a payload object, mirroring the live relay
+ * path's content-type handling: JSON (or empty content-type) → parsed object;
+ * anything else → `{ rawBody, contentType }`. An empty body is an empty object.
+ */
+export declare function parseRelayPayload(body: Buffer, headers: Record<string, string>): Record<string, unknown>;
+/**
+ * Build the relay-origin overflow re-injector. Re-admits on the routing key,
+ * re-verifies the stored raw body (relay deliveries are captured pre-verify),
+ * normalizes it, and processes it through the admission-gated relay pipeline.
+ * A re-shed maps to `shed` (revert); a verify miss maps to `skipped` (terminal
+ * — the delivery is no longer routable, so it is not retried forever).
+ */
+export declare function buildRelayReinject(seams: RelayReinjectSeams): ReinjectFn;
+//# sourceMappingURL=relay-reinject.d.ts.map