@graphorin/observability 0.5.0

package/dist/redaction/patterns.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"patterns.js","names":["PATTERNS: readonly RedactionPattern[]","BUILT_IN_PATTERNS: readonly RedactionPattern[]","OPT_IN_PATTERNS: readonly RedactionPattern[]","ALL_BUILT_IN_PATTERNS: readonly RedactionPattern[]"],"sources":["../../src/redaction/patterns.ts"],"sourcesContent":["/**\n * Built-in PII / secret detection patterns. The catalogue is intentionally\n * conservative — every pattern has both positive and negative test\n * fixtures and is documented so operators understand exactly what is\n * matched.\n *\n * The catalogue is split into two groups:\n *\n * - **secret** — credentials, API tokens, JWTs, private keys. Matches\n *   are always dropped + counted, regardless of the configured tier\n *   floor.\n * - **pii** — email / phone / IBAN / credit card / SSN / IP address.\n *   Subject to the configured tier floor + per-pattern enable / disable\n *   knobs.\n *\n * @packageDocumentation\n */\n\n/**\n * Stable pattern identifier. The catalogue is curated; user-supplied\n * patterns can use any identifier they want and will be passed through\n * the validator in addition to the built-ins.\n *\n * @stable\n */\nexport type BuiltInPatternName =\n  | 'graphorin-token'\n  | 'openai-key'\n  | 'anthropic-key'\n  | 'aws-access-key'\n  | 'gcp-service-account'\n  | 'github-pat'\n  | 'jwt'\n  | 'bearer-header'\n  | 'basic-auth'\n  | 'private-key-pem'\n  | 'email'\n  | 'creditcard'\n  | 'us-ssn'\n  | 'phone-e164'\n  | 'iban'\n  | 'ipv4'\n  | 'ipv6';\n\n/**\n * Pattern category — `secret` matches always force a drop; `pii`\n * matches respect the configured `enabledPatterns` allow-list.\n *\n * @stable\n */\nexport type PatternCategory = 'secret' | 'pii';\n\n/**\n * One entry in the redaction catalogue.\n *\n * @stable\n */\nexport interface RedactionPattern {\n  readonly name: string;\n  readonly category: PatternCategory;\n  readonly description: string;\n  readonly regex: RegExp;\n  /** Replacement string used when `mode === 'mask'`. */\n  readonly mask?: string;\n  /**\n   * Optional per-match predicate (RP-21). When present, a regex hit is only\n   * treated as a real match — and masked — when this returns `true` for the\n   * matched substring. Used by the `creditcard` pattern to require a valid\n   * Luhn checksum so look-alike digit runs (epoch-ms timestamps, order ids)\n   * are not corrupted.\n   */\n  readonly verify?: (match: string) => boolean;\n  /**\n   * Optional opt-in flag. When `true` the pattern is **not** active by\n   * default; operators must add it to `enabledPatterns` explicitly. Used\n   * by the IPv4 / IPv6 patterns because raw IPs frequently appear in\n   * non-PII log lines (host headers, debug traces, …).\n   */\n  readonly optIn?: boolean;\n}\n\nconst PATTERNS: readonly RedactionPattern[] = [\n  {\n    name: 'graphorin-token',\n    category: 'secret',\n    description: 'Graphorin server token (`kru_<env>_v1_<entropy>_<crc32>`).',\n    regex: /kru_(?:dev|test|prod)_v1_[A-Za-z0-9]{20,80}_[A-Za-z0-9]{6}/g,\n    mask: '[REDACTED graphorin-token]',\n  },\n  {\n    name: 'openai-key',\n    category: 'secret',\n    description: 'OpenAI API key (`sk-...`).',\n    regex: /\\bsk-[A-Za-z0-9_-]{20,}\\b/g,\n    mask: '[REDACTED openai-key]',\n  },\n  {\n    name: 'anthropic-key',\n    category: 'secret',\n    description: 'Anthropic API key (`sk-ant-...`).',\n    regex: /\\bsk-ant-[A-Za-z0-9_-]{20,}\\b/g,\n    mask: '[REDACTED anthropic-key]',\n  },\n  {\n    name: 'aws-access-key',\n    category: 'secret',\n    description: 'AWS access-key id (`AKIA...`).',\n    regex: /\\b(?:AKIA|ASIA)[0-9A-Z]{16}\\b/g,\n    mask: '[REDACTED aws-access-key]',\n  },\n  {\n    name: 'gcp-service-account',\n    category: 'secret',\n    description:\n      'GCP service-account email (`...@...iam.gserviceaccount.com`). Opt-in; the `email` pattern already redacts the address shape; this entry exists for operators wanting the explicit `gcp-service-account` counter label.',\n    regex: /[A-Za-z0-9._-]+@[A-Za-z0-9-]+\\.iam\\.gserviceaccount\\.com\\b/g,\n    mask: '[REDACTED gcp-service-account]',\n    optIn: true,\n  },\n  {\n    name: 'github-pat',\n    category: 'secret',\n    description: 'GitHub personal-access token / OAuth token / app token.',\n    regex: /\\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36,255}\\b/g,\n    mask: '[REDACTED github-pat]',\n  },\n  {\n    name: 'jwt',\n    category: 'secret',\n    description: 'JSON Web Token (`eyJ...`).',\n    regex: /\\beyJ[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\b/g,\n    mask: '[REDACTED jwt]',\n  },\n  {\n    name: 'bearer-header',\n    category: 'secret',\n    description: '`Authorization: Bearer ...` header values.',\n    regex: /\\bBearer\\s+[A-Za-z0-9._-]{16,}\\b/gi,\n    mask: 'Bearer [REDACTED]',\n  },\n  {\n    name: 'basic-auth',\n    category: 'secret',\n    description: '`Authorization: Basic ...` header values.',\n    regex: /\\bBasic\\s+[A-Za-z0-9+/=]{16,}\\b/gi,\n    mask: 'Basic [REDACTED]',\n  },\n  {\n    name: 'private-key-pem',\n    category: 'secret',\n    description: 'PEM private-key block (`-----BEGIN ... PRIVATE KEY-----`).',\n    regex: /-----BEGIN [A-Z ]*PRIVATE KEY-----[\\s\\S]+?-----END [A-Z ]*PRIVATE KEY-----/g,\n    mask: '[REDACTED private-key-pem]',\n  },\n  {\n    name: 'email',\n    category: 'pii',\n    description: 'RFC-5322-ish email address.',\n    regex: /\\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}\\b/g,\n    mask: '[REDACTED email]',\n  },\n  {\n    name: 'creditcard',\n    category: 'pii',\n    description: 'Credit card number (13–19 digits, optional spaces / dashes; Luhn-checked).',\n    regex: /\\b(?:\\d[\\s-]*?){13,19}\\b/g,\n    mask: '[REDACTED creditcard]',\n    // RP-21: require a valid Luhn checksum so a 13–19 digit run that is not a\n    // real PAN (millisecond epoch timestamps, order numbers, …) is left alone.\n    verify: isLuhnValid,\n  },\n  {\n    name: 'us-ssn',\n    category: 'pii',\n    description: 'US Social Security Number (`123-45-6789`).',\n    regex: /\\b\\d{3}-\\d{2}-\\d{4}\\b/g,\n    mask: '[REDACTED us-ssn]',\n  },\n  {\n    name: 'phone-e164',\n    category: 'pii',\n    description: 'E.164 phone number (`+11234567890`).',\n    regex: /\\+\\d{7,15}\\b/g,\n    mask: '[REDACTED phone-e164]',\n  },\n  {\n    name: 'iban',\n    category: 'pii',\n    description: 'IBAN (2-letter country + 2 check digits + up to 30 alphanumerics).',\n    regex: /\\b[A-Z]{2}\\d{2}[A-Z0-9]{11,30}\\b/g,\n    mask: '[REDACTED iban]',\n  },\n  {\n    name: 'ipv4',\n    category: 'pii',\n    description: 'IPv4 dotted-quad address. Opt-in (often appears legitimately in logs).',\n    regex: /\\b(?:\\d{1,3}\\.){3}\\d{1,3}\\b/g,\n    mask: '[REDACTED ipv4]',\n    optIn: true,\n  },\n  {\n    name: 'ipv6',\n    category: 'pii',\n    description: 'IPv6 address (full / compressed). Opt-in.',\n    regex: /\\b(?:[0-9a-fA-F]{1,4}:){2,7}[0-9a-fA-F]{1,4}\\b/g,\n    mask: '[REDACTED ipv6]',\n    optIn: true,\n  },\n];\n\n/**\n * The 14 default-on built-in patterns (the IPv4 and IPv6 detectors are\n * opt-in and live in {@link OPT_IN_PATTERNS}).\n *\n * @stable\n */\nexport const BUILT_IN_PATTERNS: readonly RedactionPattern[] = PATTERNS.filter(\n  (p) => p.optIn !== true,\n);\n\n/**\n * Patterns that are recognised by the validator but are NOT enabled by\n * default. Use them via `patterns: [...BUILT_IN_PATTERNS, ...OPT_IN_PATTERNS]`.\n *\n * @stable\n */\nexport const OPT_IN_PATTERNS: readonly RedactionPattern[] = PATTERNS.filter(\n  (p) => p.optIn === true,\n);\n\n/**\n * Full registry — for tooling that wants to introspect every pattern\n * the framework knows about (e.g. CLI `graphorin redaction list`).\n *\n * @stable\n */\nexport const ALL_BUILT_IN_PATTERNS: readonly RedactionPattern[] = PATTERNS;\n\n/**\n * Luhn (mod-10) checksum validator used by the `creditcard` pattern (RP-21).\n * Strips spaces / dashes, bounds the length to 13–19 digits, and verifies the\n * checksum so a digit run that merely *looks* like a PAN is not redacted.\n */\nfunction isLuhnValid(value: string): boolean {\n  const digits = value.replace(/\\D/g, '');\n  if (digits.length < 13 || digits.length > 19) return false;\n  let sum = 0;\n  let double = false;\n  for (let i = digits.length - 1; i >= 0; i -= 1) {\n    let d = digits.charCodeAt(i) - 48; // '0'\n    if (double) {\n      d *= 2;\n      if (d > 9) d -= 9;\n    }\n    sum += d;\n    double = !double;\n  }\n  return sum % 10 === 0;\n}\n"],"mappings":";AAiFA,MAAMA,WAAwC;CAC5C;EACE,MAAM;EACN,UAAU;EACV,aAAa;EACb,OAAO;EACP,MAAM;EACP;CACD;EACE,MAAM;EACN,UAAU;EACV,aAAa;EACb,OAAO;EACP,MAAM;EACP;CACD;EACE,MAAM;EACN,UAAU;EACV,aAAa;EACb,OAAO;EACP,MAAM;EACP;CACD;EACE,MAAM;EACN,UAAU;EACV,aAAa;EACb,OAAO;EACP,MAAM;EACP;CACD;EACE,MAAM;EACN,UAAU;EACV,aACE;EACF,OAAO;EACP,MAAM;EACN,OAAO;EACR;CACD;EACE,MAAM;EACN,UAAU;EACV,aAAa;EACb,OAAO;EACP,MAAM;EACP;CACD;EACE,MAAM;EACN,UAAU;EACV,aAAa;EACb,OAAO;EACP,MAAM;EACP;CACD;EACE,MAAM;EACN,UAAU;EACV,aAAa;EACb,OAAO;EACP,MAAM;EACP;CACD;EACE,MAAM;EACN,UAAU;EACV,aAAa;EACb,OAAO;EACP,MAAM;EACP;CACD;EACE,MAAM;EACN,UAAU;EACV,aAAa;EACb,OAAO;EACP,MAAM;EACP;CACD;EACE,MAAM;EACN,UAAU;EACV,aAAa;EACb,OAAO;EACP,MAAM;EACP;CACD;EACE,MAAM;EACN,UAAU;EACV,aAAa;EACb,OAAO;EACP,MAAM;EAGN,QAAQ;EACT;CACD;EACE,MAAM;EACN,UAAU;EACV,aAAa;EACb,OAAO;EACP,MAAM;EACP;CACD;EACE,MAAM;EACN,UAAU;EACV,aAAa;EACb,OAAO;EACP,MAAM;EACP;CACD;EACE,MAAM;EACN,UAAU;EACV,aAAa;EACb,OAAO;EACP,MAAM;EACP;CACD;EACE,MAAM;EACN,UAAU;EACV,aAAa;EACb,OAAO;EACP,MAAM;EACN,OAAO;EACR;CACD;EACE,MAAM;EACN,UAAU;EACV,aAAa;EACb,OAAO;EACP,MAAM;EACN,OAAO;EACR;CACF;;;;;;;AAQD,MAAaC,oBAAiD,SAAS,QACpE,MAAM,EAAE,UAAU,KACpB;;;;;;;AAQD,MAAaC,kBAA+C,SAAS,QAClE,MAAM,EAAE,UAAU,KACpB;;;;;;;AAQD,MAAaC,wBAAqD;;;;;;AAOlE,SAAS,YAAY,OAAwB;CAC3C,MAAM,SAAS,MAAM,QAAQ,OAAO,GAAG;AACvC,KAAI,OAAO,SAAS,MAAM,OAAO,SAAS,GAAI,QAAO;CACrD,IAAI,MAAM;CACV,IAAI,SAAS;AACb,MAAK,IAAI,IAAI,OAAO,SAAS,GAAG,KAAK,GAAG,KAAK,GAAG;EAC9C,IAAI,IAAI,OAAO,WAAW,EAAE,GAAG;AAC/B,MAAI,QAAQ;AACV,QAAK;AACL,OAAI,IAAI,EAAG,MAAK;;AAElB,SAAO;AACP,WAAS,CAAC;;AAEZ,QAAO,MAAM,OAAO"}

