@kici-dev/orchestrator 0.0.0 → 0.1.1

package/dist/cluster/raft.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Minimal Raft leader election implementation.
+ *
+ * Implements only leader election (no log replication) for cluster coordination.
+ * State machine: follower -> candidate -> leader. State is persisted to Postgres
+ * via RaftStateStore for crash recovery. Election timeout is 5-10s with randomized
+ * jitter (WAN-appropriate per research). Leader sends heartbeats every 2s.
+ *
+ * Dormant mode: When peerRegistry has 0 connected peers, the node self-elects
+ * immediately (single-orchestrator deployment). If peers connect later, normal
+ * election resumes.
+ *
+ * Raft heartbeat (raft.append.entries every 2s) is separate from peer inventory
+ * heartbeat (peer.heartbeat every 30s). Raft heartbeat is purely for leader
+ * liveness detection.
+ */
+import type { RaftVoteRequest, RaftVoteResponse, RaftAppendEntries } from '@kici-dev/engine';
+import type { PeerRegistry } from './peer-registry.js';
+import type { RaftStateStore } from './raft-state.js';
+export type RaftRole = 'follower' | 'candidate' | 'leader';
+interface RaftNodeDeps {
+    instanceId: string;
+    stateStore: RaftStateStore;
+    peerRegistry: PeerRegistry;
+    broadcastToPeers: (msg: RaftVoteRequest | RaftAppendEntries) => void;
+    onBecomeLeader: () => void;
+    onLoseLeadership: () => void;
+    electionTimeoutMinMs?: number;
+    electionTimeoutMaxMs?: number;
+    leaderHeartbeatMs?: number;
+    /** Grace period in ms before dormant-mode self-election. Default: 0 (no grace period). */
+    gracePeriodMs?: number;
+}
+export declare class RaftNode {
+    private readonly instanceId;
+    private readonly stateStore;
+    private readonly peerRegistry;
+    private readonly broadcastToPeers;
+    private readonly onBecomeLeader;
+    private readonly onLoseLeadership;
+    private readonly electionTimeoutMinMs;
+    private readonly electionTimeoutMaxMs;
+    private readonly leaderHeartbeatMs;
+    private readonly gracePeriodMs;
+    private startedAt;
+    private currentTerm;
+    private votedFor;
+    private leaderId;
+    private role;
+    private electionTimer;
+    private leaderHeartbeatTimer;
+    /** Votes received during the current election as candidate. */
+    private votesReceived;
+    /**
+     * Consecutive elections where no peer responded with a vote.
+     * When this exceeds the threshold, the node force-self-elects as a safety
+     * valve against delayed WebSocket close detection (peer appears "connected"
+     * but is actually dead).
+     */
+    private consecutiveUnansweredElections;
+    constructor(deps: RaftNodeDeps);
+    /**
+     * Start the Raft node. Loads persisted state from DB and starts
+     * as follower with election timer.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the Raft node. Clears all timers and persists state.
+     */
+    stop(): Promise<void>;
+    /** Whether this node is the current leader. */
+    isLeader(): boolean;
+    /** Get the current known leader's instance ID. */
+    getLeaderId(): string | null;
+    /** Get the current Raft term. */
+    getCurrentTerm(): number;
+    /** Get the current role (for testing/diagnostics). */
+    getRole(): RaftRole;
+    /**
+     * Handle a peer.leaving announcement from a gracefully shutting down peer.
+     * If the leaving peer is the current leader, immediately clear leaderId and
+     * start a new election. Otherwise, no election action (peer registry update
+     * is done by the caller before calling this method).
+     */
+    handlePeerLeaving(instanceId: string): void;
+    /**
+     * Reset the election timer with a randomized timeout.
+     * On expiry, starts an election.
+     */
+    resetElectionTimer(): void;
+    private clearElectionTimer;
+    /**
+     * Notify Raft that a peer disconnected. If this node is a follower or
+     * candidate, reset the election timer to a short value so Raft quickly
+     * re-evaluates whether it should self-elect (dormant mode).
+     * Without this, the node waits for the full election timeout (3-5s)
+     * before discovering all peers are gone.
+     */
+    onPeerDisconnected(): void;
+    /**
+     * Start a new election. Increment term, vote for self, request votes
+     * from peers. If no peers are connected, self-elect immediately
+     * (dormant mode for single-orchestrator deployments).
+     */
+    private startElection;
+    /**
+     * Handle an incoming vote request from another candidate.
+     */
+    handleVoteRequest(msg: RaftVoteRequest): RaftVoteResponse;
+    /**
+     * Handle a vote response from a peer.
+     */
+    handleVoteResponse(msg: RaftVoteResponse): void;
+    /**
+     * Check if we have a majority of votes to become leader.
+     * Cluster size = connected peers + self.
+     */
+    private checkMajority;
+    /**
+     * Transition to leader role. Start heartbeat timer, persist state,
+     * call onBecomeLeader callback.
+     */
+    private becomeLeader;
+    /**
+     * Step down from leader/candidate to follower.
+     */
+    private stepDown;
+    /**
+     * Start sending periodic leader heartbeats (raft.append.entries).
+     */
+    private startLeaderHeartbeat;
+    private sendHeartbeat;
+    private clearLeaderHeartbeat;
+    /**
+     * Handle an incoming append entries (heartbeat) from a leader.
+     */
+    handleAppendEntries(msg: RaftAppendEntries): void;
+}
+export {};
+//# sourceMappingURL=raft.d.ts.map

