@kici-dev/orchestrator 0.16.0 → 0.18.0

package/dist/__test-helpers__/mock-db-query.d.ts

@@ -1,129 +0,0 @@
-/**
- * Predicate + projection evaluation for the shared `createMockDb` harness.
- *
- * Kept BYTE-IDENTICAL in the orchestrator and the Platform, which each carry a
- * copy. Each package owns an
- * independent `createMockDb` builder and neither package may import the other, so
- * the evaluator is duplicated rather than shared. A drift test fails the moment
- * the copies diverge.
- *
- * `createMockDb` used to return its configured rows verbatim, whatever the
- * query asked for: a `.where(...)` or a `.select([...])` was recorded on a spy
- * and then discarded. A test therefore observed only the rows it had itself
- * configured, so dropping a filter or a projected column from the code under
- * test changed nothing the test could see. This module is the evaluator that
- * closes that: the mock now *applies* the query it was handed.
- *
- * Scope, stated precisely because the guarantee is partial by construction:
- *
- * - **Binary predicates are evaluated.** `.where(column, op, value)` for the
- *   operators in {@link MockDbOperator}. That is the overwhelming majority of
- *   the predicates this repo issues.
- * - **Anything else is opaque and is NOT evaluated.** An expression-builder
- *   callback (`.where((eb) => …)`) and a raw `sql` fragment carry their meaning
- *   in code the mock cannot read, so they are recorded and skipped. A filter
- *   written in one of those shapes is still unpinned.
- * - **A predicate on a column the fixture row does not declare is NOT
- *   evaluated.** The fixture, not the schema, is the source of truth here: a
- *   test row is a partial literal, and a missing key means "this test did not
- *   model that column", not "this column is NULL". Treating absence as NULL
- *   would fail nearly every fixture in the repo for saying too little, while
- *   catching nothing a fixture that *does* declare the column would not
- *   already catch. The consequence is real and worth naming: to pin a filter,
- *   a fixture row must mention the column that filter reads.
- *
- * Everything here is pure — no vitest, no chain state — so it is unit-tested
- * directly in `mock-db-query.test.ts` rather than only through the mock.
- */
-/** SQL comparison operators the mock evaluates. Anything else is opaque. */
-export declare enum MockDbOperator {
-    eq = "=",
-    neq = "!=",
-    neqAnsi = "<>",
-    lt = "<",
-    lte = "<=",
-    gt = ">",
-    gte = ">=",
-    in = "in",
-    notIn = "not in",
-    is = "is",
-    isNot = "is not",
-    like = "like",
-    notLike = "not like",
-    ilike = "ilike",
-    notILike = "not ilike"
-}
-/** A `.where(column, op, value)` predicate the mock can evaluate. */
-export interface BinaryPredicate {
-    kind: 'binary';
-    /** Column name with any `table.` qualifier stripped. */
-    column: string;
-    op: MockDbOperator;
-    value: unknown;
-}
-/** A predicate shape the mock cannot read (eb callback, raw sql, unknown op). */
-export interface OpaquePredicate {
-    kind: 'opaque';
-    /** Why it could not be parsed — surfaced in `explainSkippedPredicates`. */
-    reason: string;
-}
-export type MockDbPredicate = BinaryPredicate | OpaquePredicate;
-/** Drop a `table.` / `"table".` qualifier so a predicate keys into a flat row. */
-export declare function unqualify(column: string): string;
-/**
- * Parse the arguments of one `.where(...)` call into a predicate.
- *
- * Only the 3-argument `(column, op, value)` form with a string column and a
- * recognized operator is evaluable; everything else is opaque.
- */
-export declare function parseWhereArgs(args: readonly unknown[]): MockDbPredicate;
-/**
- * Evaluate one binary predicate against a row.
- *
- * Returns `undefined` when the predicate cannot be decided — the row does not
- * declare the column, or the values are not comparable. An undecided predicate
- * does not exclude the row (see the module docblock).
- */
-export declare function evaluatePredicate(row: Record<string, unknown>, predicate: BinaryPredicate): boolean | undefined;
-/** True when the row satisfies every predicate the mock could decide. */
-export declare function rowMatches(row: unknown, predicates: readonly MockDbPredicate[]): boolean;
-/** Keep only the rows satisfying every decidable predicate. */
-export declare function filterRows<T>(rows: readonly T[], predicates: readonly MockDbPredicate[]): T[];
-/** One projected column: the row key read, and the key it is emitted under. */
-export interface ProjectedColumn {
-    source: string;
-    alias: string;
-}
-/**
- * Parse `.select(...)` arguments into a projection.
- *
- * Returns `undefined` when the projection cannot be modelled — an aggregate
- * expression, an `eb` callback, a raw `sql` fragment. An unmodelled projection
- * leaves rows untouched rather than guessing at their shape.
- */
-export declare function parseSelectArgs(args: readonly unknown[]): ProjectedColumn[] | undefined;
-/**
- * Narrow a row to the projected columns.
- *
- * A projected column the fixture row does not declare is omitted rather than
- * emitted as `undefined`, so `'key' in row` keeps meaning "the fixture modelled
- * this" — the same convention {@link evaluatePredicate} reads.
- *
- * A column is read under its `source` name and, failing that, under its
- * `alias`. Fixtures in this repo are written both ways — some model the raw
- * table row (`storage_key`), others the row the aliased query returns
- * (`storageKey`) — and the projection has to narrow both. Reading either name
- * costs nothing: a column dropped from the projection disappears from the
- * output under both conventions, which is the regression this exists to catch.
- */
-export declare function projectRow<T>(row: T, columns: readonly ProjectedColumn[]): T;
-/** Narrow every row to the projected columns. */
-export declare function projectRows<T>(rows: readonly T[], columns: readonly ProjectedColumn[]): T[];
-/**
- * Describe the predicates the mock recorded but could not evaluate.
- *
- * Exposed so a test that cares whether its filter was actually pinned can
- * assert the mock understood it, instead of assuming it did.
- */
-export declare function explainSkippedPredicates(predicates: readonly MockDbPredicate[]): string[];
-//# sourceMappingURL=mock-db-query.d.ts.map