package/dist/redaction/types.d.ts

@@ -0,0 +1,103 @@
+import { RedactionPattern } from "./patterns.js";
+import { RedactionInput, RedactionInput as RedactionInput$1, RedactionOutput, RedactionOutput as RedactionOutput$1, RedactionValidator, RedactionValidator as RedactionValidator$1 } from "@graphorin/core";
+
+//#region src/redaction/types.d.ts
+
+/**
+ * Optional sink invoked every time the validator drops a value or
+ * masks a pattern. Useful for emitting custom metrics, audit entries,
+ * or alert hooks. The callback receives only sanitized data — secret
+ * values are never forwarded.
+ *
+ * @stable
+ */
+type RedactionViolationCallback = (violation: RedactionViolation) => void;
+/**
+ * Sanitized record describing a single redaction event. Never carries
+ * the secret value itself; only metadata that is safe to log.
+ *
+ * @stable
+ */
+interface RedactionViolation {
+  readonly reason: 'sensitivity-tier-exceeded' | 'pii-pattern-match' | 'secret-pattern-match' | 'unredacted-secret-value' | 'invalid-input';
+  readonly attribute?: string;
+  readonly spanType?: string;
+  readonly origin?: string;
+  /** Pattern names that fired (if applicable). */
+  readonly patterns?: ReadonlyArray<string>;
+  /** Tier declared by the upstream caller. */
+  readonly declaredTier?: RedactionInput['tier'];
+}
+/**
+ * Counter exposed via {@link createRedactionValidator}. Implementations
+ * keep counters in-memory; downstream code can scrape them and convert
+ * to Prometheus metrics.
+ *
+ * @stable
+ */
+interface RedactionCounters {
+  /** Total values dropped by the validator. */
+  droppedTotal: number;
+  /** Drops by reason; the four built-in reasons + any custom ones. */
+  droppedByReason: Readonly<Record<string, number>>;
+  /** Pattern-matching counters keyed by pattern name. */
+  matchesByPattern: Readonly<Record<string, number>>;
+}
+/**
+ * Configuration shape for {@link createRedactionValidator}.
+ *
+ * @stable
+ */
+interface RedactionValidatorOptions {
+  /** Identifier reported via `validator.id`. Defaults to `'default'`. */
+  readonly id?: string;
+  /** Lowest tier that may pass through the validator. Default: `'public'`. */
+  readonly minTier?: RedactionInput['tier'];
+  /**
+   * When `true`, throw a {@link RedactionValidationError} on any drop.
+   * Useful in tests; production should keep this off so the validator
+   * silently drops + counts.
+   */
+  readonly failOnUnredactedSensitive?: boolean;
+  /**
+   * Pattern catalogue. Defaults to the 14 built-in default-on
+   * patterns. Custom patterns can extend or replace this list.
+   */
+  readonly patterns?: ReadonlyArray<RedactionPattern>;
+  /**
+   * Per-name allow-list. When provided, only patterns whose `name`
+   * appears here are evaluated. Empty array disables all pattern
+   * matching (tier filtering still applies).
+   */
+  readonly enabledPatterns?: ReadonlyArray<string>;
+  /**
+   * Per-name deny-list. Patterns listed here are skipped entirely.
+   * Applied **after** `enabledPatterns`.
+   */
+  readonly disabledPatterns?: ReadonlyArray<string>;
+  /**
+   * Optional sink invoked on every violation. Receives only sanitized
+   * data; never receives secret values.
+   */
+  readonly onViolation?: RedactionViolationCallback;
+  /**
+   * Optional pluggable additional check, fired after the pattern
+   * scan succeeds. The callback returns `null` to drop the value or a
+   * sanitized {@link RedactionOutput} to forward.
+   */
+  readonly customValidator?: (input: RedactionInput) => RedactionOutput | null;
+}
+/**
+ * Concrete validator returned by {@link createRedactionValidator}.
+ *
+ * @stable
+ */
+interface RedactionValidatorInstance extends RedactionValidator {
+  /** Snapshot of internal counters. Returned object is a fresh copy. */
+  readonly counters: () => RedactionCounters;
+  /** Reset all counters back to zero. */
+  readonly resetCounters: () => void;
+}
+//#endregion
+export { RedactionCounters, type RedactionInput$1 as RedactionInput, type RedactionOutput$1 as RedactionOutput, type RedactionValidator$1 as RedactionValidator, RedactionValidatorInstance, RedactionValidatorOptions, RedactionViolation, RedactionViolationCallback };
+//# sourceMappingURL=types.d.ts.map