package/dist/cold-store/load-access-log-range.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Read-through helper for `access_log` (Orchestrator) — Phase D.
+ *
+ * Unlike `audit_log` and `secret_audit_log`, the `access_log` callers
+ * (dashboard "Data access" tab, admin HTTP route, `kici-admin
+ * access-log list` CLI) all use the same cursor-based pagination
+ * already implemented by `AccessLogWriter.query()`. Phase D's design
+ * §7 row 11 classifies access_log as "paginated/transparent" — there
+ * is NO `--include-archived` flag. The helper merges cold rows
+ * automatically when pagination crosses the warm cutoff or the caller
+ * supplies a `from` timestamp older than warm.
+ *
+ * Cursor extension: the existing cursor encodes `{createdAt, id}` for
+ * the hot tuple comparison `(created_at, id) < (cursor.createdAt, cursor.id)`.
+ * The cursor also carries a `source: 'hot' | 'cold'` discriminator so a
+ * cursor minted while the page boundary was inside cold can resume in
+ * the cold stream on the next request. Cursors without a `source` field
+ * default to `'hot'` — backwards-compatible with any tab the user had
+ * open across a deploy boundary.
+ */
+import { type Kysely, type Selectable } from 'kysely';
+import { type ColdStore } from '@kici-dev/shared';
+import { type AccessLogAction, type AccessLogItem, type AccessLogOutcome, type AccessLogSource, type AccessLogTargetType, type ActorType } from '@kici-dev/engine';
+import type { AccessLogTable, Database } from '../db/types.js';
+/**
+ * Synthetic tenant placeholder for orchestrator-level rows whose `org_id IS
+ * NULL` — collapses every NULL-tenant row under one cold-store prefix so the
+ * `(tenant_id, day)` partition scheme still yields a single scan key. Shared
+ * across every cold-store reader / adapter touching tables that may emit
+ * NULL-tenant rows (`access_log`, `secret_audit_log`); export once here so
+ * the four call sites in `cold-store/` and the fallback in
+ * `audit/access-log.ts` cannot drift apart.
+ */
+export declare const SYNTHETIC_ORCH_TENANT = "__orchestrator__";
+export type AccessLogColdRow = Selectable<AccessLogTable>;
+export interface LoadAccessLogRangeArgs {
+    db: Kysely<Database>;
+    coldStore: ColdStore | undefined;
+    filter: {
+        orgId?: string;
+        actorType?: ActorType;
+        actorId?: string;
+        action?: AccessLogAction;
+        source?: AccessLogSource;
+        outcome?: AccessLogOutcome;
+        targetType?: AccessLogTargetType;
+        targetId?: string;
+        fromTimestamp?: Date | string;
+        toTimestamp?: Date | string;
+        /**
+         * Full-text search over `error_message`. Trigram-indexed via migration
+         * `009_access_log_trigram.ts`. Min ~3 chars for the index to help.
+         */
+        q?: string;
+    };
+    limit: number;
+    cursor?: string;
+}
+export interface LoadAccessLogRangeResult {
+    items: AccessLogItem[];
+    nextCursor: string | null;
+}
+export declare function loadAccessLogRange(args: LoadAccessLogRangeArgs): Promise<LoadAccessLogRangeResult>;
+/**
+ * Canonical hot-or-cold `AccessLogRow → AccessLogItem` adapter. Exported
+ * because `AccessLogWriter.getById` (in `audit/access-log.ts`) needs to
+ * convert both hot (`AccessLogRow`) and cold (`AccessLogColdRow`) rows
+ * into the same `AccessLogItem` shape — the two row types are
+ * structurally identical (`Selectable<AccessLogTable>`), so a single
+ * converter avoids drift.
+ */
+export declare function toAccessLogItem(row: AccessLogColdRow): AccessLogItem;
+//# sourceMappingURL=load-access-log-range.d.ts.map