package/dist/__test-helpers__/mock-db.d.ts

@@ -1,134 +0,0 @@
-/**
- * Shared mock Kysely database builder for orchestrator tests.
- *
- * Provides a configurable `createMockDb()` that constructs a chainable
- * mock supporting the common query patterns used by the orchestrator:
- *
- * - selectFrom().selectAll().where()...execute() / executeTakeFirst()
- * - selectFrom().select().where()...execute() / executeTakeFirst() / executeTakeFirstOrThrow()
- * - insertInto().values().execute() / returning().executeTakeFirstOrThrow()
- * - insertInto().values().onConflict(cb).execute()
- * - insertInto().values().returningAll().executeTakeFirstOrThrow()
- * - updateTable().set().where()...execute() / executeTakeFirst()
- * - deleteFrom().where()...execute() / executeTakeFirst()
- * - transaction().execute(async (trx) => { ... })
- *
- * Each test can configure return values via options and access the
- * underlying vi.fn() mocks for assertions via the `mocks` property.
- *
- * ## The select chain APPLIES the query (contract)
- *
- * A select chain does not return `selectRows` / `selectFirstRow` verbatim. It
- * evaluates the `.where(...)` predicates and the `.select([...])` projection the
- * code under test issued, so a test observes the query instead of restating it:
- * dropping a filter or a projected column changes what the test sees.
- *
- * - **Per query, not per test.** Every `db.selectFrom(...)` builds a fresh chain
- *   with its own predicate list, so two queries in one test cannot inherit each
- *   other's filters. The `mocks.select*` spies stay shared across the whole
- *   test, so existing clause assertions are unaffected.
- * - **Only the shapes the evaluator reads.** `.where(column, op, value)` is
- *   evaluated; an `eb` callback or a raw `sql` fragment is recorded and skipped.
- *   `.select()` is applied only when every argument is a plain column string, so
- *   an aggregate or `eb` projection leaves rows untouched.
- * - **A predicate on a column the fixture omits does not exclude the row.** To
- *   pin a filter, the fixture row must declare the column that filter reads.
- * - **`executeTakeFirstOrThrow` yields `{}`** when the configured row does not
- *   satisfy the query, rather than throwing as Kysely would.
- *
- * `mock-db-query.ts` holds the evaluator and states the same contract with its
- * reasoning; `mock-db-query.test.ts` tests it directly.
- */
-import { vi } from 'vitest';
-export interface MockDbOptions {
-    /** Rows returned by selectAll/select chains ending in .execute(). Default: [] */
-    selectRows?: unknown[];
-    /** Row returned by select chains ending in .executeTakeFirst(). Default: undefined */
-    selectFirstRow?: unknown | undefined;
-    /** Row returned by insert chains ending in .returningAll().executeTakeFirstOrThrow(). Default: { id: 'mock-id' } */
-    insertedRow?: unknown;
-    /** Row returned by insert chains ending in .returning().executeTakeFirstOrThrow(). Default: { id: 'mock-id' } */
-    insertReturning?: unknown;
-    /** Row returned by update chains ending in .returningAll().executeTakeFirstOrThrow() or executeTakeFirst(). Default: undefined */
-    updatedRow?: unknown;
-    /** Rows returned by update chains ending in .returningAll().execute(). Default: [] */
-    updatedRows?: unknown[];
-    /** Row returned by update chains ending in .returning(...).executeTakeFirst(). Default: undefined */
-    updateReturning?: unknown;
-    /** Result for update .execute() calls. Default: { numUpdatedRows: 0n } */
-    updateResult?: {
-        numUpdatedRows: bigint;
-    };
-    /** Result for delete .executeTakeFirst() calls. Default: { numDeletedRows: 0n } */
-    deleteResult?: {
-        numDeletedRows: bigint;
-    };
-    /** Result for count queries (fn.countAll). Default: { count: 0 } */
-    countResult?: {
-        count: number;
-    };
-    /** Result for insert chains ending in .executeTakeFirst(). Default: undefined */
-    insertResult?: {
-        numInsertedOrUpdatedRows: bigint;
-    };
-}
-export interface MockDb {
-    db: any;
-    mocks: MockDbMocks;
-}
-export interface MockDbMocks {
-    selectFrom: ReturnType<typeof vi.fn>;
-    selectAll: ReturnType<typeof vi.fn>;
-    select: ReturnType<typeof vi.fn>;
-    selectWhere: ReturnType<typeof vi.fn>;
-    selectOrderBy: ReturnType<typeof vi.fn>;
-    selectLimit: ReturnType<typeof vi.fn>;
-    selectExecute: ReturnType<typeof vi.fn>;
-    selectExecuteTakeFirst: ReturnType<typeof vi.fn>;
-    selectExecuteTakeFirstOrThrow: ReturnType<typeof vi.fn>;
-    selectForUpdate: ReturnType<typeof vi.fn>;
-    selectSkipLocked: ReturnType<typeof vi.fn>;
-    insertInto: ReturnType<typeof vi.fn>;
-    insertValues: ReturnType<typeof vi.fn>;
-    insertReturning: ReturnType<typeof vi.fn>;
-    insertReturningAll: ReturnType<typeof vi.fn>;
-    insertExecute: ReturnType<typeof vi.fn>;
-    insertExecuteTakeFirstOrThrow: ReturnType<typeof vi.fn>;
-    onConflict: ReturnType<typeof vi.fn>;
-    /** The upsert's ON CONFLICT DO UPDATE SET payload — shared across both the
-     *  column() and columns() shapes, so a test can assert what an existing row
-     *  is actually updated with. */
-    doUpdateSet: ReturnType<typeof vi.fn>;
-    updateTable: ReturnType<typeof vi.fn>;
-    updateSet: ReturnType<typeof vi.fn>;
-    updateWhere: ReturnType<typeof vi.fn>;
-    updateReturningAll: ReturnType<typeof vi.fn>;
-    updateExecute: ReturnType<typeof vi.fn>;
-    updateExecuteTakeFirst: ReturnType<typeof vi.fn>;
-    updateExecuteTakeFirstOrThrow: ReturnType<typeof vi.fn>;
-    deleteFrom: ReturnType<typeof vi.fn>;
-    deleteWhere: ReturnType<typeof vi.fn>;
-    deleteExecute: ReturnType<typeof vi.fn>;
-    deleteExecuteTakeFirst: ReturnType<typeof vi.fn>;
-    transaction: ReturnType<typeof vi.fn>;
-    transactionExecute: ReturnType<typeof vi.fn>;
-    countAll: ReturnType<typeof vi.fn>;
-    countAs: ReturnType<typeof vi.fn>;
-    countExecuteTakeFirst: ReturnType<typeof vi.fn>;
-}
-/**
- * Create a mock Kysely DB instance for orchestrator unit tests.
- *
- * All query chains are fully wired and return sensible defaults.
- * Override specific return values via the `options` parameter.
- *
- * @example
- * ```ts
- * const { db, mocks } = createMockDb({ selectRows: [row1, row2] });
- * const store = new SomeStore(db);
- * await store.list();
- * expect(mocks.selectFrom).toHaveBeenCalledWith('my_table');
- * ```
- */
-export declare function createMockDb(options?: MockDbOptions): MockDb;
-//# sourceMappingURL=mock-db.d.ts.map

