@kici-dev/shared 0.0.0 → 0.1.0

package/dist/cold-store/metrics.js

@@ -0,0 +1,179 @@
+import "../chunk-gOLHoazu.js";
+import { createMeter } from "../telemetry/metrics.js";
+//#region src/cold-store/metrics.ts
+let _meter;
+function meter() {
+	if (!_meter) _meter = createMeter("kici-cold-store");
+	return _meter;
+}
+let _archiveCyclesTotal;
+let _archiveRowsTotal;
+let _archiveBytesTotal;
+let _archiveDurationSeconds;
+let _rehydrateRequestsTotal;
+let _rehydrateBytesTotal;
+let _rehydrateDurationSeconds;
+let _verifyFailuresTotal;
+let _replayRowsTotal;
+let _replayDurationSeconds;
+let _purgeChunksTotal;
+let _purgeBytesTotal;
+let _purgeDurationSeconds;
+/**
+* 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`.
+*/
+function coldStoreArchiveCyclesTotal() {
+	if (!_archiveCyclesTotal) _archiveCyclesTotal = meter().createCounter("cold_store_archive_cycles_total", { description: "Completed archive cycles by db and outcome" });
+	return _archiveCyclesTotal;
+}
+/**
+* Total rows archived, by db / table / outcome.
+* `result` ∈ success | failure | skipped_min_chunk | skipped_min_warm.
+*
+* Hidden from /metrics until the first Phase B+ TableAdapter moves
+* a row; the visible proof that the subsystem is wired is
+* `cold_store_archive_cycles_total`, not this counter.
+*/
+function coldStoreArchiveRowsTotal() {
+	if (!_archiveRowsTotal) _archiveRowsTotal = meter().createCounter("cold_store_archive_rows_total", { description: "Rows archived into cold storage by db, table, and outcome" });
+	return _archiveRowsTotal;
+}
+/**
+* Total bytes archived, by kind ∈ raw | gzipped. Lets us compute the
+* ongoing compression ratio.
+*/
+function coldStoreArchiveBytesTotal() {
+	if (!_archiveBytesTotal) _archiveBytesTotal = meter().createCounter("cold_store_archive_bytes_total", { description: "Bytes archived (raw vs gzipped) by db and table" });
+	return _archiveBytesTotal;
+}
+/**
+* Per-chunk archive duration histogram.
+* Buckets: 10ms, 100ms, 500ms, 1s, 5s, 30s, 120s.
+*/
+function coldStoreArchiveDurationSeconds() {
+	if (!_archiveDurationSeconds) _archiveDurationSeconds = meter().createHistogram("cold_store_archive_duration_seconds", {
+		description: "Archive duration per chunk, seconds",
+		advice: { explicitBucketBoundaries: [
+			.01,
+			.1,
+			.5,
+			1,
+			5,
+			30,
+			120
+		] }
+	});
+	return _archiveDurationSeconds;
+}
+/**
+* Rehydrate requests (cache hit vs miss). Incremented by the
+* read-through layer (Phase B+) when it serves a range query from
+* cold storage.
+*/
+function coldStoreRehydrateRequestsTotal() {
+	if (!_rehydrateRequestsTotal) _rehydrateRequestsTotal = meter().createCounter("cold_store_rehydrate_requests_total", { description: "Cold-store rehydrate requests by cache outcome" });
+	return _rehydrateRequestsTotal;
+}
+/** Bytes read from S3 on rehydrate cache miss. */
+function coldStoreRehydrateBytesTotal() {
+	if (!_rehydrateBytesTotal) _rehydrateBytesTotal = meter().createCounter("cold_store_rehydrate_bytes_total", { description: "Bytes read from S3 on rehydrate cache miss, by db and table" });
+	return _rehydrateBytesTotal;
+}
+/** Rehydrate duration (S3 fetch + decode), seconds. */
+function coldStoreRehydrateDurationSeconds() {
+	if (!_rehydrateDurationSeconds) _rehydrateDurationSeconds = meter().createHistogram("cold_store_rehydrate_duration_seconds", {
+		description: "Rehydrate duration per request, seconds",
+		advice: { explicitBucketBoundaries: [
+			.01,
+			.1,
+			.5,
+			1,
+			5,
+			30
+		] }
+	});
+	return _rehydrateDurationSeconds;
+}
+/**
+* Verify-failure counter — bumped on the rare `contentHash` mismatch
+* path during post-write verification.
+*/
+function coldStoreVerifyFailuresTotal() {
+	if (!_verifyFailuresTotal) _verifyFailuresTotal = meter().createCounter("cold_store_verify_failures_total", { description: "Post-write contentHash mismatch count, by db and table" });
+	return _verifyFailuresTotal;
+}
+/**
+* Phase F — rows promoted back into PG via `replayChunk` / `replayRow`.
+* `result` ∈ `success` | `failure` | `idempotent_skip`. The
+* `idempotent_skip` bucket counts rows already present in PG (chunk
+* replayed twice — no-op via ON CONFLICT). Hidden until the first
+* replay runs; the visible proof of the subsystem is
+* `cold_store_archive_cycles_total`.
+*/
+function coldStoreReplayRowsTotal() {
+	if (!_replayRowsTotal) _replayRowsTotal = meter().createCounter("cold_store_replay_rows_total", { description: "Rows promoted back into PG by db, table, and outcome" });
+	return _replayRowsTotal;
+}
+/**
+* Phase F — replay duration (S3 GET + manifest scan + decode + INSERT),
+* seconds. Buckets mirror archive duration: 10ms, 100ms, 500ms, 1s, 5s,
+* 30s, 120s.
+*/
+function coldStoreReplayDurationSeconds() {
+	if (!_replayDurationSeconds) _replayDurationSeconds = meter().createHistogram("cold_store_replay_duration_seconds", {
+		description: "Replay duration per chunk, seconds",
+		advice: { explicitBucketBoundaries: [
+			.01,
+			.1,
+			.5,
+			1,
+			5,
+			30,
+			120
+		] }
+	});
+	return _replayDurationSeconds;
+}
+/**
+* Phase 2 — chunks acted on by `purgeExpiredChunks`, labeled by db,
+* table, and outcome. `result` ∈ `purged` | `dry_run` | `skipped_locked`
+* | `failure`. Hidden until the first GC sweep finds candidates;
+* `cold_store_archive_cycles_total` remains the always-non-zero
+* heartbeat for the subsystem.
+*/
+function coldStorePurgeChunksTotal() {
+	if (!_purgeChunksTotal) _purgeChunksTotal = meter().createCounter("cold_store_purge_chunks_total", { description: "Chunks processed by the purge sweep, by db, table, and outcome" });
+	return _purgeChunksTotal;
+}
+/** Phase 2 — gzipped bytes deleted from S3 by the purge sweep. */
+function coldStorePurgeBytesTotal() {
+	if (!_purgeBytesTotal) _purgeBytesTotal = meter().createCounter("cold_store_purge_bytes_total", { description: "Gzipped bytes deleted by the purge sweep, by db and table" });
+	return _purgeBytesTotal;
+}
+/**
+* Phase 2 — purge duration per sweep, seconds. Buckets mirror the
+* archive duration histogram: 10ms, 100ms, 500ms, 1s, 5s, 30s, 120s.
+*/
+function coldStorePurgeDurationSeconds() {
+	if (!_purgeDurationSeconds) _purgeDurationSeconds = meter().createHistogram("cold_store_purge_duration_seconds", {
+		description: "Purge sweep duration per cycle, seconds",
+		advice: { explicitBucketBoundaries: [
+			.01,
+			.1,
+			.5,
+			1,
+			5,
+			30,
+			120
+		] }
+	});
+	return _purgeDurationSeconds;
+}
+//#endregion
+export { coldStoreArchiveBytesTotal, coldStoreArchiveCyclesTotal, coldStoreArchiveDurationSeconds, coldStoreArchiveRowsTotal, coldStorePurgeBytesTotal, coldStorePurgeChunksTotal, coldStorePurgeDurationSeconds, coldStoreRehydrateBytesTotal, coldStoreRehydrateDurationSeconds, coldStoreRehydrateRequestsTotal, coldStoreReplayDurationSeconds, coldStoreReplayRowsTotal, coldStoreVerifyFailuresTotal };
+
+//# sourceMappingURL=metrics.js.map

