@nodii/telemetry 0.12.0 → 0.14.0

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -8,6 +8,11 @@
 //                                 that SET NodiiContext at the entry seam.
 //   - @nodii/telemetry/outbox   — Outbox emit + propagation-column adapter.
 //   - @nodii/telemetry/drizzle  — Drizzle audit_event schema fragments.
+//   - @nodii/telemetry/lambda   — AWS Lambda lifecycle wrapper (C4 lock):
+//                                 cold-start init at module-load +
+//                                 force-flush-on-return so spans/metrics/
+//                                 logs survive the post-handler freeze.
+//                                 First consumer: s2s-auth-service.
 //
 // Not yet shipped (D44 § 6.5 lists them; no implementation exists yet —
 // they are tracked as follow-on requests, NOT advertised as vapor):

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,EAAE;AACF,0EAA0E;AAC1E,EAAE;AACF,0EAA0E;AAC1E,yEAAyE;AACzE,4EAA4E;AAC5E,2EAA2E;AAC3E,4EAA4E;AAC5E,wEAAwE;AACxE,EAAE;AACF,wEAAwE;AACxE,oEAAoE;AACpE,uEAAuE;AACvE,8DAA8D;AAC9D,mDAAmD;AACnD,EAAE;AACF,oEAAoE;AACpE,gBAAgB;AAChB,EAAE;AACF,oEAAoE;AACpE,gEAAgE;AAChE,0DAA0D;AAE1D,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EACL,UAAU,EACV,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAOnD,OAAO,EAAE,MAAM,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAWjD,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,OAAO,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAS5E,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,wBAAwB,EACxB,gCAAgC,EAChC,yBAAyB,EACzB,cAAc,EACd,eAAe,EACf,8BAA8B,EAC9B,KAAK,EACL,iBAAiB,EACjB,cAAc,GACf,MAAM,YAAY,CAAC;AAYpB,OAAO,EAAE,2BAA2B,EAAE,MAAM,YAAY,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEpD,OAAO,EAAE,MAAM,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,UAAU,EACV,cAAc,EACd,WAAW,GACZ,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,cAAc,EACd,eAAe,GAChB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AA0BrD,OAAO,EACL,uBAAuB,EACvB,eAAe,EACf,4BAA4B,EAC5B,2BAA2B,GAC5B,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,EAAE;AACF,0EAA0E;AAC1E,EAAE;AACF,0EAA0E;AAC1E,yEAAyE;AACzE,4EAA4E;AAC5E,2EAA2E;AAC3E,4EAA4E;AAC5E,wEAAwE;AACxE,0EAA0E;AAC1E,mEAAmE;AACnE,0EAA0E;AAC1E,wEAAwE;AACxE,oEAAoE;AACpE,EAAE;AACF,wEAAwE;AACxE,oEAAoE;AACpE,uEAAuE;AACvE,8DAA8D;AAC9D,mDAAmD;AACnD,EAAE;AACF,oEAAoE;AACpE,gBAAgB;AAChB,EAAE;AACF,oEAAoE;AACpE,gEAAgE;AAChE,0DAA0D;AAE1D,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EACL,UAAU,EACV,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAOnD,OAAO,EAAE,MAAM,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAWjD,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,OAAO,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAS5E,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,wBAAwB,EACxB,gCAAgC,EAChC,yBAAyB,EACzB,cAAc,EACd,eAAe,EACf,8BAA8B,EAC9B,KAAK,EACL,iBAAiB,EACjB,cAAc,GACf,MAAM,YAAY,CAAC;AAYpB,OAAO,EAAE,2BAA2B,EAAE,MAAM,YAAY,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEpD,OAAO,EAAE,MAAM,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,UAAU,EACV,cAAc,EACd,WAAW,GACZ,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,cAAc,EACd,eAAe,GAChB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AA0BrD,OAAO,EACL,uBAAuB,EACvB,eAAe,EACf,4BAA4B,EAC5B,2BAA2B,GAC5B,MAAM,YAAY,CAAC"}