package/dist/cold-store/load-event-log-range.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Read-through helper for `event_log` (Orchestrator) — Phase E.
+ *
+ * Mirrors the Platform-side `load-event-log-range.ts`. Tenant column is
+ * `routing_key` (NOT NULL on this side) so cold-store partitioning
+ * doesn't need a synthetic-tenant fallback. Partition column is
+ * `received_at`.
+ *
+ * The orchestrator's `event_log` row carries the `payload_key` reference
+ * (an S3 object that holds the gzipped webhook body). Cold-store
+ * archives the row metadata and preserves `payload_key` verbatim — the
+ * payload blob itself stays in object storage indefinitely so the
+ * dashboard's payload-detail view continues to resolve archived
+ * deliveries identically to hot ones.
+ */
+import { type Kysely, type Selectable } from 'kysely';
+import { type ColdStore } from '@kici-dev/shared';
+import type { Database, EventLogTable } from '../db/types.js';
+export type EventLogColdStoreRow = Selectable<EventLogTable>;
+export interface LoadOrchEventLogRangeArgs {
+    db: Kysely<Database>;
+    coldStore: ColdStore | undefined;
+    /**
+     * Routing key (tenant column on this side). Required when
+     * `includeArchived` is true — cold-store fetch is keyed by tenant.
+     * The hot list endpoint also typically narrows by routing_key.
+     */
+    routingKey: string;
+    /** Optional org filter (event_log carries org_id for cross-tier joins). */
+    orgId?: string;
+    event?: string;
+    action?: string;
+    status?: string;
+    deliveryId?: string;
+    fromTs?: Date;
+    toTs?: Date;
+    limit: number;
+    offset: number;
+    includeArchived: boolean;
+}
+export declare function loadEventLogRange(args: LoadOrchEventLogRangeArgs): Promise<EventLogColdStoreRow[]>;
+/**
+ * Detail lookup by `(orgId, deliveryId)`. The dashboard handler joins
+ * cross-tier on this composite key. Hot first; on miss scans cold for
+ * the matching tenant. The caller must know `routingKey` to scope the
+ * cold scan — when only `orgId+deliveryId` are known, callers fall
+ * back to enumerating all routing keys for the org (rare; the dashboard
+ * always knows the routing_key from the Platform-side row).
+ */
+export declare function loadEventLogByDeliveryId(args: {
+    db: Kysely<Database>;
+    coldStore: ColdStore | undefined;
+    orgId: string;
+    deliveryId: string;
+    /**
+     * Optional routing-key hint. When omitted, the cold scan iterates
+     * every routing_key for the org — bounded but slower. The dashboard
+     * always provides this hint from the Platform-side join.
+     */
+    routingKey?: string;
+}): Promise<EventLogColdStoreRow | null>;
+//# sourceMappingURL=load-event-log-range.d.ts.map

