@kici-dev/orchestrator 0.12.0 → 0.14.0

package/dist/cluster/settings-propagation.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Which cluster-settings version each orchestrator in a cluster has applied,
+ * compared with the version of the shared `cluster_settings` row.
+ *
+ * A worker reports the version of the snapshot it pulled, which is the one its
+ * next spawn reads. A coordinator reports the version its settings reader
+ * currently serves. Pure, because `kici-admin cluster-settings show` imports
+ * it to validate and render the report the admin route builds.
+ */
+import { z } from 'zod';
+import type { PeerInfo } from './peer-registry.js';
+export declare const settingsPropagationStatusSchema: z.ZodEnum<{
+    ahead: "ahead";
+    behind: "behind";
+    "in-sync": "in-sync";
+}>;
+export type SettingsPropagationStatus = z.infer<typeof settingsPropagationStatusSchema>;
+export declare const SettingsPropagationStatus: {
+    ahead: "ahead";
+    behind: "behind";
+    "in-sync": "in-sync";
+};
+export declare const settingsPropagationRoleSchema: z.ZodEnum<{
+    coordinator: "coordinator";
+    worker: "worker";
+}>;
+export declare const settingsPropagationEntrySchema: z.ZodObject<{
+    instanceId: z.ZodString;
+    role: z.ZodEnum<{
+        coordinator: "coordinator";
+        worker: "worker";
+    }>;
+    self: z.ZodBoolean;
+    connected: z.ZodBoolean;
+    appliedVersion: z.ZodNumber;
+    status: z.ZodEnum<{
+        ahead: "ahead";
+        behind: "behind";
+        "in-sync": "in-sync";
+    }>;
+    lastHeartbeatAt: z.ZodNullable<z.ZodString>;
+    lastHeartbeatAgeMs: z.ZodNullable<z.ZodNumber>;
+}, z.core.$loose>;
+export type SettingsPropagationEntry = z.infer<typeof settingsPropagationEntrySchema>;
+export declare const settingsPropagationReportSchema: z.ZodObject<{
+    currentVersion: z.ZodNumber;
+    reportedBy: z.ZodString;
+    generatedAt: z.ZodString;
+    orchestrators: z.ZodArray<z.ZodObject<{
+        instanceId: z.ZodString;
+        role: z.ZodEnum<{
+            coordinator: "coordinator";
+            worker: "worker";
+        }>;
+        self: z.ZodBoolean;
+        connected: z.ZodBoolean;
+        appliedVersion: z.ZodNumber;
+        status: z.ZodEnum<{
+            ahead: "ahead";
+            behind: "behind";
+            "in-sync": "in-sync";
+        }>;
+        lastHeartbeatAt: z.ZodNullable<z.ZodString>;
+        lastHeartbeatAgeMs: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+export type SettingsPropagationReport = z.infer<typeof settingsPropagationReportSchema>;
+/** The peer-registry fields a report reads. */
+export type PropagationPeer = Pick<PeerInfo, 'instanceId' | 'role' | 'connected' | 'lastHeartbeatAt' | 'clusterSettingsVersion'>;
+/**
+ * `ahead` means the row's version went backwards. A worker in that state never
+ * pulls again, because it pulls only when a coordinator advertises a higher
+ * version than its own.
+ */
+export declare function classifySettingsVersion(applied: number, current: number): SettingsPropagationStatus;
+export declare function buildSettingsPropagationReport(input: {
+    currentVersion: number;
+    self: {
+        instanceId: string;
+        appliedVersion: number;
+    };
+    peers: readonly PropagationPeer[];
+    now: number;
+}): SettingsPropagationReport;
+//# sourceMappingURL=settings-propagation.d.ts.map

package/dist/cluster/worker-cluster-settings.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The cluster-settings snapshot a coordinator serves to DB-less workers.
+ *
+ * A worker cannot read `cluster_settings`, so every knob it applies at spawn
+ * reaches it through this snapshot, pulled over the peer channel whenever a
+ * coordinator advertises a newer settings version. Each value is the stored
+ * override, or the serving coordinator's configured default when the column
+ * is NULL.
+ */
+import type { WorkerClusterSettings } from '@kici-dev/engine';
+import type { ClusterSettingsReader } from './cluster-settings-reader.js';
+/** The configured defaults behind each snapshot field. */
+export interface WorkerClusterSettingDefaults {
+    agentTokenTtlMs: number;
+    firecrackerApiSocketWaitMs: number;
+}
+/** A worker snapshot and the `cluster_settings.version` its values belong to. */
+export interface WorkerClusterSettingsSnapshot {
+    version: number;
+    settings: WorkerClusterSettings;
+}
+/**
+ * Resolve the worker snapshot and its version from ONE read of the row. A
+ * worker stores the version with the values and pulls again only when a
+ * coordinator advertises a higher version, so a version read separately from
+ * the values could pair a newer version with older values for good.
+ */
+export declare function resolveWorkerClusterSettingsSnapshot(reader: Pick<ClusterSettingsReader, 'getRow'>, defaults: WorkerClusterSettingDefaults): Promise<WorkerClusterSettingsSnapshot>;
+//# sourceMappingURL=worker-cluster-settings.d.ts.map

package/dist/config.d.ts

@@ -72,6 +72,7 @@ declare const configSchema: z.ZodObject<{
     globalEvalCandidateTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     globalEvalCacheMax: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     globalEvalWaitTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    firecrackerApiSocketWaitMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     queueMaxDepth: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     queueTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     unroutableGraceMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
@@ -104,6 +105,8 @@ declare const configSchema: z.ZodObject<{
     rerouteSpawnWindowMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     rerouteAckTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     rerouteMaxHops: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    rerouteSpawnMaxAttempts: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    rerouteSpawnRetryBackoffMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     rerouteFlapGraceMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     scalerSpawnTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     backupStalenessWarnHours: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
@@ -147,6 +150,7 @@ declare const configSchema: z.ZodObject<{
     reconnectReplayWindowHours: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     cacheBuildTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     cacheMaxTarballBytes: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    cacheUploadSettleTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     userCacheQuotaBytes: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     userCacheTtlMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     artifactQuotaBytes: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
@@ -282,6 +286,7 @@ export declare const packagingConfigSchema: z.ZodObject<{
     globalEvalCandidateTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     globalEvalCacheMax: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     globalEvalWaitTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    firecrackerApiSocketWaitMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     queueMaxDepth: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     queueTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     unroutableGraceMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
@@ -314,6 +319,8 @@ export declare const packagingConfigSchema: z.ZodObject<{
     rerouteSpawnWindowMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     rerouteAckTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     rerouteMaxHops: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    rerouteSpawnMaxAttempts: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    rerouteSpawnRetryBackoffMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     rerouteFlapGraceMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     scalerSpawnTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     backupStalenessWarnHours: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
@@ -357,6 +364,7 @@ export declare const packagingConfigSchema: z.ZodObject<{
     reconnectReplayWindowHours: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     cacheBuildTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     cacheMaxTarballBytes: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    cacheUploadSettleTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     userCacheQuotaBytes: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     userCacheTtlMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     artifactQuotaBytes: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
@@ -525,6 +533,7 @@ export declare const envDef: import("@kici-dev/shared/env").DefineEnvResult<{
     globalEvalCandidateTimeoutMs: number;
     globalEvalCacheMax: number;
     globalEvalWaitTimeoutMs: number;
+    firecrackerApiSocketWaitMs: number;
     queueMaxDepth: number;
     queueTimeoutMs: number;
     unroutableGraceMs: number;
@@ -554,6 +563,8 @@ export declare const envDef: import("@kici-dev/shared/env").DefineEnvResult<{
     rerouteSpawnWindowMs: number;
     rerouteAckTimeoutMs: number;
     rerouteMaxHops: number;
+    rerouteSpawnMaxAttempts: number;
+    rerouteSpawnRetryBackoffMs: number;
     rerouteFlapGraceMs: number;
     scalerSpawnTimeoutMs: number;
     backupStalenessWarnHours: number;
@@ -591,6 +602,7 @@ export declare const envDef: import("@kici-dev/shared/env").DefineEnvResult<{
     reconnectReplayWindowHours: number;
     cacheBuildTimeoutMs: number;
     cacheMaxTarballBytes: number;
+    cacheUploadSettleTimeoutMs: number;
     userCacheQuotaBytes: number;
     userCacheTtlMs: number;
     artifactQuotaBytes: number;

package/dist/db/migrations/152_org_settings_cache_upload_settle_timeout.d.ts

@@ -0,0 +1,15 @@
+import { type Kysely } from 'kysely';
+/**
+ * Add `org_settings.cache_upload_settle_timeout_ms BIGINT` (nullable).
+ *
+ * Per-org bound on how long a build job's `job.status success` waits for the
+ * cache publish (object metadata plus pointer) its agent reported just before
+ * it. NULL falls back to the cluster default
+ * (`KICI_CACHE_UPLOAD_SETTLE_TIMEOUT_MS`, 10s); 0 turns the wait off. Operators
+ * tune it via `kici-admin org-settings cache-upload-settle`.
+ *
+ * Idempotent: a re-run on a DB that already has the column is a no-op.
+ */
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=152_org_settings_cache_upload_settle_timeout.d.ts.map

package/dist/db/migrations/153_execution_runs_cancel_force.d.ts

@@ -0,0 +1,16 @@
+import { type Kysely } from 'kysely';
+/**
+ * Add `execution_runs.cancel_force BOOLEAN` (nullable, no default).
+ *
+ * TRUE once a forced cancel reached the run. The leader's stuck-cancelling
+ * sweep reads it to re-send a cancel that did not complete with `force` set,
+ * so a forced cancel whose first forward to a sibling coordinator was lost is
+ * not re-sent as a graceful one. NULL (every existing row, and every run no
+ * forced cancel reached) re-sends gracefully. No backfill: nothing recorded
+ * whether an earlier cancel was forced.
+ *
+ * Idempotent: a re-run on a DB that already has the column is a no-op.
+ */
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=153_execution_runs_cancel_force.d.ts.map

package/dist/db/migrations/154_cluster_settings_firecracker_api_socket_wait.d.ts

@@ -0,0 +1,4 @@
+import { type Kysely } from 'kysely';
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=154_cluster_settings_firecracker_api_socket_wait.d.ts.map

package/dist/db/migrations/155_org_settings_reroute_spawn_retry.d.ts

@@ -0,0 +1,17 @@
+import { type Kysely } from 'kysely';
+/**
+ * Add the two per-org spawn-retry columns a worker applies to a rerouted job (both nullable):
+ *
+ * - `reroute_spawn_max_attempts INTEGER` — agent spawns a worker attempts for one rerouted
+ *   job before it gives the job back to its coordinator. NULL falls back to the cluster
+ *   default (`rerouteSpawnMaxAttempts`, 3).
+ * - `reroute_spawn_retry_backoff_ms BIGINT` — wait after a failed spawn before the next
+ *   attempt. NULL falls back to `rerouteSpawnRetryBackoffMs` (5 s).
+ *
+ * Operators tune them per org via `kici-admin org-settings reroute set`.
+ *
+ * Idempotent: each add is guarded on column existence.
+ */
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=155_org_settings_reroute_spawn_retry.d.ts.map

package/dist/db/migrations/156_kici_events_match_outcome.d.ts

@@ -0,0 +1,17 @@
+import { type Kysely } from 'kysely';
+/**
+ * Record how the event router resolved each internal event:
+ *
+ * - `match_outcome TEXT` — `matched`, `buffered`, `no-registration`,
+ *   `no-target-repo`, `trust-blocked` or `no-trigger-match`.
+ * - `matched_count INTEGER` — how many registrations the event was dispatched to.
+ *
+ * Both are written when the event is processed and are NULL before that, and
+ * for rows processed before these columns existed. Nullable with no default,
+ * so the ALTER is catalog-only on a large table.
+ *
+ * Idempotent: `ADD COLUMN IF NOT EXISTS`.
+ */
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=156_kici_events_match_outcome.d.ts.map

package/dist/db/types.d.ts

@@ -514,6 +514,13 @@ export interface ExecutionRunTable {
      * cancelled and for one that entered `cancelling` before the column existed.
      */
     cancelling_at: ColumnType<Date | null, Date | null | undefined, Date | null>;
+    /**
+     * TRUE once a forced cancel reached the run (migration 153). The
+     * stuck-cancelling re-drive reads it so a cancel that did not complete is
+     * re-sent with `force`. Never reset to FALSE: a later graceful cancel does
+     * not undo a forced one. NULL re-drives gracefully.
+     */
+    cancel_force: ColumnType<boolean | null, boolean | null | undefined, boolean | null>;
     /**
      * The run's status generation (migration 150). Starts at 0 and rises by one
      * each time the run leaves a terminal status to continue. Forwarded on every
@@ -1499,6 +1506,10 @@ export interface KiciEventTable {
     dlq_at: Date | null;
     /** Short DLQ reason: 'exhausted_retries' | 'non_retryable' */
     dlq_reason: string | null;
+    /** How the router resolved the event (an `EventMatchOutcome`); NULL until processed */
+    match_outcome: string | null;
+    /** Registrations the event was dispatched to; NULL until processed */
+    matched_count: number | null;
 }
 export type KiciEvent = Selectable<KiciEventTable>;
 export type NewKiciEvent = Insertable<KiciEventTable>;
@@ -1982,6 +1993,16 @@ export interface OrgSettingsTable {
      * (config.rerouteMaxHops). Plain INTEGER — pg returns a number on select.
      */
     reroute_max_hops: ColumnType<number | null, number | null | undefined, number | null>;
+    /**
+     * Per-org agent spawns a worker attempts for one rerouted job. Null = cluster
+     * default (config.rerouteSpawnMaxAttempts). Plain INTEGER.
+     */
+    reroute_spawn_max_attempts: ColumnType<number | null, number | null | undefined, number | null>;
+    /**
+     * Per-org wait (ms) after a failed spawn of a rerouted job. Null = cluster
+     * default (config.rerouteSpawnRetryBackoffMs). BIGINT.
+     */
+    reroute_spawn_retry_backoff_ms: ColumnType<string | null, number | null | undefined, number | null>;
     /**
      * Per-org staleness threshold (hours) for the DB-backup freshness diagnostic.
      * Null = cluster default (config.backupStalenessWarnHours). Plain INTEGER.
@@ -1994,6 +2015,14 @@ export interface OrgSettingsTable {
      * returns a string on select; accept a number on insert/update.
      */
     queue_timeout_ms: ColumnType<string | null, number | null | undefined, number | null>;
+    /**
+     * Per-org bound (ms) on how long a build job's success waits for the cache
+     * publish its agent reported just before it. 0 turns the wait off. Null =
+     * cluster default (config.cacheUploadSettleTimeoutMs /
+     * KICI_CACHE_UPLOAD_SETTLE_TIMEOUT_MS). Postgres BIGINT — pg returns a string
+     * on select; accept a number on insert/update.
+     */
+    cache_upload_settle_timeout_ms: ColumnType<string | null, number | null | undefined, number | null>;
     /**
      * Per-org expiry (seconds) for a held approval element before it is rejected
      * and its run/job/step fails. NOT NULL, default 86400 (one day). An SDK
@@ -2182,6 +2211,8 @@ export interface ClusterSettingsTable {
      * per round.
      */
     global_eval_wait_timeout_ms: ColumnType<string | null, number | null | undefined, number | null>;
+    /** How long a Firecracker spawn waits for the VM's API socket. NULL: config default. */
+    firecracker_api_socket_wait_ms: ColumnType<string | null, number | null | undefined, number | null>;
     /**
      * Retention window in days for `check_run_tracking` rows. The hourly cleanup
      * sweep deletes rows untouched for longer than this; 0 disables the sweep.

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

@@ -6,7 +6,7 @@ import type { EventStore } from './event-store.js';
 import type { EventCircuitBreaker } from './circuit-breaker.js';
 import type { TrustStore } from './trust-store.js';
 import type { RegisteredWorkflow, RegistrationIndex } from '../registration/registration-index.js';
-import type { EventRouterConfig, StoredEvent } from './types.js';
+import { type EventRouterConfig, type 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
@@ -213,6 +213,10 @@ export declare class EventRouter {
      * schedule a retry or move the event to the DLQ. Swallowing the error
      * here would silently lose the event — exactly the failure mode the
      * lease pattern fixes.
+     *
+     * Returns how the event resolved, which `dispatchAndRecord` persists on the
+     * processed row: `matched` when it dispatched at least one workflow, else
+     * the reason nothing ran.
      */
     private processSubscriptions;
     /**
@@ -225,6 +229,8 @@ export declare class EventRouter {
      * itself dispatched by a failure-lifecycle trigger is neither buffered nor
      * dispatched — a broken notifier must not re-trigger the batch on its own
      * failure. The chain-depth breaker remains the backstop for anything missed.
+     *
+     * `bufferedCount` counts the decisions appended to a batch window.
      */
     private bufferBatchDecisions;
     /** Open (or reuse) the registration's batch window and append the failed run. */

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

@@ -1,6 +1,6 @@
 import { type Kysely, type Transaction } from 'kysely';
 import type { Database } from '../db/types.js';
-import type { DlqReason, EventRouterConfig, StoredEvent } from './types.js';
+import { EventMatchOutcome, type DlqReason, type EventMatchResult, type EventRouterConfig, type StoredEvent } from './types.js';
 /** Either a Kysely DB handle or an active transaction. */
 export type DbExecutor = Kysely<Database> | Transaction<Database>;
 /**
@@ -81,11 +81,28 @@ export declare class EventStore {
      * re-queries until a page returns fewer than `limit` rows.
      */
     getUnprocessedSince(sinceId: string | null, limit?: number): Promise<StoredEvent[]>;
+    /**
+     * List events newest first, for `kici-admin event list`. Every filter is
+     * optional except the limit. `before` keeps events created before a
+     * timestamp. `afterEventId` is the next-page cursor: the events that sort
+     * after that event in this order, compared on the stored `(created_at, id)`
+     * so events created in the same millisecond are neither skipped nor repeated.
+     */
+    list(opts: {
+        name?: string;
+        outcome?: EventMatchOutcome;
+        since?: Date;
+        before?: Date;
+        afterEventId?: string;
+        limit: number;
+        sourceRoutingKey?: string;
+    }): Promise<StoredEvent[]>;
     /**
      * Mark an event as fully processed. Called after a successful dispatch.
-     * Clears any prior lease so the row is unambiguously terminal.
+     * Clears any prior lease so the row is unambiguously terminal, and records
+     * how the router resolved it when `result` is given.
      */
-    markProcessed(id: string): Promise<void>;
+    markProcessed(id: string, result?: EventMatchResult): Promise<void>;
     /**
      * Atomically take a dispatch lease on an event. Replaces the previous
      * "flip processed=true upfront" pattern that silently lost events when

package/dist/events/types.d.ts

@@ -1,6 +1,7 @@
 /**
  * Event routing configuration and types.
  */
+import { z } from 'zod';
 /**
  * Configuration for the event routing system.
  */
@@ -45,6 +46,22 @@ export interface EventRouterConfig {
  * Reason an event landed in the DLQ.
  */
 export type DlqReason = 'exhausted_retries' | 'non_retryable';
+/** How the router resolved one event against the registered workflows. */
+export declare const EventMatchOutcome: z.ZodEnum<{
+    buffered: "buffered";
+    matched: "matched";
+    "no-registration": "no-registration";
+    "no-target-repo": "no-target-repo";
+    "no-trigger-match": "no-trigger-match";
+    "trust-blocked": "trust-blocked";
+}>;
+export type EventMatchOutcome = z.infer<typeof EventMatchOutcome>;
+/** What the router resolved for one event, persisted on its processed row. */
+export interface EventMatchResult {
+    outcome: EventMatchOutcome;
+    /** Registrations the event was dispatched to. */
+    matchedCount: number;
+}
 /**
  * A stored internal event (matches DB row shape but with JS types).
  */
@@ -70,7 +87,35 @@ export interface StoredEvent {
     nextRetryAt: Date | null;
     dlqAt: Date | null;
     dlqReason: DlqReason | null;
+    /**
+     * How the router resolved the event. Set when the event is processed; null
+     * before, and for rows processed before the column existed.
+     */
+    matchOutcome: EventMatchOutcome | null;
+    /** Registrations the event was dispatched to; null when `matchOutcome` is. */
+    matchedCount: number | null;
 }
+/**
+ * An event payload safe to show an operator. An event-scaler scale-up carries
+ * a single-use claim code an agent redeems for credentials, so every read
+ * surface (event show, the dead-letter queue) replaces it with `[redacted]`.
+ */
+export declare function redactEventPayload(payload: Record<string, unknown>): Record<string, unknown>;
+/** Where an internal event is in its dispatch lifecycle. */
+export declare const EventProcessingState: z.ZodEnum<{
+    dlq: "dlq";
+    leased: "leased";
+    pending: "pending";
+    processed: "processed";
+    retrying: "retrying";
+}>;
+export type EventProcessingState = z.infer<typeof EventProcessingState>;
+/**
+ * Derive an event's dispatch state from its row: DLQ wins, then processed;
+ * an unprocessed row is leased while a node holds it, retrying once a failed
+ * dispatch scheduled another attempt, and pending before its first lease.
+ */
+export declare function eventProcessingState(e: StoredEvent): EventProcessingState;
 /**
  * Default event router configuration.
  */

package/dist/helpers/windows-batch.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Running a Windows batch file (`.cmd` / `.bat`) through cmd.exe.
+ *
+ * Node.js refuses to start a batch file without a shell (it throws `EINVAL`),
+ * and every launcher a KiCI package ships on Windows is a batch file. Two
+ * callers run one: the service installer, which registers the command with
+ * shawl, and the bare-metal scaler, which spawns it.
+ *
+ * Both quote a token on cmd.exe's command line only when it contains a space
+ * or a tab — shawl does, and so does libuv when Node.js builds a Windows
+ * command line — so one safety rule fits both.
+ */
+/**
+ * The cmd.exe arguments that run a batch-file launcher, ahead of its path.
+ *
+ * shawl stops the service with a ctrl-C to its console, and cmd.exe gets it
+ * too: when the batch file's node process exits, cmd.exe asks "Terminate batch
+ * job (Y/N)?" and waits for an answer. shawl sees the service exit only when its
+ * stop timeout kills cmd.exe. With stdin from NUL ({@link BATCH_STDIN}), cmd.exe
+ * reads end-of-input at that prompt and exits with node.
+ *
+ * `call` keeps the launcher path out of the first position after `/c`, where
+ * cmd.exe strips the quotes from a path that contains `(`, `)` or `&`. `/e:on`
+ * and `/v:off` pin command extensions (the launchers use `%~dp0`) and delayed
+ * expansion whatever the host's registry defaults are.
+ */
+export declare const BATCH_WRAPPER_ARGS: readonly ['/d', '/e:on', '/v:off', '/c', 'call'];
+/** The redirect that closes {@link BATCH_WRAPPER_ARGS}: the launcher's stdin is NUL. */
+export declare const BATCH_STDIN = "<NUL";
+/** A `.cmd` or `.bat` file, which Windows runs through cmd.exe. */
+export declare function isBatchFile(executablePath: string): boolean;
+/**
+ * The cmd.exe that COMSPEC names in `env`, as Node itself uses to run a shell on
+ * Windows. A COMSPEC that names another shell is not used: the wrapper
+ * arguments are cmd.exe's.
+ */
+export declare function cmdExePath(env?: NodeJS.ProcessEnv): string;
+/**
+ * Why cmd.exe would read part of `token` as syntax, or null when it would not.
+ *
+ * A token is quoted on cmd.exe's command line only when it contains a space or
+ * a tab. Inside quotes cmd.exe reads `&`, `|`, `<`, `>`, `(`, `)` and the `,`
+ * `;` `=` delimiters as text; outside quotes it reads them as syntax. `%` and
+ * `^` change even inside quotes (`call` expands `%` again and doubles `^`), and
+ * a `"` ends the quoting.
+ *
+ * @param use - what the token runs as, completing "cannot run <token> …".
+ * @param remedy - the sentence that tells the operator what to change.
+ */
+export declare function cmdSafetyRefusal(token: string, use: string, remedy: string): string | null;
+/** Throw the {@link cmdSafetyRefusal} message for `token`, if it has one. */
+export declare function assertCmdSafe(token: string, use: string, remedy: string): void;
+/**
+ * The cmd.exe command that runs `command` — a batch file and its arguments —
+ * with stdin from NUL. The caller checks each token with
+ * {@link assertCmdSafe} first.
+ */
+export declare function batchFileCommand(command: readonly string[], env?: NodeJS.ProcessEnv): string[];
+//# sourceMappingURL=windows-batch.d.ts.map