package/dist/lambda/index.d.ts

@@ -0,0 +1,77 @@
+import type { InitTelemetryConfig, MetricFamily } from "../types.js";
+/**
+ * A minimal structural AWS Lambda handler. We intentionally do NOT depend
+ * on `aws-lambda` types — the wrapper is event-shape agnostic so it works
+ * for an APIGW-proxied Hono app (`handle(app)` from `hono/aws-lambda`), a
+ * raw SQS/SNS/EventBridge handler, or any other `async (event, context)`
+ * function. `Event` / `Result` are inferred from the wrapped handler.
+ */
+export type LambdaHandler<Event = unknown, Result = unknown> = (event: Event, context?: unknown) => Promise<Result> | Result;
+/** Config for the cold-start counter tick (C4: `s2s.cold_start_total`). */
+export interface ColdStartMetricConfig {
+    /**
+     * The vocabulary-registered counter name to increment once per cold
+     * boot (e.g. `"s2s.cold_start_total"`). MUST be registered by the
+     * consumer via `initTelemetry({ vocabularyRegistry })` — the name is
+     * service-specific, so the wrapper cannot hardcode it.
+     *
+     * If the name is NOT registered (vocabulary miss), the increment is a
+     * caught no-op + a one-line warn — a metric mis-config must NOT crash
+     * module-load (R1 / pillar 5).
+     */
+    name: string;
+    /** The metric family for the counter. Defaults to `"request_handler"`. */
+    family?: MetricFamily;
+    /** Static labels stamped on the cold-start tick. */
+    labels?: Record<string, string | number>;
+}
+/**
+ * `initLambdaTelemetry({...})` argument shape. Extends the base
+ * `initTelemetry` config (serviceName + env + otlp + vocabulary, …) with
+ * the Lambda-specific cold-start knob.
+ */
+export interface InitLambdaTelemetryConfig extends InitTelemetryConfig {
+    /**
+     * Counter to increment once per cold boot. Omit to skip the cold-start
+     * tick entirely (some services track cold starts via a log line only).
+     */
+    coldStartMetric?: ColdStartMetricConfig;
+    /**
+     * Name of the per-invocation request span opened by `wrap`. Defaults to
+     * `"<serviceName>.lambda.invoke"`.
+     */
+    requestSpanName?: string;
+}
+/** The handle returned by `initLambdaTelemetry`. */
+export interface LambdaTelemetry {
+    /**
+     * Wrap a Lambda handler so every invocation:
+     *   1. runs inside a request span (`requestSpanName`);
+     *   2. force-flushes the trace + log + metric providers BEFORE the
+     *      handler's result returns (success AND error paths), so nothing
+     *      is lost when Lambda freezes;
+     *   3. is RESILIENT — a flush failure is caught + logged and never
+     *      propagates; the handler's own result / error is what returns.
+     */
+    wrap<Event, Result>(handler: LambdaHandler<Event, Result>): (event: Event, context?: unknown) => Promise<Result>;
+    /**
+     * Force-flush the active OTLP pipelines (trace + log + metric). No-op
+     * when no OTLP adapter is installed (e.g. `disableOtlp` / no endpoint).
+     * Exposed for callers that flush at custom lifecycle points.
+     */
+    forceFlush(): Promise<void>;
+}
+/**
+ * Boot telemetry for a Lambda at MODULE LOAD (per C4). Call this once at
+ * the top of the handler module — not per invocation. Returns a
+ * `LambdaTelemetry` handle whose `wrap` adds the per-invocation request
+ * span + force-flush-on-return.
+ *
+ * Idempotency: `initTelemetry` is itself idempotent (a second call
+ * warn-no-ops), so a doubly-imported / re-required handler module does
+ * NOT double-configure the SDK. The cold-start tick is likewise fired
+ * only on the call that actually performs init (the first one) — a second
+ * `initLambdaTelemetry` will not re-tick, matching "once per cold boot".
+ */
+export declare function initLambdaTelemetry(config: InitLambdaTelemetryConfig): LambdaTelemetry;
+//# sourceMappingURL=index.d.ts.map

