settld 0.1.0

package/services/finance-sink/src/ack-worker.js

@@ -0,0 +1,152 @@
+import { hmacSignArtifact } from "../../../src/core/artifacts.js";
+import { SETTLD_PROTOCOL_CURRENT } from "../../../src/core/protocol.js";
+
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+function computeBackoffMs({ attempts, baseMs = 1000, maxMs = 60_000, random = Math.random }) {
+  if (!Number.isInteger(attempts) || attempts <= 0) return baseMs;
+  const exp = Math.min(16, attempts);
+  const raw = Math.min(maxMs, baseMs * 2 ** exp);
+  const jitter = 0.8 + random() * 0.4;
+  return Math.max(baseMs, Math.floor(raw * jitter));
+}
+
+async function fetchWithTimeout(url, options, timeoutMs) {
+  const ms = Number(timeoutMs);
+  if (!Number.isFinite(ms) || ms <= 0) return await fetch(url, options);
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(new Error("timeout")), ms);
+  try {
+    return await fetch(url, { ...(options ?? {}), signal: controller.signal });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export function createAckWorker({ cfg, dedupeStore, metrics, logger }) {
+  if (!cfg || typeof cfg !== "object") throw new TypeError("cfg is required");
+  if (!dedupeStore) throw new TypeError("dedupeStore is required");
+
+  const ackUrl = cfg.ackUrl;
+  const tenantId = cfg.tenantId;
+  const destinationId = cfg.destinationId;
+  const secret = cfg.hmacSecret;
+  const timeoutMs = cfg.ack?.timeoutMs ?? 5000;
+  const maxInflight = cfg.ack?.maxInflight ?? 10;
+  const retryMax = cfg.ack?.retryMax ?? 50;
+
+  assertNonEmptyString(ackUrl, "FINANCE_SINK_ACK_URL");
+  assertNonEmptyString(tenantId, "FINANCE_SINK_TENANT_ID");
+  assertNonEmptyString(destinationId, "FINANCE_SINK_DESTINATION_ID");
+  assertNonEmptyString(secret, "FINANCE_SINK_HMAC_SECRET");
+
+  const inflight = new Set(); // dedupeKey
+  let stopped = false;
+
+  function metricInc(name, labels, value = 1) {
+    try {
+      metrics?.incCounter?.(name, labels, value);
+    } catch {}
+  }
+
+  function metricGauge(name, labels, value) {
+    try {
+      metrics?.setGauge?.(name, labels, value);
+    } catch {}
+  }
+
+  async function attemptAck({ record }) {
+    const dedupeKey = String(record.dedupeKey ?? "");
+    const artifactHash = String(record.artifactHash ?? "");
+    const deliveryId = record.deliveryId ?? null;
+    if (!deliveryId) throw new Error("missing deliveryId for ack");
+
+    const bodyJson = { deliveryId, artifactHash, receivedAt: new Date().toISOString() };
+    const timestamp = new Date().toISOString();
+    const signature = hmacSignArtifact({ secret, timestamp, bodyJson });
+
+    const res = await fetchWithTimeout(
+      ackUrl,
+      {
+        method: "POST",
+        headers: {
+          "content-type": "application/json; charset=utf-8",
+          "x-settld-protocol": SETTLD_PROTOCOL_CURRENT,
+          "x-proxy-tenant-id": tenantId,
+          "x-proxy-destination-id": destinationId,
+          "x-proxy-timestamp": timestamp,
+          "x-proxy-signature": signature,
+          "x-proxy-dedupe-key": dedupeKey
+        },
+        body: JSON.stringify(bodyJson)
+      },
+      timeoutMs
+    );
+
+    const ok = res.status >= 200 && res.status < 300;
+    if (!ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(text ? `http ${res.status}: ${text.slice(0, 200)}` : `http ${res.status}`);
+    }
+  }
+
+  async function tick() {
+    if (stopped) return;
+    metricGauge("finance_sink_inflight_acks_gauge", null, inflight.size);
+    if (inflight.size >= maxInflight) return;
+
+    const capacity = maxInflight - inflight.size;
+    const due = dedupeStore.listPendingAcks({ limit: capacity });
+    for (const record of due) {
+      const dedupeKey = String(record.dedupeKey ?? "");
+      if (!dedupeKey || inflight.has(dedupeKey)) continue;
+      inflight.add(dedupeKey);
+      const attempts = (Number.isSafeInteger(record.ackAttempts) ? record.ackAttempts : 0) + 1;
+      const artifactHash = String(record.artifactHash ?? "");
+      const deliveryId = String(record.deliveryId ?? "");
+      const p = (async () => {
+        try {
+          await attemptAck({ record });
+          await dedupeStore.markAckResult({ dedupeKey, artifactHash, deliveryId, ok: true, attempts, nextAttemptAt: null, error: null });
+          metricInc("finance_sink_ack_success_total", null, 1);
+          if (logger) logger.info("finance_sink.ack.ok", { dedupeKey, artifactHash, attempts });
+        } catch (err) {
+          const errMsg = err?.message ?? String(err);
+          metricInc("finance_sink_ack_failed_total", null, 1);
+          const permanent = attempts >= retryMax;
+          const delayMs = permanent ? 0 : computeBackoffMs({ attempts, baseMs: 1000, maxMs: 60_000 });
+          const nextAttemptAt = permanent ? null : new Date(Date.now() + delayMs).toISOString();
+          await dedupeStore.markAckResult({ dedupeKey, artifactHash, deliveryId, ok: false, attempts, nextAttemptAt, error: errMsg });
+          if (logger) logger.error("finance_sink.ack.failed", { dedupeKey, artifactHash, attempts, permanent, err });
+        } finally {
+          inflight.delete(dedupeKey);
+          metricGauge("finance_sink_inflight_acks_gauge", null, inflight.size);
+        }
+      })();
+      p.catch(() => {});
+    }
+  }
+
+  async function loop() {
+    while (!stopped) {
+      await tick();
+      await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+  }
+
+  return {
+    start() {
+      loop().catch((err) => {
+        try {
+          logger?.error?.("finance_sink.ack_worker.crashed", { err });
+        } catch {}
+      });
+    },
+    stop() {
+      stopped = true;
+    }
+  };
+}
+

package/services/finance-sink/src/config.js

@@ -0,0 +1,176 @@
+import fs from "node:fs/promises";
+
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+function parsePositiveIntEnv(name, fallback) {
+  const raw = typeof process !== "undefined" ? process.env[name] : null;
+  if (raw === null || raw === undefined || String(raw).trim() === "") return fallback;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || !Number.isSafeInteger(n) || n <= 0) throw new TypeError(`${name} must be a positive safe integer`);
+  return n;
+}
+
+function parseNonNegativeIntEnv(name, fallback) {
+  const raw = typeof process !== "undefined" ? process.env[name] : null;
+  if (raw === null || raw === undefined || String(raw).trim() === "") return fallback;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || !Number.isSafeInteger(n) || n < 0) throw new TypeError(`${name} must be a non-negative safe integer`);
+  return n;
+}
+
+function parseFlagEnv(name, fallback) {
+  const raw = typeof process !== "undefined" ? process.env[name] : null;
+  if (raw === null || raw === undefined || String(raw).trim() === "") return fallback;
+  const v = String(raw).trim();
+  if (v === "1") return true;
+  if (v === "0") return false;
+  throw new TypeError(`${name} must be 0 or 1`);
+}
+
+async function readSecretRef(ref) {
+  assertNonEmptyString(ref, "ref");
+  const text = String(ref).trim();
+  const idx = text.indexOf(":");
+  if (idx === -1) return { ok: false, code: "SECRET_REF_INVALID", message: "secret ref must be env:NAME or file:/path" };
+  const scheme = text.slice(0, idx);
+  const rest = text.slice(idx + 1);
+  if (scheme === "env") {
+    const key = rest.trim();
+    if (!key) return { ok: false, code: "SECRET_REF_INVALID", message: "env: requires a variable name" };
+    const v = typeof process !== "undefined" ? process.env[key] : null;
+    if (typeof v !== "string" || v.trim() === "") return { ok: false, code: "SECRET_NOT_FOUND", message: `env var ${key} is empty` };
+    return { ok: true, value: v.trim() };
+  }
+  if (scheme === "file") {
+    const filePath = rest.trim();
+    if (!filePath) return { ok: false, code: "SECRET_REF_INVALID", message: "file: requires a path" };
+    try {
+      const raw = await fs.readFile(filePath, "utf8");
+      const v = String(raw).replace(/\r?\n$/, "");
+      if (!v.trim()) return { ok: false, code: "SECRET_NOT_FOUND", message: "file secret is empty" };
+      return { ok: true, value: v };
+    } catch (err) {
+      return { ok: false, code: "SECRET_READ_FAILED", message: err?.message ?? "failed to read secret file" };
+    }
+  }
+  return { ok: false, code: "SECRET_PROVIDER_FORBIDDEN", message: `unsupported secret ref provider: ${scheme}` };
+}
+
+export async function loadConfig() {
+  const nodeEnv = typeof process !== "undefined" ? (process.env.NODE_ENV ?? "development") : "development";
+  const port = parsePositiveIntEnv("FINANCE_SINK_PORT", 4100);
+
+  const ackMaxInflight = Math.min(100, parsePositiveIntEnv("FINANCE_SINK_ACK_MAX_INFLIGHT", 10));
+  const ackRetryMax = Math.min(1000, parsePositiveIntEnv("FINANCE_SINK_ACK_RETRY_MAX", 50));
+  const ackTimeoutMs = parsePositiveIntEnv("FINANCE_SINK_ACK_TIMEOUT_MS", 5000);
+
+  const dedupeDbPath =
+    typeof process !== "undefined" ? (process.env.FINANCE_SINK_DEDUPE_DB_PATH ?? "./finance-sink-dedupe.jsonl") : "./finance-sink-dedupe.jsonl";
+
+  const tenantId = typeof process !== "undefined" ? (process.env.FINANCE_SINK_TENANT_ID ?? "tenant_default") : "tenant_default";
+  const destinationId = typeof process !== "undefined" ? (process.env.FINANCE_SINK_DESTINATION_ID ?? null) : null;
+  const ackUrl = typeof process !== "undefined" ? (process.env.FINANCE_SINK_ACK_URL ?? null) : null;
+
+  const allowInlineSecrets = parseFlagEnv("FINANCE_SINK_ALLOW_INLINE_SECRETS", nodeEnv !== "production");
+  const hmacSecretInline = typeof process !== "undefined" ? (process.env.FINANCE_SINK_HMAC_SECRET ?? null) : null;
+  const hmacSecretRef = typeof process !== "undefined" ? (process.env.FINANCE_SINK_HMAC_SECRET_REF ?? null) : null;
+
+  let hmacSecret = null;
+  if (allowInlineSecrets && typeof hmacSecretInline === "string" && hmacSecretInline.trim()) {
+    hmacSecret = hmacSecretInline.trim();
+  } else if (typeof hmacSecretRef === "string" && hmacSecretRef.trim()) {
+    const resolved = await readSecretRef(hmacSecretRef);
+    if (!resolved.ok) {
+      const err = new Error(resolved.message);
+      err.code = resolved.code;
+      throw err;
+    }
+    hmacSecret = resolved.value;
+  }
+
+  const s3Endpoint = typeof process !== "undefined" ? (process.env.FINANCE_SINK_S3_ENDPOINT ?? null) : null;
+  const s3Region = typeof process !== "undefined" ? (process.env.FINANCE_SINK_S3_REGION ?? "us-east-1") : "us-east-1";
+  const s3Bucket = typeof process !== "undefined" ? (process.env.FINANCE_SINK_S3_BUCKET ?? null) : null;
+  const s3Prefix = typeof process !== "undefined" ? (process.env.FINANCE_SINK_S3_PREFIX ?? "finance/") : "finance/";
+  const s3ForcePathStyle = parseFlagEnv("FINANCE_SINK_S3_FORCE_PATH_STYLE", true);
+
+  const s3AccessKeyIdInline = typeof process !== "undefined" ? (process.env.FINANCE_SINK_S3_ACCESS_KEY_ID ?? null) : null;
+  const s3SecretAccessKeyInline = typeof process !== "undefined" ? (process.env.FINANCE_SINK_S3_SECRET_ACCESS_KEY ?? null) : null;
+  const s3AccessKeyIdRef = typeof process !== "undefined" ? (process.env.FINANCE_SINK_S3_ACCESS_KEY_ID_REF ?? null) : null;
+  const s3SecretAccessKeyRef = typeof process !== "undefined" ? (process.env.FINANCE_SINK_S3_SECRET_ACCESS_KEY_REF ?? null) : null;
+
+  let s3AccessKeyId = null;
+  if (allowInlineSecrets && typeof s3AccessKeyIdInline === "string" && s3AccessKeyIdInline.trim()) {
+    s3AccessKeyId = s3AccessKeyIdInline.trim();
+  } else if (typeof s3AccessKeyIdRef === "string" && s3AccessKeyIdRef.trim()) {
+    const resolved = await readSecretRef(s3AccessKeyIdRef);
+    if (!resolved.ok) {
+      const err = new Error(resolved.message);
+      err.code = resolved.code;
+      throw err;
+    }
+    s3AccessKeyId = resolved.value;
+  }
+
+  let s3SecretAccessKey = null;
+  if (allowInlineSecrets && typeof s3SecretAccessKeyInline === "string" && s3SecretAccessKeyInline.trim()) {
+    s3SecretAccessKey = s3SecretAccessKeyInline.trim();
+  } else if (typeof s3SecretAccessKeyRef === "string" && s3SecretAccessKeyRef.trim()) {
+    const resolved = await readSecretRef(s3SecretAccessKeyRef);
+    if (!resolved.ok) {
+      const err = new Error(resolved.message);
+      err.code = resolved.code;
+      throw err;
+    }
+    s3SecretAccessKey = resolved.value;
+  }
+
+  const testDelayFirstResponseMs = nodeEnv === "test" ? parseNonNegativeIntEnv("FINANCE_SINK_TEST_DELAY_FIRST_RESPONSE_MS", 0) : 0;
+
+  return {
+    nodeEnv,
+    port,
+    tenantId,
+    destinationId,
+    ackUrl,
+    hmacSecret,
+    allowInlineSecrets,
+    dedupeDbPath,
+    ack: {
+      maxInflight: ackMaxInflight,
+      retryMax: ackRetryMax,
+      timeoutMs: ackTimeoutMs
+    },
+    s3: {
+      endpoint: s3Endpoint,
+      region: s3Region,
+      bucket: s3Bucket,
+      prefix: s3Prefix,
+      forcePathStyle: s3ForcePathStyle,
+      accessKeyId: s3AccessKeyId,
+      secretAccessKey: s3SecretAccessKey
+    },
+    test: {
+      delayFirstResponseMs: testDelayFirstResponseMs
+    }
+  };
+}
+
+export function validateConfigForReady(cfg) {
+  if (!cfg || typeof cfg !== "object") throw new TypeError("cfg is required");
+  assertNonEmptyString(cfg.tenantId, "FINANCE_SINK_TENANT_ID");
+  assertNonEmptyString(cfg.destinationId, "FINANCE_SINK_DESTINATION_ID");
+  assertNonEmptyString(cfg.ackUrl, "FINANCE_SINK_ACK_URL");
+  assertNonEmptyString(cfg.hmacSecret, "FINANCE_SINK_HMAC_SECRET[_REF]");
+
+  const s3 = cfg.s3 ?? {};
+  assertNonEmptyString(s3.endpoint, "FINANCE_SINK_S3_ENDPOINT");
+  assertNonEmptyString(s3.region, "FINANCE_SINK_S3_REGION");
+  assertNonEmptyString(s3.bucket, "FINANCE_SINK_S3_BUCKET");
+  assertNonEmptyString(s3.prefix, "FINANCE_SINK_S3_PREFIX");
+  assertNonEmptyString(s3.accessKeyId, "FINANCE_SINK_S3_ACCESS_KEY_ID[_REF]");
+  assertNonEmptyString(s3.secretAccessKey, "FINANCE_SINK_S3_SECRET_ACCESS_KEY[_REF]");
+}
+

