@kici-dev/shared 0.6.1 → 0.8.0

package/dist/cold-store/cold-store.js

@@ -5,7 +5,7 @@ import { coldDaysToBucket, isLongerColdRetention } from "./bucket.js";
 import { computeChunkId } from "./chunk-id.js";
 import { decodeChunk, encodeChunk } from "./chunk-encoder.js";
 import { parseManifest, serializeManifest } from "./manifest.js";
-import { coldStoreArchiveBytesTotal, coldStoreArchiveCyclesTotal, coldStoreArchiveDurationSeconds, coldStoreArchiveRowsTotal, coldStorePurgeBytesTotal, coldStorePurgeChunksTotal, coldStorePurgeDurationSeconds, coldStoreRehydrateBytesTotal, coldStoreRehydrateDurationSeconds, coldStoreRehydrateRequestsTotal, coldStoreReplayDurationSeconds, coldStoreReplayRowsTotal, coldStoreVerifyFailuresTotal } from "./metrics.js";
+import { ColdStoreCycleResult, coldStoreArchiveBytesTotal, coldStoreArchiveCyclesTotal, coldStoreArchiveDurationSeconds, coldStoreArchiveRowsTotal, coldStorePurgeBytesTotal, coldStorePurgeChunksTotal, coldStorePurgeDurationSeconds, coldStoreRehydrateBytesTotal, coldStoreRehydrateDurationSeconds, coldStoreRehydrateRequestsTotal, coldStoreReplayDurationSeconds, coldStoreReplayRowsTotal, coldStoreVerifyFailuresTotal } from "./metrics.js";
 import { resolveTableConfig } from "./config.js";
 import { sha256 } from "@kici-dev/core";
 import { DeleteObjectCommand, GetObjectCommand, HeadObjectCommand, ListObjectsV2Command, PutObjectCommand } from "@aws-sdk/client-s3";