package/dist/lambda/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lambda/index.ts"],"names":[],"mappings":"AAsCA,OAAO,KAAK,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAErE;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,CAAC,KAAK,GAAG,OAAO,EAAE,MAAM,GAAG,OAAO,IAAI,CAC7D,KAAK,EAAE,KAAK,EACZ,OAAO,CAAC,EAAE,OAAO,KACd,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;AAE9B,2EAA2E;AAC3E,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;;OASG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;CAC1C;AAED;;;;GAIG;AACH,MAAM,WAAW,yBAA0B,SAAQ,mBAAmB;IACpE;;;OAGG;IACH,eAAe,CAAC,EAAE,qBAAqB,CAAC;IACxC;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,oDAAoD;AACpD,MAAM,WAAW,eAAe;IAC9B;;;;;;;;OAQG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,EAChB,OAAO,EAAE,aAAa,CAAC,KAAK,EAAE,MAAM,CAAC,GACpC,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACxD;;;;OAIG;IACH,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAyBD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,yBAAyB,GAChC,eAAe,CAiDjB"}

package/dist/lambda/index.js

@@ -0,0 +1,130 @@
+// `@nodii/telemetry/lambda` — the Lambda lifecycle wrapper.
+//
+// Spec: C4 lock — `services/s2s-auth-service/features/telemetry-instrumentation.md`
+//       § "The `@nodii/telemetry/lambda` sub-package" + `nodii-libs/telemetry.md`
+//       § 10 (subpath exports). First consumer: s2s-auth-service (Lambda-shaped).
+//
+// AWS Lambda freezes the execution environment the instant a handler
+// returns. The OTel batch processors buffer spans / logs / metrics and
+// flush them on a timer — so on a Lambda that timer rarely fires before
+// the freeze, and signals are LOST. Two lifecycle hooks fix this, both
+// locked by C4:
+//
+//   1. Cold-start init at module-load — `initLambdaTelemetry({...})` is
+//      called once at the top of the handler module (NOT per-invocation).
+//      It boots the SDK (idempotent — a second call warn-no-ops, see
+//      `initTelemetry`) and ticks a cold-start counter exactly once per
+//      cold boot.
+//
+//   2. `forceFlush()` before the handler returns — `handle.wrap(fn)`
+//      runs the handler inside a request span and `await`s a force-flush
+//      of the trace + log + metric providers BEFORE returning (and on the
+//      error path), so nothing is lost when the environment freezes.
+//
+// RESILIENCE (telemetry-doctrine pillar 5 / R1 — dependency-down path):
+//   a force-flush FAILURE (collector down / OTLP timeout) MUST NOT break
+//   the Lambda. A flaky telemetry backend cannot be allowed to take down
+//   the function. `wrap` therefore catches + logs any flush rejection and
+//   STILL returns the handler's result (or re-throws the handler's own
+//   error). The only thing that propagates out of the wrapper is the
+//   handler's own outcome — never a telemetry-plumbing failure.
+//
+// Lives behind a subpath so non-Lambda services never pull this lifecycle
+// glue into their bundle.
+import { getTelemetryOrNull, initTelemetry } from "../init.js";
+import { metrics } from "../metrics.js";
+import { forceFlush as flushOtlpPipelines } from "../otlp-adapter.js";
+import { tracer } from "../tracer.js";
+/**
+ * Increment the cold-start counter exactly once, defensively. A
+ * vocabulary miss (name not registered) or any other metric error is
+ * caught + warn-logged — a cold-start metric mis-config must NOT crash
+ * the Lambda at module load (R1 / pillar 5).
+ */
+function tickColdStart(cfg) {
+    try {
+        const counter = metrics.counter(cfg.name, {
+            family: cfg.family ?? "request_handler",
+            description: "Lambda cold-start counter (incremented once per cold boot)",
+            labelKeys: Object.keys(cfg.labels ?? {}),
+        });
+        counter.inc(cfg.labels ?? {});
+    }
+    catch (err) {
+        const cause = err instanceof Error ? err.message : String(err);
+        // eslint-disable-next-line no-console
+        console.warn(`[@nodii/telemetry/lambda] cold-start counter "${cfg.name}" could not be incremented (is it in the vocabularyRegistry?). Continuing — a metric mis-config must not crash module-load. Cause: ${cause}`);
+    }
+}
+/**
+ * Boot telemetry for a Lambda at MODULE LOAD (per C4). Call this once at
+ * the top of the handler module — not per invocation. Returns a
+ * `LambdaTelemetry` handle whose `wrap` adds the per-invocation request
+ * span + force-flush-on-return.
+ *
+ * Idempotency: `initTelemetry` is itself idempotent (a second call
+ * warn-no-ops), so a doubly-imported / re-required handler module does
+ * NOT double-configure the SDK. The cold-start tick is likewise fired
+ * only on the call that actually performs init (the first one) — a second
+ * `initLambdaTelemetry` will not re-tick, matching "once per cold boot".
+ */
+export function initLambdaTelemetry(config) {
+    // Was the SDK already initialized before this call? If so, this is a
+    // redundant init (re-imported module / double-call) and we must NOT
+    // re-tick the cold-start counter — "once per cold boot".
+    const alreadyInitialized = getTelemetryOrNull() !== null;
+    // `initTelemetry` consumes only the base config keys; the extra
+    // Lambda-specific keys are ignored by it (excess-property tolerant at
+    // runtime). It is idempotent — a second call warn-no-ops.
+    initTelemetry(config);
+    if (!alreadyInitialized && config.coldStartMetric) {
+        tickColdStart(config.coldStartMetric);
+    }
+    const spanName = config.requestSpanName ?? `${config.serviceName}.lambda.invoke`;
+    // The handle is built first so `wrap` can route its flush through
+    // `handle.forceFlush` — that is the single flush seam (and the one a
+    // test spies on to fault-inject a flush failure).
+    const handle = {
+        async forceFlush() {
+            await flushOtlpPipelines();
+        },
+        wrap(handler) {
+            return async (event, context) => {
+                try {
+                    // Run the handler inside a request span. `tracer.span` opens +
+                    // closes the span and applies D27 status mapping.
+                    const result = await tracer.span(spanName, () => Promise.resolve(handler(event, context)));
+                    // Flush BEFORE returning — but a flush failure must NOT mask a
+                    // successful handler result.
+                    await safeFlush(handle);
+                    return result;
+                }
+                catch (handlerErr) {
+                    // The handler itself threw. Still flush (so the error span +
+                    // partial signals aren't lost on freeze) — non-fatally — then
+                    // re-throw the handler's OWN error (NOT a flush error).
+                    await safeFlush(handle);
+                    throw handlerErr;
+                }
+            };
+        },
+    };
+    return handle;
+}
+/**
+ * Force-flush via `handle.forceFlush` but NEVER throw. A flush failure
+ * (collector down / OTLP timeout) is caught + warn-logged; the Lambda
+ * result must not be lost to a flaky telemetry backend (pillar 5 / R1
+ * dependency-down path).
+ */
+async function safeFlush(handle) {
+    try {
+        await handle.forceFlush();
+    }
+    catch (err) {
+        const cause = err instanceof Error ? err.message : String(err);
+        // eslint-disable-next-line no-console
+        console.warn(`[@nodii/telemetry/lambda] forceFlush() failed before return (telemetry backend down?). Swallowed — the handler result is returned regardless. Cause: ${cause}`);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/lambda/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/lambda/index.ts"],"names":[],"mappings":"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"}

package/dist/worker/checkpoint-store.d.ts

@@ -0,0 +1,66 @@
+import type { SqlExecutor } from "./tx.js";
+/** Default table name for the generalized checkpoint cursor. */
+export declare const DEFAULT_CHECKPOINT_TABLE = "worker_checkpoint";
+/** The durable checkpoint a worker resumes from. */
+export interface Checkpoint {
+    subscription: string;
+    /** Redis-Streams id of the last event committed, or null if none yet. */
+    lastStreamId: string | null;
+    /** Optional LWW entity_version HWM (per D402 "+ optional"); null when unused. */
+    highWaterEntityVersion: bigint | null;
+    /** Count of events committed against this subscription. */
+    consumedCount: bigint;
+}
+/** The cursor position to advance to inside the apply tx. */
+export interface CheckpointAdvance {
+    subscription: string;
+    /** The Redis-Streams id of the event being committed in this apply tx. */
+    lastStreamId: string;
+    /**
+     * Optional LWW entity_version high-water-mark. When provided the cursor only
+     * advances `high_water_entity_version` MONOTONICALLY (GREATEST of old/new) so
+     * an out-of-order replay cannot regress it. Omit when the subscription
+     * doesn't track an entity-version HWM.
+     */
+    highWaterEntityVersion?: bigint | null;
+    /** How much to bump `consumed_count` by (default 1). */
+    incrementBy?: number;
+}
+/** Idempotent DDL to create the generalized checkpoint table. */
+export declare function checkpointTableDDL(table?: string): string;
+/**
+ * Durable HWM cursor store. ONE instance per subscription family (or share one
+ * across subscriptions — the `subscription` key disambiguates). The
+ * `advance(...)` write joins the caller's apply transaction via the injected
+ * `tx`; the store has NO pool of its own and cannot commit independently.
+ */
+export declare class CheckpointStore {
+    readonly table: string;
+    private readonly upsertSql;
+    private readonly selectSql;
+    constructor(opts?: {
+        table?: string;
+    });
+    /**
+     * Read the durable checkpoint for a subscription, or `null` if none exists
+     * yet (cold start → the worker bootstraps from the snapshot per
+     * 09-replication § 7, then stitches to live from `lastStreamId`).
+     *
+     * `tx` may be a transaction handle OR a pooled connection — a read does not
+     * need to join the apply tx, but accepting the same seam keeps the API
+     * uniform and lets the caller read its OWN uncommitted advance inside a tx if
+     * it wants to.
+     */
+    get(subscription: string, tx: SqlExecutor): Promise<Checkpoint | null>;
+    /**
+     * Advance the durable cursor INSIDE the caller's apply transaction. MUST be
+     * called on the SAME `tx` the caller runs its projection upsert + dedupe
+     * record on, so cursor + projection + dedupe commit together-or-none. This is
+     * the atomic-in-apply-tx guarantee D402 pins.
+     *
+     * @param adv      the new cursor position (the event id being committed).
+     * @param tx       the caller's transaction handle (NOT a fresh pool conn).
+     */
+    advance(adv: CheckpointAdvance, tx: SqlExecutor): Promise<void>;
+}
+//# sourceMappingURL=checkpoint-store.d.ts.map

package/dist/worker/checkpoint-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-store.d.ts","sourceRoot":"","sources":["../../src/worker/checkpoint-store.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAAE,WAAW,EAAU,MAAM,SAAS,CAAC;AAYnD,gEAAgE;AAChE,eAAO,MAAM,wBAAwB,sBAAsB,CAAC;AAE5D,oDAAoD;AACpD,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,iFAAiF;IACjF,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,2DAA2D;IAC3D,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,6DAA6D;AAC7D,MAAM,WAAW,iBAAiB;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,iEAAiE;AACjE,wBAAgB,kBAAkB,CAAC,KAAK,SAA2B,GAAG,MAAM,CAS3E;AAcD;;;;;GAKG;AACH,qBAAa,eAAe;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,IAAI,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO;IAsBzC;;;;;;;;;OASG;IACG,GAAG,CAAC,YAAY,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAY5E;;;;;;;;OAQG;IACG,OAAO,CAAC,GAAG,EAAE,iBAAiB,EAAE,EAAE,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;CActE"}

package/dist/worker/checkpoint-store.js

@@ -0,0 +1,131 @@
+// D402 — CheckpointStore: the durable high-water-mark (HWM) cursor primitive.
+//
+// D402 (LOCKED):
+//   "CheckpointStore (HWM cursor) — durable `last_stream_id` per subscription;
+//    advanced ATOMICALLY inside the apply transaction (cursor + projection
+//    upsert + dedupe commit together or none); snapshot→live 'stitch' per
+//    09-replication-doctrine § 7."
+//
+// This GENERALIZES the two hand-rolled cursors that exist today (the task's
+// instruction — "generalize, don't duplicate the table"):
+//   - replica-consumer's `replication_cursor` keyed by `source_stream`
+//     (ts/replica-consumer/src/sql-builders.ts CURSOR_UPSERT_SQL).
+//   - outbox-dispatcher's in-memory `HwmTracker` (ts/outbox-dispatcher/src/hwm.ts).
+//
+// THE LOAD-BEARING CORRECTNESS PROPERTY — atomic-in-apply-tx:
+//   `advance(...)` runs on a `tx` handle the CALLER owns. The store NEVER opens
+//   its own connection for the cursor write, so it physically cannot commit the
+//   cursor independently of the projection. The caller wraps projection upsert +
+//   `dedupe.record(...)` + `checkpoint.advance(...)` in ONE transaction; a
+//   failure anywhere rolls back ALL THREE (cursor does NOT advance past an
+//   un-applied event → no silent gap, no double-apply on retry).
+//
+// Table shape (generalized `replication_cursor`, keyed by `subscription`):
+//   subscription            TEXT PRIMARY KEY   -- the per-subscription key
+//   last_stream_id          TEXT NOT NULL      -- Redis-Streams id of last applied
+//   high_water_entity_version BIGINT           -- optional LWW pointer (nullable)
+//   consumed_count          BIGINT NOT NULL DEFAULT 0
+//   updated_at              TIMESTAMPTZ NOT NULL DEFAULT now()
+/** Strict SQL identifier whitelist (mirrors replica-consumer's quoteIdent). */
+const IDENT_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function quoteIdent(name) {
+    if (!IDENT_PATTERN.test(name)) {
+        throw new Error(`invalid SQL identifier: ${name}`);
+    }
+    return `"${name}"`;
+}
+/** Default table name for the generalized checkpoint cursor. */
+export const DEFAULT_CHECKPOINT_TABLE = "worker_checkpoint";
+/** Idempotent DDL to create the generalized checkpoint table. */
+export function checkpointTableDDL(table = DEFAULT_CHECKPOINT_TABLE) {
+    const t = quoteIdent(table);
+    return `CREATE TABLE IF NOT EXISTS ${t} (
+  subscription TEXT PRIMARY KEY,
+  last_stream_id TEXT,
+  high_water_entity_version BIGINT,
+  consumed_count BIGINT NOT NULL DEFAULT 0,
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+)`;
+}
+function toBigintOrNull(v) {
+    if (v === null || v === undefined)
+        return null;
+    return BigInt(v);
+}
+/**
+ * Durable HWM cursor store. ONE instance per subscription family (or share one
+ * across subscriptions — the `subscription` key disambiguates). The
+ * `advance(...)` write joins the caller's apply transaction via the injected
+ * `tx`; the store has NO pool of its own and cannot commit independently.
+ */
+export class CheckpointStore {
+    table;
+    upsertSql;
+    selectSql;
+    constructor(opts = {}) {
+        this.table = opts.table ?? DEFAULT_CHECKPOINT_TABLE;
+        const t = quoteIdent(this.table);
+        // ON CONFLICT upsert: advance the cursor + bump consumed_count.
+        // `high_water_entity_version` advances MONOTONICALLY (GREATEST) so an
+        // out-of-order apply can't regress the LWW HWM; a NULL incoming value keeps
+        // the existing one (COALESCE on EXCLUDED).
+        this.upsertSql = `INSERT INTO ${t}
+  (subscription, last_stream_id, high_water_entity_version, consumed_count, updated_at)
+VALUES ($1, $2, $3, $4, now())
+ON CONFLICT (subscription) DO UPDATE SET
+  last_stream_id = EXCLUDED.last_stream_id,
+  high_water_entity_version = GREATEST(
+    COALESCE(${t}.high_water_entity_version, EXCLUDED.high_water_entity_version, 0),
+    COALESCE(EXCLUDED.high_water_entity_version, ${t}.high_water_entity_version, 0)
+  ),
+  consumed_count = ${t}.consumed_count + EXCLUDED.consumed_count,
+  updated_at = now()`;
+        this.selectSql = `SELECT subscription, last_stream_id, high_water_entity_version, consumed_count
+FROM ${t} WHERE subscription = $1`;
+    }
+    /**
+     * Read the durable checkpoint for a subscription, or `null` if none exists
+     * yet (cold start → the worker bootstraps from the snapshot per
+     * 09-replication § 7, then stitches to live from `lastStreamId`).
+     *
+     * `tx` may be a transaction handle OR a pooled connection — a read does not
+     * need to join the apply tx, but accepting the same seam keeps the API
+     * uniform and lets the caller read its OWN uncommitted advance inside a tx if
+     * it wants to.
+     */
+    async get(subscription, tx) {
+        const res = await tx.query(this.selectSql, [subscription]);
+        const row = res.rows[0];
+        if (!row)
+            return null;
+        return {
+            subscription: row.subscription,
+            lastStreamId: row.last_stream_id,
+            highWaterEntityVersion: toBigintOrNull(row.high_water_entity_version),
+            consumedCount: BigInt(row.consumed_count),
+        };
+    }
+    /**
+     * Advance the durable cursor INSIDE the caller's apply transaction. MUST be
+     * called on the SAME `tx` the caller runs its projection upsert + dedupe
+     * record on, so cursor + projection + dedupe commit together-or-none. This is
+     * the atomic-in-apply-tx guarantee D402 pins.
+     *
+     * @param adv      the new cursor position (the event id being committed).
+     * @param tx       the caller's transaction handle (NOT a fresh pool conn).
+     */
+    async advance(adv, tx) {
+        const inc = adv.incrementBy ?? 1;
+        const hwev = adv.highWaterEntityVersion === undefined ||
+            adv.highWaterEntityVersion === null
+            ? null
+            : adv.highWaterEntityVersion.toString();
+        await tx.query(this.upsertSql, [
+            adv.subscription,
+            adv.lastStreamId,
+            hwev,
+            inc,
+        ]);
+    }
+}
+//# sourceMappingURL=checkpoint-store.js.map

package/dist/worker/checkpoint-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-store.js","sourceRoot":"","sources":["../../src/worker/checkpoint-store.ts"],"names":[],"mappings":"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"}

package/dist/worker/dead-letter.d.ts

@@ -0,0 +1,81 @@
+import type { SqlExecutor } from "./tx.js";
+/**
+ * A poison event handed to a dead-letter sink after exhausting in-line retries.
+ * Carries enough to make it REPLAYABLE (mirrors replica-consumer's DLQ envelope
+ * columns) plus the failure cause.
+ */
+export interface DeadLetterItem {
+    /** Source stream the event came off (the subscription / topic stream). */
+    sourceStream: string;
+    /** The outbox topic. */
+    topic: string;
+    /** The event's dedupe id (event_id). */
+    eventId: string;
+    /**
+     * The event payload — possibly containing PII. The redaction hook scrubs this
+     * BEFORE it reaches the sink (fail-closed). The sink NEVER sees raw PII.
+     */
+    payload: Record<string, unknown>;
+    /** Why it was dead-lettered (the terminal error message). */
+    errorMessage: string;
+    /** How many in-line retries were attempted before giving up. */
+    retryCount: number;
+}
+/**
+ * The injected dead-letter sink. The caller provides the impl; there is NO
+ * default. `deadLetter(item)` MUST be durable / loud — a dead item must never
+ * vanish silently.
+ */
+export interface DeadLetterSink {
+    deadLetter(item: DeadLetterItem): Promise<void>;
+}
+/**
+ * A minimal logger seam for the loud sink (structurally satisfied by the
+ * telemetry `logger` or `console`). Only `error` is required.
+ */
+export interface DeadLetterLogger {
+    error(msg: string, fields?: Record<string, unknown>): void;
+}
+export declare function withPiiRedaction(sink: DeadLetterSink, opts?: {
+    extraPaths?: readonly string[];
+}): DeadLetterSink;
+/**
+ * The FAIL-CLOSED-BY-DEFAULT wrapper every worker applies to its injected
+ * DeadLetterSink: redaction runs on every dead item WITHOUT the consumer having
+ * to remember to wrap (D15: the SAFE state must be the default). An
+ * already-wrapped sink is returned as-is (no double-wrap). Used internally by the
+ * worker constructors.
+ */
+export declare function ensurePiiRedaction(sink: DeadLetterSink): DeadLetterSink;
+/**
+ * Reference sink #1: accepts the dead item but logs it LOUDLY (error-level,
+ * with the failure cause + identity, never the raw payload — that's already
+ * redacted by `withPiiRedaction`). It does NOT persist. Useful as an explicit
+ * "I have NO durable DLQ yet but I refuse to silently drop" choice. NEVER
+ * auto-wired — the caller must construct + inject it.
+ */
+export declare class LoudNoopDeadLetterSink implements DeadLetterSink {
+    private readonly logger;
+    constructor(logger: DeadLetterLogger);
+    deadLetter(item: DeadLetterItem): Promise<void>;
+}
+/**
+ * Reference sink #2: persists the dead item into a CONSUMER-OWNED quarantine
+ * table the caller opts into (passing its OWN transaction/pool executor + table
+ * name). This is the SUBSCRIBER's own DLQ — NOT a source-side `outbox_dlq`
+ * (which D401 forbids). The caller controls the executor, so the write joins
+ * whatever transaction the caller chooses (or runs standalone on a pool conn).
+ */
+export declare class TableDeadLetterSink implements DeadLetterSink {
+    readonly table: string;
+    private readonly insertSql;
+    private readonly exec;
+    constructor(opts: {
+        executor: SqlExecutor;
+        table?: string;
+    });
+    /** Idempotent DDL for the consumer-owned quarantine table. */
+    static tableDDL(table?: string): string;
+    deadLetter(item: DeadLetterItem): Promise<void>;
+}
+//# sourceMappingURL=dead-letter.d.ts.map

package/dist/worker/dead-letter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dead-letter.d.ts","sourceRoot":"","sources":["../../src/worker/dead-letter.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAY3C;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;IACrB,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,6DAA6D;IAC7D,YAAY,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjD;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC5D;AAqBD,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,cAAc,EACpB,IAAI,GAAE;IAAE,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAO,GAC5C,cAAc,CA6BhB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,cAAc,GAAG,cAAc,CAGvE;AAED;;;;;;GAMG;AACH,qBAAa,sBAAuB,YAAW,cAAc;IAC/C,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,gBAAgB;IAE/C,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;CAWtD;AAED;;;;;;GAMG;AACH,qBAAa,mBAAoB,YAAW,cAAc;IACxD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAc;gBAEvB,IAAI,EAAE;QAAE,QAAQ,EAAE,WAAW,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE;IAS3D,8DAA8D;IAC9D,MAAM,CAAC,QAAQ,CAAC,KAAK,SAAuB,GAAG,MAAM;IAc/C,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;CAUtD"}