package/dist/__test-helpers__/mock-ws.d.ts

@@ -1,13 +0,0 @@
-import type { WsLike } from '../agent/registry.js';
-import type { ObserverWsLike } from '../ws/observer-registry.js';
-/**
- * Create a mock WsLike with vi.fn() spies on send/close.
- * Used across agent registry, dispatcher, heartbeat, and WS handler tests.
- */
-export declare function mockWs(): WsLike;
-/**
- * Create a mock ObserverWsLike with vi.fn() spies on send/close.
- * Used by observer-registry tests.
- */
-export declare function mockObserverWs(): ObserverWsLike;
-//# sourceMappingURL=mock-ws.d.ts.map

package/dist/__test-helpers__/peer-mutual-auth.d.ts

@@ -1,42 +0,0 @@
-export declare function refTranscriptHash(serverPub: Buffer, serverNonce: Buffer, authSchemes: readonly string[], clientPub: Buffer): Buffer;
-export declare function refClientProof(o: {
-    psk: Buffer;
-    th: Buffer;
-    mode: string;
-    instanceId: string;
-    role: string;
-    protocolVersion: number;
-    tokenRouting: string;
-}): Buffer;
-export declare function refServerProof(o: {
-    psk: Buffer;
-    th: Buffer;
-    clientProof: Buffer;
-    serverInstanceId: string;
-    grantedRole: string;
-    sessionCredential: string | null;
-}): Buffer;
-export declare function refAppKey(o: {
-    handshakeKey: Buffer;
-    psk: Buffer;
-    th: Buffer;
-    clientProof: Buffer;
-    serverProof: Buffer;
-}): Buffer;
-/** A join token in the production format, with its routing segment and stored hash. */
-export declare function makeTestJoinToken(routing: {
-    orgId: string;
-    routingKey: string;
-    expiry: number;
-    role: 'coordinator' | 'worker';
-}): {
-    token: string;
-    routingB64: string;
-    secretHex: string;
-    tokenHash: string;
-};
-/** The PSK a credential-mode peer proves with: the bytes of sha256(credential). */
-export declare function credentialPsk(credential: string): Buffer;
-/** The PSK a token-mode peer proves with: the bytes of the stored token hash. */
-export declare function tokenPsk(tokenHash: string): Buffer;
-//# sourceMappingURL=peer-mutual-auth.d.ts.map