package/dist/cold-store/load-secret-audit-log-range.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Read-through helper for `secret_audit_log` (Orchestrator) — Phase D.
+ *
+ * Mirrors the Phase B/C reader pattern. Wraps `AuditLogger.query()`'s
+ * existing offset/limit shape; cold-store rows are fetched only when
+ * `includeArchived === true`.
+ *
+ * Design contract: the `kici-admin secret audit` CLI surfaces an
+ * explicit `--include-archived` flag; admin HTTP route mirrors via a
+ * query param. Default is hot-only so existing tooling doesn't pay an
+ * S3 round-trip on every invocation.
+ *
+ * Cold-side filter handling: any filter that the hot SELECT applies
+ * (contextName, action, run_id, ...) is re-applied in-process to cold
+ * rows after streaming. This is correct because cold chunks are
+ * partitioned by `(routing_key, day)`, not by the secondary filters.
+ */
+import { type Kysely, type Selectable } from 'kysely';
+import { type ColdStore } from '@kici-dev/shared';
+import type { Database, SecretAuditLogTable } from '../db/types.js';
+export type SecretAuditLogRow = Selectable<SecretAuditLogTable>;
+export interface LoadSecretAuditLogRangeArgs {
+    db: Kysely<Database>;
+    coldStore: ColdStore | undefined;
+    /** Optional filters mirroring AuditLogger.query(). */
+    contextName?: string;
+    routingKey?: string;
+    action?: string;
+    /** Inclusive lower bound on `timestamp`. */
+    fromTs?: Date;
+    /** Exclusive upper bound on `timestamp`. */
+    toTs?: Date;
+    limit: number;
+    offset: number;
+    includeArchived: boolean;
+}
+export declare function loadSecretAuditLogRange(args: LoadSecretAuditLogRangeArgs): Promise<SecretAuditLogRow[]>;
+//# sourceMappingURL=load-secret-audit-log-range.d.ts.map

package/dist/cold-store/orchestrator-cold-store.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Orchestrator-side cold-store.
+ *
+ * Extends BaseColdStore with orchestrator-specific table adapters.
+ * Phase A registered no adapters; Phase C added execution_runs /
+ * execution_jobs / execution_steps. Phase D adds secret_audit_log
+ * and access_log.
+ */
+import { type Kysely } from 'kysely';
+import { BaseColdStore, type BaseColdStoreDeps, type ColdStoreConfig, type PurgeableChunk } from '@kici-dev/shared';
+import type { Database } from '../db/types.js';
+export interface OrchestratorColdStoreDeps extends Omit<BaseColdStoreDeps, 'db'> {
+    /** Kysely handle used by every registered Orchestrator adapter. */
+    kdb: Kysely<Database>;
+}
+export declare class OrchestratorColdStore extends BaseColdStore {
+    private readonly kdb;
+    constructor(deps: OrchestratorColdStoreDeps);
+    /**
+     * Phase 2 — query the orchestrator's `cold_store_chunks` table for
+     * chunks past their per-row cold-retention horizon. See the matching
+     * Platform-side method for the full rationale.
+     */
+    protected listPurgeableChunks(opts: {
+        tableFilter?: string;
+        bucketFilter?: string;
+        limit: number;
+    }): Promise<PurgeableChunk[]>;
+    /**
+     * Phase 2 — per-chunk advisory lock keyed on
+     * `hashtext('cold-store-purge|orchestrator|<table>|<chunkId>')`.
+     */
+    protected withPurgeLock<T>(args: {
+        table: string;
+        chunkId: string;
+    }, fn: () => Promise<T>): Promise<T | null>;
+}
+/**
+ * Build the orchestrator cold-store config from env vars. Reads
+ * `KICI_COLD_STORE_*` vars mirrored with the Platform side. YAML
+ * integration (per the design doc) lands in a follow-up commit that
+ * wires the `coldStore` section of the orchestrator config schema;
+ * Phase A ships the env-var path only.
+ */
+export declare function readOrchestratorColdStoreConfig(env?: NodeJS.ProcessEnv): ColdStoreConfig;
+/**
+ * Build the cold-store-archive scheduled-job handler for the
+ * orchestrator. Re-reads env vars on every tick so SIGHUP-driven
+ * config reload picks up new bucket/prefix values without a restart.
+ */
+export declare function createColdStoreArchiveHandler(instanceId: string, kdb: Kysely<Database>): () => Promise<void>;
+/**
+ * Phase 2 — build the cold-store-purge scheduled-job handler. Same
+ * env-var re-read pattern as the archive handler so SIGHUP picks up
+ * config changes mid-run.
+ */
+export declare function createColdStorePurgeHandler(instanceId: string, kdb: Kysely<Database>): () => Promise<void>;
+//# sourceMappingURL=orchestrator-cold-store.d.ts.map