package/services/finance-sink/src/dedupe-store.js

@@ -0,0 +1,232 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+function safeJsonParse(line) {
+  try {
+    return JSON.parse(line);
+  } catch {
+    return null;
+  }
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+export class DedupeStore {
+  constructor({ filePath }) {
+    assertNonEmptyString(filePath, "filePath");
+    this.filePath = filePath;
+    this.records = new Map(); // dedupeKey -> record
+    this._appendQueue = Promise.resolve();
+  }
+
+  async init() {
+    await fs.mkdir(path.dirname(this.filePath), { recursive: true });
+    let raw = "";
+    try {
+      raw = await fs.readFile(this.filePath, "utf8");
+    } catch (err) {
+      if (err?.code !== "ENOENT") throw err;
+      raw = "";
+    }
+
+    const lines = raw.split("\n").filter((l) => l.trim() !== "");
+    for (const line of lines) {
+      const evt = safeJsonParse(line);
+      if (!evt || typeof evt !== "object") continue;
+      const k = typeof evt.dedupeKey === "string" ? evt.dedupeKey : null;
+      if (!k) continue;
+      const type = typeof evt.type === "string" ? evt.type : null;
+      const existing =
+        this.records.get(k) ??
+        ({
+          dedupeKey: k,
+          artifactHash: null,
+          deliveryId: null,
+          storedAt: null,
+          ackedAt: null,
+          ackAttempts: 0,
+          ackNextAttemptAt: null,
+          lastAckError: null
+        });
+      if (type === "RECEIVED") {
+        this.records.set(k, {
+          ...existing,
+          artifactHash: evt.artifactHash ?? existing.artifactHash ?? null,
+          deliveryId: evt.deliveryId ?? existing.deliveryId ?? null,
+          receivedAt: evt.at ?? existing.receivedAt ?? null
+        });
+        continue;
+      }
+      if (type === "STORED") {
+        this.records.set(k, {
+          ...existing,
+          artifactHash: evt.artifactHash ?? existing.artifactHash ?? null,
+          deliveryId: evt.deliveryId ?? existing.deliveryId ?? null,
+          storedAt: evt.at ?? existing.storedAt ?? null
+        });
+        continue;
+      }
+      if (type === "ACK_QUEUED") {
+        this.records.set(k, {
+          ...existing,
+          artifactHash: evt.artifactHash ?? existing.artifactHash ?? null,
+          deliveryId: evt.deliveryId ?? existing.deliveryId ?? null,
+          ackNextAttemptAt: evt.nextAttemptAt ?? evt.at ?? existing.ackNextAttemptAt ?? null,
+          lastAckError: null
+        });
+        continue;
+      }
+      if (type === "ACK_RESULT") {
+        const ok = evt.ok === true;
+        this.records.set(k, {
+          ...existing,
+          artifactHash: evt.artifactHash ?? existing.artifactHash ?? null,
+          deliveryId: evt.deliveryId ?? existing.deliveryId ?? null,
+          ackedAt: ok ? (evt.at ?? existing.ackedAt ?? null) : existing.ackedAt ?? null,
+          ackAttempts: Number.isSafeInteger(evt.attempts) ? evt.attempts : existing.ackAttempts ?? 0,
+          ackNextAttemptAt: ok ? null : (evt.nextAttemptAt ?? existing.ackNextAttemptAt ?? null),
+          lastAckError: ok ? null : (evt.error ?? existing.lastAckError ?? null)
+        });
+      }
+    }
+  }
+
+  get(dedupeKey) {
+    assertNonEmptyString(dedupeKey, "dedupeKey");
+    return this.records.get(dedupeKey) ?? null;
+  }
+
+  async appendEvent(evt) {
+    if (!evt || typeof evt !== "object") throw new TypeError("evt must be an object");
+    const line = `${JSON.stringify(evt)}\n`;
+    this._appendQueue = this._appendQueue.then(() => fs.appendFile(this.filePath, line, "utf8"));
+    return await this._appendQueue;
+  }
+
+  async ensureReceived({ dedupeKey, artifactHash }) {
+    assertNonEmptyString(dedupeKey, "dedupeKey");
+    assertNonEmptyString(artifactHash, "artifactHash");
+    const existing = this.records.get(dedupeKey) ?? null;
+    if (existing) return existing;
+    const at = nowIso();
+    const record = {
+      dedupeKey,
+      artifactHash,
+      deliveryId: null,
+      receivedAt: at,
+      storedAt: null,
+      ackedAt: null,
+      ackAttempts: 0,
+      ackNextAttemptAt: null,
+      lastAckError: null
+    };
+    this.records.set(dedupeKey, record);
+    await this.appendEvent({ type: "RECEIVED", dedupeKey, artifactHash, deliveryId: null, at });
+    return record;
+  }
+
+  async touchDeliveryId({ dedupeKey, artifactHash, deliveryId }) {
+    assertNonEmptyString(dedupeKey, "dedupeKey");
+    assertNonEmptyString(artifactHash, "artifactHash");
+    assertNonEmptyString(deliveryId, "deliveryId");
+    const at = nowIso();
+    const existing =
+      this.records.get(dedupeKey) ??
+      ({
+        dedupeKey,
+        artifactHash,
+        deliveryId: null,
+        receivedAt: null,
+        storedAt: null,
+        ackedAt: null,
+        ackAttempts: 0,
+        ackNextAttemptAt: null,
+        lastAckError: null
+      });
+    const next = { ...existing, artifactHash, deliveryId };
+    this.records.set(dedupeKey, next);
+    await this.appendEvent({ type: "RECEIVED", dedupeKey, artifactHash, deliveryId, at });
+    return next;
+  }
+
+  async markStored({ dedupeKey, artifactHash, deliveryId = null }) {
+    assertNonEmptyString(dedupeKey, "dedupeKey");
+    assertNonEmptyString(artifactHash, "artifactHash");
+    const at = nowIso();
+    const existing =
+      this.records.get(dedupeKey) ??
+      ({ dedupeKey, artifactHash, deliveryId: null, receivedAt: null, storedAt: null, ackedAt: null, ackAttempts: 0, ackNextAttemptAt: null, lastAckError: null });
+    const next = { ...existing, artifactHash, deliveryId: deliveryId ?? existing.deliveryId ?? null, storedAt: at };
+    this.records.set(dedupeKey, next);
+    await this.appendEvent({ type: "STORED", dedupeKey, artifactHash, deliveryId: next.deliveryId ?? null, at });
+    return next;
+  }
+
+  async markAckQueued({ dedupeKey, artifactHash, deliveryId = null, nextAttemptAt = null }) {
+    assertNonEmptyString(dedupeKey, "dedupeKey");
+    assertNonEmptyString(artifactHash, "artifactHash");
+    const at = nowIso();
+    const existing =
+      this.records.get(dedupeKey) ??
+      ({ dedupeKey, artifactHash, deliveryId: null, receivedAt: null, storedAt: null, ackedAt: null, ackAttempts: 0, ackNextAttemptAt: null, lastAckError: null });
+    const nextAt = nextAttemptAt ? new Date(String(nextAttemptAt)).toISOString() : at;
+    const next = { ...existing, artifactHash, deliveryId: deliveryId ?? existing.deliveryId ?? null, ackNextAttemptAt: nextAt, lastAckError: null };
+    this.records.set(dedupeKey, next);
+    await this.appendEvent({ type: "ACK_QUEUED", dedupeKey, artifactHash, deliveryId: next.deliveryId ?? null, at, nextAttemptAt: nextAt });
+    return next;
+  }
+
+  async markAckResult({ dedupeKey, artifactHash, deliveryId = null, ok, attempts, nextAttemptAt, error }) {
+    assertNonEmptyString(dedupeKey, "dedupeKey");
+    assertNonEmptyString(artifactHash, "artifactHash");
+    const at = nowIso();
+    const existing =
+      this.records.get(dedupeKey) ??
+      ({ dedupeKey, artifactHash, deliveryId: null, receivedAt: null, storedAt: null, ackedAt: null, ackAttempts: 0, ackNextAttemptAt: null, lastAckError: null });
+
+    const next = ok
+      ? { ...existing, artifactHash, deliveryId: deliveryId ?? existing.deliveryId ?? null, ackedAt: at, ackAttempts: attempts, ackNextAttemptAt: null, lastAckError: null }
+      : {
+          ...existing,
+          artifactHash,
+          deliveryId: deliveryId ?? existing.deliveryId ?? null,
+          ackAttempts: attempts,
+          ackNextAttemptAt: nextAttemptAt ?? null,
+          lastAckError: error ?? "ack_failed"
+        };
+    this.records.set(dedupeKey, next);
+    await this.appendEvent({
+      type: "ACK_RESULT",
+      dedupeKey,
+      artifactHash,
+      deliveryId: next.deliveryId ?? null,
+      ok: ok === true,
+      attempts,
+      nextAttemptAt: ok ? null : (nextAttemptAt ?? null),
+      error: ok ? null : (error ?? null),
+      at
+    });
+    return next;
+  }
+
+  listPendingAcks({ nowMs = Date.now(), limit = 50 } = {}) {
+    const out = [];
+    for (const r of this.records.values()) {
+      if (!r || typeof r !== "object") continue;
+      if (r.ackedAt) continue;
+      const nextAt = r.ackNextAttemptAt ? Date.parse(r.ackNextAttemptAt) : null;
+      if (nextAt && Number.isFinite(nextAt) && nextAt > nowMs) continue;
+      out.push(r);
+      if (out.length >= limit) break;
+    }
+    out.sort((a, b) => String(a.ackNextAttemptAt ?? "").localeCompare(String(b.ackNextAttemptAt ?? "")));
+    return out;
+  }
+}
+