package/dist/__test-helpers__/scratch-db.d.ts

@@ -1,16 +0,0 @@
-/** Throwaway PostgreSQL databases for DB-gated tests, dropped by `cleanup`. */
-import pg from 'pg';
-import { Kysely } from 'kysely';
-export interface ScratchDb {
-    url: string;
-    pool: pg.Pool;
-    db: Kysely<any>;
-}
-/** Creates databases on `adminUrl`; `cleanup` drops every one of them. */
-export declare function scratchDbFactory(adminUrl: string): {
-    freshDb: (tag: string) => Promise<ScratchDb>;
-    cleanup: () => Promise<void>;
-};
-/** The applied migration names, sorted. */
-export declare function ledgerNames(db: Kysely<any>): Promise<string[]>;
-//# sourceMappingURL=scratch-db.d.ts.map

package/dist/__test-helpers__/test-db.d.ts

@@ -1,34 +0,0 @@
-/**
- * Teardown helper for tests that create their own PostgreSQL database.
- */
-import type pg from 'pg';
-/** Backends still hold the database after they were terminated and waited on. */
-export declare class TestDbBackendsRemainError extends Error {
-    readonly dbName: string;
-    readonly remaining: number;
-    constructor(dbName: string, remaining: number);
-}
-/**
- * Terminate whatever backends still hold `dbName`, after first waiting for
- * the connections the test itself closed to finish closing, then wait for the
- * terminated backends to exit.
- *
- * `pool.end()` — and Kysely's `destroy()`, which calls it — resolves as soon
- * as every client has SENT its Terminate message, not when its socket has
- * closed. A `pg_terminate_backend` issued inside that window delivers a FATAL
- * `57P01` to a client that is mid-shutdown and no longer carries an error
- * listener, and that surfaces as an uncaught exception that fails the whole
- * test file after every test in it passed. So this polls `pg_stat_activity`
- * until the database has no backend left (bounded by `timeoutMs`), and
- * terminates only what is still there — a connection the test never closed.
- *
- * A terminated backend stays in `pg_stat_activity` until it has exited, and
- * `DROP DATABASE` fails while it is listed. So after the terminate this polls
- * again until the count is zero, bounded by `exitTimeoutMs`, and throws
- * {@link TestDbBackendsRemainError} if the bound passes.
- */
-export declare function terminateTestDbBackends(admin: pg.Pool, dbName: string, opts?: {
-    timeoutMs?: number;
-    exitTimeoutMs?: number;
-}): Promise<void>;
-//# sourceMappingURL=test-db.d.ts.map

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