package/dist/cold-store/tables/access-log.d.ts

@@ -0,0 +1,80 @@
+/**
+ * `access_log` cold-store adapter (Orchestrator side).
+ *
+ *
+ * Contract:
+ *   - tenant column: `org_id` (NULL → synthetic `__orchestrator__`)
+ *   - partition column: `created_at`
+ *   - warm TTL: 30 days (design §5 matrix row 11)
+ *
+ * Replaces the previous 90-day `expires_at`-based hard delete (removed
+ * by migration 007). Rows older than 30 days now live in S3
+ * indefinitely.
+ *
+ * Synthetic tenant: orchestrator-level access events (e.g. scheduler
+ * tick failures, admin-triggered scheduled jobs) carry `org_id IS
+ * NULL`; they collapse to the `__orchestrator__` synthetic prefix.
+ *
+ * Recursion: archiving access_log rows writes a new access_log row
+ * recording the archive (one per chunk). The new row is itself
+ * eligible for archive in a future cycle. Volume is bounded — one
+ * audit row per ~50K-row chunk.
+ */
+import { type Kysely, type Selectable } from 'kysely';
+import { type ChunkCommitMetadata, type ColdRetention, type ColdStoreTableConfig, type EligiblePartition, type TableAdapter } from '@kici-dev/shared';
+import type { AccessLogTable, Database } from '../../db/types.js';
+export type AccessLogColdStoreRow = Selectable<AccessLogTable>;
+export interface AccessLogAdapterOptions {
+    overrides?: Partial<ColdStoreTableConfig>;
+}
+export declare class AccessLogAdapter implements TableAdapter<AccessLogColdStoreRow> {
+    private readonly kdb;
+    private readonly instanceId;
+    readonly db: "orchestrator";
+    readonly table = "access_log";
+    readonly tenantColumn = "org_id";
+    readonly partitionColumn = "created_at";
+    readonly config: ColdStoreTableConfig;
+    constructor(kdb: Kysely<Database>, instanceId: string, opts?: AccessLogAdapterOptions);
+    listEligiblePartitions(args: {
+        warmCutoff: Date;
+    }): AsyncIterable<EligiblePartition>;
+    countTenantWarmBytes(args: {
+        tenantId: string;
+        warmCutoff: Date;
+    }): Promise<number>;
+    withPartitionLock<T>(args: {
+        tenantId: string;
+        partitionDate: string;
+    }, fn: () => Promise<T>): Promise<T | null>;
+    selectEligible(args: {
+        tenantId: string;
+        partitionDate: string;
+        limit: number;
+    }): AsyncIterable<AccessLogColdStoreRow>;
+    encodeRow(row: AccessLogColdStoreRow): string;
+    decodeRow(line: string): AccessLogColdStoreRow;
+    rowId(row: AccessLogColdStoreRow): string | number;
+    rowTimestamp(row: AccessLogColdStoreRow): Date | string;
+    /**
+     * Phase 2 — per-row cold-retention TTL. Mirrors the warm-side override
+     * layering: outcome=denied/error → 730d (forensic), platform_operator →
+     * `'forever'` (compliance), otherwise per-action map. The framework
+     * groups rows by `coldDaysToBucket(coldTtlDays(row))` at archive time.
+     */
+    coldTtlDays(row: AccessLogColdStoreRow): ColdRetention;
+    markArchivedAndDelete(args: {
+        rowIds: ReadonlyArray<string | number>;
+        chunkMeta: ChunkCommitMetadata;
+    }): Promise<void>;
+    purgeChunkRecord(args: {
+        tenantId: string;
+        chunkId: string;
+        gzipBytes: number;
+        rowCount: number;
+        bucket: string;
+        maxColdDays: number;
+        objectKey: string;
+    }): Promise<void>;
+}
+//# sourceMappingURL=access-log.d.ts.map

