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

package/dist/node/index.mjs

@@ -23,10 +23,7 @@ function createFilesystemCursorStore(options) {
       try {
         const raw = await readFile(filePath, "utf8");
         const parsed = JSON.parse(raw);
-        if (typeof parsed.lastProcessedBlock !== "number" || !Number.isFinite(parsed.lastProcessedBlock)) {
-          return void 0;
-        }
-        return parsed.lastProcessedBlock;
+        return typeof parsed.lastProcessedBlock !== "number" || !Number.isFinite(parsed.lastProcessedBlock) ? void 0 : parsed.lastProcessedBlock;
       } catch (error) {
         if (isNotFound(error)) return void 0;
         throw error;
@@ -481,10 +478,7 @@ function replaceJsonValue(_key, candidate) {
   return typeof candidate === "bigint" ? { $eventKitBigInt: candidate.toString() } : candidate;
 }
 function reviveJson(_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;
 }
 async function unlinkIfMissing3(path) {
   try {
@@ -1076,7 +1070,7 @@ function createFilesystemPublisherEndpointChallengeStore(options) {
       if (await publish(attempted)) return { kind: "started", record: attempted };
       const winner = await current(challengeHash);
       if (winner === void 0) throw new Error("challenge attempt winner vanished");
-      return winner.state === "verified" ? { kind: "verified", record: winner } : { kind: "already-attempted", record: winner };
+      return { kind: winner.state === "verified" ? "verified" : "already-attempted", record: winner };
     },
     async completeVerified(input) {
       const challengeHash = HashZod3.parse(input.challengeHash);
@@ -1085,7 +1079,7 @@ function createFilesystemPublisherEndpointChallengeStore(options) {
       const observed = await current(challengeHash);
       if (observed === void 0) return { kind: "missing" };
       if (observed.state === "verified") {
-        return observed.responseHash === responseHash ? { kind: "duplicate", record: observed } : { kind: "collision", record: observed };
+        return { kind: observed.responseHash === responseHash ? "duplicate" : "collision", record: observed };
       }
       if (observed.state !== "attempted") return { kind: "not-attempted", record: observed };
       if (!isLive(observed, input.nowSeconds)) return { kind: "expired", record: observed };
@@ -1097,7 +1091,7 @@ function createFilesystemPublisherEndpointChallengeStore(options) {
       if (await publish(verified)) return { kind: "verified", record: verified };
       const winner = await readState(challengeHash, "verified");
       if (winner === void 0) throw new Error("verified challenge winner vanished");
-      return winner.responseHash === responseHash ? { kind: "duplicate", record: winner } : { kind: "collision", record: winner };
+      return { kind: winner.responseHash === responseHash ? "duplicate" : "collision", record: winner };
     },
     get: async (rawHash) => await current(HashZod3.parse(rawHash)),
     async issue(input) {
@@ -1355,6 +1349,8 @@ async function persistMutationIntent(store, intent) {
 }
 async function publisherServiceRequestFingerprint(input) {
   return await handshakeMutationRequestFingerprint({
+    deliveryMode: input.deliveryMode,
+    bestEffort: input.bestEffort ?? null,
     expiresAtBlock: input.expiresAtBlock ?? null,
     maxPositionsPerWake: input.maxPositionsPerWake,
     sources: input.sources,
@@ -1374,6 +1370,8 @@ async function publisherRotationRequestFingerprint(input) {
 }
 async function subscriberSubscriptionRequestFingerprint(input) {
   return await handshakeMutationRequestFingerprint({
+    deliveryMode: input.deliveryMode,
+    bestEffort: input.bestEffort ?? null,
     audience: input.audience,
     challengeSecret: input.challengeSecret,
     deploymentId: input.deploymentId,
@@ -1760,6 +1758,8 @@ function createPublisherHandshakeClient(options) {
         validFromBlock
       };
       const service = createPublisherService({
+        deliveryMode: input.deliveryMode,
+        ...input.bestEffort === void 0 ? {} : { bestEffort: input.bestEffort },
         ...serviceInput,
         authorizationChainId: options.reader.chainId,
         sources: input.sources,
@@ -1879,6 +1879,8 @@ function createPublisherHandshakeClient(options) {
         validFromBlock
       };
       const service = createPublisherService({
+        deliveryMode: selected.service.body.deliveryMode,
+        ...selected.service.body.bestEffort === void 0 ? {} : { bestEffort: selected.service.body.bestEffort },
         ...serviceInput,
         authorizationChainId: options.reader.chainId,
         sources: selected.service.body.events.map((event) => event.source),
@@ -2172,6 +2174,8 @@ function createSubscriberHandshakeClient(options) {
   return Object.freeze(client);
 }
 function subscriberPlaintext(service, input, maxPositionsPerWake) {
+  if (input.deliveryMode !== service.deliveryMode || canonicalJson(input.bestEffort ?? null) !== canonicalJson(service.bestEffort ?? null))
+    throw new Error("Requested delivery terms do not match exact selected service");
   const plaintextInput = {
     audience: input.audience,
     challengeSecret: input.challengeSecret,
@@ -2184,6 +2188,8 @@ function subscriberPlaintext(service, input, maxPositionsPerWake) {
     throw new Error("Requested source is not advertised by the selected service");
   }
   return createWakeSubscriptionPlaintext({
+    deliveryMode: input.deliveryMode,
+    ...input.bestEffort === void 0 ? {} : { bestEffort: input.bestEffort },
     ...plaintextInput,
     source,
     fromPosition: input.fromPosition,
@@ -2323,6 +2329,7 @@ function createBoundedPublisherEthersTransport(options = {}) {
 }
 
 // src/runtime/handshakeDiscovery.ts
+import { isDeepStrictEqual as isDeepStrictEqual2 } from "node:util";
 import { decryptWakeSubscription, sourceWakeFilterHash } from "@xyo-network/event-kit-protocol";
 import { EndpointChallengeResponseZod as EndpointChallengeResponseZod2 } from "@xyo-network/event-kit-schemas";
 function createPublisherHandshakeDiscovery(options) {
@@ -2338,6 +2345,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 || isDeepStrictEqual2(tuple.service.body.bestEffort, options.bestEffort));
+  }
   async function activeView(signal) {
     signal.throwIfAborted();
     viewing ??= (async () => {
@@ -2355,7 +2365,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;
@@ -2420,7 +2430,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];
@@ -2436,30 +2446,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)
@@ -2479,6 +2499,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,
@@ -2498,7 +2521,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) {
@@ -2717,11 +2740,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);
@@ -2828,18 +2847,128 @@ function createPublisherHttpsTransport(input) {
 }
 
 // src/runtime/publisherRuntime.ts
-import { randomBytes as randomBytes6 } from "node:crypto";
-import { isDeepStrictEqual as isDeepStrictEqual2 } from "node:util";
+import { isDeepStrictEqual as isDeepStrictEqual4 } 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 z3 } from "zod";
 
-// src/runtime/sourceSigner.ts
+// src/runtime/publisherDeliveryState.ts
 import { randomBytes as randomBytes5 } from "node:crypto";
+import { isDeepStrictEqual as isDeepStrictEqual3 } from "node:util";
+import { WakeEnvelopeSchema, WakeEnvelopeZod } from "@xyo-network/event-kit-schemas";
+function assertDeliveryState(record, subscription) {
+  if (!isDeepStrictEqual3(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 || !isDeepStrictEqual3(pending.source, subscription.source))
+    throw new Error("Persisted publisher outbox binding is invalid");
+}
+function makeEvent(subscription, fromPosition, toPosition, now, wakeId = randomBytes5(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 randomBytes6 } from "node:crypto";
 import {
   NormalizedAddressZod as NormalizedAddressZod4,
-  WakeEnvelopeZod,
+  WakeEnvelopeZod as WakeEnvelopeZod2,
   WakeJwtSchema
 } from "@xyo-network/event-kit-schemas";
 import { PayloadBuilder as PayloadBuilder2 } from "@xyo-network/sdk";
@@ -2849,14 +2978,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: randomBytes5(16).toString("hex") },
+        claims: { eventHash, jti: randomBytes6(16).toString("hex") },
         now,
         schema: WakeJwtSchema,
         ttl: 60
@@ -2875,31 +3004,6 @@ function createAccountSourceWakeSigner(options) {
 function activationReady(status) {
   return (status?.keyLoaded ?? true) && (status?.pendingSubscriptions ?? 0) === 0;
 }
-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)) || !["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 || !isDeepStrictEqual2(pending.source, subscription.source))
-      throw new Error("Persisted publisher outbox binding is invalid");
-  }
-}
-function makeEvent(subscription, fromPosition, toPosition, now, wakeId = randomBytes6(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);
@@ -2914,20 +3018,24 @@ var TimingZod = z3.object({
   maxSubscriptions: z3.number().int().min(1).max(1024).default(64),
   requestTimeoutMs: z3.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));
@@ -2939,7 +3047,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;
@@ -2947,11 +3060,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 || !isDeepStrictEqual4(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) {
@@ -2965,12 +3083,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));
@@ -2982,43 +3114,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 = z3.object({ receiptId: z3.string().min(1), wakeId: z3.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,
@@ -3030,7 +3193,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);
@@ -3038,17 +3201,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) {
@@ -3078,13 +3240,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"
@@ -3142,10 +3304,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)
@@ -3177,9 +3340,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),
@@ -3191,10 +3359,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
@@ -3285,7 +3458,7 @@ async function openPublisherDataLake(options) {
 }
 
 // src/runtime/sqliteHandshakeStores.ts
-import { isDeepStrictEqual as isDeepStrictEqual3 } from "node:util";
+import { isDeepStrictEqual as isDeepStrictEqual5 } from "node:util";
 import { endpointChallengeHash as endpointChallengeHash2 } from "@xyo-network/event-kit-protocol";
 import {
   Base64Url32BytesZod as Base64Url32BytesZod3,
@@ -3306,7 +3479,7 @@ function requireTime2(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 && isDeepStrictEqual3(left.eventHashes, right.eventHashes) && isDeepStrictEqual3(left.attachmentHashes, right.attachmentHashes);
+  return left.chainId === right.chainId && left.source === right.source && left.operationId === right.operationId && isDeepStrictEqual5(left.eventHashes, right.eventHashes) && isDeepStrictEqual5(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) => !HashZod5.safeParse(hash).success)) {
@@ -3314,11 +3487,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 = {
@@ -3356,7 +3530,7 @@ function createSqlitePublisherHandshakeStores(state) {
         const key = `${record.publisher}:${record.keyId}`;
         const prior = state.get("encryption-keys", key);
         if (prior !== void 0) {
-          if (!isDeepStrictEqual3(prior, record)) throw new Error("Encryption key collision");
+          if (!isDeepStrictEqual5(prior, record)) throw new Error("Encryption key collision");
           return "duplicate";
         }
         state.set("encryption-keys", key, record);
@@ -3376,7 +3550,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 isDeepStrictEqual3(prior.challenge, challenge) ? { kind: "duplicate", record: prior } : { kind: "collision" };
+        if (prior !== void 0) return isDeepStrictEqual5(prior.challenge, challenge) ? { kind: "duplicate", record: prior } : { kind: "collision" };
         const record = {
           challenge,
           challengeHash: hash,
@@ -3429,7 +3603,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) || !isDeepStrictEqual3(record.evidence, signed.evidence)) {
+        if (record.phase !== phase || !samePublicationIntent(record, intent) || !isDeepStrictEqual5(record.evidence, signed.evidence)) {
           throw new Error("Publication evidence collision");
         }
         latest = record;
@@ -3443,12 +3617,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) || !isDeepStrictEqual3(signed.evidence, record.evidence))) {
+        if (signed !== void 0 && (!samePublicationIntent(signed, record) || !isDeepStrictEqual5(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 && !isDeepStrictEqual3(prior, record)) throw new Error("Publication phase collision");
+        if (prior !== void 0 && !isDeepStrictEqual5(prior, record)) throw new Error("Publication phase collision");
         if (prior === void 0) state.set(namespace, key, record);
       });
     }
@@ -3474,9 +3648,7 @@ import { hostname } from "node:os";
 import PATH12 from "node:path";
 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) {