@@ -1,121 +0,0 @@
-/**
- * Shared fixtures for the `dispatchMatchedWorkflow` test files.
- *
- * Kept out of any `*.test.ts` file so importing it does not re-register another
- * file's suites in the importer.
- */
-import { type Mock } from 'vitest';
-import type { ProviderType } from '@kici-dev/engine';
-import type { QueuedJobInput } from '../queue/job-queue.js';
-import type { WorkflowDispatchContext } from './dispatch-matched-workflow.js';
-/** Provider of the inbound event every {@link makeSingleJobContext} fixture carries. */
-export declare const TEST_INBOUND_PROVIDER: ProviderType;
-/** Overrides {@link makeSingleJobContext} accepts. */
-export interface SingleJobContextOptions {
-    bundle: WorkflowDispatchContext['bundle'];
-    fullRepo?: boolean;
-    testRun?: {
-        fixtureId: string;
-    };
-    db?: unknown;
-    executionTracker?: unknown;
-    withBuildInfra?: boolean;
-    withBuildMiss?: boolean;
-    localWorkingTree?: boolean;
-    runWideFlatSecrets?: Record<string, string>;
-    jobContext?: string;
-    /** Workflow-level context names (`LockWorkflow.contexts`) bound by every job. */
-    workflowContexts?: string[];
-    secretResolver?: unknown;
-    checkMode?: string;
-    jobContainer?: unknown;
-    jobSandbox?: {
-        capabilities?: string[];
-        network?: string;
-    };
-    sandboxAllowListReader?: unknown;
-    jobMatrix?: unknown;
-    contextConcurrencyLimit?: number | null;
-    /** Set wait_timer_seconds on the jobContext row, so its gate returns `wait`. */
-    contextWaitTimerSeconds?: number | null;
-    heldRunStore?: unknown;
-    /** Append a dynamic job fn, so dispatch spawns a deferred dynamic entry. */
-    withDynamicEntry?: boolean;
-    /** Give the static job a dynamic matrix, so its init is deferred. */
-    withDeferredInit?: boolean;
-    /** Declare a workflow-level filter, so every job defers to the init round. */
-    withFilter?: boolean;
-    pendingDynamics?: unknown;
-    pendingInits?: unknown;
-    /** Give the static job an explicit SDK requireApproval. */
-    jobApproval?: unknown;
-    /** Give the job a dynamic env, so its init is deferred without a matrix. */
-    withDynamicEnv?: boolean;
-    /** Bind the job to a DYNAMIC context, resolved only by the init round. */
-    withDynamicContext?: boolean;
-    /** A contextStore stub used verbatim (overrides the jobContext-derived one). */
-    contextStore?: unknown;
-    /**
-     * A checkRunReporter stub, so a case can observe the queued check runs the
-     * dispatch setup phase creates against the commit.
-     */
-    checkRunReporter?: unknown;
-}
-/**
- * A context row named `name` with no rules, always enabled; `rowOver` replaces
- * any column.
- */
-export declare function makeJobContextRow(name: string, over: SingleJobContextOptions, rowOver?: Record<string, unknown>): {
-    id: string;
-    org_id: string;
-    name: string;
-    type: string;
-    glob_pattern: null;
-    branch_restrictions: null;
-    trigger_type_filters: null;
-    repo_patterns: null;
-    concurrency_limit: number | null;
-    concurrency_strategy: null;
-    concurrency_timeout_ms: null;
-    required_reviewers: null;
-    wait_timer_seconds: number | null;
-    hold_expiry_seconds: null;
-    minimum_trust: null;
-    allow_local_execution: boolean;
-    enabled: boolean;
-    created_at: Date;
-    updated_at: Date;
-    created_by: null;
-};
-/**
- * Assemble a minimal real `WorkflowDispatchContext` for a single static job,
- * with a capturing dispatcher and all optional deps absent unless overridden.
- * This is the test-mode shape: `bundle` may be undefined and `trustResolution`
- * is undefined (single-orch, no holds, no trust).
- */
-export declare function makeSingleJobContext(over: SingleJobContextOptions): {
-    ctx: WorkflowDispatchContext;
-    dispatched: QueuedJobInput[];
-};
-/** An execution-tracker stub covering the calls a gated dispatch makes. */
-export interface GateTracker {
-    addJobsToRun: Mock;
-    onExecutionStarted: Mock;
-    onJobStatus: Mock;
-    holdRunForPendingJobs: Mock;
-    releasePendingJobsHold: Mock;
-    recordInitFailureRun: Mock;
-}
-/**
- * Resolve once every background task a dispatch started has finished. Each task
- * (a dynamic entry, a deferred init job) takes a pending-jobs token before
- * `dispatchMatchedWorkflow` returns and gives it back when it settles, so the
- * two counts match only when none is still running. A negative assertion made
- * after this cannot pass by running before the task reached its decision.
- */
-export declare function awaitDispatchTasksSettled(tracker: GateTracker): Promise<void>;
-/** A fresh {@link GateTracker}. */
-export declare function makeGateTracker(): GateTracker;
-/** Enough Kysely surface for the hold path: counts, upserts, and one transaction. */
-export declare function makeHoldDb(): Record<string, unknown>;
-//# sourceMappingURL=dispatch-matched-workflow.test-helpers.d.ts.map

