@kici-dev/orchestrator 0.16.0 → 0.18.0

package/dist/cluster/reconcile-identity.d.ts

@@ -3,10 +3,9 @@ export type ReconcileDirection = 'db-from-sentinel' | 'sentinel-from-db';
 export interface ReconcileS3Config {
     bucket: string;
     /**
-     * Optional storage prefix (mirrors `KICI_STORAGE_PREFIX`). The sentinel lives
-     * at `<prefix>/.kici-cluster-id`; must match the prefix the orchestrator boots
-     * with. When omitted, `clusterSentinelKey` resolves the bucket root — the same
-     * as the orchestrator's `DEFAULT_CACHE_STORAGE_S3_PREFIX` (empty) default.
+     * Mirrors `KICI_STORAGE_PREFIX` and must match the orchestrator's boot prefix.
+     * When omitted, the sentinel sits at the bucket root, matching the empty
+     * `DEFAULT_CACHE_STORAGE_S3_PREFIX` default.
      */
     prefix?: string;
     region?: string;
@@ -25,9 +24,8 @@ declare function writeClusterIdToDb(databaseUrl: string, clusterId: string): Pro
 declare function readSentinel(s3: ReconcileS3Config): Promise<string | null>;
 declare function writeSentinel(s3: ReconcileS3Config, clusterId: string): Promise<void>;
 /**
- * Indirection object for the DB + S3 reads/writes, so the unit test can stub
- * the I/O without an ESM partial-mock dance. `buildReconcileStep` calls every
- * reader/writer through this object; the test overrides its members directly.
+ * `buildReconcileStep` calls all I/O through this object, so the unit test
+ * stubs its members without an ESM partial mock.
  */
 export declare const reconcileIo: {
     readClusterIdFromDb: typeof readClusterIdFromDb;
@@ -36,10 +34,9 @@ export declare const reconcileIo: {
     writeSentinel: typeof writeSentinel;
 };
 /**
- * Build the idempotent step that reconciles the cluster identity in the given
- * direction. `check()` returns drift when the two sides disagree (or null when
- * in sync); `apply()` performs the single write that brings them into
- * agreement. Run it through `runIdempotentStep` (`@kici-dev/core/idempotency`).
+ * `check()` returns drift when the sides disagree (null when in sync);
+ * `apply()` performs the single write that brings them into agreement. Run it
+ * through `runIdempotentStep` (`@kici-dev/core/idempotency`).
  */
 export declare function buildReconcileStep(deps: {
     databaseUrl: string;

package/dist/cluster/rerouted-job-guard.d.ts

@@ -17,18 +17,14 @@ import type { PeerRegistry } from './peer-registry.js';
  */
 export declare const DEFAULT_REROUTE_FLAP_GRACE_MS = 120000;
 /**
- * A non-terminal job that was rerouted to a remote worker peer must NOT be
- * force-failed by the run-recovery sweepers (OrphanRecovery, StaleRunDetector)
- * while that worker peer can still replay the job's terminal status from its
- * durable outbox.
+ * Whether the run-recovery sweepers (OrphanRecovery, StaleRunDetector) must defer
+ * force-failing a non-terminal rerouted job, because its worker peer can still
+ * replay the terminal status from its durable outbox.
  *
- * Returns `true` (defer the sweeper's force-fail) when the job carries a
- * `rerouted_to_peer` marker AND its peer is either currently connected OR was
- * last seen within the flap-grace window (a transient peer-WS reconnect during
- * a coordinator restart / leadership transition). A rerouted job whose peer has
- * been gone longer than the grace window — or is no longer tracked at all — is
- * NOT deferred, so a dead worker's job is still failed and cannot hang forever.
- * Local (non-rerouted) jobs — `rerouted_to_peer === null` — are never deferred.
+ * True when the job has a `rerouted_to_peer` AND that peer is connected or was
+ * last seen within the flap grace. A peer gone longer than the grace, or no
+ * longer tracked, is not deferred, so a dead worker cannot hang a run. Local
+ * jobs (`rerouted_to_peer === null`) are never deferred.
  */
 export declare function shouldDeferReroutedJob(job: {
     rerouted_to_peer: string | null;

package/dist/cluster/verified-issuer.d.ts

@@ -54,10 +54,9 @@ export declare function tryResolveVerifiedIssuer(reader: VerifiedIssuerReader):
  * out". An unknown read must therefore produce an object with no key at all —
  * not one whose value is `undefined`, which would still overwrite on spread.
  *
- * Extracted as a pure function because its only caller is a closure inside
- * server.ts's connection handler, which has no test seam.
+ * Pure so it is testable: its only caller is a closure in server.ts's connection
+ * handler, which has no test seam.
  */
 export declare function verifiedIssuerCapabilityUpdate(read: VerifiedIssuerRead): Partial<Pick<OrchCapabilities, 'dashboardVerifiedIssuer'>>;
-/** The JWKS document URL for an issuer origin. */
 export declare function jwksUrlFor(issuer: string): string;
 //# sourceMappingURL=verified-issuer.d.ts.map

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

@@ -1,15 +1,13 @@
 /**
  * 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.
+ * Every knob a worker 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;
@@ -21,10 +19,9 @@ export interface WorkerClusterSettingsSnapshot {
     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.
+ * Resolve the snapshot and its version from ONE row read: a worker pulls again
+ * only on a higher advertised version, so a separately read version 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/cluster/worker-eviction.d.ts

@@ -2,29 +2,24 @@ import type { PeerInfo, PeerRegistry } from './peer-registry.js';
 /** How long a draining worker may hold in-flight jobs before it is disconnected anyway. */
 export declare const WORKER_DRAIN_TIMEOUT_MS: number;
 /**
- * The coordinator-side operations eviction needs.
- *
- * Declared here rather than reached for on the coordinator directly: the
- * coordinator owns dispatch and job attribution, but exposes no ineligibility
- * or idle-notification surface, and widening its public API for one caller
- * would couple eviction to it. A fake implementation makes this class unit
- * testable without a running cluster.
+ * The coordinator-side operations eviction needs, declared here because the
+ * coordinator exposes no ineligibility or idle-notification surface, and
+ * widening its API for one caller would couple eviction to it. A fake makes
+ * this class unit testable without a running cluster.
  */
 export interface EvictionHooks {
     /** Stop rerouting new jobs to this peer. */
     markIneligible(instanceId: string): void;
     /**
-     * Restore this peer to dispatch eligibility and drop any idle-notification
-     * registration. Called when a drain is cancelled (the ceiling rose so the
-     * peer is no longer excess) and after a drained peer is disconnected, so a
-     * later re-admission of the same instance starts dispatch-eligible.
+     * Restore dispatch eligibility and drop any idle-notification registration.
+     * Called when a drain is cancelled and after a drained peer is disconnected,
+     * so a later re-admission of the same instance starts dispatch-eligible.
      */
     clearIneligible(instanceId: string): void;
     /** In-flight rerouted jobs currently attributed to this peer. */
     runningJobCount(instanceId: string): number;
     /** Invoke the callback once this peer has no in-flight rerouted jobs. */
     onPeerIdle(instanceId: string, callback: () => void): void;
-    /** Close this peer's connection with the given code and reason. */
     closePeer(instanceId: string, code: number, reason: string): void;
 }
 /**
@@ -37,11 +32,10 @@ export declare function selectEvictionTargets(workers: readonly PeerInfo[], ceil
 /**
  * Drain-then-disconnect this coordinator's excess workers.
  *
- * A target is first marked ineligible for new dispatch, then closed once its
- * in-flight rerouted jobs reach terminal status — which the worker's durable
- * outbox and `job.progress.ack` already guarantee — or after
- * `WORKER_DRAIN_TIMEOUT_MS`, after which the coordinator's existing
- * orphan-recovery guard handles whatever remains.
+ * A target is marked ineligible for new dispatch, then closed once its
+ * in-flight rerouted jobs reach terminal status (guaranteed by the worker's
+ * durable outbox and `job.progress.ack`) or after `WORKER_DRAIN_TIMEOUT_MS`,
+ * when the orphan-recovery guard handles whatever remains.
  */
 export declare class WorkerEviction {
     private readonly peerRegistry;
@@ -52,17 +46,13 @@ export declare class WorkerEviction {
         warn: (msg: string, meta?: unknown) => void;
     });
     /**
-     * Reconcile the connected worker set against the ceiling.
-     *
-     * When `evictExcess` is true, drain the newest workers past `ceiling`;
-     * otherwise the target set is empty. Any drain in flight for a worker that is
-     * no longer a target is CANCELLED — its timer cleared and its dispatch
-     * eligibility restored — so a raised ceiling (or the Platform clearing
-     * `evictExcess` once the org drops back under) rescues a worker instead of
-     * disconnecting it at the drain timeout.
+     * With `evictExcess`, drain the newest workers past `ceiling`; otherwise the
+     * target set is empty. A drain in flight for a worker no longer targeted is
+     * CANCELLED (timer cleared, eligibility restored), so a raised ceiling or the
+     * Platform clearing `evictExcess` once the org drops back under its limit
+     * rescues the worker instead of disconnecting it at the drain timeout.
      */
     reconcile(ceiling: number, evictExcess: boolean): void;
-    /** Stop an in-flight drain and restore the worker to dispatch eligibility. */
     private cancelDrain;
     private startDrain;
 }

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

@@ -1,35 +1,25 @@
 /**
  * Read-through helper for `access_log` (Orchestrator).
  *
- * 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()`. access_log is
- * "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.
+ * Unlike `audit_log` and `secret_audit_log`, every `access_log` caller (dashboard "Data access"
+ * tab, admin HTTP route, `kici-admin access-log list`) shares the cursor pagination of
+ * `AccessLogWriter.query()`, so there is NO `--include-archived` flag: cold rows merge in
+ * automatically when pagination crosses the warm cutoff or `from` is 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. A cursor without a valid `source` is
- * invalid, like any other unparsable cursor, and the read starts from the
- * first page.
+ * The cursor encodes `{createdAt, id}` for the tuple comparison
+ * `(created_at, id) < (cursor.createdAt, cursor.id)`, plus a `source: 'hot' | 'cold'`
+ * discriminator so a page boundary inside cold resumes in the cold stream. A cursor without a
+ * valid `source` is unparsable, and the read starts from the first page.
  */
 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.
+ * Synthetic tenant for orchestrator-level rows whose `org_id IS NULL`: it collapses them under
+ * one cold-store prefix so the `(tenant_id, day)` partition still yields a single scan key.
+ * Exported once so the `cold-store/` readers and adapters for NULL-tenant tables (`access_log`,
+ * `secret_audit_log`) and the fallback in `audit/access-log.ts` cannot drift apart.
  */
 export declare const SYNTHETIC_ORCH_TENANT = "__orchestrator__";
 export type AccessLogColdRow = Selectable<AccessLogTable>;
@@ -47,10 +37,7 @@ export interface LoadAccessLogRangeArgs {
         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.
-         */
+        /** Search over `error_message`; trigram-indexed (migration 009), so ~3+ chars use the index. */
         q?: string;
         /** Exact-match filter on the agent provenance label (`agent_label` column). */
         agentLabel?: string;
@@ -66,11 +53,8 @@ export interface LoadAccessLogRangeResult {
 }
 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
+ * Canonical hot-or-cold row → `AccessLogItem` adapter, exported for `AccessLogWriter.getById`
+ * (`audit/access-log.ts`). Hot and cold rows are both `Selectable<AccessLogTable>`, so one
  * converter avoids drift.
  */
 export declare function toAccessLogItem(row: AccessLogColdRow): AccessLogItem;

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

@@ -1,37 +1,24 @@
 /**
- * Read-through helper for `event_log` (Orchestrator).
+ * Read-through helper for `event_log`; mirrors the Platform-side `load-event-log-range.ts`.
  *
- * 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.
+ * Tenant column is `routing_key` (NOT NULL here, so no synthetic-tenant fallback); partition
+ * column is `received_at`. Cold-store archives the row metadata and keeps `payload_key` (the
+ * S3 object holding the gzipped webhook body) verbatim; the blob stays in object storage
+ * indefinitely, so the payload-detail view resolves archived deliveries like hot ones.
  */
 import { type Kysely } from 'kysely';
 import { type ColdStore } from '@kici-dev/shared';
 import type { Database } from '../db/types.js';
 import type { EventLogColdStoreRow } from './tables/event-log.js';
 /**
- * Re-exported, not re-declared: the alias is defined beside the cold-store
- * adapter that owns the table, and a second identical declaration here is what
- * a homonym sweep flags. Kept as an export so this module's public surface is
- * unchanged for its consumers.
+ * Re-exported, not re-declared: the alias lives beside the cold-store adapter that owns the
+ * table (a second declaration trips the homonym sweep); the export keeps this module's surface.
  */
 export type { EventLogColdStoreRow };
 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.
-     */
+    /** Tenant column; required for `includeArchived` because the cold-store fetch is keyed by it. */
     routingKey: string;
     /** Optional org filter (event_log carries org_id for cross-tier joins). */
     orgId?: string;
@@ -49,9 +36,8 @@ export declare function loadEventLogRange(args: LoadOrchEventLogRangeArgs): Prom
 /**
  * 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
+ * the matching tenant. The caller must pass `routingKey` to scope the
+ * cold scan; without it a hot miss returns `null` (the dashboard
  * always knows the routing_key from the Platform-side row).
  */
 export declare function loadEventLogByDeliveryId(args: {
@@ -60,9 +46,9 @@ export declare function loadEventLogByDeliveryId(args: {
     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.
+     * Routing-key hint that scopes the cold scan. When omitted, the cold
+     * scan is skipped with a warning and a hot miss returns `null`. The
+     * dashboard always provides this hint from the Platform-side join.
      */
     routingKey?: string;
 }): Promise<EventLogColdStoreRow | null>;

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

@@ -1,19 +1,15 @@
 /**
  * Read-through helper for `secret_audit_log` (Orchestrator).
  *
- * Mirrors the execution-table reader pattern. Wraps `AuditLogger.query()`'s
- * existing offset/limit shape; cold-store rows are fetched only when
- * `includeArchived === true`.
+ * Follows the execution-table reader pattern with `AuditLogger.query()`'s
+ * offset/limit shape. Cold rows are fetched only when `includeArchived` is
+ * true (`kici-admin secret audit --include-archived`, or the admin HTTP query
+ * param); hot-only is the default so tooling skips an S3 round-trip.
  *
- * 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.
+ * Hot-side filters also apply to cold rows: routingKey selects the tenant, the
+ * time bounds go to `fetchRange`, and contextName / action are checked
+ * in-process, because cold chunks are partitioned by `(routing_key, day)`,
+ * not by the secondary filters.
  */
 import { type Kysely } from 'kysely';
 import { type ColdStore } from '@kici-dev/shared';

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

@@ -1,10 +1,4 @@
-/**
- * Orchestrator-side cold-store.
- *
- * Extends BaseColdStore with orchestrator-specific table adapters:
- * execution_runs / execution_jobs / execution_steps, secret_audit_log,
- * access_log and event_log.
- */
+/** Orchestrator cold-store: BaseColdStore plus the orchestrator table adapters. */
 import { type Kysely } from 'kysely';
 import { BaseColdStore, type BaseColdStoreDeps, type ColdStoreConfig, type PurgeableChunk } from '@kici-dev/shared';
 import type { Database } from '../db/types.js';
@@ -15,42 +9,28 @@ export interface OrchestratorColdStoreDeps extends Omit<BaseColdStoreDeps, 'db'>
 export declare class OrchestratorColdStore extends BaseColdStore {
     private readonly kdb;
     constructor(deps: OrchestratorColdStoreDeps);
-    /**
-     * 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.
-     */
+    /** Chunks past their per-row cold-retention horizon; rationale on the Platform-side method. */
     protected listPurgeableChunks(opts: {
         tableFilter?: string;
         bucketFilter?: string;
         limit: number;
     }): Promise<PurgeableChunk[]>;
-    /**
-     * Per-chunk advisory lock keyed on
-     * `hashtext('cold-store-purge|orchestrator|<table>|<chunkId>')`.
-     */
+    /** Per-chunk advisory lock 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. The
- * orchestrator config schema has no `coldStore` section, so env vars are
- * the only input.
+ * Reads the `KICI_COLD_STORE_*` env vars (mirrored with the Platform side). The orchestrator
+ * config schema has no `coldStore` section, so env vars are the only input.
  */
 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.
+ * Re-reads env vars on every tick, so a SIGHUP config reload picks up new bucket/prefix
+ * values without a restart.
  */
 export declare function createColdStoreArchiveHandler(instanceId: string, kdb: Kysely<Database>): () => Promise<void>;
-/**
- * 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.
- */
+/** Re-reads env vars on every tick, like the archive handler. */
 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

@@ -4,19 +4,17 @@
  * Contract:
  *   - tenant column: `org_id` (NULL → synthetic `__orchestrator__`)
  *   - partition column: `created_at`
- *   - warm TTL: 30 days
+ *   - warm TTL: `minAccessLogWarmDays()` table-wide, tightened per row
+ *     by `accessLogWarmSqlCase()`
+ *   - archived chunks purge per `getAccessLogColdDays()`
  *
- * Rows older than 30 days live in S3 indefinitely; there is no
- * `expires_at`-based hard delete.
+ * There is no `expires_at`-based hard delete.
  *
- * 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.
+ * Orchestrator-level events (e.g. scheduler tick failures, admin-triggered
+ * scheduled jobs) carry `org_id IS NULL` and use the `__orchestrator__` 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.
+ * Recursion: archiving writes one access_log row per chunk, itself archivable
+ * later. 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, PgTableAdapterBase } from '@kici-dev/shared';
@@ -49,10 +47,10 @@ export declare class AccessLogAdapter extends PgTableAdapterBase<Database> imple
     rowId(row: AccessLogColdStoreRow): string | number;
     rowTimestamp(row: AccessLogColdStoreRow): Date | string;
     /**
-     * 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.
+     * Per-row cold-retention TTL, mirroring the warm-side layering:
+     * outcome=denied/error → 730d (forensic), platform_operator → `'forever'`
+     * (compliance), otherwise the per-action map. Archive buckets rows by
+     * `coldDaysToBucket(coldTtlDays(row))`.
      */
     coldTtlDays(row: AccessLogColdStoreRow): ColdRetention;
     markArchivedAndDelete(args: {

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

@@ -2,18 +2,14 @@
  * `event_log` cold-store adapter (Orchestrator side).
  *
  * Contract:
- *   - tenant column: `routing_key` (NOT NULL on this side — no
- *     synthetic-tenant fallback like access_log / secret_audit_log)
+ *   - tenant column: `routing_key` (NOT NULL — no synthetic-tenant fallback)
  *   - partition column: `received_at`
  *   - warm TTL: 30 days (rows are archived, not hard-deleted)
  *
- * Each row's `payload_key` points at a gzipped webhook body in object
- * storage. Archiving moves the row, `payload_key` included, and leaves the
- * body where it is, so the delivery-detail page reads payloads the same way
- * for hot and cold rows.
+ * Archiving moves the row with its `payload_key` and leaves the gzipped webhook body in object
+ * storage, so the delivery-detail page reads hot and cold payloads the same way.
  *
- * Each archived chunk writes one `access_log` audit row, which the
- * AccessLogAdapter archives in a later cycle.
+ * Each archived chunk writes one `access_log` audit row, archived in a later cycle.
  */
 import { type Kysely, type Selectable } from 'kysely';
 import { type ChunkCommitMetadata, type ColdStoreTableConfig, type EligiblePartition, type TableAdapter, PgTableAdapterBase } from '@kici-dev/shared';

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

@@ -37,20 +37,15 @@ export declare class ExecutionRunsAdapter extends PgTableAdapterBase<Database> i
     rowId(row: ExecutionRunRow): string | number;
     rowTimestamp(row: ExecutionRunRow): Date | string;
     /**
-     * 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()`.
+     * Natural key for `replayRow`, so the rerun pipeline finds the chunk holding
+     * a UUID `run_id` without the internal SERIAL `id` from `rowId()`.
      */
     replayLookupKey(row: ExecutionRunRow): string;
     /**
-     * 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.
-     *
-     * Idempotent on duplicate replays via `ON CONFLICT (run_id) DO
-     * NOTHING`. Decrements `cold_store_chunk_counts` (floored at 0).
+     * Replay a chunk's `execution_runs` rows into Orchestrator PG, mirroring the
+     * Platform-side replayInsert. The audit row goes to `access_log`, the
+     * orchestrator's audit surface. Idempotent via `ON CONFLICT (run_id) DO
+     * NOTHING`; decrements `cold_store_chunk_counts` (floored at 0).
      */
     replayInsert(args: {
         rows: ReadonlyArray<ExecutionRunRow>;

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

@@ -7,10 +7,8 @@
  *   - warm TTL: `minSecretAuditLogWarmDays()` table-wide, tightened per row
  *     by `secretAuditLogWarmSqlCase()`
  *
- * Synthetic tenant: rows without `routing_key` (e.g. orchestrator-level
- * key rotations done before any source is bound) collapse to a single
- * synthetic prefix `__orchestrator__`. Mirrors the same pattern already
- * used for `event_log` payload keys when the routing key is missing.
+ * Rows without `routing_key` (e.g. key rotations before any source is bound) collapse to the
+ * synthetic prefix `__orchestrator__`, the pattern `event_log` payload keys use too.
  */
 import { type Kysely } from 'kysely';
 import { type ChunkCommitMetadata, type ColdRetention, type ColdStoreTableConfig, type EligiblePartition, type TableAdapter, PgTableAdapterBase } from '@kici-dev/shared';
@@ -44,14 +42,9 @@ export declare class SecretAuditLogAdapter extends PgTableAdapterBase<Database>
     rowId(row: SecretAuditLogRow): string | number;
     rowTimestamp(row: SecretAuditLogRow): Date | string;
     /**
-     * Per-row cold-retention TTL. Sampled `resolve` /
-     * `resolve_named` rows get 180d cold; mutations get `'forever'`. The
-     * denied-outcome override promotes to 730d (forensic).
-     *
-     * `outcome` is a free-form string in PG but the engine helper only
-     * branches on `outcome !== 'allowed'`, so any other value
-     * (`'denied'`, `'error'`, future categories) lands in the forensic
-     * bucket.
+     * Sampled `resolve` / `resolve_named` rows get 180d cold; mutations get `'forever'`; a
+     * denied outcome promotes to 730d (forensic). `outcome` is free-form in PG, so any value
+     * other than `'allowed'` (`'error'`, future categories) lands in the forensic bucket.
      */
     coldTtlDays(row: SecretAuditLogRow): ColdRetention;
     markArchivedAndDelete(args: {