package/dist/redaction/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../src/redaction/types.ts"],"sourcesContent":[],"mappings":";;;;;;;;;AAiEA;;;;AAqB6B,KAlEjB,0BAAA,GAkEiB,CAAA,SAAA,EAlEwB,kBAkExB,EAAA,GAAA,IAAA;;;;;;AAwB7B;UAlFiB,kBAAA;;;;;;sBAWK;;0BAEI;;;;;;;;;UAUT,iBAAA;;;;mBAIE,SAAS;;oBAER,SAAS;;;;;;;UAQZ,yBAAA;;;;qBAII;;;;;;;;;;;sBAWC,cAAc;;;;;;6BAMP;;;;;8BAKC;;;;;yBAKL;;;;;;qCAMY,mBAAmB;;;;;;;UAQvC,0BAAA,SAAmC;;2BAEzB"}

package/dist/redaction/validator.d.ts

@@ -0,0 +1,26 @@
+import { RedactionValidatorInstance, RedactionValidatorOptions } from "./types.js";
+import { Sensitivity } from "@graphorin/core";
+
+//#region src/redaction/validator.d.ts
+
+/**
+ * Create a {@link RedactionValidator} configured against the supplied
+ * options. The result implements both the `RedactionValidator`
+ * contract from `@graphorin/core` and the
+ * {@link RedactionValidatorInstance} extension surface (counters +
+ * reset).
+ *
+ * @stable
+ */
+declare function createRedactionValidator(opts?: RedactionValidatorOptions): RedactionValidatorInstance;
+/**
+ * Quickly compute the relative ordering of two sensitivity tiers.
+ * Exposed because the tracer + replay layers need it without taking a
+ * full dependency on the validator implementation.
+ *
+ * @stable
+ */
+declare function compareSensitivityTiers(a: Sensitivity, b: Sensitivity): number;
+//#endregion
+export { compareSensitivityTiers, createRedactionValidator };
+//# sourceMappingURL=validator.d.ts.map