package/dist/scaler/container-spawn.d.ts

@@ -1,28 +0,0 @@
-/**
- * Container-spawn primitives specific to the orchestrator's scaler backends.
- *
- * The runtime-injection half of this module (`pullImageIfMissing`,
- * `ensureRuntimeVolume`, `runtimeInjectBind`, `injectedAgentCommand`,
- * `runtimeVolumeName`, `RUNTIME_MOUNT`) now lives in
- * `@kici-dev/shared/container-runtime`, because the AGENT needs exactly the
- * same behaviour when it nests a job container. What stays here is the piece
- * only a scaler backend does: streaming a host workspace into a container it
- * just created.
- */
-/**
- * Stream a host directory into a container path.
- *
- * Used to populate a container-owned `/workspace` volume, which is a volume
- * rather than a host bind precisely so the host-uid vs container-uid conflict
- * disappears once `CapDrop: ALL` removes CAP_DAC_OVERRIDE — so the tree has to
- * be copied in rather than mounted.
- *
- * A failure is fatal to the spawn: swallowing it starts the job against an
- * empty workspace, which surfaces as a baffling "file not found" later.
- */
-export declare function copyTreeIntoContainer(container: {
-    putArchive(stream: unknown, opts: {
-        path: string;
-    }): Promise<unknown>;
-}, hostDir: string, containerPath: string): Promise<void>;
-//# sourceMappingURL=container-spawn.d.ts.map