package/dist/cold-store/tables/event-log.d.ts

@@ -0,0 +1,70 @@
+/**
+ * `event_log` cold-store adapter (Orchestrator side) —.
+ *
+ *  §2 row 6
+ * and §10.
+ *
+ * Contract:
+ *   - tenant column: `routing_key` (NOT NULL on this side — no
+ *     synthetic-tenant fallback like access_log / secret_audit_log)
+ *   - partition column: `received_at`
+ *   - warm TTL: 30 days (replaces the previous 30-day hard delete in
+ *     `packages/orchestrator/src/webhook/event-log.ts:cleanup` +
+ *     `packages/orchestrator/src/queue/cleanup.ts:runCleanup` step 4)
+ *
+ * Per-row payload retention: rows on this table carry a `payload_key`
+ * pointing at a gzipped webhook body in object storage (LogStorage).
+ * Cold-store packages the row metadata — including `payload_key` —
+ * but does NOT touch the body the key points to. The body remains in
+ * S3 indefinitely so the dashboard delivery-detail page resolves
+ * payload reads identically for hot and cold rows. The pre-Phase-E
+ * cleanup that deleted both the row and the payload blob in
+ * lock-step is retired.
+ *
+ * Recursive write: archiving event_log rows writes one access_log
+ * audit row per chunk (the orchestrator's audit surface). The new
+ * access_log rows themselves get archived in a later cycle by the
+ * AccessLogAdapter, bounded.
+ */
+import { type Kysely, type Selectable } from 'kysely';
+import { type ChunkCommitMetadata, type ColdStoreTableConfig, type EligiblePartition, type TableAdapter } from '@kici-dev/shared';
+import type { Database, EventLogTable } from '../../db/types.js';
+export type EventLogColdStoreRow = Selectable<EventLogTable>;
+export interface EventLogAdapterOptions {
+    overrides?: Partial<ColdStoreTableConfig>;
+}
+export declare class EventLogAdapter implements TableAdapter<EventLogColdStoreRow> {
+    private readonly kdb;
+    private readonly instanceId;
+    readonly db: "orchestrator";
+    readonly table = "event_log";
+    readonly tenantColumn = "routing_key";
+    readonly partitionColumn = "received_at";
+    readonly config: ColdStoreTableConfig;
+    constructor(kdb: Kysely<Database>, instanceId: string, opts?: EventLogAdapterOptions);
+    listEligiblePartitions(args: {
+        warmCutoff: Date;
+    }): AsyncIterable<EligiblePartition>;
+    countTenantWarmBytes(args: {
+        tenantId: string;
+        warmCutoff: Date;
+    }): Promise<number>;
+    withPartitionLock<T>(args: {
+        tenantId: string;
+        partitionDate: string;
+    }, fn: () => Promise<T>): Promise<T | null>;
+    selectEligible(args: {
+        tenantId: string;
+        partitionDate: string;
+        limit: number;
+    }): AsyncIterable<EventLogColdStoreRow>;
+    encodeRow(row: EventLogColdStoreRow): string;
+    decodeRow(line: string): EventLogColdStoreRow;
+    rowId(row: EventLogColdStoreRow): string | number;
+    rowTimestamp(row: EventLogColdStoreRow): Date | string;
+    markArchivedAndDelete(args: {
+        rowIds: ReadonlyArray<string | number>;
+        chunkMeta: ChunkCommitMetadata;
+    }): Promise<void>;
+}
+//# sourceMappingURL=event-log.d.ts.map