package/dist/cold-store/table-adapter.d.ts

@@ -0,0 +1,229 @@
+/**
+ * TableAdapter interface — the concrete per-table contract.
+ *
+ * Phase A shipped this interface with ZERO implementations. Phase B adds
+ * `run_events`; Phase C adds `execution_runs` / `execution_jobs` /
+ * `execution_steps`; etc. Each adapter lives next to its owning
+ * package (`packages/{platform,orchestrator}/src/cold-store/tables/`)
+ * and is registered on the respective `BaseColdStore` subclass.
+ */
+import type { ColdStoreTableConfig } from './config.js';
+import type { DbKind } from './key.js';
+import type { ColdRetention } from './types.js';
+/**
+ * Discovered (tenant, partition-day) tuple eligible for archival.
+ * Yielded by `listEligiblePartitions` in PK-ordered streams.
+ */
+export interface EligiblePartition {
+    tenantId: string;
+    /** `YYYY-MM-DD`. */
+    partitionDate: string;
+}
+/**
+ * Arguments to `writeAuditAndChunkCount`. The adapter's implementation
+ * is responsible for writing a row into whichever audit surface its DB
+ * has (Platform → `audit_log`, Orchestrator → `access_log` in later
+ * phases) AND upserting the per-(db, table, tenant) row in
+ * `cold_store_chunk_counts` — both inside the same transaction as the
+ * data-mutation in `markArchivedAndDelete`.
+ */
+export interface ChunkCommitMetadata {
+    chunkId: string;
+    tenantId: string;
+    partitionDate: string;
+    rowCount: number;
+    byteCount: number;
+    gzipByteCount: number;
+    objectKey: string;
+    /**
+     * Phase 2 — present on chunks written by adapters that implement
+     * `coldTtlDays(row)` (the per-bucket layout). Adapters use this to
+     * INSERT a corresponding row into `cold_store_chunks` inside the same
+     * transaction as the data delete + audit + rollup updates.
+     *
+     * Pre-Phase-2 (v1) chunks omit both fields — adapters skip the
+     * `cold_store_chunks` insert in that case and the GC sweep treats
+     * the chunk as `'forever'`.
+     */
+    bucket?: string;
+    /** Phase 2 — see `bucket`. Numeric day-count or `'forever'`. */
+    maxColdDays?: ColdRetention;
+}
+export interface TableAdapter<TRow> {
+    readonly db: DbKind;
+    /** Postgres table name the adapter archives. */
+    readonly table: string;
+    /** Column used to shard S3 keys (e.g. `org_id`, `routing_key`). */
+    readonly tenantColumn: string;
+    /** Column used for day-partitioning (e.g. `created_at`). */
+    readonly partitionColumn: string;
+    /** Effective per-table config after merging defaults + overrides. */
+    readonly config: ColdStoreTableConfig;
+    /**
+     * Stream the distinct (tenant, partitionDate) combinations that carry
+     * rows older than `warmCutoff`. The framework iterates these and,
+     * per combination, calls `selectEligible` inside `withPartitionLock`.
+     *
+     * Order: `(tenantId, partitionDate)` ascending. This lets the
+     * framework pause mid-iteration at a byte / row cap and resume on
+     * the next cycle without skipping partitions.
+     */
+    listEligiblePartitions(args: {
+        warmCutoff: Date;
+    }): AsyncIterable<EligiblePartition>;
+    /**
+     * Approximate size-in-bytes of warm rows for a single tenant.
+     * Used to enforce `minWarmTenantBytes` — we skip archival for
+     * low-traffic tenants where the chunk would be tiny.
+     *
+     * Implementations MAY approximate via `pg_column_size` sum + row
+     * count; accuracy within ~20% is fine.
+     */
+    countTenantWarmBytes(args: {
+        tenantId: string;
+        warmCutoff: Date;
+    }): Promise<number>;
+    /**
+     * Run `fn` while holding a Postgres advisory lock keyed by
+     * `hashtext('cold-store|<db>|<table>|<tenantId>|<partitionDate>')`.
+     *
+     * Returns the `fn` result on successful lock acquisition, or `null`
+     * when another archiver replica already holds the lock. The adapter
+     * owns this because the lock lives on its Kysely instance.
+     *
+     * Implementations SHOULD use `pg_try_advisory_xact_lock` inside a
+     * short-lived transaction so the lock is auto-released on commit
+     * or rollback.
+     */
+    withPartitionLock<T>(args: {
+        tenantId: string;
+        partitionDate: string;
+    }, fn: () => Promise<T>): Promise<T | null>;
+    /**
+     * Stream the eligible rows for one (tenant, partitionDate) combination,
+     * up to the adapter's byte/row cap. Rows yielded in PK order so min/max
+     * bounds are computed correctly.
+     */
+    selectEligible(args: {
+        tenantId: string;
+        partitionDate: string;
+        limit: number;
+    }): AsyncIterable<TRow>;
+    /** Stringify a row for the JSONL body. */
+    encodeRow(row: TRow): string;
+    /** Parse a row back from a JSONL line. */
+    decodeRow(line: string): TRow;
+    /** Extract the primary key; used for chunk-id bounds. */
+    rowId(row: TRow): string | number;
+    /** Extract the partition-column timestamp; used for manifest bounds. */
+    rowTimestamp(row: TRow): Date | string;
+    /**
+     * Phase F — optional natural-key extractor used by
+     * `BaseColdStore.replayRow()` to find a chunk by an externally
+     * meaningful identifier (e.g. UUID `run_id`) rather than the internal
+     * SERIAL `id` returned by `rowId()`. Adapters that implement this
+     * method opt the table into single-row replay-into-PG: every chunk
+     * persisted afterwards carries a `replayLookupKeys` array on its
+     * manifest. Adapters whose primary key already IS the natural key
+     * (e.g. `event_log` keyed by UUID) can leave this undefined — the
+     * `minRowId`/`maxRowId` range comparison covers them.
+     */
+    replayLookupKey?(row: TRow): string;
+    /**
+     * Transactionally:
+     *  1. `UPDATE <table> SET archived_at = now(), archive_object_key = <objectKey> WHERE id IN (<rowIds>)`.
+     *  2. `DELETE FROM <table> WHERE id IN (<rowIds>)`.
+     *  3. Call `writeAuditAndChunkCount` with `chunkMeta` on the same
+     *     transaction handle (adapter-internal wiring).
+     *
+     * Implemented inside each adapter because the row-ID column name
+     * varies per table.
+     */
+    markArchivedAndDelete(args: {
+        rowIds: ReadonlyArray<string | number>;
+        chunkMeta: ChunkCommitMetadata;
+    }): Promise<void>;
+    /**
+     * Phase F — replay a chunk's rows back into PG.
+     *
+     * Optional. Adapters that do NOT implement this method cannot be
+     * promoted back into PG via `BaseColdStore.replayChunk()` /
+     * `replayRow()` — only those tables whose rerun / rehydrate path
+     * genuinely needs read-after-write semantics on PG (currently only
+     * `execution_runs` on both DBs) opt in.
+     *
+     * Contract:
+     *  1. INSERT each row, clearing `archived_at` / `archive_object_key`,
+     *     `ON CONFLICT ON the natural unique key DO NOTHING` so a duplicate
+     *     replay is a no-op. Exact unique key varies per table (e.g.
+     *     `run_id` for `execution_runs`).
+     *  2. Write a "replay" audit row to whichever audit surface the DB has
+     *     (`audit_log` for Platform, `access_log` for Orchestrator).
+     *     `actor_id='cold-store-replay:<instanceId>'`,
+     *     `action='replay_chunk'`, `target_id=<chunkId>`.
+     *  3. Decrement `cold_store_chunk_counts` for the (db, table, tenant):
+     *     `chunk_count = chunk_count - 1`,
+     *     `total_rows  = total_rows  - <inserted>`,
+     *     `total_bytes = total_bytes - <gzipByteCount>`. Floors at 0 so a
+     *     replay-then-rearchive cycle doesn't underflow.
+     *
+     * All three steps run in one transaction — either everything commits
+     * or nothing does.
+     *
+     * Returns `{ inserted, skipped }`. `skipped` covers rows whose unique
+     * key already exists in PG (idempotent replays — fine).
+     */
+    replayInsert?(args: {
+        rows: ReadonlyArray<TRow>;
+        chunkMeta: ChunkCommitMetadata;
+    }): Promise<{
+        inserted: number;
+        skipped: number;
+    }>;
+    /**
+     * Phase 2 — per-row cold-retention TTL.
+     *
+     * Returns the number of days the row's chunk should live in S3 after
+     * archival, or `'forever'` to never purge. The framework groups rows by
+     * `coldDaysToBucket(coldTtlDays(row))` at archive time so each chunk
+     * spans a single bucket subprefix; the chunk's manifest carries the
+     * MAXIMUM `coldTtlDays` of any row in the chunk so the GC sweep keys
+     * off row-level retention rather than the bucket name.
+     *
+     * Adapters that don't implement this method opt out of the per-bucket
+     * layout: every chunk is written to the day-prefix root with the
+     * legacy v1 manifest and is treated as `'forever'` by the GC sweep.
+     * Audit-style adapters (`audit_log`, `access_log`, `secret_audit_log`)
+     * implement this; the high-volume execution / event tables retain
+     * their existing layout until their own retention policy is finalized.
+     */
+    coldTtlDays?(row: TRow): ColdRetention;
+    /**
+     * Phase 2 — transactionally purge a chunk's PG bookkeeping after the
+     * S3 objects have been deleted.
+     *
+     * Implementations MUST run all three steps in one transaction so a
+     * partial failure doesn't leave inconsistent state:
+     *   1. `DELETE FROM cold_store_chunks WHERE chunk_id = $1`.
+     *   2. Decrement `cold_store_chunk_counts` (`chunk_count -= 1`,
+     *      `total_bytes -= gzipBytes`, `total_rows -= rowCount`,
+     *      floored at 0 so a purge-then-rearchive doesn't underflow).
+     *   3. INSERT a `'purge_chunk'` audit row into the adapter's audit
+     *      surface (Platform → `audit_log`, Orchestrator → `access_log`)
+     *      with `actor_id='cold-store-purge:<instanceId>'` and details
+     *      `{ bucket, maxColdDays, gzipBytes, rowCount, objectKey }`.
+     *
+     * Optional — adapters that don't opt into the per-bucket layout via
+     * `coldTtlDays` also can't be purged, so they don't need this hook.
+     */
+    purgeChunkRecord?(args: {
+        tenantId: string;
+        chunkId: string;
+        gzipBytes: number;
+        rowCount: number;
+        bucket: string;
+        maxColdDays: number;
+        objectKey: string;
+    }): Promise<void>;
+}
+//# sourceMappingURL=table-adapter.d.ts.map

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