package/dist/redaction/validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","names":[],"sources":["../../src/redaction/validator.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;iBA0KgB,wBAAA,QACR,4BACL;;;;;;;;iBA+Ha,uBAAA,IAA2B,gBAAgB"}

package/dist/redaction/validator.js

@@ -0,0 +1,195 @@
+import { RedactionValidationError } from "./errors.js";
+import { BUILT_IN_PATTERNS } from "./patterns.js";
+import { SENSITIVITY_ORDER } from "@graphorin/core";
+
+//#region src/redaction/validator.ts
+/**
+* `createRedactionValidator(...)` — the building block for the
+* mandatory `withValidation()` wrapper applied to every exporter.
+*
+* @packageDocumentation
+*/
+const TIER_INDEX = new Map(SENSITIVITY_ORDER.map((tier, idx) => [tier, idx]));
+function rank(tier) {
+	return TIER_INDEX.get(tier) ?? 0;
+}
+function makeCounters() {
+	return {
+		droppedTotal: 0,
+		droppedByReason: /* @__PURE__ */ new Map(),
+		matchesByPattern: /* @__PURE__ */ new Map()
+	};
+}
+function bump(map, key) {
+	map.set(key, (map.get(key) ?? 0) + 1);
+}
+function freezeCounters(c) {
+	return {
+		droppedTotal: c.droppedTotal,
+		droppedByReason: Object.freeze(Object.fromEntries(c.droppedByReason)),
+		matchesByPattern: Object.freeze(Object.fromEntries(c.matchesByPattern))
+	};
+}
+function selectPatterns(patterns, enabled, disabled) {
+	const enabledSet = enabled === void 0 ? null : new Set(enabled);
+	const disabledSet = new Set(disabled ?? []);
+	const out = [];
+	for (const p of patterns) {
+		if (enabledSet !== null && !enabledSet.has(p.name)) continue;
+		if (disabledSet.has(p.name)) continue;
+		out.push(p);
+	}
+	return out;
+}
+/**
+* Walk every string discovered in `value` and apply `fn`. Returns
+* `{ output, matched }` where `output` is the rewritten payload and
+* `matched` is the de-duplicated list of pattern names that fired.
+*
+* The walker handles strings, plain objects, and arrays. Other JS
+* primitives are passed through untouched. Cycles are detected via a
+* `WeakSet` and broken with `'[Circular]'`.
+*/
+function walk(value, fn, matched, seen) {
+	if (typeof value === "string") return fn(value, matched);
+	if (value === null || typeof value !== "object") return value;
+	if (seen.has(value)) return "[Circular]";
+	seen.add(value);
+	if (Array.isArray(value)) {
+		const out$1 = new Array(value.length);
+		for (let i = 0; i < value.length; i++) out$1[i] = walk(value[i], fn, matched, seen);
+		return out$1;
+	}
+	const obj = value;
+	const out = {};
+	for (const key of Object.keys(obj)) out[key] = walk(obj[key], fn, matched, seen);
+	return out;
+}
+/**
+* Apply every active pattern to `s`. Mutates `matched` with the names
+* that fired and returns the rewritten string.
+*/
+function applyPatterns(s, patterns, matched) {
+	let out = s;
+	for (const p of patterns) {
+		const mask = p.mask ?? `[REDACTED ${p.name}]`;
+		p.regex.lastIndex = 0;
+		if (p.verify === void 0) {
+			if (p.regex.test(out)) {
+				matched.add(p.name);
+				p.regex.lastIndex = 0;
+				out = out.replace(p.regex, mask);
+			}
+			continue;
+		}
+		const verify = p.verify;
+		p.regex.lastIndex = 0;
+		out = out.replace(p.regex, (m) => {
+			if (verify(m)) {
+				matched.add(p.name);
+				return mask;
+			}
+			return m;
+		});
+	}
+	return out;
+}
+function violationFor(reason, input, patterns) {
+	const baseContext = input.context;
+	return {
+		reason,
+		declaredTier: input.tier,
+		...baseContext?.attribute === void 0 ? {} : { attribute: baseContext.attribute },
+		...baseContext?.spanType === void 0 ? {} : { spanType: baseContext.spanType },
+		...baseContext?.origin === void 0 ? {} : { origin: baseContext.origin },
+		...patterns === void 0 || patterns.length === 0 ? {} : { patterns }
+	};
+}
+/**
+* Create a {@link RedactionValidator} configured against the supplied
+* options. The result implements both the `RedactionValidator`
+* contract from `@graphorin/core` and the
+* {@link RedactionValidatorInstance} extension surface (counters +
+* reset).
+*
+* @stable
+*/
+function createRedactionValidator(opts = {}) {
+	const id = opts.id ?? "default";
+	const minTier = opts.minTier ?? "public";
+	const failOnUnredacted = opts.failOnUnredactedSensitive === true;
+	const patterns = selectPatterns(opts.patterns ?? BUILT_IN_PATTERNS, opts.enabledPatterns, opts.disabledPatterns);
+	const onViolation = opts.onViolation;
+	const custom = opts.customValidator;
+	let counters = makeCounters();
+	function recordViolation(violation) {
+		counters.droppedTotal += 1;
+		bump(counters.droppedByReason, violation.reason);
+		for (const name of violation.patterns ?? []) bump(counters.matchesByPattern, name);
+		if (onViolation !== void 0) try {
+			onViolation(violation);
+		} catch {}
+	}
+	function dropOrThrow(_input, violation) {
+		recordViolation(violation);
+		if (failOnUnredacted) throw new RedactionValidationError(`RedactionValidator dropped value (${violation.reason}) — set failOnUnredactedSensitive: false in production to keep the pipeline running.`, violation);
+		return null;
+	}
+	return {
+		id,
+		minTier,
+		validate(input) {
+			if (input === null || input === void 0 || typeof input !== "object") return dropOrThrow(input, violationFor("invalid-input", input));
+			const declared = input.tier ?? "internal";
+			if (rank(declared) > rank(minTier)) return dropOrThrow(input, violationFor("sensitivity-tier-exceeded", input));
+			const matched = /* @__PURE__ */ new Set();
+			const rewritten = walk(input.value, (s, m) => applyPatterns(s, patterns, m), matched, /* @__PURE__ */ new WeakSet());
+			if (matched.size > 0) {
+				const matchedList = [...matched];
+				for (const name of matchedList) bump(counters.matchesByPattern, name);
+				if (matchedList.some((name) => patterns.find((p) => p.name === name)?.category === "secret")) {
+					if (failOnUnredacted) {
+						const violation = violationFor("secret-pattern-match", input, matchedList);
+						counters.droppedTotal += 1;
+						bump(counters.droppedByReason, violation.reason);
+						if (onViolation !== void 0) try {
+							onViolation(violation);
+						} catch {}
+						throw new RedactionValidationError(`RedactionValidator detected secret pattern(s) in attribute (${matchedList.join(", ")}).`, violation);
+					}
+				}
+			}
+			const out = matched.size === 0 ? {
+				value: rewritten,
+				tier: declared
+			} : {
+				value: rewritten,
+				tier: declared,
+				matched: [...matched]
+			};
+			if (custom !== void 0) return custom({
+				...input,
+				value: rewritten
+			});
+			return out;
+		},
+		counters: () => freezeCounters(counters),
+		resetCounters: () => {
+			counters = makeCounters();
+		}
+	};
+}
+/**
+* Quickly compute the relative ordering of two sensitivity tiers.
+* Exposed because the tracer + replay layers need it without taking a
+* full dependency on the validator implementation.
+*
+* @stable
+*/
+function compareSensitivityTiers(a, b) {
+	return rank(a) - rank(b);
+}
+
+//#endregion
+export { compareSensitivityTiers, createRedactionValidator };
+//# sourceMappingURL=validator.js.map