package/dist/cold-store/tables/execution-jobs.d.ts

@@ -0,0 +1,63 @@
+/**
+ * `execution_jobs` cold-store adapter (Orchestrator side).
+ *
+ *
+ * Contract:
+ *   - tenant column: `routing_key` (denormalized in migration 006)
+ *   - partition column: `created_at`
+ *   - warm TTL: 30 days (design §5 matrix row 8)
+ *   - eligibility: terminal job status AND no live steps remain for this
+ *     (run, job)
+ *
+ * Order: registered AFTER `ExecutionStepsAdapter`, BEFORE
+ * `ExecutionRunsAdapter` (within one cycle: steps → jobs → runs). The
+ * "no live steps" predicate makes the ordering self-correcting across
+ * cycle interruptions.
+ *
+ * FK ordering on the orchestrator side: `execution_jobs.run_id` is a
+ * FK to `execution_runs(run_id)`. Deleting a job is safe from the FK's
+ * perspective (the FK only constrains job → run direction). The runs
+ * adapter's eligibility predicate handles the dependent-rows check.
+ */
+import { type Kysely, type Selectable } from 'kysely';
+import { type ChunkCommitMetadata, type ColdStoreTableConfig, type EligiblePartition, type TableAdapter } from '@kici-dev/shared';
+import type { Database, ExecutionJobTable } from '../../db/types.js';
+export type ExecutionJobRow = Selectable<ExecutionJobTable>;
+export interface ExecutionJobsAdapterOptions {
+    overrides?: Partial<ColdStoreTableConfig>;
+}
+export declare class ExecutionJobsAdapter implements TableAdapter<ExecutionJobRow> {
+    private readonly kdb;
+    private readonly instanceId;
+    readonly db: "orchestrator";
+    readonly table = "execution_jobs";
+    readonly tenantColumn = "routing_key";
+    readonly partitionColumn = "created_at";
+    readonly config: ColdStoreTableConfig;
+    constructor(kdb: Kysely<Database>, instanceId: string, opts?: ExecutionJobsAdapterOptions);
+    listEligiblePartitions(args: {
+        warmCutoff: Date;
+    }): AsyncIterable<EligiblePartition>;
+    countTenantWarmBytes(args: {
+        tenantId: string;
+        warmCutoff: Date;
+    }): Promise<number>;
+    withPartitionLock<T>(args: {
+        tenantId: string;
+        partitionDate: string;
+    }, fn: () => Promise<T>): Promise<T | null>;
+    selectEligible(args: {
+        tenantId: string;
+        partitionDate: string;
+        limit: number;
+    }): AsyncIterable<ExecutionJobRow>;
+    encodeRow(row: ExecutionJobRow): string;
+    decodeRow(line: string): ExecutionJobRow;
+    rowId(row: ExecutionJobRow): string | number;
+    rowTimestamp(row: ExecutionJobRow): Date | string;
+    markArchivedAndDelete(args: {
+        rowIds: ReadonlyArray<string | number>;
+        chunkMeta: ChunkCommitMetadata;
+    }): Promise<void>;
+}
+//# sourceMappingURL=execution-jobs.d.ts.map