@@ -0,0 +1,2 @@
+import "../chunk-gOLHoazu.js";
+export {};

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

@@ -0,0 +1,111 @@
+/**
+ * Core types for the cold-storage archival framework.
+ *
+ *  for
+ * the full design. This module defines the shapes that the DB-agnostic
+ * cold-store framework exchanges with its two concrete consumers
+ * (Platform, Orchestrator).
+ */
+import type { DbKind } from './key.js';
+export type { DbKind } from './key.js';
+/**
+ * Sidecar manifest written next to every archived chunk.
+ *
+ * The manifest is the authoritative description of a chunk: callers
+ * MUST rely on it (not on file listings) to decide whether to rehydrate
+ * a given chunk for a range query. The `contentHash` field lets the
+ * `verify-chunk` CLI detect bit-rot or mutation without re-reading the
+ * body at ingestion time.
+ */
+/**
+ * Cold-retention horizon for a chunk: number of days the chunk lives in S3
+ * after archival before being purged, or `'forever'` to never purge.
+ */
+export type ColdRetention = number | 'forever';
+export interface ChunkManifest {
+    /**
+     * Manifest schema version.
+     *
+     * - `1`: Phase A–F. No bucket, no cold-TTL metadata. The framework
+     *   treats v1 chunks as `bucket='forever'` / `maxColdDays='forever'` so
+     *   the GC sweep never purges pre-Phase-2 chunks.
+     * - `2`: Phase 2 (cold-store purge). Adds `bucket` (S3-segment string)
+     *   and `maxColdDays` (numeric or `'forever'`). The GC sweep keys off
+     *   `archivedAt + maxColdDays`, NOT the bucket name — multiple actions
+     *   with different per-row TTLs can share a bucket.
+     */
+    schemaVersion: 1 | 2;
+    db: DbKind;
+    /** Postgres table name the chunk was sourced from. */
+    table: string;
+    /** `org_id` for Platform tables, `routing_key` for Orchestrator tables. */
+    tenantId: string;
+    /** `YYYY-MM-DD`. Derived from the table's partition column. */
+    partitionDate: string;
+    rowCount: number;
+    /** Size of the uncompressed JSONL body. */
+    byteCount: number;
+    /** Size of the gzipped data file. */
+    gzipByteCount: number;
+    /** Min of the partition column (ISO) across rows in this chunk. */
+    minTimestamp: string;
+    /** Max of the partition column (ISO) across rows in this chunk. */
+    maxTimestamp: string;
+    /** Min PK in the chunk (string or numeric, matches adapter output). */
+    minRowId: string | number;
+    /** Max PK in the chunk. */
+    maxRowId: string | number;
+    /** sha256 hex of the gzipped body. */
+    contentHash: string;
+    /** Filename-stem of the chunk; matches the deterministic ID. */
+    chunkId: string;
+    /** ISO wall clock at archive time. */
+    createdAt: string;
+    /** Instance ID of the archiver process, for forensics. */
+    archiverInstanceId: string;
+    /**
+     * Phase F — optional list of natural-key lookup tokens (e.g. UUID
+     * `run_id`) for every row in the chunk, populated when the adapter
+     * implements `replayLookupKey()`. Used by `BaseColdStore.replayRow()`
+     * to find the chunk holding a specific natural key when the manifest's
+     * `minRowId`/`maxRowId` are an internal SERIAL `id` that callers don't
+     * have. Older chunks (Phase C–E or any adapter without
+     * `replayLookupKey()`) omit this field; replayRow falls back to the
+     * `minRowId`/`maxRowId` range comparison in that case.
+     */
+    replayLookupKeys?: string[];
+    /**
+     * Phase 2 — S3 prefix segment under the `<tenant>/<YYYY>/<MM>/<DD>/`
+     * day directory. Examples: `'30d'`, `'180d'`, `'1y'`, `'2y'`, `'forever'`.
+     * V1 manifests omit this; the framework treats them as `'forever'`.
+     */
+    bucket?: string;
+    /**
+     * Phase 2 — maximum per-row cold TTL (days, or `'forever'`) across all
+     * rows in the chunk. The GC sweep purges a chunk when
+     * `now > archivedAt + maxColdDays * 86_400_000`. Multiple actions with
+     * different per-row TTLs can share a bucket, so the sweep MUST use this
+     * field (not the bucket name) for correctness.
+     */
+    maxColdDays?: ColdRetention;
+}
+/**
+ * Return value of `ColdStore.runArchiveCycle()`.
+ *
+ * Phase A's no-op path always reports zero work with
+ * `skipped.no_tables = 1` to signal "framework alive, no adapters
+ * registered". Phase B onward will report real values.
+ */
+export interface ArchiveCycleSummary {
+    tablesProcessed: number;
+    chunksWritten: number;
+    rowsArchived: number;
+    rowsFailed: number;
+    skipped: {
+        disabled: number;
+        min_chunk: number;
+        min_warm: number;
+        no_tables: number;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/cold-store/types.js

@@ -0,0 +1,2 @@
+import "../chunk-gOLHoazu.js";
+export {};

package/dist/crypto.d.ts

@@ -0,0 +1,33 @@
+/** Compute SHA-256 hex digest of a string or Buffer. */
+export declare function sha256(input: string | Buffer): string;
+/** Compute SHA-256 hex digest of a file's contents. */
+export declare function sha256File(filePath: string): Promise<string>;
+/**
+ * Normalize line endings to LF so hashes computed on different platforms agree.
+ *
+ * Git for Windows ships with `core.autocrlf=true` in the system gitconfig, so a
+ * `git clone` of a Linux-authored repo on a Windows host checks out text files
+ * with CRLF in the working tree. The compiler hashed the LF source on Linux,
+ * but the agent on Windows reads CRLF and computes a different hash — every
+ * dispatch fails with a "lock file is out of date" error even though the
+ * semantic content is identical.
+ *
+ * Applied at the boundaries where source / asset content enters the hash:
+ *   - raw workflow source (`.kici/workflows/*.ts`) at hash time, in both the
+ *     compiler (lockfile generation) and the agent (drift verification).
+ *   - file content portions of the asset digest (`hashFiles` resolution) on
+ *     both sides.
+ *
+ * Standalone `\r` is also collapsed to `\n` for safety against legacy
+ * Mac-style endings, though TypeScript source files essentially never carry
+ * those in practice.
+ */
+export declare function normalizeLineEndings(input: string): string;
+/**
+ * Derive an AES-256 key from an X25519 ECDH shared secret using HKDF.
+ *
+ * Used by the compiler (encrypt) and agent (decrypt) for tarball uploads.
+ * Keys must be DER-encoded (PKCS8 for private, SPKI for public).
+ */
+export declare function deriveSharedSecret(ourPrivateKey: Buffer, theirPublicKey: Buffer): Buffer;
+//# sourceMappingURL=crypto.d.ts.map

package/dist/crypto.js

@@ -0,0 +1,67 @@
+import "./chunk-gOLHoazu.js";
+import crypto, { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+//#region src/crypto.ts
+/** Compute SHA-256 hex digest of a string or Buffer. */
+function sha256(input) {
+	return createHash("sha256").update(input).digest("hex");
+}
+/** Compute SHA-256 hex digest of a file's contents. */
+async function sha256File(filePath) {
+	return sha256(await readFile(filePath));
+}
+/**
+* Normalize line endings to LF so hashes computed on different platforms agree.
+*
+* Git for Windows ships with `core.autocrlf=true` in the system gitconfig, so a
+* `git clone` of a Linux-authored repo on a Windows host checks out text files
+* with CRLF in the working tree. The compiler hashed the LF source on Linux,
+* but the agent on Windows reads CRLF and computes a different hash — every
+* dispatch fails with a "lock file is out of date" error even though the
+* semantic content is identical.
+*
+* Applied at the boundaries where source / asset content enters the hash:
+*   - raw workflow source (`.kici/workflows/*.ts`) at hash time, in both the
+*     compiler (lockfile generation) and the agent (drift verification).
+*   - file content portions of the asset digest (`hashFiles` resolution) on
+*     both sides.
+*
+* Standalone `\r` is also collapsed to `\n` for safety against legacy
+* Mac-style endings, though TypeScript source files essentially never carry
+* those in practice.
+*/
+function normalizeLineEndings(input) {
+	return input.replace(/\r\n?/g, "\n");
+}
+/** HKDF info string for ECDH-derived AES keys (upload encryption). */
+const HKDF_INFO = "kici-upload-encryption";
+/** Empty salt — ECDH output is already high entropy. */
+const HKDF_SALT = Buffer.alloc(0);
+/**
+* Derive an AES-256 key from an X25519 ECDH shared secret using HKDF.
+*
+* Used by the compiler (encrypt) and agent (decrypt) for tarball uploads.
+* Keys must be DER-encoded (PKCS8 for private, SPKI for public).
+*/
+function deriveSharedSecret(ourPrivateKey, theirPublicKey) {
+	const ourKeyObj = crypto.createPrivateKey({
+		key: ourPrivateKey,
+		format: "der",
+		type: "pkcs8"
+	});
+	const theirKeyObj = crypto.createPublicKey({
+		key: theirPublicKey,
+		format: "der",
+		type: "spki"
+	});
+	const sharedSecret = crypto.diffieHellman({
+		publicKey: theirKeyObj,
+		privateKey: ourKeyObj
+	});
+	const derivedKey = crypto.hkdfSync("sha256", sharedSecret, HKDF_SALT, HKDF_INFO, 32);
+	return Buffer.from(derivedKey);
+}
+//#endregion
+export { deriveSharedSecret, normalizeLineEndings, sha256, sha256File };
+
+//# sourceMappingURL=crypto.js.map