@kici-dev/shared 0.0.0 → 0.1.0

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cold-store.test.d.ts.map

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

@@ -0,0 +1,62 @@
+/**
+ * Cold-store configuration types.
+ *
+ * section 5. Per-table defaults in DEFAULT_TABLE_CONFIG mirror the
+ * design doc's table.
+ */
+import type { SharedS3Config } from '../s3-client.js';
+/**
+ * Per-table archival tuning parameters.
+ *
+ * A table's effective config is the global default, overridden by any
+ * values from the YAML/env config, overridden by any per-org values
+ * (Platform only) from `cold_store_org_overrides`.
+ */
+export interface ColdStoreTableConfig {
+    /** Minimum age (in days) before a row is eligible to archive. */
+    warmTtlDays: number;
+    /**
+     * Floor for total warm bytes per tenant per table. Below this, no
+     * archival happens — even if rows are old. Prevents thrashing on
+     * low-traffic tenants.
+     */
+    minWarmTenantBytes: number;
+    /** Floor for chunk size. Smaller eligible sets are deferred. */
+    minChunkBytes: number;
+    /** Ceiling for chunk size. Larger eligible sets are split. */
+    maxChunkBytes: number;
+    /** Hard cap on rows archived per (table, tenant) per cycle. */
+    maxRowsPerCycle: number;
+    /** Whether the table's archival is enabled (kill switch). */
+    enabled: boolean;
+}
+/**
+ * Reasonable defaults — matches the design doc's section 5 table.
+ * Concrete adapters can override any subset of these.
+ */
+export declare const DEFAULT_TABLE_CONFIG: ColdStoreTableConfig;
+/**
+ * Top-level cold-store configuration passed to `BaseColdStore`.
+ */
+export interface ColdStoreConfig {
+    /**
+     * S3-compatible storage config. The `prefix` defaults to
+     * `'cold-store/'` when unset.
+     */
+    storage: SharedS3Config;
+    /**
+     * Per-table overrides keyed by table name; unset tables use
+     * DEFAULT_TABLE_CONFIG.
+     */
+    tables: Record<string, Partial<ColdStoreTableConfig>>;
+    /** Global concurrency cap on in-flight S3 PUTs. Default 4. */
+    s3Concurrency: number;
+    /** Master feature toggle; when false, cycles no-op fast. */
+    enabled: boolean;
+}
+/**
+ * Merge DEFAULT_TABLE_CONFIG with overrides to produce the effective
+ * per-table config.
+ */
+export declare function resolveTableConfig(overrides: Partial<ColdStoreTableConfig> | undefined): ColdStoreTableConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/cold-store/config.js

@@ -0,0 +1,28 @@
+import "../chunk-gOLHoazu.js";
+//#region src/cold-store/config.ts
+/**
+* Reasonable defaults — matches the design doc's section 5 table.
+* Concrete adapters can override any subset of these.
+*/
+const DEFAULT_TABLE_CONFIG = {
+	warmTtlDays: 30,
+	minWarmTenantBytes: 5 * 1024 * 1024,
+	minChunkBytes: 1 * 1024 * 1024,
+	maxChunkBytes: 50 * 1024 * 1024,
+	maxRowsPerCycle: 5e4,
+	enabled: true
+};
+/**
+* Merge DEFAULT_TABLE_CONFIG with overrides to produce the effective
+* per-table config.
+*/
+function resolveTableConfig(overrides) {
+	return {
+		...DEFAULT_TABLE_CONFIG,
+		...overrides ?? {}
+	};
+}
+//#endregion
+export { DEFAULT_TABLE_CONFIG, resolveTableConfig };
+
+//# sourceMappingURL=config.js.map

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