package/dist/redaction/validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.js","names":["out: RedactionPattern[]","out","out: Record<string, unknown>","minTier: Sensitivity","out: RedactionOutput"],"sources":["../../src/redaction/validator.ts"],"sourcesContent":["/**\n * `createRedactionValidator(...)` — the building block for the\n * mandatory `withValidation()` wrapper applied to every exporter.\n *\n * @packageDocumentation\n */\n\nimport { SENSITIVITY_ORDER, type Sensitivity } from '@graphorin/core';\n\nimport { RedactionValidationError } from './errors.js';\nimport { BUILT_IN_PATTERNS, type RedactionPattern } from './patterns.js';\nimport type {\n  RedactionCounters,\n  RedactionInput,\n  RedactionOutput,\n  RedactionValidator,\n  RedactionValidatorInstance,\n  RedactionValidatorOptions,\n  RedactionViolation,\n} from './types.js';\n\nconst TIER_INDEX = new Map<Sensitivity, number>(\n  SENSITIVITY_ORDER.map((tier, idx) => [tier, idx] as const),\n);\n\nfunction rank(tier: Sensitivity): number {\n  const idx = TIER_INDEX.get(tier);\n  return idx ?? 0;\n}\n\ninterface CountersInternal {\n  droppedTotal: number;\n  droppedByReason: Map<string, number>;\n  matchesByPattern: Map<string, number>;\n}\n\nfunction makeCounters(): CountersInternal {\n  return {\n    droppedTotal: 0,\n    droppedByReason: new Map(),\n    matchesByPattern: new Map(),\n  };\n}\n\nfunction bump(map: Map<string, number>, key: string): void {\n  map.set(key, (map.get(key) ?? 0) + 1);\n}\n\nfunction freezeCounters(c: CountersInternal): RedactionCounters {\n  return {\n    droppedTotal: c.droppedTotal,\n    droppedByReason: Object.freeze(Object.fromEntries(c.droppedByReason)),\n    matchesByPattern: Object.freeze(Object.fromEntries(c.matchesByPattern)),\n  };\n}\n\nfunction selectPatterns(\n  patterns: ReadonlyArray<RedactionPattern>,\n  enabled?: ReadonlyArray<string>,\n  disabled?: ReadonlyArray<string>,\n): RedactionPattern[] {\n  const enabledSet = enabled === undefined ? null : new Set(enabled);\n  const disabledSet = new Set(disabled ?? []);\n  const out: RedactionPattern[] = [];\n  for (const p of patterns) {\n    if (enabledSet !== null && !enabledSet.has(p.name)) continue;\n    if (disabledSet.has(p.name)) continue;\n    out.push(p);\n  }\n  return out;\n}\n\n/**\n * Walk every string discovered in `value` and apply `fn`. Returns\n * `{ output, matched }` where `output` is the rewritten payload and\n * `matched` is the de-duplicated list of pattern names that fired.\n *\n * The walker handles strings, plain objects, and arrays. Other JS\n * primitives are passed through untouched. Cycles are detected via a\n * `WeakSet` and broken with `'[Circular]'`.\n */\nfunction walk(\n  value: unknown,\n  fn: (s: string, matched: Set<string>) => string,\n  matched: Set<string>,\n  seen: WeakSet<object>,\n): unknown {\n  if (typeof value === 'string') return fn(value, matched);\n  if (value === null || typeof value !== 'object') return value;\n  if (seen.has(value as object)) return '[Circular]';\n  seen.add(value as object);\n\n  if (Array.isArray(value)) {\n    const out = new Array<unknown>(value.length);\n    for (let i = 0; i < value.length; i++) {\n      out[i] = walk(value[i], fn, matched, seen);\n    }\n    return out;\n  }\n\n  const obj = value as Record<string, unknown>;\n  const out: Record<string, unknown> = {};\n  for (const key of Object.keys(obj)) {\n    out[key] = walk(obj[key], fn, matched, seen);\n  }\n  return out;\n}\n\n/**\n * Apply every active pattern to `s`. Mutates `matched` with the names\n * that fired and returns the rewritten string.\n */\nfunction applyPatterns(\n  s: string,\n  patterns: ReadonlyArray<RedactionPattern>,\n  matched: Set<string>,\n): string {\n  let out = s;\n  for (const p of patterns) {\n    const mask = p.mask ?? `[REDACTED ${p.name}]`;\n    p.regex.lastIndex = 0;\n    if (p.verify === undefined) {\n      if (p.regex.test(out)) {\n        matched.add(p.name);\n        p.regex.lastIndex = 0;\n        out = out.replace(p.regex, mask);\n      }\n      continue;\n    }\n    // RP-21: per-match predicate — only mask hits the verifier accepts (e.g.\n    // Luhn-valid PANs), and only count the pattern as matched when one did.\n    const verify = p.verify;\n    p.regex.lastIndex = 0;\n    out = out.replace(p.regex, (m) => {\n      if (verify(m)) {\n        matched.add(p.name);\n        return mask;\n      }\n      return m;\n    });\n  }\n  return out;\n}\n\nfunction violationFor(\n  reason: RedactionViolation['reason'],\n  input: RedactionInput,\n  patterns?: ReadonlyArray<string>,\n): RedactionViolation {\n  const baseContext = input.context;\n  const base: RedactionViolation = {\n    reason,\n    declaredTier: input.tier,\n    ...(baseContext?.attribute === undefined ? {} : { attribute: baseContext.attribute }),\n    ...(baseContext?.spanType === undefined ? {} : { spanType: baseContext.spanType }),\n    ...(baseContext?.origin === undefined ? {} : { origin: baseContext.origin }),\n    ...(patterns === undefined || patterns.length === 0 ? {} : { patterns }),\n  };\n  return base;\n}\n\n/**\n * Create a {@link RedactionValidator} configured against the supplied\n * options. The result implements both the `RedactionValidator`\n * contract from `@graphorin/core` and the\n * {@link RedactionValidatorInstance} extension surface (counters +\n * reset).\n *\n * @stable\n */\nexport function createRedactionValidator(\n  opts: RedactionValidatorOptions = {},\n): RedactionValidatorInstance {\n  const id = opts.id ?? 'default';\n  const minTier: Sensitivity = opts.minTier ?? 'public';\n  const failOnUnredacted = opts.failOnUnredactedSensitive === true;\n  const patterns = selectPatterns(\n    opts.patterns ?? BUILT_IN_PATTERNS,\n    opts.enabledPatterns,\n    opts.disabledPatterns,\n  );\n  const onViolation = opts.onViolation;\n  const custom = opts.customValidator;\n\n  let counters = makeCounters();\n\n  function recordViolation(violation: RedactionViolation): void {\n    counters.droppedTotal += 1;\n    bump(counters.droppedByReason, violation.reason);\n    for (const name of violation.patterns ?? []) {\n      bump(counters.matchesByPattern, name);\n    }\n    if (onViolation !== undefined) {\n      try {\n        onViolation(violation);\n      } catch {\n        // Listener errors must never break the exporter.\n      }\n    }\n  }\n\n  function dropOrThrow(_input: RedactionInput, violation: RedactionViolation): null {\n    recordViolation(violation);\n    if (failOnUnredacted) {\n      throw new RedactionValidationError(\n        `RedactionValidator dropped value (${violation.reason}) — set ` +\n          'failOnUnredactedSensitive: false in production to keep the ' +\n          'pipeline running.',\n        violation,\n      );\n    }\n    return null;\n  }\n\n  const validator: RedactionValidator = {\n    id,\n    minTier,\n    validate(input: RedactionInput): RedactionOutput | null {\n      if (input === null || input === undefined || typeof input !== 'object') {\n        return dropOrThrow(\n          input as RedactionInput,\n          violationFor('invalid-input', input as RedactionInput),\n        );\n      }\n\n      const declared = input.tier ?? 'internal';\n\n      if (rank(declared) > rank(minTier)) {\n        return dropOrThrow(input, violationFor('sensitivity-tier-exceeded', input));\n      }\n\n      const matched = new Set<string>();\n      const rewritten = walk(\n        input.value,\n        (s, m) => applyPatterns(s, patterns, m),\n        matched,\n        new WeakSet(),\n      );\n\n      if (matched.size > 0) {\n        const matchedList = [...matched];\n        for (const name of matchedList) {\n          bump(counters.matchesByPattern, name);\n        }\n        const containsSecret = matchedList.some(\n          (name) => patterns.find((p) => p.name === name)?.category === 'secret',\n        );\n\n        if (containsSecret) {\n          if (failOnUnredacted) {\n            const violation = violationFor('secret-pattern-match', input, matchedList);\n            counters.droppedTotal += 1;\n            bump(counters.droppedByReason, violation.reason);\n            if (onViolation !== undefined) {\n              try {\n                onViolation(violation);\n              } catch {\n                /* listener errors swallowed */\n              }\n            }\n            throw new RedactionValidationError(\n              `RedactionValidator detected secret pattern(s) in attribute (${matchedList.join(', ')}).`,\n              violation,\n            );\n          }\n        }\n      }\n\n      const out: RedactionOutput =\n        matched.size === 0\n          ? { value: rewritten, tier: declared }\n          : { value: rewritten, tier: declared, matched: [...matched] };\n\n      if (custom !== undefined) {\n        return custom({ ...input, value: rewritten });\n      }\n\n      return out;\n    },\n  };\n\n  const instance: RedactionValidatorInstance = {\n    ...validator,\n    counters: () => freezeCounters(counters),\n    resetCounters: () => {\n      counters = makeCounters();\n    },\n  };\n\n  return instance;\n}\n\n/**\n * Quickly compute the relative ordering of two sensitivity tiers.\n * Exposed because the tracer + replay layers need it without taking a\n * full dependency on the validator implementation.\n *\n * @stable\n */\nexport function compareSensitivityTiers(a: Sensitivity, b: Sensitivity): number {\n  return rank(a) - rank(b);\n}\n"],"mappings":"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"}

package/dist/replay/config.d.ts

@@ -0,0 +1,56 @@
+//#region src/replay/config.d.ts
+/**
+ * Configuration shapes for the replay log. The shapes mirror the
+ * canonical `observability.replayLog.*` settings so consumer
+ * configuration files can use a single typed structure.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Shape consumed by `observability.replayLog.*`.
+ *
+ * @stable
+ */
+interface ReplayLogConfig {
+  /**
+   * Root directory for the JSONL trace files. Required when the
+   * replay log is enabled.
+   */
+  readonly path: string;
+  /**
+   * Retention window in days. `0` keeps every file forever.
+   *
+   * @default 30
+   */
+  readonly retentionDays?: number;
+  /**
+   * Auto-prune hint. `enabled` + `schedule` describe a daily prune of files
+   * older than `retentionDays`, but **no built-in scheduler consumes this
+   * yet** (RP-19) — it is a declarative intent. Until a host wires it to a
+   * trigger, callers must run `pruneTraces(...)` themselves; the default is
+   * therefore `enabled: false` so the option is not an inert default-on.
+   *
+   * @default { enabled: false, schedule: '0 4 * * *' }
+   */
+  readonly autoPrune?: {
+    readonly enabled: boolean;
+    readonly schedule?: string;
+  };
+  /**
+   * Encryption-at-rest toggle. `'off'` (default) writes plain JSONL;
+   * the opt-in `'aes256gcm'` mode hooks into the encryption-at-rest
+   * passphrase chain (Phase 16 deliverable).
+   *
+   * @default 'off'
+   */
+  readonly encryption?: 'off' | 'aes256gcm';
+}
+/**
+ * Default values for the replay log configuration.
+ *
+ * @stable
+ */
+declare const DEFAULT_REPLAY_LOG_CONFIG: Omit<Required<ReplayLogConfig>, 'path'>;
+//#endregion
+export { DEFAULT_REPLAY_LOG_CONFIG, ReplayLogConfig };
+//# sourceMappingURL=config.d.ts.map

package/dist/replay/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","names":[],"sources":["../../src/replay/config.ts"],"sourcesContent":[],"mappings":";;AAaA;AAwCA;;;;;;;;;;UAxCiB,eAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAwCJ,2BAA2B,KAAK,SAAS"}

package/dist/replay/config.js

@@ -0,0 +1,18 @@
+//#region src/replay/config.ts
+/**
+* Default values for the replay log configuration.
+*
+* @stable
+*/
+const DEFAULT_REPLAY_LOG_CONFIG = Object.freeze({
+	retentionDays: 30,
+	autoPrune: Object.freeze({
+		enabled: false,
+		schedule: "0 4 * * *"
+	}),
+	encryption: "off"
+});
+
+//#endregion
+export { DEFAULT_REPLAY_LOG_CONFIG };
+//# sourceMappingURL=config.js.map

package/dist/replay/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","names":["DEFAULT_REPLAY_LOG_CONFIG: Omit<Required<ReplayLogConfig>, 'path'>"],"sources":["../../src/replay/config.ts"],"sourcesContent":["/**\n * Configuration shapes for the replay log. The shapes mirror the\n * canonical `observability.replayLog.*` settings so consumer\n * configuration files can use a single typed structure.\n *\n * @packageDocumentation\n */\n\n/**\n * Shape consumed by `observability.replayLog.*`.\n *\n * @stable\n */\nexport interface ReplayLogConfig {\n  /**\n   * Root directory for the JSONL trace files. Required when the\n   * replay log is enabled.\n   */\n  readonly path: string;\n  /**\n   * Retention window in days. `0` keeps every file forever.\n   *\n   * @default 30\n   */\n  readonly retentionDays?: number;\n  /**\n   * Auto-prune hint. `enabled` + `schedule` describe a daily prune of files\n   * older than `retentionDays`, but **no built-in scheduler consumes this\n   * yet** (RP-19) — it is a declarative intent. Until a host wires it to a\n   * trigger, callers must run `pruneTraces(...)` themselves; the default is\n   * therefore `enabled: false` so the option is not an inert default-on.\n   *\n   * @default { enabled: false, schedule: '0 4 * * *' }\n   */\n  readonly autoPrune?: {\n    readonly enabled: boolean;\n    readonly schedule?: string;\n  };\n  /**\n   * Encryption-at-rest toggle. `'off'` (default) writes plain JSONL;\n   * the opt-in `'aes256gcm'` mode hooks into the encryption-at-rest\n   * passphrase chain (Phase 16 deliverable).\n   *\n   * @default 'off'\n   */\n  readonly encryption?: 'off' | 'aes256gcm';\n}\n\n/**\n * Default values for the replay log configuration.\n *\n * @stable\n */\nexport const DEFAULT_REPLAY_LOG_CONFIG: Omit<Required<ReplayLogConfig>, 'path'> = Object.freeze({\n  retentionDays: 30,\n  autoPrune: Object.freeze({ enabled: false, schedule: '0 4 * * *' }),\n  encryption: 'off' as const,\n});\n"],"mappings":";;;;;;AAqDA,MAAaA,4BAAqE,OAAO,OAAO;CAC9F,eAAe;CACf,WAAW,OAAO,OAAO;EAAE,SAAS;EAAO,UAAU;EAAa,CAAC;CACnE,YAAY;CACb,CAAC"}

package/dist/replay/index.d.ts

@@ -0,0 +1,5 @@
+import { DEFAULT_REPLAY_LOG_CONFIG, ReplayLogConfig } from "./config.js";
+import { PruneTracesOptions, getTraceLog, pruneTraces } from "./log.js";
+import { ReplayAuditBridge, ReplayAuditEvent, ReplayEvent, ReplayMode, ReplayOptions, ReplayRunInput } from "./types.js";
+import { Replay, createReplay } from "./replay.js";
+export { DEFAULT_REPLAY_LOG_CONFIG, type PruneTracesOptions, type Replay, type ReplayAuditBridge, type ReplayAuditEvent, type ReplayEvent, type ReplayLogConfig, type ReplayMode, type ReplayOptions, type ReplayRunInput, createReplay, getTraceLog, pruneTraces };

package/dist/replay/index.js

@@ -0,0 +1,5 @@
+import { DEFAULT_REPLAY_LOG_CONFIG } from "./config.js";
+import { getTraceLog, pruneTraces } from "./log.js";
+import { createReplay } from "./replay.js";
+
+export { DEFAULT_REPLAY_LOG_CONFIG, createReplay, getTraceLog, pruneTraces };

package/dist/replay/log.d.ts

@@ -0,0 +1,39 @@
+import { SpanRecord } from "../exporters/types.js";
+
+//#region src/replay/log.d.ts
+
+/**
+ * Read every span record from a JSONL trace log. Lines that fail to parse are
+ * skipped (the iterator keeps going); the generator only ever yields parsed
+ * {@link SpanRecord} values, never `null`.
+ *
+ * @stable
+ */
+declare function getTraceLog(filePath: string): AsyncIterable<SpanRecord>;
+/**
+ * Configuration shape for {@link pruneTraces}.
+ *
+ * @stable
+ */
+interface PruneTracesOptions {
+  /** Root directory housing the JSONL files. */
+  readonly root: string;
+  /** Files older than `olderThanDays` are deleted. `0` keeps every file. */
+  readonly olderThanDays: number;
+  /**
+   * Wall clock used to compute the threshold. Defaults to `Date.now`.
+   *
+   * @internal
+   */
+  readonly now?: () => number;
+}
+/**
+ * Remove every JSONL file that is older than the configured retention
+ * window. Returns the deleted files for caller-side accounting.
+ *
+ * @stable
+ */
+declare function pruneTraces(opts: PruneTracesOptions): Promise<ReadonlyArray<string>>;
+//#endregion
+export { PruneTracesOptions, getTraceLog, pruneTraces };
+//# sourceMappingURL=log.d.ts.map

package/dist/replay/log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.d.ts","names":[],"sources":["../../src/replay/log.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;iBAoBuB,WAAA,oBAA+B,cAAc;;;;;;UAkBnD,kBAAA;;;;;;;;;;;;;;;;;;iBAmBK,WAAA,OAAkB,qBAAqB,QAAQ"}

package/dist/replay/log.js

@@ -0,0 +1,59 @@
+import { readFile, readdir, stat, unlink } from "node:fs/promises";
+import { join, resolve } from "node:path";
+
+//#region src/replay/log.ts
+/**
+* `getTraceLog(...)` / `pruneTraces(...)` — minimal helpers for reading
+* back the JSONL files produced by {@link createJSONLExporter} and
+* pruning old files based on retention policy.
+*
+* @packageDocumentation
+*/
+/**
+* Read every span record from a JSONL trace log. Lines that fail to parse are
+* skipped (the iterator keeps going); the generator only ever yields parsed
+* {@link SpanRecord} values, never `null`.
+*
+* @stable
+*/
+async function* getTraceLog(filePath) {
+	const data = await readFile(filePath, "utf8");
+	for (const line of data.split("\n")) {
+		if (line.trim() === "") continue;
+		try {
+			yield JSON.parse(line);
+		} catch {}
+	}
+}
+/**
+* Remove every JSONL file that is older than the configured retention
+* window. Returns the deleted files for caller-side accounting.
+*
+* @stable
+*/
+async function pruneTraces(opts) {
+	if (opts.olderThanDays <= 0) return [];
+	const threshold = (opts.now ?? (() => Date.now()))() - opts.olderThanDays * 24 * 60 * 60 * 1e3;
+	const root = resolve(opts.root);
+	const removed = [];
+	for await (const filePath of walkJsonl(root)) if ((await stat(filePath)).mtimeMs < threshold) {
+		await unlink(filePath);
+		removed.push(filePath);
+	}
+	return removed;
+}
+async function* walkJsonl(root) {
+	const entries = await readdir(root, { withFileTypes: true });
+	for (const entry of entries) {
+		const full = join(root, entry.name);
+		if (entry.isDirectory()) {
+			yield* walkJsonl(full);
+			continue;
+		}
+		if (entry.isFile() && full.endsWith(".jsonl")) yield full;
+	}
+}
+
+//#endregion
+export { getTraceLog, pruneTraces };
+//# sourceMappingURL=log.js.map

package/dist/replay/log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.js","names":["removed: string[]"],"sources":["../../src/replay/log.ts"],"sourcesContent":["/**\n * `getTraceLog(...)` / `pruneTraces(...)` — minimal helpers for reading\n * back the JSONL files produced by {@link createJSONLExporter} and\n * pruning old files based on retention policy.\n *\n * @packageDocumentation\n */\n\nimport { readdir, readFile, stat, unlink } from 'node:fs/promises';\nimport { join, resolve } from 'node:path';\n\nimport type { SpanRecord } from '../exporters/types.js';\n\n/**\n * Read every span record from a JSONL trace log. Lines that fail to parse are\n * skipped (the iterator keeps going); the generator only ever yields parsed\n * {@link SpanRecord} values, never `null`.\n *\n * @stable\n */\nexport async function* getTraceLog(filePath: string): AsyncIterable<SpanRecord> {\n  const data = await readFile(filePath, 'utf8');\n  for (const line of data.split('\\n')) {\n    if (line.trim() === '') continue;\n    try {\n      const parsed = JSON.parse(line) as SpanRecord;\n      yield parsed;\n    } catch {\n      // Skip malformed lines — replay must keep going.\n    }\n  }\n}\n\n/**\n * Configuration shape for {@link pruneTraces}.\n *\n * @stable\n */\nexport interface PruneTracesOptions {\n  /** Root directory housing the JSONL files. */\n  readonly root: string;\n  /** Files older than `olderThanDays` are deleted. `0` keeps every file. */\n  readonly olderThanDays: number;\n  /**\n   * Wall clock used to compute the threshold. Defaults to `Date.now`.\n   *\n   * @internal\n   */\n  readonly now?: () => number;\n}\n\n/**\n * Remove every JSONL file that is older than the configured retention\n * window. Returns the deleted files for caller-side accounting.\n *\n * @stable\n */\nexport async function pruneTraces(opts: PruneTracesOptions): Promise<ReadonlyArray<string>> {\n  if (opts.olderThanDays <= 0) return [];\n\n  const now = opts.now ?? (() => Date.now());\n  const threshold = now() - opts.olderThanDays * 24 * 60 * 60 * 1000;\n  const root = resolve(opts.root);\n  const removed: string[] = [];\n\n  for await (const filePath of walkJsonl(root)) {\n    const info = await stat(filePath);\n    if (info.mtimeMs < threshold) {\n      await unlink(filePath);\n      removed.push(filePath);\n    }\n  }\n\n  return removed;\n}\n\nasync function* walkJsonl(root: string): AsyncIterable<string> {\n  const entries = await readdir(root, { withFileTypes: true });\n  for (const entry of entries) {\n    const full = join(root, entry.name);\n    if (entry.isDirectory()) {\n      yield* walkJsonl(full);\n      continue;\n    }\n    if (entry.isFile() && full.endsWith('.jsonl')) {\n      yield full;\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAoBA,gBAAuB,YAAY,UAA6C;CAC9E,MAAM,OAAO,MAAM,SAAS,UAAU,OAAO;AAC7C,MAAK,MAAM,QAAQ,KAAK,MAAM,KAAK,EAAE;AACnC,MAAI,KAAK,MAAM,KAAK,GAAI;AACxB,MAAI;AAEF,SADe,KAAK,MAAM,KAAK;UAEzB;;;;;;;;;AA8BZ,eAAsB,YAAY,MAA0D;AAC1F,KAAI,KAAK,iBAAiB,EAAG,QAAO,EAAE;CAGtC,MAAM,aADM,KAAK,cAAc,KAAK,KAAK,IAClB,GAAG,KAAK,gBAAgB,KAAK,KAAK,KAAK;CAC9D,MAAM,OAAO,QAAQ,KAAK,KAAK;CAC/B,MAAMA,UAAoB,EAAE;AAE5B,YAAW,MAAM,YAAY,UAAU,KAAK,CAE1C,MADa,MAAM,KAAK,SAAS,EACxB,UAAU,WAAW;AAC5B,QAAM,OAAO,SAAS;AACtB,UAAQ,KAAK,SAAS;;AAI1B,QAAO;;AAGT,gBAAgB,UAAU,MAAqC;CAC7D,MAAM,UAAU,MAAM,QAAQ,MAAM,EAAE,eAAe,MAAM,CAAC;AAC5D,MAAK,MAAM,SAAS,SAAS;EAC3B,MAAM,OAAO,KAAK,MAAM,MAAM,KAAK;AACnC,MAAI,MAAM,aAAa,EAAE;AACvB,UAAO,UAAU,KAAK;AACtB;;AAEF,MAAI,MAAM,QAAQ,IAAI,KAAK,SAAS,SAAS,CAC3C,OAAM"}

package/dist/replay/replay.d.ts

@@ -0,0 +1,25 @@
+import { ReplayEvent, ReplayOptions, ReplayRunInput } from "./types.js";
+
+//#region src/replay/replay.d.ts
+
+/**
+ * @stable
+ */
+interface Replay {
+  run(input: ReplayRunInput): AsyncIterable<ReplayEvent>;
+}
+/**
+ * Build a replay primitive. The returned object exposes a single
+ * `run(...)` async iterator that yields {@link ReplayEvent} records.
+ *
+ * Sanitized mode is the default and applies the configured
+ * {@link RedactionValidatorInstance} to every record. Raw mode
+ * requires the `canReadRaw` callback to return `true` AND emits an
+ * audit log entry on every invocation.
+ *
+ * @stable
+ */
+declare function createReplay(opts?: ReplayOptions): Replay;
+//#endregion
+export { Replay, createReplay };
+//# sourceMappingURL=replay.d.ts.map

package/dist/replay/replay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.d.ts","names":[],"sources":["../../src/replay/replay.ts"],"sourcesContent":[],"mappings":";;;;;;;UAgCiB,MAAA;aACJ,iBAAiB,cAAc;;;;;;;;;;;;;iBAc5B,YAAA,QAAmB,gBAAqB"}