package/dist/cold-store/tables/execution-runs.d.ts

@@ -0,0 +1,81 @@
+/**
+ * `execution_runs` cold-store adapter (Orchestrator side).
+ *
+ *
+ * Contract:
+ *   - tenant column: `routing_key`
+ *   - partition column: `created_at`
+ *   - warm TTL: 30 days (design §5 matrix row 7)
+ *   - eligibility: terminal run status AND no live jobs reference this run
+ *
+ * Order: registered LAST in the orchestrator cold-store. Within one
+ * cycle the framework iterates adapters steps → jobs → runs; this
+ * adapter goes last so the FK `execution_jobs.run_id →
+ * execution_runs(run_id)` doesn't fire on DELETE. The "no live jobs"
+ * predicate enforces the same invariant across cycle interruptions.
+ */
+import { type Kysely, type Selectable } from 'kysely';
+import { type ChunkCommitMetadata, type ColdStoreTableConfig, type EligiblePartition, type TableAdapter } from '@kici-dev/shared';
+import type { Database, ExecutionRunTable } from '../../db/types.js';
+export type ExecutionRunRow = Selectable<ExecutionRunTable>;
+export interface ExecutionRunsAdapterOptions {
+    overrides?: Partial<ColdStoreTableConfig>;
+}
+export declare class ExecutionRunsAdapter implements TableAdapter<ExecutionRunRow> {
+    private readonly kdb;
+    private readonly instanceId;
+    readonly db: "orchestrator";
+    readonly table = "execution_runs";
+    readonly tenantColumn = "routing_key";
+    readonly partitionColumn = "created_at";
+    readonly config: ColdStoreTableConfig;
+    constructor(kdb: Kysely<Database>, instanceId: string, opts?: ExecutionRunsAdapterOptions);
+    listEligiblePartitions(args: {
+        warmCutoff: Date;
+    }): AsyncIterable<EligiblePartition>;
+    countTenantWarmBytes(args: {
+        tenantId: string;
+        warmCutoff: Date;
+    }): Promise<number>;
+    withPartitionLock<T>(args: {
+        tenantId: string;
+        partitionDate: string;
+    }, fn: () => Promise<T>): Promise<T | null>;
+    selectEligible(args: {
+        tenantId: string;
+        partitionDate: string;
+        limit: number;
+    }): AsyncIterable<ExecutionRunRow>;
+    encodeRow(row: ExecutionRunRow): string;
+    decodeRow(line: string): ExecutionRunRow;
+    rowId(row: ExecutionRunRow): string | number;
+    rowTimestamp(row: ExecutionRunRow): Date | string;
+    /**
+     * Phase F — natural-key extractor used by `replayRow` so callers
+     * (the rerun pipeline) can locate the chunk holding a given UUID
+     * `run_id` without knowing the internal SERIAL `id` returned by
+     * `rowId()`.
+     */
+    replayLookupKey(row: ExecutionRunRow): string;
+    /**
+     * Phase F — replay a chunk's `execution_runs` rows back into
+     * Orchestrator PG. Mirrors the Platform-side replayInsert; the
+     * audit row goes to `access_log` (not `audit_log`) because the
+     * orchestrator's audit surface is access_log per design §8.
+     *
+     * Idempotent on duplicate replays via `ON CONFLICT (run_id) DO
+     * NOTHING`. Decrements `cold_store_chunk_counts` (floored at 0).
+     */
+    replayInsert(args: {
+        rows: ReadonlyArray<ExecutionRunRow>;
+        chunkMeta: ChunkCommitMetadata;
+    }): Promise<{
+        inserted: number;
+        skipped: number;
+    }>;
+    markArchivedAndDelete(args: {
+        rowIds: ReadonlyArray<string | number>;
+        chunkMeta: ChunkCommitMetadata;
+    }): Promise<void>;
+}
+//# sourceMappingURL=execution-runs.d.ts.map