@xyo-network/event-kit-node 1.0.0 → 2.1.0

package/dist/node/runtime.mjs

@@ -141,6 +141,7 @@ function createBoundedPublisherEthersTransport(options = {}) {
 }
 
 // src/runtime/handshakeDiscovery.ts
+import { isDeepStrictEqual } from "node:util";
 import { decryptWakeSubscription, sourceWakeFilterHash } from "@xyo-network/event-kit-protocol";
 import { EndpointChallengeResponseZod } from "@xyo-network/event-kit-schemas";
 function createPublisherHandshakeDiscovery(options) {
@@ -156,6 +157,9 @@ function createPublisherHandshakeDiscovery(options) {
     rejectedSubscriptions: 0,
     challengeFailures: 0
   };
+  function selectedTuple(tuple) {
+    return (options.serviceHash === void 0 || tuple.service.objectHash === options.serviceHash) && (options.deliveryMode === void 0 || tuple.service.body.deliveryMode === options.deliveryMode) && (options.deliveryMode === void 0 || tuple.subscription.body.deliveryMode === options.deliveryMode) && (options.deliveryMode === void 0 || isDeepStrictEqual(tuple.service.body.bestEffort, options.bestEffort));
+  }
   async function activeView(signal) {
     signal.throwIfAborted();
     viewing ??= (async () => {
@@ -173,7 +177,7 @@ function createPublisherHandshakeDiscovery(options) {
       ...status,
       finalizedHead: view.finalizedHead,
       indexedThrough: view.indexedThrough,
-      pendingSubscriptions: view.subscriptions.filter((item) => item.state === "pending").length,
+      pendingSubscriptions: view.subscriptions.filter((item) => item.state === "pending" && item.tuples.some(selectedTuple)).length,
       rejectedSubscriptions: view.rejections.length
     };
     return view;
@@ -238,7 +242,7 @@ function createPublisherHandshakeDiscovery(options) {
     if (!found.ok)
       throw new Error("Publisher acceptance candidates are unavailable");
     const offset = options.state.get("challenge-rate", "offset") ?? 0;
-    const candidates = found.candidates;
+    const candidates = found.candidates.filter((candidate) => selectedTuple(candidate.tuple));
     let attempted = 0;
     for (let index = 0; index < Math.min(candidates.length, 128) && attempted < 4; index += 1) {
       const candidate = candidates[(offset + index) % candidates.length];
@@ -254,30 +258,40 @@ function createPublisherHandshakeDiscovery(options) {
       await acceptCandidate(candidate.subscriber, candidate.tuple.subscription.objectHash, signal);
     }
   }
+  async function loadScopedKeys(view, active) {
+    const scopedKeys = active.flatMap((item) => item.tuples.filter((tuple) => tuple.subscription.objectHash === item.selectedSubscription).map((tuple) => ({
+      encryptionKey: tuple.subscription.body.encryptionKey,
+      keyId: tuple.subscription.body.keyId,
+      publisher: options.publisher
+    })));
+    if (view.hasCurrentAdvertisement && (options.serviceHash === void 0 || view.service.objectHash === options.serviceHash) && (options.deliveryMode === void 0 || view.service.body.deliveryMode === options.deliveryMode)) {
+      scopedKeys.push({
+        encryptionKey: view.key.objectHash,
+        keyId: view.key.body.keyId,
+        publisher: options.publisher
+      });
+    }
+    const loadedKeys = await Promise.all(scopedKeys.map(async (key) => await options.keys.getPrivateKey(key)));
+    status = {
+      ...status,
+      keyLoaded: scopedKeys.length > 0 && loadedKeys.every((key) => key !== void 0),
+      activeKeyIds: [...new Set(scopedKeys.map((key) => key.keyId))]
+    };
+  }
   return {
     async discover(signal) {
       const view = await activeView(signal);
-      const key = view.hasCurrentAdvertisement ? view.key : void 0;
-      const loaded = key === void 0 ? void 0 : await options.keys.getPrivateKey({
-        encryptionKey: key.objectHash,
-        keyId: key.body.keyId,
-        publisher: options.publisher
-      });
-      status = {
-        ...status,
-        keyLoaded: loaded !== void 0,
-        activeKeyIds: key === void 0 ? [] : [key.body.keyId]
-      };
-      const subscriptions = [];
-      const active = view.subscriptions.filter((item) => item.state === "active");
+      const active = view.subscriptions.filter((item) => item.state === "active" && item.tuples.some((tuple) => tuple.subscription.objectHash === item.selectedSubscription && selectedTuple(tuple)));
+      await loadScopedKeys(view, active);
       if (active.length > (options.maxSubscriptions ?? 64))
         throw new Error("Publisher active subscription limit exceeded");
+      const subscriptions = [];
       for (const lifecycle of active) {
         if (lifecycle.state !== "active" || lifecycle.activeFromBlock === void 0)
           continue;
         try {
           const tuple = lifecycle.tuples.find((item) => item.subscription.objectHash === lifecycle.selectedSubscription);
-          if (tuple === void 0)
+          if (tuple === void 0 || !selectedTuple(tuple))
             throw new Error("Active publisher subscription has no selected tuple");
           const encrypted = tuple.subscription.body;
           if (encrypted.chainId !== options.authorizationChainId)
@@ -297,6 +311,9 @@ function createPublisherHandshakeDiscovery(options) {
           options.transport.assertAllowed(plaintext.endpoint);
           subscriptions.push({
             subscriptionHash: tuple.subscription.objectHash,
+            serviceHash: tuple.service.objectHash,
+            deliveryMode: plaintext.filter.deliveryMode,
+            ...plaintext.filter.bestEffort === void 0 ? {} : { bestEffort: plaintext.filter.bestEffort },
             authorizationChainId: options.authorizationChainId,
             controller: tuple.subscriber,
             audience: plaintext.audience,
@@ -316,7 +333,7 @@ function createPublisherHandshakeDiscovery(options) {
     },
     async isActive(subscription, signal) {
       const view = await activeView(signal);
-      return view.subscriptions.some((item) => item.state === "active" && item.selectedSubscription === subscription.subscriptionHash && item.tuples.some((tuple) => tuple.subscription.objectHash === subscription.subscriptionHash && tuple.subscriber === subscription.controller));
+      return view.subscriptions.some((item) => item.state === "active" && item.selectedSubscription === subscription.subscriptionHash && item.tuples.some((tuple) => tuple.subscription.objectHash === subscription.subscriptionHash && tuple.subscriber === subscription.controller && selectedTuple(tuple)));
     },
     async acceptPending(signal) {
       if (accepting === void 0) {
@@ -535,11 +552,7 @@ function loadPublisherAddressPolicy() {
 }
 function isPublicPublisherAddress(address) {
   const policy = loadPublisherAddressPolicy();
-  if (isIP(address) === 4)
-    return !policy.nonPublicIpv4.check(address, "ipv4");
-  if (isIP(address) !== 6)
-    return false;
-  return policy.globalIpv6.check(address, "ipv6") && !policy.nonPublicIpv6.check(address, "ipv6");
+  return isIP(address) === 4 ? !policy.nonPublicIpv4.check(address, "ipv4") : isIP(address) === 6 && policy.globalIpv6.check(address, "ipv6") && !policy.nonPublicIpv6.check(address, "ipv6");
 }
 function createPublisherHttpsTransport(input) {
   const parsed = OptionsZod.safeParse(input);
@@ -646,18 +659,128 @@ function createPublisherHttpsTransport(input) {
 }
 
 // src/runtime/publisherRuntime.ts
-import { randomBytes as randomBytes2 } from "node:crypto";
-import { isDeepStrictEqual } from "node:util";
+import { isDeepStrictEqual as isDeepStrictEqual3 } from "node:util";
 import { createMemoryLocator, PeriodicActor } from "@ariestools/actor";
 import { creatable } from "@ariestools/sdk";
-import { WakeEnvelopeSchema, WakeEnvelopeZod as WakeEnvelopeZod2 } from "@xyo-network/event-kit-schemas";
+import { BestEffortAdmissionAcknowledgmentZod } from "@xyo-network/event-kit-protocol";
+import { BestEffortDeliveryPolicyZod, WakeDeliveryModeZod } from "@xyo-network/event-kit-schemas";
 import { z as z2 } from "zod";
 
-// src/runtime/sourceSigner.ts
+// src/runtime/publisherDeliveryState.ts
 import { randomBytes } from "node:crypto";
+import { isDeepStrictEqual as isDeepStrictEqual2 } from "node:util";
+import { WakeEnvelopeSchema, WakeEnvelopeZod } from "@xyo-network/event-kit-schemas";
+function assertDeliveryState(record, subscription) {
+  if (!isDeepStrictEqual2(record.subscription, subscription))
+    throw new Error("Subscription revision changed without a new identity");
+  if (!Number.isSafeInteger(record.cursor) || record.cursor < subscription.fromPosition - 1 || [record.delivered, record.failures, record.nextAttemptMs].some((value) => !(Number.isSafeInteger(value) && value >= 0)) || [record.attempts, record.superseded, record.abandoned, record.totalAttempts, record.lastHintAt, record.lastNotifiedAt, record.lastHintTarget].some((value) => value !== void 0 && !(Number.isSafeInteger(value) && value >= 0)) || !["active", "blocked", "cancelled"].includes(record.state))
+    throw new Error("Persisted publisher delivery state is invalid");
+  if (record.pending === void 0) return;
+  const pending = WakeEnvelopeZod.parse(record.pending);
+  if (subscription.deliveryMode === "durable" && pending.fromPosition !== record.cursor + 1 || pending.deliveryMode !== subscription.deliveryMode || pending.toPosition - pending.fromPosition + 1 > subscription.maxPositionsPerWake || pending.authorizationChainId !== subscription.authorizationChainId || pending.deploymentId !== subscription.deploymentId || pending.queueId !== subscription.queueId || pending.filterHash !== subscription.filterHash || !isDeepStrictEqual2(pending.source, subscription.source))
+    throw new Error("Persisted publisher outbox binding is invalid");
+}
+function makeEvent(subscription, fromPosition, toPosition, now, wakeId = randomBytes(16).toString("hex")) {
+  return WakeEnvelopeZod.parse({
+    schema: WakeEnvelopeSchema,
+    authorizationChainId: subscription.authorizationChainId,
+    deliveryMode: subscription.deliveryMode,
+    deploymentId: subscription.deploymentId,
+    filterHash: subscription.filterHash,
+    fromPosition,
+    issuedAt: now,
+    source: subscription.source,
+    toPosition,
+    wakeId,
+    ...subscription.queueId === void 0 ? {} : { queueId: subscription.queueId }
+  });
+}
+var DeliveryResponseError = class extends Error {
+  retryAfterMs;
+  status;
+  constructor(status, retryAfterMs) {
+    super("Publisher admission failed");
+    this.status = status;
+    this.retryAfterMs = retryAfterMs;
+  }
+  get retryable() {
+    return this.status === 408 || this.status === 429 || this.status >= 500;
+  }
+};
+function prepareBestEffortDelivery(options) {
+  const {
+    bestEffort,
+    first,
+    heads,
+    now,
+    record,
+    state
+  } = options;
+  const subscription = record.subscription;
+  const head = heads.get(publisherSourceKey(subscription.source));
+  const prior = record.pending;
+  const expired = isHintExpired(record, now, bestEffort);
+  if (head === void 0 || head instanceof Error || head.position < subscription.fromPosition) {
+    if (prior !== void 0 && !expired) return { ...record, pending: prior };
+    if (prior !== void 0) state.set("best-effort-deliveries", subscription.subscriptionHash, {
+      ...record,
+      pending: void 0,
+      abandoned: (record.abandoned ?? 0) + 1
+    });
+    return;
+  }
+  const refresh = refreshDue(record, now, bestEffort);
+  if (freshHintRequired(record, head.position, first, refresh, expired)) {
+    const pending = makeEvent(subscription, head.position, head.position, now);
+    const prepared = {
+      ...record,
+      pending,
+      attempts: 0,
+      lastHintAt: now,
+      lastHintTarget: head.position,
+      superseded: (record.superseded ?? 0) + (prior !== void 0 && !expired ? 1 : 0),
+      abandoned: (record.abandoned ?? 0) + (expired ? 1 : 0),
+      nextAttemptMs: 0,
+      state: "active"
+    };
+    state.set("best-effort-deliveries", subscription.subscriptionHash, prepared);
+    return prepared;
+  }
+  if (expired) state.set("best-effort-deliveries", subscription.subscriptionHash, {
+    ...record,
+    pending: void 0,
+    abandoned: (record.abandoned ?? 0) + 1
+  });
+  return prior === void 0 || expired ? void 0 : { ...record, pending: prior };
+}
+function isHintExpired(record, now, policy) {
+  return record.pending !== void 0 && (now > record.pending.issuedAt + policy.maxHintAgeSeconds || (record.attempts ?? 0) >= policy.maxAttempts);
+}
+function refreshDue(record, now, policy) {
+  return now - (record.lastHintAt ?? record.lastNotifiedAt ?? 0) >= policy.refreshIntervalSeconds;
+}
+function freshHintRequired(record, head, first, refresh, expired) {
+  return first || head > (record.pending?.toPosition ?? record.lastHintTarget ?? record.cursor) || refresh && (record.pending === void 0 || expired);
+}
+function failedDelivery(record, current, mode, error, now) {
+  const bestEffort = mode === "best-effort";
+  const wait = error instanceof DeliveryResponseError && error.retryAfterMs !== void 0 ? error.retryAfterMs : Math.min(3e5, 1e3 * 2 ** Math.min(record.failures, 8));
+  return {
+    ...record,
+    failures: record.failures + 1,
+    totalAttempts: bestEffort ? current?.totalAttempts ?? record.totalAttempts ?? 0 : record.totalAttempts,
+    attempts: bestEffort ? current?.attempts ?? record.attempts ?? 0 : record.attempts,
+    state: !bestEffort && error instanceof DeliveryResponseError && !error.retryable ? "blocked" : "active",
+    nextAttemptMs: now * 1e3 + Math.min(36e5, wait),
+    lastError: "delivery-failed"
+  };
+}
+
+// src/runtime/sourceSigner.ts
+import { randomBytes as randomBytes2 } from "node:crypto";
 import {
   NormalizedAddressZod,
-  WakeEnvelopeZod,
+  WakeEnvelopeZod as WakeEnvelopeZod2,
   WakeJwtSchema
 } from "@xyo-network/event-kit-schemas";
 import { PayloadBuilder as PayloadBuilder2 } from "@xyo-network/sdk";
@@ -667,14 +790,14 @@ function createAccountSourceWakeSigner(options) {
     throw new Error("Publisher signing account mismatch");
   return {
     async sign(input, audience) {
-      const event = WakeEnvelopeZod.parse(input);
+      const event = WakeEnvelopeZod2.parse(input);
       const eventHash = await PayloadBuilder2.dataHash(event);
       const now = options.nowSeconds?.() ?? Math.floor(Date.now() / 1e3);
       if (!Number.isSafeInteger(now) || now < 0)
         throw new Error("Publisher signing clock is invalid");
       const { token: jwt } = await options.account.signJwt({
         audience,
-        claims: { eventHash, jti: randomBytes(16).toString("hex") },
+        claims: { eventHash, jti: randomBytes2(16).toString("hex") },
         now,
         schema: WakeJwtSchema,
         ttl: 60
@@ -693,31 +816,6 @@ function createAccountSourceWakeSigner(options) {
 function activationReady(status) {
   return (status?.keyLoaded ?? true) && (status?.pendingSubscriptions ?? 0) === 0;
 }
-function assertDeliveryState(record, subscription) {
-  if (!isDeepStrictEqual(record.subscription, subscription))
-    throw new Error("Subscription revision changed without a new identity");
-  if (!Number.isSafeInteger(record.cursor) || record.cursor < subscription.fromPosition - 1 || [record.delivered, record.failures, record.nextAttemptMs].some((value) => !(Number.isSafeInteger(value) && value >= 0)) || !["active", "blocked", "cancelled"].includes(record.state))
-    throw new Error("Persisted publisher delivery state is invalid");
-  if (record.pending !== void 0) {
-    const pending = WakeEnvelopeZod2.parse(record.pending);
-    if (pending.fromPosition !== record.cursor + 1 || pending.toPosition - pending.fromPosition + 1 > subscription.maxPositionsPerWake || pending.authorizationChainId !== subscription.authorizationChainId || pending.deploymentId !== subscription.deploymentId || pending.queueId !== subscription.queueId || pending.filterHash !== subscription.filterHash || !isDeepStrictEqual(pending.source, subscription.source))
-      throw new Error("Persisted publisher outbox binding is invalid");
-  }
-}
-function makeEvent(subscription, fromPosition, toPosition, now, wakeId = randomBytes2(16).toString("hex")) {
-  return WakeEnvelopeZod2.parse({
-    schema: WakeEnvelopeSchema,
-    authorizationChainId: subscription.authorizationChainId,
-    deploymentId: subscription.deploymentId,
-    filterHash: subscription.filterHash,
-    fromPosition,
-    issuedAt: now,
-    source: subscription.source,
-    toPosition,
-    wakeId,
-    ...subscription.queueId === void 0 ? {} : { queueId: subscription.queueId }
-  });
-}
 var PublisherRuntimeActor = class extends PeriodicActor {
   async runPass(context) {
     await this.params.tick(context.signal);
@@ -732,20 +830,24 @@ var TimingZod = z2.object({
   maxSubscriptions: z2.number().int().min(1).max(1024).default(64),
   requestTimeoutMs: z2.number().int().min(100).max(6e4).default(1e4)
 });
-var DeliveryResponseError = class extends Error {
-  retryAfterMs;
-  status;
-  constructor(status, retryAfterMs) {
-    super("Publisher admission failed");
-    this.status = status;
-    this.retryAfterMs = retryAfterMs;
-  }
-  get retryable() {
-    return this.status === 408 || this.status === 429 || this.status >= 500;
-  }
-};
+function runtimeSettings(options) {
+  const deliveryMode = WakeDeliveryModeZod.parse(options.deliveryMode);
+  const bestEffort = options.bestEffort === void 0 ? void 0 : BestEffortDeliveryPolicyZod.parse(options.bestEffort);
+  if (deliveryMode === "best-effort" !== (bestEffort !== void 0)) throw new TypeError("Explicit delivery mode requires its exact policy");
+  return {
+    bestEffort,
+    deliveryMode,
+    deliveryNamespace: deliveryMode === "best-effort" ? "best-effort-deliveries" : "deliveries",
+    timing: TimingZod.parse(options)
+  };
+}
 async function createPersistentEventPublisherRuntime(options) {
-  const timing = TimingZod.parse(options);
+  const {
+    bestEffort,
+    deliveryMode,
+    deliveryNamespace,
+    timing
+  } = runtimeSettings(options);
   if (options.sources.length < 1 || options.sources.length > 16)
     throw new Error("Publisher requires between one and sixteen bounded sources");
   const clock = options.nowSeconds ?? (() => Math.floor(Date.now() / 1e3));
@@ -757,7 +859,12 @@ async function createPersistentEventPublisherRuntime(options) {
   const sourceReaders = new Map(options.sources.map((reader) => [publisherSourceKey(reader.source), reader]));
   if (sourceReaders.size !== options.sources.length)
     throw new Error("Duplicate publisher source identity");
+  const state = options.state;
+  const existingMode = state.get("metadata", "runtime-delivery-mode");
+  if (existingMode !== void 0 && existingMode !== deliveryMode) throw new Error("Publisher state delivery mode mismatch; preserve custody and use an explicitly qualified state binding");
+  state.set("metadata", "runtime-delivery-mode", deliveryMode);
   const abort = new AbortController();
+  const seenThisProcess = /* @__PURE__ */ new Set();
   let running = false;
   let ready = false;
   let clockHealthy = true;
@@ -765,11 +872,16 @@ async function createPersistentEventPublisherRuntime(options) {
   let lastError;
   let sourcesHealthy = false;
   let stop;
-  const state = options.state;
   const timed = (promise, signal) => boundedPublisherOperation(promise, signal, timing.requestTimeoutMs);
   function loadDelivery(subscription, now) {
+    if (subscription.deliveryMode !== deliveryMode || !isDeepStrictEqual3(subscription.bestEffort, bestEffort))
+      throw new Error("Subscription delivery mode or policy disagrees with runtime");
+    if (deliveryMode === "best-effort" && (subscription.maxPositionsPerWake !== 1 || subscription.serviceHash === void 0)) throw new Error("Best Effort requires point range");
+    if (options.serviceHash !== void 0 && subscription.serviceHash !== options.serviceHash)
+      throw new Error("Subscription does not match the configured exact service descriptor");
     const key = subscription.subscriptionHash;
-    let record = state.get("deliveries", key);
+    if (deliveryMode === "best-effort" && state.get(deliveryNamespace, key) === void 0 && state.entries(deliveryNamespace).length >= timing.maxSubscriptions) throw new Error("Best Effort state capacity exceeded; live records are not evicted");
+    let record = state.get(deliveryNamespace, key);
     if (record === void 0) {
       makeEvent(subscription, subscription.fromPosition, subscription.fromPosition, now, "0".repeat(32));
       if (!Number.isSafeInteger(subscription.maxPositionsPerWake) || subscription.maxPositionsPerWake < 1 || subscription.maxPositionsPerWake > 4096) {
@@ -783,12 +895,26 @@ async function createPersistentEventPublisherRuntime(options) {
         nextAttemptMs: 0,
         state: "active"
       };
-      state.set("deliveries", key, record);
+      state.set(deliveryNamespace, key, record);
     }
     assertDeliveryState(record, subscription);
     return record;
   }
   function prepareDelivery(record, now, heads) {
+    if (deliveryMode === "best-effort" && bestEffort !== void 0) {
+      const first = !seenThisProcess.has(record.subscription.subscriptionHash);
+      const head2 = heads.get(publisherSourceKey(record.subscription.source));
+      if (head2 !== void 0 && !(head2 instanceof Error) && head2.position >= record.subscription.fromPosition)
+        seenThisProcess.add(record.subscription.subscriptionHash);
+      return prepareBestEffortDelivery({
+        bestEffort,
+        first,
+        heads,
+        now,
+        record,
+        state
+      });
+    }
     if (record.pending !== void 0) return { ...record, pending: record.pending };
     const subscription = record.subscription;
     const head = heads.get(publisherSourceKey(subscription.source));
@@ -800,43 +926,74 @@ async function createPersistentEventPublisherRuntime(options) {
     state.transaction(() => {
       const logicalKey = JSON.stringify([subscription.subscriptionHash, pending.fromPosition, pending.toPosition]);
       if (!state.insert("delivery-events", logicalKey, pending)) throw new Error("Publisher logical range already exists outside its contiguous cursor");
-      state.set("deliveries", subscription.subscriptionHash, prepared);
+      state.set(deliveryNamespace, subscription.subscriptionHash, prepared);
     });
     return prepared;
   }
   async function stillActive(record, signal) {
     if (await timed(options.discovery.isActive(record.subscription, signal), signal)) return true;
-    state.set("deliveries", record.subscription.subscriptionHash, {
+    state.set(deliveryNamespace, record.subscription.subscriptionHash, {
       ...record,
       pending: void 0,
       state: "cancelled"
     });
     return false;
   }
+  function acknowledgeBestEffort(record, body, eventHash, signal, now) {
+    const { pending, subscription } = record;
+    const acknowledgment = BestEffortAdmissionAcknowledgmentZod.safeParse(body);
+    if (!acknowledgment.success || acknowledgment.data.eventHash !== eventHash || acknowledgment.data.wakeId !== pending.wakeId || acknowledgment.data.expiresAt !== pending.issuedAt + (bestEffort?.maxHintAgeSeconds ?? 0) + 60 || acknowledgment.data.acceptedAt < pending.issuedAt - 60 || acknowledgment.data.acceptedAt > now + 60)
+      throw new Error("Publisher did not receive a matching finite acknowledgment");
+    signal.throwIfAborted();
+    state.set(deliveryNamespace, subscription.subscriptionHash, {
+      subscription,
+      cursor: pending.toPosition,
+      delivered: record.delivered + 1,
+      failures: 0,
+      attempts: 0,
+      superseded: record.superseded ?? 0,
+      abandoned: record.abandoned ?? 0,
+      totalAttempts: (record.totalAttempts ?? 0) + 1,
+      lastNotifiedAt: now,
+      lastHintAt: pending.issuedAt,
+      lastHintTarget: pending.toPosition,
+      nextAttemptMs: 0,
+      state: "active"
+    });
+  }
   async function sendDelivery(record, signal, now) {
     const { pending, subscription } = record;
     signal.throwIfAborted();
     const signed = await signer.sign(pending, subscription.audience);
     signal.throwIfAborted();
-    const attempt = state.get("delivery-attempts", pending.wakeId)?.count ?? 0;
-    state.set("delivery-attempts", pending.wakeId, {
+    const attempt = deliveryMode === "best-effort" ? record.attempts ?? 0 : state.get("delivery-attempts", pending.wakeId)?.count ?? 0;
+    if (deliveryMode === "best-effort") state.set(deliveryNamespace, subscription.subscriptionHash, {
+      ...record,
+      attempts: attempt + 1,
+      totalAttempts: (record.totalAttempts ?? 0) + 1
+    });
+    else state.set("delivery-attempts", pending.wakeId, {
       count: attempt + 1,
       startedAt: now,
       status: "in-flight"
     });
     const response = await options.transport.post(subscription.endpoint, signed.event, signal, signed.jwt);
-    state.set("delivery-attempts", pending.wakeId, {
+    if (deliveryMode === "durable") state.set("delivery-attempts", pending.wakeId, {
       count: attempt + 1,
       startedAt: now,
       status: response.status
     });
     if (response.status !== 200 && response.status !== 202) throw new DeliveryResponseError(response.status, response.retryAfterMs);
+    if (deliveryMode === "best-effort") {
+      acknowledgeBestEffort(record, response.body, signed.eventHash, signal, now);
+      return;
+    }
     const receipt = z2.object({ receiptId: z2.string().min(1), wakeId: z2.literal(pending.wakeId) }).safeParse(response.body);
     if (!receipt.success) throw new Error("Publisher admission did not return a matching durable receipt");
     signal.throwIfAborted();
     state.transaction(() => {
       state.set("delivery-receipts", pending.wakeId, { receiptId: receipt.data.receiptId, receivedAt: now });
-      state.set("deliveries", subscription.subscriptionHash, {
+      state.set(deliveryNamespace, subscription.subscriptionHash, {
         subscription,
         cursor: pending.toPosition,
         delivered: record.delivered + 1,
@@ -848,7 +1005,7 @@ async function createPersistentEventPublisherRuntime(options) {
   }
   async function deliver(subscription, signal, now, heads) {
     let record = loadDelivery(subscription, now);
-    if (record.state !== "active" || record.nextAttemptMs > now * 1e3) return;
+    if (deliveryMode === "durable" && (record.state !== "active" || record.nextAttemptMs > now * 1e3)) return;
     try {
       if (!await stillActive(record, signal)) return;
       options.transport.assertAllowed(subscription.endpoint);
@@ -856,17 +1013,16 @@ async function createPersistentEventPublisherRuntime(options) {
       const prepared = prepareDelivery(record, now, heads);
       if (prepared === void 0) return;
       record = prepared;
+      if (record.nextAttemptMs > now * 1e3) return;
       if (!await stillActive(record, signal)) return;
       await sendDelivery(prepared, signal, now);
     } catch (error) {
       if (signal.aborted) return;
-      state.set("deliveries", subscription.subscriptionHash, {
-        ...record,
-        failures: record.failures + 1,
-        state: error instanceof DeliveryResponseError && !error.retryable ? "blocked" : "active",
-        nextAttemptMs: now * 1e3 + Math.min(36e5, error instanceof DeliveryResponseError && error.retryAfterMs !== void 0 ? error.retryAfterMs : Math.min(3e5, 1e3 * 2 ** Math.min(record.failures, 8))),
-        lastError: "delivery-failed"
-      });
+      state.set(
+        deliveryNamespace,
+        subscription.subscriptionHash,
+        failedDelivery(record, state.get(deliveryNamespace, subscription.subscriptionHash), deliveryMode, error, now)
+      );
     }
   }
   async function readSources(signal) {
@@ -896,13 +1052,13 @@ async function createPersistentEventPublisherRuntime(options) {
     if (subscriptions.length > timing.maxSubscriptions) throw new Error("Publisher subscription limit exceeded");
     const active = new Set(subscriptions.map((subscription) => subscription.subscriptionHash));
     if (active.size !== subscriptions.length) throw new Error("Duplicate subscription identity");
-    const unavailable = state.entries("deliveries").filter((item) => !active.has(item.key) && item.value.state !== "cancelled");
+    const unavailable = state.entries(deliveryNamespace).filter((item) => !active.has(item.key) && item.value.state !== "cancelled");
     let available = true;
     for (let offset = 0; offset < unavailable.length; offset += timing.concurrency) {
       signal.throwIfAborted();
       const results = await Promise.allSettled(unavailable.slice(offset, offset + timing.concurrency).map(async ({ key, value }) => {
         const stillAuthorized = await timed(options.discovery.isActive(value.subscription, signal), signal);
-        if (!stillAuthorized) state.set("deliveries", key, {
+        if (!stillAuthorized) state.set(deliveryNamespace, key, {
           ...value,
           pending: void 0,
           state: "cancelled"
@@ -960,10 +1116,11 @@ async function createPersistentEventPublisherRuntime(options) {
     async start() {
       if (stop !== void 0)
         throw new Error("Publisher is stopped");
-      if (!running) {
-        await actor.start();
-        running = true;
+      if (running) {
+        return;
       }
+      await actor.start();
+      running = true;
     },
     async runOnce() {
       if (stop !== void 0)
@@ -995,9 +1152,14 @@ async function createPersistentEventPublisherRuntime(options) {
         throw new AggregateError(failures, "Publisher runtime shutdown failed");
     })(),
     status() {
-      const deliveries = state.entries("deliveries").map((item) => item.value);
+      const deliveries = state.entries(deliveryNamespace).map((item) => item.value);
       return {
         running,
+        deliveryMode,
+        ...bestEffort === void 0 ? {} : { bestEffort: Object.freeze({ ...bestEffort }) },
+        superseded: deliveries.reduce((sum, item) => sum + (item.superseded ?? 0), 0),
+        abandoned: deliveries.reduce((sum, item) => sum + (item.abandoned ?? 0), 0),
+        totalAttempts: deliveries.reduce((sum, item) => sum + (item.totalAttempts ?? 0), 0),
         ready: running && ready,
         clockHealthy,
         degraded: !ready || deliveries.some((item) => item.state !== "cancelled" && item.failures > 0),
@@ -1009,10 +1171,15 @@ async function createPersistentEventPublisherRuntime(options) {
         passes,
         ...lastError === void 0 ? {} : { lastError },
         ...options.discovery.status === void 0 ? {} : { handshake: options.discovery.status() },
-        sources: state.entries("source-heads").map((item) => ({ id: item.key, ...item.value })),
-        subscriptions: state.entries("deliveries").map((item) => ({
+        sources: state.entries("source-heads").filter((item) => sourceReaders.has(item.key)).map((item) => ({ id: item.key, ...item.value })),
+        subscriptions: state.entries(deliveryNamespace).map((item) => ({
           id: item.key,
           cursor: item.value.cursor,
+          ...deliveryMode === "best-effort" ? {
+            ...item.value.cursor < item.value.subscription.fromPosition ? {} : { lastAdmissionTarget: item.value.cursor },
+            attempts: item.value.attempts ?? 0,
+            lastHintAt: item.value.lastHintAt
+          } : {},
           state: item.value.state,
           pending: item.value.pending !== void 0,
           failures: item.value.failures
@@ -1103,7 +1270,7 @@ async function openPublisherDataLake(options) {
 }
 
 // src/runtime/sqliteHandshakeStores.ts
-import { isDeepStrictEqual as isDeepStrictEqual2 } from "node:util";
+import { isDeepStrictEqual as isDeepStrictEqual4 } from "node:util";
 import { endpointChallengeHash } from "@xyo-network/event-kit-protocol";
 import {
   Base64Url32BytesZod as Base64Url32BytesZod2,
@@ -1334,7 +1501,7 @@ function requireTime(value) {
   if (!Number.isSafeInteger(value) || value < 0) throw new Error("Publisher clock is invalid");
 }
 function samePublicationIntent(left, right) {
-  return left.chainId === right.chainId && left.source === right.source && left.operationId === right.operationId && isDeepStrictEqual2(left.eventHashes, right.eventHashes) && isDeepStrictEqual2(left.attachmentHashes, right.attachmentHashes);
+  return left.chainId === right.chainId && left.source === right.source && left.operationId === right.operationId && isDeepStrictEqual4(left.eventHashes, right.eventHashes) && isDeepStrictEqual4(left.attachmentHashes, right.attachmentHashes);
 }
 function publicationKey(intent) {
   if (!/^[0-9a-f]{40}$/u.test(intent.chainId) || !/^[0-9a-f]{40}$/u.test(intent.source) || intent.operationId.length === 0 || intent.operationId.length > 256 || [...intent.eventHashes, ...intent.attachmentHashes].some((hash) => !HashZod2.safeParse(hash).success)) {
@@ -1342,11 +1509,12 @@ function publicationKey(intent) {
   }
   return JSON.stringify([intent.chainId, intent.source, intent.operationId]);
 }
-function createSqlitePublisherHandshakeStores(state) {
+function createSqlitePublisherHandshakeStores(state, options = {}) {
+  const replayKey = options.replayNamespace === void 0 ? "checkpoint" : `checkpoint:${z4.string().min(1).max(128).regex(/^[A-Za-z0-9_-]+$/u).parse(options.replayNamespace)}`;
   const replay = {
-    load: async () => state.get("replay", "checkpoint"),
+    load: async () => state.get("replay", replayKey),
     async save(checkpoint) {
-      state.set("replay", "checkpoint", checkpoint);
+      state.set("replay", replayKey, checkpoint);
     }
   };
   const intents = {
@@ -1384,7 +1552,7 @@ function createSqlitePublisherHandshakeStores(state) {
         const key = `${record.publisher}:${record.keyId}`;
         const prior = state.get("encryption-keys", key);
         if (prior !== void 0) {
-          if (!isDeepStrictEqual2(prior, record)) throw new Error("Encryption key collision");
+          if (!isDeepStrictEqual4(prior, record)) throw new Error("Encryption key collision");
           return "duplicate";
         }
         state.set("encryption-keys", key, record);
@@ -1404,7 +1572,7 @@ function createSqlitePublisherHandshakeStores(state) {
         const priorNonce = state.get("challenge-nonces", challenge.nonce);
         if (priorNonce !== void 0 && priorNonce !== hash) return { kind: "collision" };
         const prior = current(hash);
-        if (prior !== void 0) return isDeepStrictEqual2(prior.challenge, challenge) ? { kind: "duplicate", record: prior } : { kind: "collision" };
+        if (prior !== void 0) return isDeepStrictEqual4(prior.challenge, challenge) ? { kind: "duplicate", record: prior } : { kind: "collision" };
         const record = {
           challenge,
           challengeHash: hash,
@@ -1457,7 +1625,7 @@ function createSqlitePublisherHandshakeStores(state) {
       for (const phase of phases) {
         const record = state.get(`publication:${phase}`, key);
         if (record === void 0) continue;
-        if (record.phase !== phase || !samePublicationIntent(record, intent) || !isDeepStrictEqual2(record.evidence, signed.evidence)) {
+        if (record.phase !== phase || !samePublicationIntent(record, intent) || !isDeepStrictEqual4(record.evidence, signed.evidence)) {
           throw new Error("Publication evidence collision");
         }
         latest = record;
@@ -1471,12 +1639,12 @@ function createSqlitePublisherHandshakeStores(state) {
       state.transaction(() => {
         const signed = state.get("publication:signed", key);
         if (signed === void 0 && record.phase !== "signed") throw new Error("Publication must bind signed evidence first");
-        if (signed !== void 0 && (!samePublicationIntent(signed, record) || !isDeepStrictEqual2(signed.evidence, record.evidence))) {
+        if (signed !== void 0 && (!samePublicationIntent(signed, record) || !isDeepStrictEqual4(signed.evidence, record.evidence))) {
           throw new Error("Publication intent or evidence collision");
         }
         const namespace = `publication:${record.phase}`;
         const prior = state.get(namespace, key);
-        if (prior !== void 0 && !isDeepStrictEqual2(prior, record)) throw new Error("Publication phase collision");
+        if (prior !== void 0 && !isDeepStrictEqual4(prior, record)) throw new Error("Publication phase collision");
         if (prior === void 0) state.set(namespace, key, record);
       });
     }
@@ -1512,9 +1680,7 @@ function replaceJsonValue(_key, candidate) {
 // src/runtime/sqlitePublisherState.ts
 function decode(value) {
   return JSON.parse(value, (_key, candidate) => {
-    if (typeof candidate === "object" && candidate !== null && Object.keys(candidate).length === 1 && "$eventKitBigInt" in candidate && typeof candidate.$eventKitBigInt === "string" && /^(?:0|[1-9][0-9]*)$/u.test(candidate.$eventKitBigInt))
-      return BigInt(candidate.$eventKitBigInt);
-    return candidate;
+    return typeof candidate === "object" && candidate !== null && Object.keys(candidate).length === 1 && "$eventKitBigInt" in candidate && typeof candidate.$eventKitBigInt === "string" && /^(?:0|[1-9][0-9]*)$/u.test(candidate.$eventKitBigInt) ? BigInt(candidate.$eventKitBigInt) : candidate;
   });
 }
 function processExists(pid) {