@@ -154,14 +154,14 @@ var BaseColdStore = class {
 			summary.skipped.disabled += 1;
 			coldStoreArchiveCyclesTotal().add(1, {
 				db: this.db,
-				result: "disabled"
+				result: ColdStoreCycleResult.enum.disabled
 			});
 			return summary;
 		}
 		if (this.adapters.size === 0) {
 			coldStoreArchiveCyclesTotal().add(1, {
 				db: this.db,
-				result: "no_tables"
+				result: ColdStoreCycleResult.enum.no_tables
 			});
 			summary.skipped.no_tables += 1;
 			this.log("info", "cold-store cycle: no adapters registered", {
@@ -178,7 +178,7 @@ var BaseColdStore = class {
 			await this.processAdapter(adapter, summary);
 			summary.tablesProcessed += 1;
 		}
-		const cycleResult = summary.rowsFailed > 0 ? "failure" : summary.chunksWritten > 0 ? "success" : "no_tables";
+		const cycleResult = summary.rowsFailed > 0 ? ColdStoreCycleResult.enum.failure : summary.chunksWritten > 0 ? ColdStoreCycleResult.enum.success : ColdStoreCycleResult.enum.no_tables;
 		coldStoreArchiveCyclesTotal().add(1, {
 			db: this.db,
 			result: cycleResult

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

@@ -14,7 +14,7 @@ export { computeChunkId } from './chunk-id.js';
 export { decodeChunk, encodeChunk, type DecodeChunkArgs, type EncodeChunkArgs, type EncodedChunk, } from './chunk-encoder.js';
 export { parseManifest, serializeManifest } from './manifest.js';
 export { DEFAULT_TABLE_CONFIG, resolveTableConfig, type ColdStoreConfig, type ColdStoreTableConfig, } from './config.js';
-export { coldStoreArchiveBytesTotal, coldStoreArchiveCyclesTotal, coldStoreArchiveDurationSeconds, coldStoreArchiveRowsTotal, coldStorePurgeBytesTotal, coldStorePurgeChunksTotal, coldStorePurgeDurationSeconds, coldStoreRehydrateBytesTotal, coldStoreRehydrateDurationSeconds, coldStoreRehydrateRequestsTotal, coldStoreReplayDurationSeconds, coldStoreReplayRowsTotal, coldStoreVerifyFailuresTotal, } from './metrics.js';
+export { ColdStoreCycleResult, coldStoreArchiveBytesTotal, coldStoreArchiveCyclesTotal, coldStoreArchiveDurationSeconds, coldStoreArchiveRowsTotal, coldStorePurgeBytesTotal, coldStorePurgeChunksTotal, coldStorePurgeDurationSeconds, coldStoreRehydrateBytesTotal, coldStoreRehydrateDurationSeconds, coldStoreRehydrateRequestsTotal, coldStoreReplayDurationSeconds, coldStoreReplayRowsTotal, coldStoreVerifyFailuresTotal, } from './metrics.js';
 export { type ChunkCommitMetadata, type EligiblePartition, type TableAdapter, } from './table-adapter.js';
 export { type ArchiveCycleSummary, type ChunkManifest, type ColdRetention } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/cold-store/index.js

@@ -4,8 +4,8 @@ import { COLD_BUCKET_NAMES, coldDaysToBucket, isLongerColdRetention } from "./bu
 import { computeChunkId } from "./chunk-id.js";
 import { decodeChunk, encodeChunk } from "./chunk-encoder.js";
 import { parseManifest, serializeManifest } from "./manifest.js";
-import { coldStoreArchiveBytesTotal, coldStoreArchiveCyclesTotal, coldStoreArchiveDurationSeconds, coldStoreArchiveRowsTotal, coldStorePurgeBytesTotal, coldStorePurgeChunksTotal, coldStorePurgeDurationSeconds, coldStoreRehydrateBytesTotal, coldStoreRehydrateDurationSeconds, coldStoreRehydrateRequestsTotal, coldStoreReplayDurationSeconds, coldStoreReplayRowsTotal, coldStoreVerifyFailuresTotal } from "./metrics.js";
+import { ColdStoreCycleResult, coldStoreArchiveBytesTotal, coldStoreArchiveCyclesTotal, coldStoreArchiveDurationSeconds, coldStoreArchiveRowsTotal, coldStorePurgeBytesTotal, coldStorePurgeChunksTotal, coldStorePurgeDurationSeconds, coldStoreRehydrateBytesTotal, coldStoreRehydrateDurationSeconds, coldStoreRehydrateRequestsTotal, coldStoreReplayDurationSeconds, coldStoreReplayRowsTotal, coldStoreVerifyFailuresTotal } from "./metrics.js";
 import { DEFAULT_TABLE_CONFIG, resolveTableConfig } from "./config.js";
 import { BaseColdStore } from "./cold-store.js";
 import { ChunkLru } from "./lru.js";
-export { BaseColdStore, COLD_BUCKET_NAMES, ChunkLru, DEFAULT_TABLE_CONFIG, chunkObjectKey, coldDaysToBucket, coldStoreArchiveBytesTotal, coldStoreArchiveCyclesTotal, coldStoreArchiveDurationSeconds, coldStoreArchiveRowsTotal, coldStorePurgeBytesTotal, coldStorePurgeChunksTotal, coldStorePurgeDurationSeconds, coldStoreRehydrateBytesTotal, coldStoreRehydrateDurationSeconds, coldStoreRehydrateRequestsTotal, coldStoreReplayDurationSeconds, coldStoreReplayRowsTotal, coldStoreVerifyFailuresTotal, computeChunkId, decodeChunk, encodeChunk, encodeKeySegment, isLongerColdRetention, parseManifest, resolveTableConfig, serializeManifest, tablePrefix, tenantDayBucketPrefix, tenantDayPrefix };
+export { BaseColdStore, COLD_BUCKET_NAMES, ChunkLru, ColdStoreCycleResult, DEFAULT_TABLE_CONFIG, chunkObjectKey, coldDaysToBucket, coldStoreArchiveBytesTotal, coldStoreArchiveCyclesTotal, coldStoreArchiveDurationSeconds, coldStoreArchiveRowsTotal, coldStorePurgeBytesTotal, coldStorePurgeChunksTotal, coldStorePurgeDurationSeconds, coldStoreRehydrateBytesTotal, coldStoreRehydrateDurationSeconds, coldStoreRehydrateRequestsTotal, coldStoreReplayDurationSeconds, coldStoreReplayRowsTotal, coldStoreVerifyFailuresTotal, computeChunkId, decodeChunk, encodeChunk, encodeKeySegment, isLongerColdRetention, parseManifest, resolveTableConfig, serializeManifest, tablePrefix, tenantDayBucketPrefix, tenantDayPrefix };

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

@@ -28,12 +28,28 @@
  * guarantees we resolve AFTER telemetry is wired up.
  */
 import type { Counter, Histogram } from '@opentelemetry/api';
+import { z } from 'zod';
+/**
+ * The `result` label of {@link coldStoreArchiveCyclesTotal}: what one
+ * `runArchiveCycle()` tick concluded. `disabled` and `no_tables` are the
+ * cycle stopping before any adapter runs (config gate off / nothing
+ * registered); `success` wrote at least one chunk; `no_tables` is also what a
+ * complete pass reports when every adapter ran and none had a row to move;
+ * `failure` had a row fail to archive.
+ */
+export declare const ColdStoreCycleResult: z.ZodEnum<{
+    disabled: "disabled";
+    failure: "failure";
+    no_tables: "no_tables";
+    success: "success";
+}>;
+export type ColdStoreCycleResult = z.infer<typeof ColdStoreCycleResult>;
 /**
  * Cycles that `runArchiveCycle()` has completed, labeled by outcome.
  * Always incremented by 1 on every tick — guaranteed-visible proof
  * that the cold-store subsystem is registered and running.
  *
- * `result` ∈ `no_tables` | `disabled` | `success` | `failure`.
+ * `result` is a {@link ColdStoreCycleResult}.
  */
 export declare function coldStoreArchiveCyclesTotal(): Counter;
 /**

package/dist/cold-store/metrics.js

@@ -1,5 +1,6 @@
 import "../rolldown-runtime-ClRpJifh.js";
 import { createMeter } from "../telemetry/metrics.js";
+import { z } from "zod";
 //#region src/cold-store/metrics.ts
 let _meter;
 function meter() {
@@ -20,11 +21,25 @@ let _purgeChunksTotal;
 let _purgeBytesTotal;
 let _purgeDurationSeconds;
 /**
+* The `result` label of {@link coldStoreArchiveCyclesTotal}: what one
+* `runArchiveCycle()` tick concluded. `disabled` and `no_tables` are the
+* cycle stopping before any adapter runs (config gate off / nothing
+* registered); `success` wrote at least one chunk; `no_tables` is also what a
+* complete pass reports when every adapter ran and none had a row to move;
+* `failure` had a row fail to archive.
+*/
+const ColdStoreCycleResult = z.enum([
+	"disabled",
+	"no_tables",
+	"success",
+	"failure"
+]);
+/**
 * Cycles that `runArchiveCycle()` has completed, labeled by outcome.
 * Always incremented by 1 on every tick — guaranteed-visible proof
 * that the cold-store subsystem is registered and running.
 *
-* `result` ∈ `no_tables` | `disabled` | `success` | `failure`.
+* `result` is a {@link ColdStoreCycleResult}.
 */
 function coldStoreArchiveCyclesTotal() {
 	if (!_archiveCyclesTotal) _archiveCyclesTotal = meter().createCounter("cold_store_archive_cycles_total", { description: "Completed archive cycles by db and outcome" });
@@ -174,6 +189,6 @@ function coldStorePurgeDurationSeconds() {
 	return _purgeDurationSeconds;
 }
 //#endregion
-export { coldStoreArchiveBytesTotal, coldStoreArchiveCyclesTotal, coldStoreArchiveDurationSeconds, coldStoreArchiveRowsTotal, coldStorePurgeBytesTotal, coldStorePurgeChunksTotal, coldStorePurgeDurationSeconds, coldStoreRehydrateBytesTotal, coldStoreRehydrateDurationSeconds, coldStoreRehydrateRequestsTotal, coldStoreReplayDurationSeconds, coldStoreReplayRowsTotal, coldStoreVerifyFailuresTotal };
+export { ColdStoreCycleResult, coldStoreArchiveBytesTotal, coldStoreArchiveCyclesTotal, coldStoreArchiveDurationSeconds, coldStoreArchiveRowsTotal, coldStorePurgeBytesTotal, coldStorePurgeChunksTotal, coldStorePurgeDurationSeconds, coldStoreRehydrateBytesTotal, coldStoreRehydrateDurationSeconds, coldStoreRehydrateRequestsTotal, coldStoreReplayDurationSeconds, coldStoreReplayRowsTotal, coldStoreVerifyFailuresTotal };
 
 //# sourceMappingURL=metrics.js.map

package/dist/env/define-env.d.ts

@@ -122,7 +122,10 @@ export declare function defineEnv<TShape extends z.ZodRawShape>(opts: DefineEnvO
  *
  * Keep this list small and well-justified. Every addition is a typo we can
  * no longer catch, so only list things that are (a) actually set in the
- * wild by our own tooling and (b) could never be a config typo.
+ * wild by our own tooling and (b) could never be a config typo. A variable
+ * only one service reads belongs in that service's `extraKnown` instead —
+ * `KICI_CONFIG` is the reference case, allowlisted at the orchestrator's own
+ * call site so the agent and Platform catchers still reject it.
  */
 export declare const RESERVED_NON_SCHEMA_KICI_VARS: readonly string[];
 /**
@@ -176,6 +179,16 @@ export interface ValidateUnknownKiciVarsOptions {
     warnOnly?: boolean;
     /** Logger callback for warn-mode (defaults to `console.warn`). */
     onWarn?: (msg: string) => void;
+    /**
+     * Advice text for names the caller recognises but does not accept — a
+     * documented variable that belongs to some other layer. A rejected name
+     * found here is reported with its advice instead of a Levenshtein guess,
+     * which finds nothing for exactly these names because they are not near
+     * misses of a schema name.
+     *
+     * This changes the message only. A name listed here is still rejected.
+     */
+    notStartupVars?: Record<string, string>;
 }
 /**
  * Inspect `env` for KICI_* keys that are not in `known`. Throws (or warns,

package/dist/env/define-env.js

@@ -241,7 +241,10 @@ function suggestClosest(name, candidates) {
 *
 * Keep this list small and well-justified. Every addition is a typo we can
 * no longer catch, so only list things that are (a) actually set in the
-* wild by our own tooling and (b) could never be a config typo.
+* wild by our own tooling and (b) could never be a config typo. A variable
+* only one service reads belongs in that service's `extraKnown` instead —
+* `KICI_CONFIG` is the reference case, allowlisted at the orchestrator's own
+* call site so the agent and Platform catchers still reject it.
 */
 const RESERVED_NON_SCHEMA_KICI_VARS = [
 	"KICI_CACHE",
@@ -305,21 +308,27 @@ function validateUnknownKiciVars(known, options = {}, env = process.env) {
 		...options.extraKnown ?? [],
 		...RESERVED_NON_SCHEMA_KICI_VARS
 	]);
+	const advice = options.notStartupVars ?? {};
 	const unknown = [];
 	for (const key of Object.keys(env)) {
 		if (!key.startsWith("KICI_")) continue;
 		if (knownSet.has(key)) continue;
 		if (RESERVED_NON_SCHEMA_KICI_PREFIXES.some((p) => key.startsWith(p))) continue;
 		if (RESERVED_NON_SCHEMA_KICI_SUFFIXES.some((s) => key.endsWith(s) || key.includes(`${s}_`))) continue;
+		const note = advice[key];
 		unknown.push({
 			name: key,
-			suggestion: suggestClosest(key, [...knownSet])
+			note,
+			suggestion: note ? void 0 : suggestClosest(key, [...knownSet])
 		});
 	}
 	if (unknown.length === 0) return;
 	const header = `Unknown KICI_* env var(s) detected — refusing to start.
 Set KICI_DEV=true to downgrade this check to a warning.
-Unknown vars:\n${unknown.map(({ name, suggestion }) => suggestion ? `  - ${name}    (did you mean ${suggestion}?)` : `  - ${name}    (no close match in the schema)`).join("\n")}`;
+Unknown vars:\n${unknown.map(({ name, suggestion, note }) => {
+		if (note) return `  - ${name}    (${note})`;
+		return suggestion ? `  - ${name}    (did you mean ${suggestion}?)` : `  - ${name}    (no close match in the schema)`;
+	}).join("\n")}`;
 	if (options.warnOnly ?? env.KICI_DEV === "true") {
 		(options.onWarn ?? console.warn)(header);
 		return;

package/dist/index.d.ts

@@ -15,5 +15,5 @@ export { setupGracefulShutdown, type ShutdownStep, type ShutdownLogger, type Shu
 export { validateRequiredTools, type ToolRequirement } from './tool-check.js';
 export { kiciTmpBase, kiciMkdtemp } from './tmp-dir.js';
 export { createS3Client, type CreateS3ClientOptions, type SharedS3Config } from './s3-client.js';
-export { BaseColdStore, ChunkLru, COLD_BUCKET_NAMES, DEFAULT_TABLE_CONFIG, chunkObjectKey, coldDaysToBucket, coldStoreArchiveBytesTotal, coldStoreArchiveCyclesTotal, coldStoreArchiveDurationSeconds, coldStoreArchiveRowsTotal, coldStorePurgeBytesTotal, coldStorePurgeChunksTotal, coldStorePurgeDurationSeconds, coldStoreRehydrateBytesTotal, coldStoreRehydrateDurationSeconds, coldStoreRehydrateRequestsTotal, coldStoreReplayDurationSeconds, coldStoreReplayRowsTotal, coldStoreVerifyFailuresTotal, computeChunkId, decodeChunk, encodeChunk, encodeKeySegment, isLongerColdRetention, parseManifest, resolveTableConfig, serializeManifest, tablePrefix, tenantDayBucketPrefix, tenantDayPrefix, type ArchiveCycleSummary, type BaseColdStoreDeps, type ChunkCommitMetadata, type ChunkLruOptions, type ChunkManifest, type ColdBucketName, type ColdRetention, type ColdStore, type ColdStoreConfig, type ColdStoreFetchRangeArgs, type ColdStoreReplayChunkArgs, type ColdStoreReplayResult, type ColdStoreReplayRowArgs, type ColdStoreTableConfig, type DbKind, type DecodeChunkArgs, type EligiblePartition, type EncodeChunkArgs, type EncodedChunk, type PurgeableChunk, type PurgeChunkResult, type PurgeExpiredChunksOpts, type PurgeExpiredChunksSummary, type TableAdapter, } from './cold-store/index.js';
+export { BaseColdStore, ChunkLru, COLD_BUCKET_NAMES, DEFAULT_TABLE_CONFIG, chunkObjectKey, coldDaysToBucket, coldStoreArchiveBytesTotal, ColdStoreCycleResult, coldStoreArchiveCyclesTotal, coldStoreArchiveDurationSeconds, coldStoreArchiveRowsTotal, coldStorePurgeBytesTotal, coldStorePurgeChunksTotal, coldStorePurgeDurationSeconds, coldStoreRehydrateBytesTotal, coldStoreRehydrateDurationSeconds, coldStoreRehydrateRequestsTotal, coldStoreReplayDurationSeconds, coldStoreReplayRowsTotal, coldStoreVerifyFailuresTotal, computeChunkId, decodeChunk, encodeChunk, encodeKeySegment, isLongerColdRetention, parseManifest, resolveTableConfig, serializeManifest, tablePrefix, tenantDayBucketPrefix, tenantDayPrefix, type ArchiveCycleSummary, type BaseColdStoreDeps, type ChunkCommitMetadata, type ChunkLruOptions, type ChunkManifest, type ColdBucketName, type ColdRetention, type ColdStore, type ColdStoreConfig, type ColdStoreFetchRangeArgs, type ColdStoreReplayChunkArgs, type ColdStoreReplayResult, type ColdStoreReplayRowArgs, type ColdStoreTableConfig, type DbKind, type DecodeChunkArgs, type EligiblePartition, type EncodeChunkArgs, type EncodedChunk, type PurgeableChunk, type PurgeChunkResult, type PurgeExpiredChunksOpts, type PurgeExpiredChunksSummary, type TableAdapter, } from './cold-store/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -22,10 +22,10 @@ import { COLD_BUCKET_NAMES, coldDaysToBucket, isLongerColdRetention } from "./co
 import { computeChunkId } from "./cold-store/chunk-id.js";
 import { decodeChunk, encodeChunk } from "./cold-store/chunk-encoder.js";
 import { parseManifest, serializeManifest } from "./cold-store/manifest.js";
-import { coldStoreArchiveBytesTotal, coldStoreArchiveCyclesTotal, coldStoreArchiveDurationSeconds, coldStoreArchiveRowsTotal, coldStorePurgeBytesTotal, coldStorePurgeChunksTotal, coldStorePurgeDurationSeconds, coldStoreRehydrateBytesTotal, coldStoreRehydrateDurationSeconds, coldStoreRehydrateRequestsTotal, coldStoreReplayDurationSeconds, coldStoreReplayRowsTotal, coldStoreVerifyFailuresTotal } from "./cold-store/metrics.js";
+import { ColdStoreCycleResult, coldStoreArchiveBytesTotal, coldStoreArchiveCyclesTotal, coldStoreArchiveDurationSeconds, coldStoreArchiveRowsTotal, coldStorePurgeBytesTotal, coldStorePurgeChunksTotal, coldStorePurgeDurationSeconds, coldStoreRehydrateBytesTotal, coldStoreRehydrateDurationSeconds, coldStoreRehydrateRequestsTotal, coldStoreReplayDurationSeconds, coldStoreReplayRowsTotal, coldStoreVerifyFailuresTotal } from "./cold-store/metrics.js";
 import { DEFAULT_TABLE_CONFIG, resolveTableConfig } from "./cold-store/config.js";
 import { BaseColdStore } from "./cold-store/cold-store.js";
 import { ChunkLru } from "./cold-store/lru.js";
 import "./cold-store/index.js";
 export * from "@kici-dev/core";
-export { AgentDeliveryMode, AgentPlatform, BaseColdStore, BundleChunkAssembler, COLD_BUCKET_NAMES, ChunkLru, ChunkRequestWaiter, DEFAULT_TABLE_CONFIG, FLEET_CHUNK_BYTES, MAX_LOG_BYTES, MIGRATION_HASH_TABLE, REGISTERABLE_TRIGGER_TYPES, RingBuffer, addLogsToArchive, chunkBuffer, chunkObjectKey, clearDispatchQueueDirect, coldDaysToBucket, coldStoreArchiveBytesTotal, coldStoreArchiveCyclesTotal, coldStoreArchiveDurationSeconds, coldStoreArchiveRowsTotal, coldStorePurgeBytesTotal, coldStorePurgeChunksTotal, coldStorePurgeDurationSeconds, coldStoreRehydrateBytesTotal, coldStoreRehydrateDurationSeconds, coldStoreRehydrateRequestsTotal, coldStoreReplayDurationSeconds, coldStoreReplayRowsTotal, coldStoreVerifyFailuresTotal, collectRuntimeMetricNames, computeChunkId, computeMigrationsHash, createContextTemplateDirect, createDb, createDbRole, createHealthRoutes, createMeter, createMetricsRoutes, createPool, createReadOnlyDbUser, createS3Client, decodeChunk, decrypt, deleteContextDirect, deriveKey, dropAndCreateDatabase, emitKiciEventDirect, encodeChunk, encodeKeySegment, encrypt, ensureDatabase, generateMasterKey, getPrometheusExporter, getReconnectDelay, initTelemetry, isLongerColdRetention, isPgUniqueViolation, isPoolAcquireTimeout, isSchemaCurrent, kiciMkdtemp, kiciTmpBase, listCheckRunTrackingDirect, listContextsDirect, listExecutionRunsDirect, listQueueDirect, listRegistrationsDirect, maskDatabaseUrl, parseDatabaseUrl, parseManifest, prunePeerCredentialsDirect, purgeContextsDirect, purgeScopedSecretsDirect, purgeSecretBackendsDirect, purgeStaleExecutionDirect, purgeStaleSourcesDirect, readStoredMigrationContentHash, registerWorkflowManualDirect, resetRaftStateDirect, resolveTableConfig, seedContextBindingDirect, seedContextDirect, serializeManifest, setContextPolicyDirect, setContextSecretDirect, setupGracefulShutdown, showContextDirect, showExecutionRunDirect, showQueueEntryDirect, showRegistrationDirect, splitAgentPlatform, storeMigrationContentHash, tablePrefix, tenantDayBucketPrefix, tenantDayPrefix, validateRequiredTools };
+export { AgentDeliveryMode, AgentPlatform, BaseColdStore, BundleChunkAssembler, COLD_BUCKET_NAMES, ChunkLru, ChunkRequestWaiter, ColdStoreCycleResult, DEFAULT_TABLE_CONFIG, FLEET_CHUNK_BYTES, MAX_LOG_BYTES, MIGRATION_HASH_TABLE, REGISTERABLE_TRIGGER_TYPES, RingBuffer, addLogsToArchive, chunkBuffer, chunkObjectKey, clearDispatchQueueDirect, coldDaysToBucket, coldStoreArchiveBytesTotal, coldStoreArchiveCyclesTotal, coldStoreArchiveDurationSeconds, coldStoreArchiveRowsTotal, coldStorePurgeBytesTotal, coldStorePurgeChunksTotal, coldStorePurgeDurationSeconds, coldStoreRehydrateBytesTotal, coldStoreRehydrateDurationSeconds, coldStoreRehydrateRequestsTotal, coldStoreReplayDurationSeconds, coldStoreReplayRowsTotal, coldStoreVerifyFailuresTotal, collectRuntimeMetricNames, computeChunkId, computeMigrationsHash, createContextTemplateDirect, createDb, createDbRole, createHealthRoutes, createMeter, createMetricsRoutes, createPool, createReadOnlyDbUser, createS3Client, decodeChunk, decrypt, deleteContextDirect, deriveKey, dropAndCreateDatabase, emitKiciEventDirect, encodeChunk, encodeKeySegment, encrypt, ensureDatabase, generateMasterKey, getPrometheusExporter, getReconnectDelay, initTelemetry, isLongerColdRetention, isPgUniqueViolation, isPoolAcquireTimeout, isSchemaCurrent, kiciMkdtemp, kiciTmpBase, listCheckRunTrackingDirect, listContextsDirect, listExecutionRunsDirect, listQueueDirect, listRegistrationsDirect, maskDatabaseUrl, parseDatabaseUrl, parseManifest, prunePeerCredentialsDirect, purgeContextsDirect, purgeScopedSecretsDirect, purgeSecretBackendsDirect, purgeStaleExecutionDirect, purgeStaleSourcesDirect, readStoredMigrationContentHash, registerWorkflowManualDirect, resetRaftStateDirect, resolveTableConfig, seedContextBindingDirect, seedContextDirect, serializeManifest, setContextPolicyDirect, setContextSecretDirect, setupGracefulShutdown, showContextDirect, showExecutionRunDirect, showQueueEntryDirect, showRegistrationDirect, splitAgentPlatform, storeMigrationContentHash, tablePrefix, tenantDayBucketPrefix, tenantDayPrefix, validateRequiredTools };

package/dist/net/nftables.d.ts

@@ -0,0 +1,356 @@
+/**
+ * Programmatic nftables rule management for agent network isolation.
+ *
+ * Manages RFC1918 + cloud metadata blocking rules per-interface (Firecracker/container)
+ * or per-UID (bare-metal). All operations use `nft` CLI via child_process.execFile.
+ *
+ * Table layout:
+ *   table ip kici {
+ *     chain forward { type filter hook forward priority 0; policy accept; }
+ *     chain input   { type filter hook input priority 0; policy accept; }
+ *     chain output  { type filter hook output priority 0; policy accept; }
+ *   }
+ *
+ * `forward` and `input` answer different questions and both are needed. A
+ * packet a sandbox sends to one of the host's OWN addresses — a bridge gateway,
+ * the host's LAN address — is delivered on the input hook and never traverses
+ * forward, so a forward rule cannot see it. `forward` governs what a sandbox
+ * reaches THROUGH the host; `input` governs what it reaches ON the host.
+ */
+/**
+ * Network policy controlling RFC1918 and internet access for the agents or job
+ * containers in one label set.
+ *
+ * Lives here rather than beside the scaler's own types because both the
+ * orchestrator's scaler (agent containers and Firecracker VMs) and the agent's
+ * container backend (nested job containers) build rules from it. The
+ * orchestrator re-exports it from `scaler/types.ts` so its call sites are
+ * unchanged.
+ */
+export interface NetworkPolicy {
+    /** CIDR ranges allowed as exceptions to the default RFC1918 block */
+    allowlist?: string[];
+    /** Block all outbound traffic except allowlisted ranges */
+    denyAll?: boolean;
+    /**
+     * What this source class may reach on the HOST itself, in the
+     * `<cidr|address|*>[:<port|*>]` vocabulary {@link parseHostAccess} reads.
+     * Everything else host-destined is dropped.
+     *
+     * Distinct from {@link allowlist}, which governs the `forward` hook and so
+     * answers what a sandbox reaches *through* the host. Leaving this undefined
+     * means the caller supplies its own class default; an empty array means
+     * "reach nothing on the host".
+     */
+    hostAccess?: string[];
+}
+/**
+ * One parsed {@link NetworkPolicy.hostAccess} entry.
+ *
+ * `null` means "unconstrained" on both fields: a `daddr` of `null` matches
+ * every host address (nft omits the `ip daddr` clause), and a `port` of
+ * `null` matches every port.
+ */
+export interface HostAccessRule {
+    daddr: string | null;
+    port: number | null;
+}
+/**
+ * Parse one host-access entry.
+ *
+ * Grammar: `<cidr|address|*>` optionally followed by `:<port|*>`. A bare number
+ * is a port on any host address, which is the common case — an operator naming
+ * a host-local registry mirror knows its port, not the host's dynamic
+ * addresses.
+ *
+ * Hostnames are rejected on purpose: nftables matches addresses, so resolving a
+ * name at rule-build time produces a rule that goes stale silently the next
+ * time the name moves.
+ *
+ * @throws Error naming the entry and what is wrong with it
+ */
+export declare function parseHostAccess(entry: string): HostAccessRule;
+/**
+ * Build the host-access rules for one identifier, in final head-to-tail order:
+ * the conntrack exception, every accept, then one terminal drop.
+ *
+ * The conntrack rule leads because the chain is keyed on the sandbox as the
+ * SOURCE, so it also sees the reply leg of a connection the HOST opened toward
+ * the sandbox — a readiness probe, a metrics scrape. Without the exception
+ * those replies fall through to the terminal drop and the host's own connection
+ * dies as an opaque timeout. It widens nothing a sandbox can initiate:
+ * `established` is reached only by a flow whose first packet was already
+ * accepted, so a sandbox connecting to a port with no accept still has its SYN
+ * dropped and never reaches that state.
+ *
+ * A port-scoped entry emits an accept per protocol in
+ * {@link HOST_ACCESS_PROTOCOLS}. UDP is not optional: a container whose
+ * resolver is the bridge gateway — which is what rootful podman with
+ * aardvark-dns gives it — resolves over UDP, so a tcp-only accept on port 53
+ * leaves it unable to resolve any name.
+ *
+ * @returns one token list per rule, in final head-to-tail order
+ */
+export declare function buildHostAccessRuleOps(matchClause: string[], hostAccess: string[]): string[][];
+/**
+ * Match mode for nftables isolation rules.
+ * - 'iifname': Match on input interface name (Firecracker TAP devices)
+ * - 'saddr': Match on source IP address (container backends)
+ */
+export type NftMatchMode = 'iifname' | 'saddr';
+/** RFC1918 private address ranges. */
+export declare const RFC1918_RANGES: string[];
+/** Cloud metadata service range (AWS/GCP/Azure link-local). */
+export declare const METADATA_RANGE = "169.254.0.0/16";
+/**
+ * Subnet of the agent's `kici-jobs` bridge, on which the agent keys ONE drop set
+ * covering every nested job container — including one that does not exist yet.
+ *
+ * It lives here rather than beside the agent's own network constants because
+ * the Firecracker host provisioner has to recognise those rules to leave them
+ * alone, and the orchestrator carries `@kici-dev/agent` only as a devDependency.
+ * The agent module re-exports it, so its own call sites are unchanged.
+ */
+export declare const JOB_NETWORK_SUBNET = "172.31.0.0/16";
+/**
+ * Options for nft command execution.
+ */
+interface NftOptions {
+    /**
+     * Wrap the `nft` invocation with `sudo -n` so non-root orchestrators (e.g.
+     * Pi user-mode systemd) can manage rules. Operators must have a NOPASSWD
+     * sudoers entry for /usr/sbin/nft. Default false.
+     */
+    requireSudo?: boolean;
+    /**
+     * nftables table these rules live in. Defaults to {@link DEFAULT_NFT_TABLE}.
+     *
+     * The Firecracker backend exposes this as an operator knob so two
+     * coordinators on one host get disjoint tables; the per-VM rules must follow
+     * the same knob as the bridge baseline, or coordinator B's rules land in
+     * coordinator A's table and A's next provision wipes them.
+     */
+    table?: string;
+}
+/** Table used when {@link NftOptions.table} is not set. */
+export declare const DEFAULT_NFT_TABLE = "kici";
+/**
+ * Validate that nftables is available and the process has NET_ADMIN capability.
+ * Attempts `nft list tables` -- if it fails:
+ *   - ENOENT: nft binary not installed
+ *   - EPERM: nft binary present but NET_ADMIN capability missing
+ * Throws with a clear error message in both cases.
+ */
+export declare function validateNftablesAvailability(opts?: NftOptions): Promise<void>;
+/**
+ * Ensure the nftables table and the chains this module writes to exist.
+ * Idempotent -- safe to call multiple times.
+ *
+ * Every chain is verified individually. A bare "does the table exist?" check is
+ * not enough: the Firecracker host provisioner creates the table before this
+ * module ever runs, so a table with no `forward` chain satisfied the old early
+ * return — and then every `addIsolationRules` failed with nft's "No such file
+ * or directory", leaving every VM on that host with no isolation rules at all.
+ *
+ * @param opts - `table` selects the table; `requireBaselineChain` additionally
+ * ensures the regular {@link BASELINE_CHAIN} exists (Firecracker hosts, whose
+ * `forward` chain ends in a jump to it).
+ */
+export declare function ensureKiciTable(opts?: NftOptions & {
+    requireBaselineChain?: boolean;
+}): Promise<void>;
+/** Chain in the kici table that filters host-destined sandbox traffic. */
+export declare const INPUT_CHAIN = "input";
+/**
+ * Ensure the kici table and its `input` chain exist. Idempotent — `nft add` is
+ * a create-or-noop for both, so there is no check-then-create window.
+ *
+ * The chain's policy is `accept` because it is a base chain on the host's own
+ * input hook: everything the host itself receives passes through it, and a
+ * default-deny there would take the machine off the network. The deny lives in
+ * the per-identifier terminal drop {@link buildHostAccessRuleOps} emits.
+ */
+export declare function ensureKiciInputChain(opts?: NftOptions): Promise<void>;
+/**
+ * Apply one identifier's host-access rules to the `input` chain, replacing
+ * whatever it had.
+ *
+ * The pre-clean is not an optimisation. Bridge networks recycle addresses, so a
+ * crash or a `kill -9` leaves the previous holder's accepts behind for the next
+ * container on that IP to inherit — which is the boundary this chain exists to
+ * hold. Applying without removing first would also stack a second terminal drop
+ * above the first run's accepts, shadowing every one of them.
+ *
+ * Rules are `insert`ed in reverse so the block lands at the chain head in the
+ * order {@link buildHostAccessRuleOps} returns: accepts first, terminal drop
+ * last. Inserting forwards would put the drop above the accepts and deny
+ * everything.
+ */
+export declare function addHostIsolationRules(identifier: string, hostAccess: string[], matchMode?: NftMatchMode, opts?: NftOptions): Promise<void>;
+/**
+ * A table's `input` chain, as `nft -a list chain` prints it, or `null` when the
+ * table or the chain does not exist yet.
+ *
+ * Returning `null` rather than throwing keeps "the chain is not there" distinct
+ * from "the chain is there and holds nothing", which a caller deciding whether
+ * a rule set is already installed has to be able to tell apart.
+ */
+export declare function readInputChain(opts?: NftOptions): Promise<string | null>;
+/**
+ * Remove one identifier's rules from the `input` chain.
+ *
+ * Best-effort: a missing chain, or a rule another path already deleted, must
+ * not abort a teardown.
+ */
+export declare function removeHostIsolationRules(identifier: string, opts?: NftOptions): Promise<void>;
+/**
+ * Name of the regular (non-hooked) chain holding the host baseline rules.
+ *
+ * The Firecracker host provisioner puts its six source-scoped baseline rules
+ * here and reaches them with a `jump` appended as the `forward` chain's LAST
+ * rule. Two properties follow, and both are load-bearing:
+ *
+ *  - **Per-VM rules always win.** They are inserted at the `forward` head, so
+ *    every one of them is evaluated before the jump. A per-VM `accept`
+ *    terminates the hook before the baseline can re-drop an allowlisted
+ *    destination, and a per-VM `denyAll` drop is terminal before the
+ *    baseline's blanket internet `accept` can let the packet out.
+ *  - **A self-heal can rebuild the baseline without touching live VMs.** The
+ *    provisioner flushes and refills only this chain, so it never has to
+ *    `delete table` — which used to drop every running VM's isolation rules
+ *    fail-open.
+ *
+ * A regular chain reached by `jump` rather than a second base chain at a lower
+ * priority: in netfilter an `accept` ends only the current base chain, so an
+ * allowlist accept in an earlier base chain would still be re-evaluated — and
+ * dropped — by the baseline's 10.0.0.0/8 rule in the later one.
+ */
+export declare const BASELINE_CHAIN = "baseline";
+/**
+ * Build the per-identifier isolation rules in their final head-to-tail order.
+ *
+ * nftables is first-match-wins within a chain and `accept` is terminal, so the
+ * order below is the whole security property:
+ *
+ *  1. gateway accept
+ *  2. allowlisted CIDR accepts — ahead of the drops, so an allowlisted
+ *     destination inside a dropped range (a 10.x registry endpoint behind the
+ *     10.0.0.0/8 drop) is accepted before the drop is evaluated
+ *  3. RFC1918 drops
+ *  4. cloud-metadata drop
+ *  5. `denyAll` drop
+ *
+ * {@link addIsolationRules} lands them in exactly this order by applying the
+ * list in REVERSE with `insert`, which puts the whole block at the chain head —
+ * ahead of the tail `jump` to {@link BASELINE_CHAIN}.
+ *
+ * @returns one token list per rule, in final head-to-tail order
+ */
+export declare function buildIsolationRuleOps(matchClause: string[], gatewayIp: string, networkPolicy?: NetworkPolicy): string[][];
+/**
+ * Add network isolation rules for one identifier (a TAP interface name, or a
+ * container's source IP).
+ *
+ * Every rule is `insert`ed, applying {@link buildIsolationRuleOps} in reverse,
+ * so the block lands at the chain head in its documented order — ahead of any
+ * host baseline reached by a tail `jump`.
+ *
+ * @param identifier - Network interface name or source IP to match (e.g., "veth-abc123" or "172.30.0.5")
+ * @param gatewayIp - Gateway IP that must remain accessible (e.g., "10.0.0.1")
+ * @param networkPolicy - Optional policy with allowlist and denyAll settings
+ * @param matchMode - How to match traffic: 'iifname' for interface name (default), 'saddr' for source IP
+ */
+export declare function addIsolationRules(identifier: string, gatewayIp: string, networkPolicy?: NetworkPolicy, matchMode?: NftMatchMode, opts?: NftOptions): Promise<void>;
+/**
+ * A table's `forward` chain, as `nft -a list chain` prints it, or `null` when
+ * the table or the chain does not exist yet.
+ *
+ * The text form is what {@link parseRuleHandles} reads, and it is also what a
+ * caller asking whether a rule set is ALREADY installed — rather than deleting
+ * it — compares against the rule text {@link buildIsolationRuleOps} emits.
+ * {@link listForwardRules} cannot answer for a subnet identifier: nft reports a
+ * subnet source as a prefix object, which its classifier treats as "not a
+ * per-agent rule" on purpose.
+ *
+ * Returning `null` rather than throwing keeps "the chain is not there" distinct
+ * from "the chain is there and holds nothing", exactly as {@link readInputChain}
+ * does for the sibling chain. The distinction is load-bearing in the install
+ * direction: a caller checking whether a rule set is present must read a missing
+ * chain as NOT installed and go install it, and a throw instead aborts the whole
+ * ensure path — which for the agent's job network degrades to a container on an
+ * unfiltered bridge.
+ */
+export declare function readForwardChain(opts?: NftOptions): Promise<string | null>;
+/**
+ * Remove every isolation rule this identifier owns, in both the `forward` and
+ * the `input` chain. Called during agent cleanup, and as the pre-clean before a
+ * re-add.
+ *
+ * Both chains are swept because they are one boundary: an identifier is a
+ * container IP or a TAP name, addresses are recycled, and leaving the input
+ * chain's accepts behind hands the next tenant on that address the previous
+ * one's host reachability.
+ *
+ * Best-effort: logs errors but does not throw (cleanup must not block
+ * destruction).
+ *
+ * @param interfaceName - Network interface name or source IP whose rules should be removed
+ */
+export declare function removeIsolationRules(interfaceName: string, opts?: NftOptions): Promise<void>;
+/**
+ * Re-export NftOptions type for use by callers (Firecracker / container backends)
+ * that need to pass the requireSudo flag through to these functions.
+ */
+export type { NftOptions };
+/** One rule in the forward chain, as reported by `nft -j -a list chain`. */
+export interface NftForwardRule {
+    /** nft rule handle, for `nft delete rule … handle N`. */
+    handle: number;
+    /**
+     * The per-identifier value this rule matches on — a concrete source IP or a
+     * concrete interface name — or `null` for a rule that is not per-identifier
+     * (a host baseline rule matching a whole subnet or a `kici-*` wildcard, or a
+     * `jump`).
+     */
+    identifier: string | null;
+}
+/**
+ * Read every rule in a table's forward chain, with its handle and the per-agent
+ * identifier it matches on.
+ *
+ * This is the enumerate-what-is-there half of rule management; the
+ * identifier-known delete path is {@link parseRuleHandles}. Reconciliation
+ * needs this one: rules are removed only on the synchronous teardown paths this
+ * process drives, so an orchestrator crash, a `kill -9`, or a VM that dies
+ * while the orchestrator is down strands `ip saddr <ip> …` rules in the shared
+ * chain forever. The allocator then hands that IP to another tenant, who
+ * inherits the dead job's allowlist.
+ *
+ * Returns an empty list rather than throwing when the chain cannot be read —
+ * the caller is a best-effort sweep, and a failed read must not be mistaken
+ * for "nothing is there".
+ */
+export declare function listForwardRules(opts?: NftOptions): Promise<NftForwardRule[]>;
+/**
+ * Every per-agent identifier currently present in the forward chain, mapped to
+ * the handles of the rules that carry it.
+ */
+export declare function listIsolationRules(opts?: NftOptions): Promise<Map<string, number[]>>;
+/**
+ * Delete rules from a table's forward chain by handle, highest first so earlier
+ * deletions cannot shift the handles still to come.
+ *
+ * Best-effort per handle: a rule another path already removed must not abort
+ * the rest of the sweep.
+ */
+export declare function deleteForwardRules(handles: number[], opts?: NftOptions): Promise<number>;
+/**
+ * Parse nft rule listing output and extract handles for rules matching a given identifier.
+ * Handles lines like: `  iifname "veth-abc" ip daddr 10.0.0.0/8 drop # handle 42`
+ *
+ * @param nftOutput - Raw output from `nft -a list chain ip kici <chain>`
+ * @param identifier - String to search for in each rule line (interface name or UID)
+ * @returns Array of numeric rule handles
+ */
+export declare function parseRuleHandles(nftOutput: string, identifier: string): number[];
+//# sourceMappingURL=nftables.d.ts.map