@kici-dev/shared 0.0.0 → 0.1.1

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

@@ -0,0 +1,1078 @@
+import "../chunk-gOLHoazu.js";
+import { sha256 } from "../crypto.js";
+import { createS3Client } from "../s3-client.js";
+import { chunkObjectKey, encodeKeySegment, tablePrefix, tenantDayPrefix } from "./key.js";
+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 { DeleteObjectCommand, GetObjectCommand, HeadObjectCommand, ListObjectsV2Command, PutObjectCommand } from "@aws-sdk/client-s3";
+//#region src/cold-store/cold-store.ts
+/**
+* BaseColdStore — the DB-agnostic framework class.
+*
+* Multiple concrete subclasses extend this one (e.g., `PlatformColdStore`,
+* `OrchestratorColdStore`). Each wires the adapter map with its
+* package-specific adapters.
+*
+* Phase B: `runArchiveCycle()` now drives the per-adapter archive loop
+* (design §4). `fetchRange` / `hasRange` / `countRange` are real — they
+* resolve manifests via `ListObjectsV2` and GET overlapping chunks
+* through an in-process LRU.
+*
+* ## Advisory-lock namespace
+*
+* All Postgres advisory locks acquired by the cold-store framework use
+* keys derived from `hashtext('cold-store|...')`. The `cold-store|`
+* prefix is reserved — do NOT reuse it in pipeline or engine code
+* without coordinating to avoid collisions.
+*
+* ## S3 bucket versioning caveat
+*
+* When the cold-store bucket has versioning ON (recommended default),
+* retried chunk PUTs produce new object versions at the same key.
+* Reconciliation (the `reconcile` CLI) MUST use `ListObjectVersions`,
+* not `ListObjects`, to detect orphaned objects correctly. The live
+* read-through uses `ListObjectsV2` because it only cares about the
+* current version of each manifest.
+*/
+const CONTENT_HASH_META = "content-hash";
+var BaseColdStore = class {
+	db;
+	config;
+	instanceId;
+	log;
+	chunkCache;
+	s3;
+	/** Registered table adapters by `table` name. */
+	adapters = /* @__PURE__ */ new Map();
+	constructor(deps) {
+		this.db = deps.db;
+		this.config = deps.config;
+		this.instanceId = deps.instanceId;
+		this.log = deps.log;
+		this.chunkCache = deps.chunkCache;
+		this.s3 = deps.s3Client ?? createS3Client({
+			region: deps.config.storage.region,
+			endpoint: deps.config.storage.endpoint,
+			forcePathStyle: deps.config.storage.forcePathStyle
+		});
+	}
+	/**
+	* Register a concrete table adapter. Subclasses typically call this
+	* from their constructor.
+	*/
+	registerAdapter(adapter) {
+		if (adapter.db !== this.db) throw new Error(`BaseColdStore: adapter db=${adapter.db} does not match cold-store db=${this.db}`);
+		if (this.adapters.has(adapter.table)) throw new Error(`BaseColdStore: duplicate adapter for table ${adapter.table}`);
+		this.adapters.set(adapter.table, adapter);
+	}
+	/** Test / CLI helper — adapter-map read access. */
+	getAdapter(table) {
+		return this.adapters.get(table);
+	}
+	listAdapters() {
+		return Array.from(this.adapters.values());
+	}
+	/**
+	* CLI-accessible S3 primitives. Exposed so admin CLI commands can run
+	* inspection / reconciliation operations without a direct dependency
+	* on `@aws-sdk/client-s3`. Not intended for hot-path use.
+	*/
+	get bucket() {
+		return this.config.storage.bucket;
+	}
+	get storagePrefix() {
+		return this.config.storage.prefix;
+	}
+	/** List all object keys under a prefix, paging internally. */
+	async listObjectKeys(prefix) {
+		const keys = [];
+		let continuationToken;
+		do {
+			const resp = await this.s3.send(new ListObjectsV2Command({
+				Bucket: this.config.storage.bucket,
+				Prefix: prefix,
+				ContinuationToken: continuationToken,
+				MaxKeys: 1e3
+			}));
+			for (const obj of resp.Contents ?? []) if (obj.Key) keys.push(obj.Key);
+			continuationToken = resp.IsTruncated ? resp.NextContinuationToken : void 0;
+		} while (continuationToken);
+		return keys;
+	}
+	/** Fetch an object's raw body as a Buffer. */
+	async getObjectBody(key) {
+		const resp = await this.s3.send(new GetObjectCommand({
+			Bucket: this.config.storage.bucket,
+			Key: key
+		}));
+		if (!resp.Body) throw new Error(`cold-store: empty body for ${key}`);
+		const bytes = await resp.Body.transformToByteArray();
+		return Buffer.from(bytes);
+	}
+	/** Upload a manifest JSON object at `key`. */
+	async putManifestObject(key, manifest) {
+		return this.putManifest(key, manifest);
+	}
+	/**
+	* Delete a single object by key. CLI-accessible companion to
+	* `listObjectKeys` / `getObjectBody`, used by tenant-scoped sweep
+	* paths (e.g. the post-`deleteOrgCascade` S3 cleanup) that operate
+	* on chunks the index already forgot about. Does NOT touch the
+	* `cold_store_chunks` index — callers that need both must follow
+	* the `purgeExpiredChunks` pattern with `withPurgeLock` +
+	* `adapter.purgeChunkRecord`.
+	*/
+	async deleteObject(key) {
+		await this.s3.send(new DeleteObjectCommand({
+			Bucket: this.config.storage.bucket,
+			Key: key
+		}));
+	}
+	async runArchiveCycle(opts) {
+		const start = Date.now();
+		const summary = {
+			tablesProcessed: 0,
+			chunksWritten: 0,
+			rowsArchived: 0,
+			rowsFailed: 0,
+			skipped: {
+				disabled: 0,
+				min_chunk: 0,
+				min_warm: 0,
+				no_tables: 0
+			}
+		};
+		if (!this.config.enabled) {
+			this.log("info", "cold-store cycle skipped: disabled by config", {
+				db: this.db,
+				instanceId: this.instanceId
+			});
+			summary.skipped.disabled += 1;
+			coldStoreArchiveCyclesTotal().add(1, {
+				db: this.db,
+				result: "disabled"
+			});
+			return summary;
+		}
+		if (this.adapters.size === 0) {
+			coldStoreArchiveCyclesTotal().add(1, {
+				db: this.db,
+				result: "no_tables"
+			});
+			summary.skipped.no_tables += 1;
+			this.log("info", "cold-store cycle: no adapters registered", {
+				db: this.db,
+				instanceId: this.instanceId,
+				durationMs: Date.now() - start
+			});
+			return summary;
+		}
+		const tableFilter = opts?.tableFilter;
+		if (tableFilter && !this.adapters.has(tableFilter)) throw new Error(`runArchiveCycle: tableFilter='${tableFilter}' has no registered adapter on db=${this.db} (registered: ${[...this.adapters.keys()].join(", ") || "(none)"})`);
+		for (const adapter of this.adapters.values()) {
+			if (tableFilter && adapter.table !== tableFilter) continue;
+			await this.processAdapter(adapter, summary);
+			summary.tablesProcessed += 1;
+		}
+		const cycleResult = summary.rowsFailed > 0 ? "failure" : summary.chunksWritten > 0 ? "success" : "no_tables";
+		coldStoreArchiveCyclesTotal().add(1, {
+			db: this.db,
+			result: cycleResult
+		});
+		this.log("info", "cold-store cycle complete", {
+			db: this.db,
+			instanceId: this.instanceId,
+			durationMs: Date.now() - start,
+			summary
+		});
+		return summary;
+	}
+	async processAdapter(adapter, summary) {
+		if (!adapter.config.enabled) {
+			summary.skipped.disabled += 1;
+			return;
+		}
+		const warmCutoff = /* @__PURE__ */ new Date(Date.now() - adapter.config.warmTtlDays * 864e5);
+		let rowsThisCycle = 0;
+		for await (const { tenantId, partitionDate } of adapter.listEligiblePartitions({ warmCutoff })) {
+			if (rowsThisCycle >= adapter.config.maxRowsPerCycle) {
+				this.log("info", "cold-store: per-cycle row cap reached; yielding", {
+					db: this.db,
+					table: adapter.table,
+					rowsThisCycle
+				});
+				break;
+			}
+			if (await adapter.countTenantWarmBytes({
+				tenantId,
+				warmCutoff
+			}) < adapter.config.minWarmTenantBytes) {
+				summary.skipped.min_warm += 1;
+				coldStoreArchiveRowsTotal().add(0, {
+					db: this.db,
+					table: adapter.table,
+					result: "skipped_min_warm"
+				});
+				continue;
+			}
+			const lockResult = await adapter.withPartitionLock({
+				tenantId,
+				partitionDate
+			}, async () => {
+				return this.archivePartition(adapter, tenantId, partitionDate, summary);
+			});
+			if (lockResult === null) {
+				this.log("info", "cold-store: another archiver holds the partition lock; skipping", {
+					db: this.db,
+					table: adapter.table,
+					tenantId,
+					partitionDate
+				});
+				continue;
+			}
+			rowsThisCycle += lockResult.rowsArchived;
+		}
+	}
+	/**
+	* Archive one (tenant, partitionDate).
+	*
+	* - Adapters WITHOUT `coldTtlDays`: legacy single-chunk path. Writes one
+	*   chunk per partition at the day-prefix root with a v1 manifest. The
+	*   GC sweep treats v1 chunks as `'forever'`.
+	* - Adapters WITH `coldTtlDays`: Phase 2 per-bucket path. Buffers all
+	*   eligible rows, groups by `coldDaysToBucket(coldTtlDays(row))`,
+	*   then emits one chunk per non-empty bucket under the bucket
+	*   subprefix with a v2 manifest carrying `bucket` + `maxColdDays`.
+	*
+	* In both paths the caller holds the advisory lock for the
+	* partition. Returns the total row count archived across all chunks
+	* so the outer loop can honor `maxRowsPerCycle`.
+	*/
+	async archivePartition(adapter, tenantId, partitionDate, summary) {
+		if (adapter.coldTtlDays) return this.archivePartitionBucketed(adapter, tenantId, partitionDate, summary);
+		return this.archivePartitionLegacy(adapter, tenantId, partitionDate, summary);
+	}
+	/**
+	* Legacy single-chunk-per-partition flow. Adapters that do not
+	* implement `coldTtlDays` get a v1 manifest at the day-prefix root.
+	*/
+	async archivePartitionLegacy(adapter, tenantId, partitionDate, summary) {
+		const partitionStart = Date.now();
+		const label = {
+			db: this.db,
+			table: adapter.table
+		};
+		let encoded;
+		try {
+			encoded = await encodeChunk({
+				rows: adapter.selectEligible({
+					tenantId,
+					partitionDate,
+					limit: adapter.config.maxRowsPerCycle
+				}),
+				encodeRow: adapter.encodeRow.bind(adapter),
+				rowId: adapter.rowId.bind(adapter),
+				rowTimestamp: adapter.rowTimestamp.bind(adapter),
+				replayLookupKey: adapter.replayLookupKey?.bind(adapter)
+			});
+		} catch (err) {
+			if (err instanceof Error && /empty row stream/.test(err.message)) {
+				summary.skipped.min_chunk += 1;
+				return { rowsArchived: 0 };
+			}
+			throw err;
+		}
+		if (encoded.gzipByteCount < adapter.config.minChunkBytes) {
+			summary.skipped.min_chunk += 1;
+			coldStoreArchiveRowsTotal().add(0, {
+				...label,
+				result: "skipped_min_chunk"
+			});
+			return { rowsArchived: 0 };
+		}
+		return this.writeChunk(adapter, {
+			tenantId,
+			partitionDate,
+			encoded,
+			partitionStart,
+			summary,
+			bucket: void 0,
+			maxColdDays: void 0
+		});
+	}
+	/**
+	* Phase 2 per-bucket flow. Buffers all eligible rows, groups by
+	* `coldDaysToBucket(coldTtlDays(row))`, then emits one chunk per
+	* non-empty bucket.
+	*/
+	async archivePartitionBucketed(adapter, tenantId, partitionDate, summary) {
+		const label = {
+			db: this.db,
+			table: adapter.table
+		};
+		const coldTtlDays = adapter.coldTtlDays.bind(adapter);
+		const buckets = /* @__PURE__ */ new Map();
+		let bufferedRows = 0;
+		for await (const row of adapter.selectEligible({
+			tenantId,
+			partitionDate,
+			limit: adapter.config.maxRowsPerCycle
+		})) {
+			const ttl = coldTtlDays(row);
+			const bucket = coldDaysToBucket(ttl);
+			const entry = buckets.get(bucket);
+			if (entry) {
+				entry.rows.push(row);
+				if (isLongerColdRetention(ttl, entry.maxColdDays)) entry.maxColdDays = ttl;
+			} else buckets.set(bucket, {
+				rows: [row],
+				maxColdDays: ttl
+			});
+			bufferedRows += 1;
+		}
+		if (bufferedRows === 0) {
+			summary.skipped.min_chunk += 1;
+			return { rowsArchived: 0 };
+		}
+		let totalArchived = 0;
+		for (const [bucket, { rows, maxColdDays }] of buckets) {
+			const partitionStart = Date.now();
+			let encoded;
+			try {
+				encoded = await encodeChunk({
+					rows: arrayToAsync(rows),
+					encodeRow: adapter.encodeRow.bind(adapter),
+					rowId: adapter.rowId.bind(adapter),
+					rowTimestamp: adapter.rowTimestamp.bind(adapter),
+					replayLookupKey: adapter.replayLookupKey?.bind(adapter)
+				});
+			} catch (err) {
+				throw err;
+			}
+			if (encoded.gzipByteCount < adapter.config.minChunkBytes) {
+				summary.skipped.min_chunk += 1;
+				coldStoreArchiveRowsTotal().add(0, {
+					...label,
+					result: "skipped_min_chunk"
+				});
+				this.log("info", "cold-store: bucket below minChunkBytes; skipping this cycle", {
+					...label,
+					tenantId,
+					partitionDate,
+					bucket,
+					rowCount: rows.length,
+					gzipByteCount: encoded.gzipByteCount,
+					minChunkBytes: adapter.config.minChunkBytes
+				});
+				continue;
+			}
+			const result = await this.writeChunk(adapter, {
+				tenantId,
+				partitionDate,
+				encoded,
+				partitionStart,
+				summary,
+				bucket,
+				maxColdDays
+			});
+			totalArchived += result.rowsArchived;
+		}
+		return { rowsArchived: totalArchived };
+	}
+	/**
+	* Common chunk-write flow: PUT data, verify, PUT manifest, transactional
+	* mark-archived-and-delete on the adapter, increment metrics.
+	*
+	* Shared by `archivePartitionLegacy` (v1 manifests) and
+	* `archivePartitionBucketed` (v2 manifests with bucket + maxColdDays).
+	*/
+	async writeChunk(adapter, args) {
+		const { tenantId, partitionDate, encoded, partitionStart, summary, bucket, maxColdDays } = args;
+		const label = {
+			db: this.db,
+			table: adapter.table
+		};
+		if (bucket === void 0 !== (maxColdDays === void 0)) throw new Error(`cold-store writeChunk: bucket and maxColdDays must both be set or both undefined; got bucket=${JSON.stringify(bucket)} maxColdDays=${JSON.stringify(maxColdDays)}`);
+		const chunkId = computeChunkId({
+			db: this.db,
+			table: adapter.table,
+			tenantId,
+			partitionDate,
+			minRowId: encoded.minRowId,
+			maxRowId: encoded.maxRowId
+		});
+		const keyArgs = {
+			prefix: this.config.storage.prefix,
+			db: this.db,
+			table: adapter.table,
+			tenantId,
+			partitionDate,
+			chunkId,
+			bucket
+		};
+		const dataKey = chunkObjectKey({
+			...keyArgs,
+			kind: "data"
+		});
+		const manifestKey = chunkObjectKey({
+			...keyArgs,
+			kind: "manifest"
+		});
+		try {
+			await this.putChunkData(dataKey, encoded.data, encoded.contentHash);
+			await this.verifyChunkData(dataKey, encoded.contentHash, adapter.table);
+			const manifest = bucket !== void 0 && maxColdDays !== void 0 ? {
+				schemaVersion: 2,
+				db: this.db,
+				table: adapter.table,
+				tenantId,
+				partitionDate,
+				rowCount: encoded.rowCount,
+				byteCount: encoded.byteCount,
+				gzipByteCount: encoded.gzipByteCount,
+				minTimestamp: encoded.minTimestamp,
+				maxTimestamp: encoded.maxTimestamp,
+				minRowId: encoded.minRowId,
+				maxRowId: encoded.maxRowId,
+				contentHash: encoded.contentHash,
+				chunkId,
+				createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+				archiverInstanceId: this.instanceId,
+				replayLookupKeys: encoded.replayLookupKeys,
+				bucket,
+				maxColdDays
+			} : {
+				schemaVersion: 1,
+				db: this.db,
+				table: adapter.table,
+				tenantId,
+				partitionDate,
+				rowCount: encoded.rowCount,
+				byteCount: encoded.byteCount,
+				gzipByteCount: encoded.gzipByteCount,
+				minTimestamp: encoded.minTimestamp,
+				maxTimestamp: encoded.maxTimestamp,
+				minRowId: encoded.minRowId,
+				maxRowId: encoded.maxRowId,
+				contentHash: encoded.contentHash,
+				chunkId,
+				createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+				archiverInstanceId: this.instanceId,
+				replayLookupKeys: encoded.replayLookupKeys
+			};
+			await this.putManifest(manifestKey, manifest);
+			await adapter.markArchivedAndDelete({
+				rowIds: encoded.rowIds,
+				chunkMeta: {
+					chunkId,
+					tenantId,
+					partitionDate,
+					rowCount: encoded.rowCount,
+					byteCount: encoded.byteCount,
+					gzipByteCount: encoded.gzipByteCount,
+					objectKey: dataKey,
+					bucket,
+					maxColdDays
+				}
+			});
+			summary.chunksWritten += 1;
+			summary.rowsArchived += encoded.rowCount;
+			coldStoreArchiveRowsTotal().add(encoded.rowCount, {
+				...label,
+				result: "success"
+			});
+			coldStoreArchiveBytesTotal().add(encoded.byteCount, {
+				...label,
+				kind: "raw"
+			});
+			coldStoreArchiveBytesTotal().add(encoded.gzipByteCount, {
+				...label,
+				kind: "gzipped"
+			});
+			coldStoreArchiveDurationSeconds().record((Date.now() - partitionStart) / 1e3, label);
+			this.log("info", "cold-store chunk archived", {
+				event: "chunk_archived",
+				...label,
+				tenantId,
+				partitionDate,
+				chunkId,
+				bucket,
+				maxColdDays,
+				rowCount: encoded.rowCount,
+				byteCount: encoded.byteCount,
+				gzipByteCount: encoded.gzipByteCount,
+				durationMs: Date.now() - partitionStart
+			});
+			return { rowsArchived: encoded.rowCount };
+		} catch (err) {
+			summary.rowsFailed += encoded.rowCount;
+			coldStoreArchiveRowsTotal().add(encoded.rowCount, {
+				...label,
+				result: "failure"
+			});
+			coldStoreArchiveDurationSeconds().record((Date.now() - partitionStart) / 1e3, label);
+			this.log("error", "cold-store chunk archive failed", {
+				...label,
+				tenantId,
+				partitionDate,
+				bucket,
+				chunkId,
+				error: err instanceof Error ? err.message : String(err)
+			});
+			return { rowsArchived: 0 };
+		}
+	}
+	async putChunkData(key, body, contentHash) {
+		await this.s3.send(new PutObjectCommand({
+			Bucket: this.config.storage.bucket,
+			Key: key,
+			Body: body,
+			ContentType: "application/gzip",
+			Metadata: { [CONTENT_HASH_META]: contentHash }
+		}));
+	}
+	async verifyChunkData(key, expectedHash, table, attempt = 0) {
+		const gotHash = (await this.s3.send(new HeadObjectCommand({
+			Bucket: this.config.storage.bucket,
+			Key: key
+		}))).Metadata?.[CONTENT_HASH_META];
+		if (gotHash === expectedHash) return;
+		coldStoreVerifyFailuresTotal().add(1, {
+			db: this.db,
+			table
+		});
+		if (attempt >= 2) throw new Error(`cold-store: HeadObject content-hash mismatch for ${key} after 3 attempts (got ${gotHash ?? "<missing>"}, expected ${expectedHash})`);
+		this.log("warn", "cold-store: verify hash mismatch; retrying", {
+			db: this.db,
+			table,
+			key,
+			attempt
+		});
+		return this.verifyChunkData(key, expectedHash, table, attempt + 1);
+	}
+	async putManifest(key, manifest) {
+		await this.s3.send(new PutObjectCommand({
+			Bucket: this.config.storage.bucket,
+			Key: key,
+			Body: Buffer.from(serializeManifest(manifest), "utf-8"),
+			ContentType: "application/json"
+		}));
+	}
+	async *fetchRange(args) {
+		if (!this.config.enabled) return;
+		const adapter = this.adapters.get(args.table);
+		const decodeLine = args.decode ?? (adapter ? (line) => adapter.decodeRow(line) : (line) => JSON.parse(line));
+		const rowTimestamp = adapter ? (row) => this.toDate(adapter.rowTimestamp(row)) : null;
+		const manifests = await this.listRelevantManifests({
+			db: args.db,
+			table: args.table,
+			tenantId: args.tenantId,
+			fromTs: args.fromTs,
+			toTs: args.toTs
+		});
+		const label = {
+			db: args.db,
+			table: args.table
+		};
+		for (const manifest of manifests) {
+			const dataKey = chunkObjectKey({
+				prefix: this.config.storage.prefix,
+				db: args.db,
+				table: args.table,
+				tenantId: args.tenantId,
+				partitionDate: manifest.partitionDate,
+				chunkId: manifest.chunkId,
+				kind: "data",
+				bucket: manifest.schemaVersion === 2 ? manifest.bucket : void 0
+			});
+			const fetchStart = Date.now();
+			const gzipped = await this.getChunkData(dataKey, manifest.contentHash);
+			coldStoreRehydrateDurationSeconds().record((Date.now() - fetchStart) / 1e3, label);
+			for await (const row of decodeChunk({
+				gzipped,
+				decodeLine
+			})) {
+				if (rowTimestamp) {
+					const ts = rowTimestamp(row);
+					if (ts < args.fromTs || ts >= args.toTs) continue;
+				}
+				yield row;
+			}
+		}
+	}
+	async hasRange(args) {
+		if (!this.config.enabled) return false;
+		return (await this.listRelevantManifests(args)).length > 0;
+	}
+	async countRange(args) {
+		if (!this.config.enabled) return 0;
+		const manifests = await this.listRelevantManifests(args);
+		let total = 0;
+		for (const m of manifests) total += m.rowCount;
+		return total;
+	}
+	/**
+	* Resolve all manifest sidecars whose time-range overlaps
+	* [fromTs, toTs). Uses one LIST walk under the tenant prefix, then
+	* GETs each `.manifest.json`.
+	*/
+	async listRelevantManifests(args) {
+		const tenantPrefix = tablePrefix({
+			prefix: this.config.storage.prefix,
+			db: args.db,
+			table: args.table
+		}) + `/${encodeKeySegment(args.tenantId)}/`;
+		const manifestKeys = [];
+		let continuationToken;
+		do {
+			const resp = await this.s3.send(new ListObjectsV2Command({
+				Bucket: this.config.storage.bucket,
+				Prefix: tenantPrefix,
+				ContinuationToken: continuationToken,
+				MaxKeys: 1e3
+			}));
+			for (const obj of resp.Contents ?? []) if (obj.Key && obj.Key.endsWith(".manifest.json")) manifestKeys.push(obj.Key);
+			continuationToken = resp.IsTruncated ? resp.NextContinuationToken : void 0;
+		} while (continuationToken);
+		const manifests = [];
+		for (const key of manifestKeys) {
+			const m = await this.getManifest(key);
+			const min = new Date(m.minTimestamp);
+			if (new Date(m.maxTimestamp) < args.fromTs) continue;
+			if (min >= args.toTs) continue;
+			manifests.push(m);
+		}
+		manifests.sort((a, b) => a.minTimestamp < b.minTimestamp ? -1 : 1);
+		return manifests;
+	}
+	async getManifest(key) {
+		const resp = await this.s3.send(new GetObjectCommand({
+			Bucket: this.config.storage.bucket,
+			Key: key
+		}));
+		if (!resp.Body) throw new Error(`cold-store: empty manifest body for ${key}`);
+		const bytes = await resp.Body.transformToByteArray();
+		return parseManifest(Buffer.from(bytes));
+	}
+	async getChunkData(key, expectedHash) {
+		const label = {
+			db: this.db,
+			table: keyToTable(key)
+		};
+		const cached = this.chunkCache?.get(key);
+		if (cached) {
+			coldStoreRehydrateRequestsTotal().add(1, {
+				...label,
+				cache_outcome: "hit"
+			});
+			return cached;
+		}
+		coldStoreRehydrateRequestsTotal().add(1, {
+			...label,
+			cache_outcome: "miss"
+		});
+		const resp = await this.s3.send(new GetObjectCommand({
+			Bucket: this.config.storage.bucket,
+			Key: key
+		}));
+		if (!resp.Body) throw new Error(`cold-store: empty chunk body for ${key}`);
+		const bytes = await resp.Body.transformToByteArray();
+		const body = Buffer.from(bytes);
+		coldStoreRehydrateBytesTotal().add(body.byteLength, label);
+		const got = sha256(body);
+		if (got !== expectedHash) {
+			coldStoreVerifyFailuresTotal().add(1, label);
+			throw new Error(`cold-store: chunk content-hash mismatch for ${key} (got ${got}, expected ${expectedHash})`);
+		}
+		this.chunkCache?.set(key, body);
+		return body;
+	}
+	/**
+	* Promote every row in a chunk back into PG. The adapter owns the
+	* actual INSERT + audit + chunk-counter decrement (transactional).
+	*
+	* Throws when:
+	*  - the cold store is disabled
+	*  - the adapter is unregistered or doesn't implement `replayInsert`
+	*  - the manifest is missing
+	*  - the data file's sha256 doesn't match the manifest's
+	*    `contentHash` (refuse to replay a tampered chunk)
+	*
+	* Idempotent on re-run: the adapter's `ON CONFLICT DO NOTHING`
+	* collapses the second pass to `inserted=0, skipped=rowCount`.
+	*/
+	async replayChunk(args) {
+		if (!this.config.enabled) throw new Error("cold-store: replayChunk called while cold-store is disabled");
+		const adapter = this.adapters.get(args.table);
+		if (!adapter) throw new Error(`cold-store: replay-chunk requires a registered adapter for table '${args.table}' on db=${this.db}`);
+		if (!adapter.replayInsert) throw new Error(`cold-store: replay-into-pg not supported for table '${args.table}' (adapter has no replayInsert)`);
+		if (adapter.db !== args.db) throw new Error(`cold-store: replayChunk db=${args.db} does not match adapter db=${adapter.db}`);
+		const start = Date.now();
+		const label = {
+			db: args.db,
+			table: args.table
+		};
+		try {
+			const dayPrefix = tenantDayPrefix({
+				prefix: this.config.storage.prefix,
+				db: args.db,
+				table: args.table,
+				tenantId: args.tenantId,
+				partitionDate: args.partitionDate
+			});
+			const dayKeys = await this.listObjectKeys(dayPrefix);
+			const manifestSuffix = `/${args.chunkId}.manifest.json`;
+			const manifestKey = dayKeys.find((k) => k.endsWith(manifestSuffix));
+			if (!manifestKey) throw new Error(`cold-store: replay-chunk ${args.chunkId} not found under ${dayPrefix} (db=${args.db} table=${args.table} tenantId=${args.tenantId} partitionDate=${args.partitionDate})`);
+			const dataKey = manifestKey.replace(/\.manifest\.json$/, ".jsonl.gz");
+			const [data, manifest] = await Promise.all([this.getObjectBody(dataKey), this.getManifest(manifestKey)]);
+			const got = sha256(data);
+			if (got !== manifest.contentHash) {
+				coldStoreVerifyFailuresTotal().add(1, label);
+				throw new Error(`cold-store: replay-chunk ${args.chunkId} refused — contentHash mismatch (got ${got}, manifest ${manifest.contentHash})`);
+			}
+			const rows = [];
+			for await (const row of decodeChunk({
+				gzipped: data,
+				decodeLine: (line) => adapter.decodeRow(line)
+			})) rows.push(row);
+			const chunkMeta = {
+				chunkId: manifest.chunkId,
+				tenantId: manifest.tenantId,
+				partitionDate: manifest.partitionDate,
+				rowCount: manifest.rowCount,
+				byteCount: manifest.byteCount,
+				gzipByteCount: manifest.gzipByteCount,
+				objectKey: dataKey
+			};
+			const result = await adapter.replayInsert.bind(adapter)({
+				rows,
+				chunkMeta
+			});
+			coldStoreReplayRowsTotal().add(result.inserted, {
+				...label,
+				result: "success"
+			});
+			if (result.skipped > 0) coldStoreReplayRowsTotal().add(result.skipped, {
+				...label,
+				result: "idempotent_skip"
+			});
+			coldStoreReplayDurationSeconds().record((Date.now() - start) / 1e3, label);
+			this.log("info", "cold-store chunk replayed", {
+				event: "chunk_replayed",
+				...label,
+				tenantId: manifest.tenantId,
+				partitionDate: manifest.partitionDate,
+				chunkId: args.chunkId,
+				rowsReplayed: result.inserted,
+				rowsSkipped: result.skipped,
+				durationMs: Date.now() - start
+			});
+			return {
+				inserted: result.inserted,
+				skipped: result.skipped,
+				chunkId: args.chunkId
+			};
+		} catch (err) {
+			coldStoreReplayRowsTotal().add(0, {
+				...label,
+				result: "failure"
+			});
+			coldStoreReplayDurationSeconds().record((Date.now() - start) / 1e3, label);
+			this.log("error", "cold-store chunk replay failed", {
+				...label,
+				chunkId: args.chunkId,
+				tenantId: args.tenantId,
+				partitionDate: args.partitionDate,
+				error: err instanceof Error ? err.message : String(err)
+			});
+			throw err;
+		}
+	}
+	/**
+	* Locate the chunk whose `[minRowId, maxRowId]` window covers
+	* `rowId` and replay it. Scans manifests under the tenant prefix
+	* (LIST is one round-trip; manifests are tiny). When several manifests
+	* match (overlapping ranges from re-archives), the one with the
+	* smallest range is preferred — it's the most recently re-archived
+	* shard and therefore the one whose row contents are freshest.
+	*
+	* Returns `chunkId: null` when no manifest matches — the caller
+	* decides whether that means "row never existed" (rerun → 404) or
+	* "S3 outage" (rerun → 410 replayFailed). This method only fails
+	* loudly on infrastructure errors (missing chunk after manifest
+	* found, hash mismatch).
+	*/
+	async replayRow(args) {
+		if (!this.config.enabled) return {
+			inserted: 0,
+			skipped: 0,
+			chunkId: null
+		};
+		const tenantPrefix = tablePrefix({
+			prefix: this.config.storage.prefix,
+			db: args.db,
+			table: args.table
+		}) + `/${encodeKeySegment(args.tenantId)}/`;
+		const manifestKeys = [];
+		let continuationToken;
+		do {
+			const resp = await this.s3.send(new ListObjectsV2Command({
+				Bucket: this.config.storage.bucket,
+				Prefix: tenantPrefix,
+				ContinuationToken: continuationToken,
+				MaxKeys: 1e3
+			}));
+			for (const obj of resp.Contents ?? []) if (obj.Key && obj.Key.endsWith(".manifest.json")) manifestKeys.push(obj.Key);
+			continuationToken = resp.IsTruncated ? resp.NextContinuationToken : void 0;
+		} while (continuationToken);
+		const wanted = String(args.rowId);
+		let best = null;
+		let exact = null;
+		for (const key of manifestKeys) {
+			const m = await this.getManifest(key);
+			if (m.replayLookupKeys && m.replayLookupKeys.includes(wanted)) {
+				exact = m;
+				break;
+			}
+			const lo = m.minRowId;
+			const hi = m.maxRowId;
+			if (compareIds(args.rowId, lo) < 0) continue;
+			if (compareIds(args.rowId, hi) > 0) continue;
+			const width = idDistance(lo, hi);
+			if (best === null || width < best.rangeWidth) best = {
+				manifest: m,
+				rangeWidth: width
+			};
+		}
+		const picked = exact ?? best?.manifest ?? null;
+		if (!picked) return {
+			inserted: 0,
+			skipped: 0,
+			chunkId: null
+		};
+		return this.replayChunk({
+			db: args.db,
+			table: args.table,
+			tenantId: picked.tenantId,
+			partitionDate: picked.partitionDate,
+			chunkId: picked.chunkId
+		});
+	}
+	toDate(v) {
+		return v instanceof Date ? v : new Date(v);
+	}
+	/**
+	* Subclass hook — query the per-DB `cold_store_chunks` index for
+	* purge candidates. Concrete subclasses (PlatformColdStore /
+	* OrchestratorColdStore) implement this with one Kysely SQL query
+	* keyed off `archived_at + max_cold_days * INTERVAL '1 day' < now()`
+	* and `max_cold_days != 'forever'`.
+	*
+	* Returning an empty array makes `purgeExpiredChunks` a no-op.
+	* Default implementation returns `[]` so non-purge subclasses (or
+	* test fixtures) can opt out trivially.
+	*/
+	async listPurgeableChunks(_opts) {
+		return [];
+	}
+	/**
+	* Acquire a per-chunk advisory lock so concurrent sweeps can't
+	* race on the same `DeleteObject` + `cold_store_chunks` row.
+	*
+	* Default implementation is a no-op (always succeeds). Subclasses
+	* with a Kysely instance override to use `pg_try_advisory_lock` on
+	* `hashtext('cold-store-purge|<db>|<table>|<chunkId>')` and release
+	* inside `fn`'s `finally`. Returns `null` when another worker holds
+	* the lock; returns the `fn` result on success.
+	*/
+	async withPurgeLock(_args, fn) {
+		return fn();
+	}
+	async purgeExpiredChunks(opts) {
+		const start = Date.now();
+		if (!this.config.enabled) return {
+			results: [],
+			bytesPurged: 0,
+			chunksPurged: 0,
+			durationMs: 0
+		};
+		const limit = opts?.limit ?? 1e3;
+		const dryRun = opts?.dryRun ?? false;
+		const candidates = await this.listPurgeableChunks({
+			tableFilter: opts?.tableFilter,
+			bucketFilter: opts?.bucketFilter,
+			limit
+		});
+		const results = [];
+		let bytesPurged = 0;
+		let chunksPurged = 0;
+		for (const c of candidates) {
+			const baseResult = {
+				table: c.table,
+				tenantId: c.tenantId,
+				chunkId: c.chunkId,
+				bucket: c.bucket,
+				gzipBytes: c.gzipBytes,
+				rowCount: c.rowCount
+			};
+			const label = {
+				db: this.db,
+				table: c.table
+			};
+			if (dryRun) {
+				results.push({
+					...baseResult,
+					outcome: "dry_run"
+				});
+				coldStorePurgeChunksTotal().add(1, {
+					...label,
+					result: "dry_run"
+				});
+				continue;
+			}
+			const adapter = this.adapters.get(c.table);
+			if (!adapter) {
+				results.push({
+					...baseResult,
+					outcome: "failure",
+					error: `no adapter registered for table=${c.table}`
+				});
+				coldStorePurgeChunksTotal().add(1, {
+					...label,
+					result: "failure"
+				});
+				continue;
+			}
+			if (!adapter.purgeChunkRecord) {
+				results.push({
+					...baseResult,
+					outcome: "failure",
+					error: `adapter ${c.table} does not implement purgeChunkRecord`
+				});
+				coldStorePurgeChunksTotal().add(1, {
+					...label,
+					result: "failure"
+				});
+				continue;
+			}
+			const lockResult = await this.withPurgeLock({
+				table: c.table,
+				chunkId: c.chunkId
+			}, async () => {
+				const manifestKey = c.objectKey.replace(/\.jsonl\.gz$/, ".manifest.json");
+				await this.s3.send(new DeleteObjectCommand({
+					Bucket: this.config.storage.bucket,
+					Key: c.objectKey
+				}));
+				await this.s3.send(new DeleteObjectCommand({
+					Bucket: this.config.storage.bucket,
+					Key: manifestKey
+				}));
+				await adapter.purgeChunkRecord({
+					tenantId: c.tenantId,
+					chunkId: c.chunkId,
+					gzipBytes: c.gzipBytes,
+					rowCount: c.rowCount,
+					bucket: c.bucket,
+					maxColdDays: c.maxColdDays,
+					objectKey: c.objectKey
+				});
+				return true;
+			}).catch((err) => {
+				results.push({
+					...baseResult,
+					outcome: "failure",
+					error: err instanceof Error ? err.message : String(err)
+				});
+				coldStorePurgeChunksTotal().add(1, {
+					...label,
+					result: "failure"
+				});
+				return false;
+			});
+			if (lockResult === null) {
+				results.push({
+					...baseResult,
+					outcome: "skipped_locked"
+				});
+				coldStorePurgeChunksTotal().add(1, {
+					...label,
+					result: "skipped_locked"
+				});
+				continue;
+			}
+			if (lockResult === true) {
+				results.push({
+					...baseResult,
+					outcome: "purged"
+				});
+				bytesPurged += c.gzipBytes;
+				chunksPurged += 1;
+				coldStorePurgeChunksTotal().add(1, {
+					...label,
+					result: "purged"
+				});
+				coldStorePurgeBytesTotal().add(c.gzipBytes, label);
+			}
+		}
+		coldStorePurgeDurationSeconds().record((Date.now() - start) / 1e3, { db: this.db });
+		const summary = {
+			results,
+			bytesPurged,
+			chunksPurged,
+			durationMs: Date.now() - start
+		};
+		this.log("info", "cold-store purge sweep complete", {
+			db: this.db,
+			dryRun,
+			candidates: candidates.length,
+			chunksPurged,
+			bytesPurged,
+			durationMs: summary.durationMs
+		});
+		return summary;
+	}
+};
+function compareIds(a, b) {
+	if (typeof a === "number" && typeof b === "number") return a - b;
+	const as = String(a);
+	const bs = String(b);
+	if (as < bs) return -1;
+	if (as > bs) return 1;
+	return 0;
+}
+function idDistance(lo, hi) {
+	if (typeof lo === "number" && typeof hi === "number") return Math.max(0, hi - lo);
+	const lenDelta = String(hi).length - String(lo).length;
+	if (lenDelta !== 0) return Math.max(0, lenDelta);
+	return String(hi) < String(lo) ? 0 : 1;
+}
+/**
+* Best-effort extraction of the table name from a chunk key of shape
+* `<prefix>/<db>/<table>/<tenant>/<YYYY>/<MM>/<DD>/<chunk>.ext` (v1) or
+* `<prefix>/<db>/<table>/<tenant>/<YYYY>/<MM>/<DD>/<bucket>/<chunk>.ext`
+* (v2 with bucket subprefix). Used for metric labels on the read-through
+* path; returns `'unknown'` if the key doesn't parse.
+*/
+function keyToTable(key) {
+	const parts = key.split("/");
+	for (let i = parts.length - 4; i >= 2; i--) if (/^\d{4}$/.test(parts[i] ?? "")) return parts[i - 2] ?? "unknown";
+	return "unknown";
+}
+/**
+* Lift an in-memory array into an `AsyncIterable` so it can feed
+* `encodeChunk` (which expects a stream). Used by the per-bucket
+* archive flow to re-stream each bucket's row subset through the
+* existing single-stream encoder without further refactoring.
+*/
+async function* arrayToAsync(items) {
+	for (const item of items) yield item;
+}
+//#endregion
+export { BaseColdStore };
+
+//# sourceMappingURL=cold-store.js.map