@@ -0,0 +1,20 @@
+/**
+ * Cold-store framework — public surface for @kici-dev/shared consumers.
+ *
+ * Multiple implementations extend `BaseColdStore` with their own
+ * DB-specific adapters. Phase A ships framework types + the abstract
+ * class with a no-op archive cycle; Phase B+ adds concrete
+ * `TableAdapter` implementations.
+ */
+export { chunkObjectKey, encodeKeySegment, tablePrefix, tenantDayBucketPrefix, tenantDayPrefix, type DbKind, } from './key.js';
+export { COLD_BUCKET_NAMES, coldDaysToBucket, isLongerColdRetention, type ColdBucketName, } from './bucket.js';
+export { BaseColdStore, type BaseColdStoreDeps, type ColdStore, type ColdStoreFetchRangeArgs, type ColdStoreReplayChunkArgs, type ColdStoreReplayResult, type ColdStoreReplayRowArgs, type PurgeableChunk, type PurgeChunkResult, type PurgeExpiredChunksOpts, type PurgeExpiredChunksSummary, } from './cold-store.js';
+export { ChunkLru, type ChunkLruOptions } from './lru.js';
+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 { 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

@@ -0,0 +1,11 @@
+import "../chunk-gOLHoazu.js";
+import { chunkObjectKey, encodeKeySegment, tablePrefix, tenantDayBucketPrefix, tenantDayPrefix } from "./key.js";
+import { COLD_BUCKET_NAMES, 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 { BaseColdStore } from "./cold-store.js";
+import { ChunkLru } from "./lru.js";
+import { DEFAULT_TABLE_CONFIG, resolveTableConfig } from "./config.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 };

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

@@ -0,0 +1,89 @@
+/**
+ * Key helpers for S3 object layouts.
+ *
+ * `encodeKeySegment` escapes non-safe characters in a single path segment
+ * so that values coming from user-controlled sources (delivery IDs,
+ * routing keys, org IDs, partition values) can be embedded in an object
+ * key without breaking the key structure.
+ *
+ * This function was originally defined in
+ * packages/orchestrator/src/webhook/event-log.ts and is now shared with
+ * the cold-store framework. The encoding algorithm MUST NOT change —
+ * previously-written chunk and event-log keys depend on this mapping
+ * remaining stable forever. A fixture test in key.test.ts locks the
+ * behavior.
+ */
+/**
+ * Encode a single S3 path segment: anything outside `[A-Za-z0-9._:-]`
+ * becomes `_<hex>` where `<hex>` is the lowercase UTF-16 code unit of
+ * the replaced character (same as `ch.charCodeAt(0).toString(16)`).
+ */
+export declare function encodeKeySegment(s: string): string;
+/**
+ * DB identifier for cold-store chunk keys.
+ */
+export type DbKind = 'platform' | 'orchestrator';
+/**
+ * Compose the prefix for a specific table's cold-store objects.
+ *
+ * Layout: `<prefix>/<db>/<table>`.
+ */
+export declare function tablePrefix(args: {
+    prefix: string;
+    db: DbKind;
+    table: string;
+}): string;
+/**
+ * Compose the prefix for a specific tenant's day-partitioned objects.
+ *
+ * Layout: `<prefix>/<db>/<table>/<tenantId>/<YYYY>/<MM>/<DD>`.
+ * `tenantId` is encoded via `encodeKeySegment`.
+ * `partitionDate` must be `YYYY-MM-DD` (no other format is accepted).
+ */
+export declare function tenantDayPrefix(args: {
+    prefix: string;
+    db: DbKind;
+    table: string;
+    tenantId: string;
+    partitionDate: string;
+}): string;
+/**
+ * Compose a tenant-day prefix that includes the cold-bucket segment
+ * introduced in Phase 2. Layout:
+ *
+ *   `<prefix>/<db>/<table>/<tenantId>/<YYYY>/<MM>/<DD>/<bucket>`
+ *
+ * Phase-1 (v1 manifest) chunks live at the day-prefix root and are
+ * addressed via `tenantDayPrefix` directly — those legacy chunks are
+ * treated as the `'forever'` bucket by `parseManifest` but DO NOT carry
+ * a `forever` segment in their key (the chunk-purge sweep keys off the
+ * manifest's `bucket` / `maxColdDays`, not the path).
+ */
+export declare function tenantDayBucketPrefix(args: {
+    prefix: string;
+    db: DbKind;
+    table: string;
+    tenantId: string;
+    partitionDate: string;
+    bucket: string;
+}): string;
+/**
+ * Compose a full object key for a cold-store chunk or its manifest.
+ *
+ * - V1 (no `bucket` arg): `<tenant-day-prefix>/<chunkId>.<ext>` — original
+ *   layout, preserved for read-back compatibility with V1 chunks.
+ * - V2 (with `bucket`): `<tenant-day-prefix>/<bucket>/<chunkId>.<ext>` —
+ *   the GC sweep can list a single bucket subprefix to find purge
+ *   candidates without scanning the whole day.
+ */
+export declare function chunkObjectKey(args: {
+    prefix: string;
+    db: DbKind;
+    table: string;
+    tenantId: string;
+    partitionDate: string;
+    chunkId: string;
+    kind: 'data' | 'manifest';
+    bucket?: string;
+}): string;
+//# sourceMappingURL=key.d.ts.map

package/dist/cold-store/key.js

@@ -0,0 +1,88 @@
+import "../chunk-gOLHoazu.js";
+//#region src/cold-store/key.ts
+/**
+* Key helpers for S3 object layouts.
+*
+* `encodeKeySegment` escapes non-safe characters in a single path segment
+* so that values coming from user-controlled sources (delivery IDs,
+* routing keys, org IDs, partition values) can be embedded in an object
+* key without breaking the key structure.
+*
+* This function was originally defined in
+* packages/orchestrator/src/webhook/event-log.ts and is now shared with
+* the cold-store framework. The encoding algorithm MUST NOT change —
+* previously-written chunk and event-log keys depend on this mapping
+* remaining stable forever. A fixture test in key.test.ts locks the
+* behavior.
+*/
+/**
+* Encode a single S3 path segment: anything outside `[A-Za-z0-9._:-]`
+* becomes `_<hex>` where `<hex>` is the lowercase UTF-16 code unit of
+* the replaced character (same as `ch.charCodeAt(0).toString(16)`).
+*/
+function encodeKeySegment(s) {
+	return s.replace(/[^A-Za-z0-9._:-]/g, (ch) => `_${ch.charCodeAt(0).toString(16)}`);
+}
+/**
+* Compose the prefix for a specific table's cold-store objects.
+*
+* Layout: `<prefix>/<db>/<table>`.
+*/
+function tablePrefix(args) {
+	return `${args.prefix.replace(/\/+$/, "")}/${args.db}/${args.table}`;
+}
+/**
+* Compose the prefix for a specific tenant's day-partitioned objects.
+*
+* Layout: `<prefix>/<db>/<table>/<tenantId>/<YYYY>/<MM>/<DD>`.
+* `tenantId` is encoded via `encodeKeySegment`.
+* `partitionDate` must be `YYYY-MM-DD` (no other format is accepted).
+*/
+function tenantDayPrefix(args) {
+	if (!/^\d{4}-\d{2}-\d{2}$/.test(args.partitionDate)) throw new Error(`partitionDate must be YYYY-MM-DD, got ${JSON.stringify(args.partitionDate)}`);
+	const [yyyy, mm, dd] = args.partitionDate.split("-");
+	const encodedTenant = encodeKeySegment(args.tenantId);
+	return `${tablePrefix(args)}/${encodedTenant}/${yyyy}/${mm}/${dd}`;
+}
+/**
+* Allowed bucket-segment shape: lowercase letters, digits, the literal
+* `forever`, e.g. `30d` / `180d` / `1y` / `2y` / `forever`. Validated to
+* keep the S3 path safe (no `/`, no `.`, no path traversal).
+*/
+const BUCKET_SEGMENT_RE = /^[a-z0-9]+$/;
+/**
+* Compose a tenant-day prefix that includes the cold-bucket segment
+* introduced in Phase 2. Layout:
+*
+*   `<prefix>/<db>/<table>/<tenantId>/<YYYY>/<MM>/<DD>/<bucket>`
+*
+* Phase-1 (v1 manifest) chunks live at the day-prefix root and are
+* addressed via `tenantDayPrefix` directly — those legacy chunks are
+* treated as the `'forever'` bucket by `parseManifest` but DO NOT carry
+* a `forever` segment in their key (the chunk-purge sweep keys off the
+* manifest's `bucket` / `maxColdDays`, not the path).
+*/
+function tenantDayBucketPrefix(args) {
+	if (!BUCKET_SEGMENT_RE.test(args.bucket)) throw new Error(`bucket must match ${BUCKET_SEGMENT_RE.source}, got ${JSON.stringify(args.bucket)}`);
+	return `${tenantDayPrefix(args)}/${args.bucket}`;
+}
+/**
+* Compose a full object key for a cold-store chunk or its manifest.
+*
+* - V1 (no `bucket` arg): `<tenant-day-prefix>/<chunkId>.<ext>` — original
+*   layout, preserved for read-back compatibility with V1 chunks.
+* - V2 (with `bucket`): `<tenant-day-prefix>/<bucket>/<chunkId>.<ext>` —
+*   the GC sweep can list a single bucket subprefix to find purge
+*   candidates without scanning the whole day.
+*/
+function chunkObjectKey(args) {
+	const suffix = args.kind === "data" ? ".jsonl.gz" : ".manifest.json";
+	return `${args.bucket ? tenantDayBucketPrefix({
+		...args,
+		bucket: args.bucket
+	}) : tenantDayPrefix(args)}/${args.chunkId}${suffix}`;
+}
+//#endregion
+export { chunkObjectKey, encodeKeySegment, tablePrefix, tenantDayBucketPrefix, tenantDayPrefix };
+
+//# sourceMappingURL=key.js.map

package/dist/cold-store/key.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=key.test.d.ts.map

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

@@ -0,0 +1,33 @@
+/**
+ * In-process size-bounded LRU cache.
+ *
+ * Used by the cold-store rehydrate path (Phase B+) to keep recently-read
+ * chunks hot in memory, so that e.g. a user paginating a 90-day audit
+ * window doesn't re-fetch the same S3 chunks for each page. Phase A
+ * ships the primitive so Phase B's first consumer gets a debugged
+ * LRU rather than having to write one.
+ *
+ * Size is tracked in bytes via a caller-supplied `sizeOf` function.
+ * Eviction happens on `set()` when the accumulated byte count exceeds
+ * `maxBytes`.
+ */
+export interface ChunkLruOptions<V> {
+    maxBytes: number;
+    sizeOf: (value: V) => number;
+    onEvict?: (key: unknown, value: V) => void;
+}
+export declare class ChunkLru<K, V> {
+    private readonly maxBytes;
+    private readonly sizeOf;
+    private readonly onEvict?;
+    private readonly map;
+    private readonly sizes;
+    private totalBytes;
+    constructor(opts: ChunkLruOptions<V>);
+    get bytes(): number;
+    get entries(): number;
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    clear(): void;
+}
+//# sourceMappingURL=lru.d.ts.map

package/dist/cold-store/lru.js

@@ -0,0 +1,59 @@
+import "../chunk-gOLHoazu.js";
+//#region src/cold-store/lru.ts
+var ChunkLru = class {
+	maxBytes;
+	sizeOf;
+	onEvict;
+	map = /* @__PURE__ */ new Map();
+	sizes = /* @__PURE__ */ new Map();
+	totalBytes = 0;
+	constructor(opts) {
+		this.maxBytes = opts.maxBytes;
+		this.sizeOf = opts.sizeOf;
+		this.onEvict = opts.onEvict;
+	}
+	get bytes() {
+		return this.totalBytes;
+	}
+	get entries() {
+		return this.map.size;
+	}
+	get(key) {
+		const v = this.map.get(key);
+		if (v === void 0) return void 0;
+		this.map.delete(key);
+		this.map.set(key, v);
+		return v;
+	}
+	set(key, value) {
+		if (this.map.has(key)) {
+			const prevSize = this.sizes.get(key) ?? 0;
+			this.totalBytes -= prevSize;
+			this.map.delete(key);
+			this.sizes.delete(key);
+		}
+		const size = this.sizeOf(value);
+		this.map.set(key, value);
+		this.sizes.set(key, size);
+		this.totalBytes += size;
+		while (this.totalBytes > this.maxBytes && this.map.size > 0) {
+			const firstKey = this.map.keys().next().value;
+			const evicted = this.map.get(firstKey);
+			const evictedSize = this.sizes.get(firstKey) ?? 0;
+			this.map.delete(firstKey);
+			this.sizes.delete(firstKey);
+			this.totalBytes -= evictedSize;
+			this.onEvict?.(firstKey, evicted);
+		}
+	}
+	clear() {
+		if (this.onEvict) for (const [key, value] of this.map.entries()) this.onEvict(key, value);
+		this.map.clear();
+		this.sizes.clear();
+		this.totalBytes = 0;
+	}
+};
+//#endregion
+export { ChunkLru };
+
+//# sourceMappingURL=lru.js.map

package/dist/cold-store/lru.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=lru.test.d.ts.map

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

@@ -0,0 +1,11 @@
+/**
+ * Manifest serialization / parsing.
+ *
+ * Manifests are small JSON sidecar files next to each `.jsonl.gz`
+ * chunk. Serialized with stable key ordering so byte-diffs across
+ * archive runs are meaningful.
+ */
+import type { ChunkManifest } from './types.js';
+export declare function serializeManifest(m: ChunkManifest): string;
+export declare function parseManifest(raw: string | Buffer): ChunkManifest;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/cold-store/manifest.js

@@ -0,0 +1,57 @@
+import "../chunk-gOLHoazu.js";
+//#region src/cold-store/manifest.ts
+/**
+* Required fields shared by v1 and v2 manifests. Order is the on-disk
+* key order — keep stable so byte-diffs across archive runs remain
+* meaningful.
+*/
+const COMMON_REQUIRED_KEYS = [
+	"schemaVersion",
+	"db",
+	"table",
+	"tenantId",
+	"partitionDate",
+	"rowCount",
+	"byteCount",
+	"gzipByteCount",
+	"minTimestamp",
+	"maxTimestamp",
+	"minRowId",
+	"maxRowId",
+	"contentHash",
+	"chunkId",
+	"createdAt",
+	"archiverInstanceId"
+];
+/** v2-only required fields — always emitted by `serializeManifest`. */
+const V2_REQUIRED_KEYS = ["bucket", "maxColdDays"];
+const OPTIONAL_MANIFEST_KEYS = ["replayLookupKeys"];
+function serializeManifest(m) {
+	const ordered = {};
+	for (const k of COMMON_REQUIRED_KEYS) ordered[k] = m[k];
+	if (m.schemaVersion === 2) for (const k of V2_REQUIRED_KEYS) {
+		if (m[k] === void 0) throw new Error(`serializeManifest: schemaVersion=2 requires field "${k}"`);
+		ordered[k] = m[k];
+	}
+	for (const k of OPTIONAL_MANIFEST_KEYS) if (m[k] !== void 0) ordered[k] = m[k];
+	return JSON.stringify(ordered, null, 2);
+}
+function parseManifest(raw) {
+	const text = typeof raw === "string" ? raw : raw.toString("utf-8");
+	const parsed = JSON.parse(text);
+	if (!parsed || typeof parsed !== "object") throw new Error("parseManifest: not a JSON object");
+	const obj = parsed;
+	if (obj.schemaVersion !== 1 && obj.schemaVersion !== 2) throw new Error(`parseManifest: unsupported schemaVersion ${String(obj.schemaVersion)}`);
+	for (const k of COMMON_REQUIRED_KEYS) if (!(k in obj)) throw new Error(`parseManifest: missing field ${k}`);
+	if (obj.schemaVersion === 2) {
+		for (const k of V2_REQUIRED_KEYS) if (!(k in obj)) throw new Error(`parseManifest: schemaVersion=2 missing field ${k}`);
+	} else {
+		if (obj.bucket === void 0) obj.bucket = "forever";
+		if (obj.maxColdDays === void 0) obj.maxColdDays = "forever";
+	}
+	return obj;
+}
+//#endregion
+export { parseManifest, serializeManifest };
+
+//# sourceMappingURL=manifest.js.map

package/dist/cold-store/manifest.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=manifest.test.d.ts.map

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

@@ -0,0 +1,103 @@
+/**
+ * Cold-store domain metrics.
+ *
+ * These are the "how much data moved through cold-store" metrics;
+ * complements (but does not overlap with) the scheduler-layer
+ * metrics (`kici_{platform,orch}_job_*`) owned by the scheduled-job
+ * wrappers.
+ *
+ * `cold_store_archive_cycles_total` is always-non-zero — incremented
+ * on every `runArchiveCycle()` call with a `result` label — so the
+ * meter scope + instrument metadata always surface on /metrics.
+ * This is the counterpart to the design doc's original "zero-add
+ * trick": `@opentelemetry/exporter-prometheus` 0.213.0 filters out
+ * counters whose only observations are `.add(0)`, so we need a
+ * guaranteed-non-zero counter to keep the series visible.
+ *
+ * `cold_store_archive_rows_total` stays dormant (hidden) until a
+ * Phase B+ `TableAdapter` actually archives rows — at which point
+ * its samples appear naturally.
+ *
+ * Lazy meter initialization: the `@kici-dev/shared` barrel is imported
+ * statically at the top of service entry points (server.ts, worker.ts),
+ * which evaluates this module BEFORE `initTelemetry()` sets the global
+ * MeterProvider. If we call `createMeter('kici-cold-store')` at module
+ * load time, the returned ProxyMeter binds to the no-op provider and
+ * its instruments never reach the Prometheus exporter. Resolving the
+ * meter + instruments on first access (inside `getCold...()` getters)
+ * guarantees we resolve AFTER telemetry is wired up.
+ */
+import type { Counter, Histogram } from '@opentelemetry/api';
+/**
+ * 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`.
+ */
+export declare function coldStoreArchiveCyclesTotal(): Counter;
+/**
+ * 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.
+ */
+export declare function coldStoreArchiveRowsTotal(): Counter;
+/**
+ * Total bytes archived, by kind ∈ raw | gzipped. Lets us compute the
+ * ongoing compression ratio.
+ */
+export declare function coldStoreArchiveBytesTotal(): Counter;
+/**
+ * Per-chunk archive duration histogram.
+ * Buckets: 10ms, 100ms, 500ms, 1s, 5s, 30s, 120s.
+ */
+export declare function coldStoreArchiveDurationSeconds(): Histogram;
+/**
+ * Rehydrate requests (cache hit vs miss). Incremented by the
+ * read-through layer (Phase B+) when it serves a range query from
+ * cold storage.
+ */
+export declare function coldStoreRehydrateRequestsTotal(): Counter;
+/** Bytes read from S3 on rehydrate cache miss. */
+export declare function coldStoreRehydrateBytesTotal(): Counter;
+/** Rehydrate duration (S3 fetch + decode), seconds. */
+export declare function coldStoreRehydrateDurationSeconds(): Histogram;
+/**
+ * Verify-failure counter — bumped on the rare `contentHash` mismatch
+ * path during post-write verification.
+ */
+export declare function coldStoreVerifyFailuresTotal(): Counter;
+/**
+ * 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`.
+ */
+export declare function coldStoreReplayRowsTotal(): Counter;
+/**
+ * Phase F — replay duration (S3 GET + manifest scan + decode + INSERT),
+ * seconds. Buckets mirror archive duration: 10ms, 100ms, 500ms, 1s, 5s,
+ * 30s, 120s.
+ */
+export declare function coldStoreReplayDurationSeconds(): Histogram;
+/**
+ * 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.
+ */
+export declare function coldStorePurgeChunksTotal(): Counter;
+/** Phase 2 — gzipped bytes deleted from S3 by the purge sweep. */
+export declare function coldStorePurgeBytesTotal(): Counter;
+/**
+ * Phase 2 — purge duration per sweep, seconds. Buckets mirror the
+ * archive duration histogram: 10ms, 100ms, 500ms, 1s, 5s, 30s, 120s.
+ */
+export declare function coldStorePurgeDurationSeconds(): Histogram;
+//# sourceMappingURL=metrics.d.ts.map