@volter/world-core 3.0.152 → 3.0.154

package/dist/src/event-delivery.d.ts

@@ -0,0 +1,4 @@
+import type { EventTransport } from './events.js';
+/** Dispatch one newly recorded packet once. Legacy rows, existing attempts and
+ * interrupted sending claims never turn into an unrequested second send. */
+export declare function sendRecordedEvent(service: string, deliveryType: string, deliveryId: string, root: string | undefined, transport: EventTransport, trace: Record<string, string>): Promise<void>;

package/dist/src/event-delivery.js

@@ -0,0 +1,70 @@
+// FIRST DECLARED-EVENT OUTCOMES (architecture, "What an author writes, and how").
+// A queued packet is not evidence its receiver answered. Keep the first attempt
+// under the shared action lock; this is not the originating-write outbox or a
+// substitute for a vendor's declared retry/redelivery policy.
+import { applyTwinWriteAtomic } from "./serve.js";
+import { worldNow } from "./world-clock.js";
+const ATTEMPT = '_world_event_delivery_attempt';
+/** Dispatch one newly recorded packet once. Legacy rows, existing attempts and
+ * interrupted sending claims never turn into an unrequested second send. */
+export async function sendRecordedEvent(service, deliveryType, deliveryId, root, transport, trace) {
+    const { value: claim } = await applyTwinWriteAtomic(service, (resources) => {
+        const row = resources.find((r) => r.type === deliveryType && r.id === deliveryId);
+        if (!row || row.deleted === true || row.delivery_protocol !== 1 || row.delivery_state !== 'queued'
+            || row.attempt_count !== 0 || row.current_attempt !== null)
+            return { kind: 'skip', value: undefined };
+        const attemptId = `${deliveryType}:${deliveryId}:1`;
+        if (resources.some((r) => r.type === ATTEMPT && r.id === attemptId))
+            return { kind: 'skip', value: undefined };
+        if (typeof row.url !== 'string' || typeof row.body !== 'string'
+            || !row.headers || typeof row.headers !== 'object' || Array.isArray(row.headers)
+            || Object.values(row.headers).some((v) => typeof v !== 'string')) {
+            throw new Error('A retained declared-event packet is incomplete; it cannot be dispatched.');
+        }
+        const occurredAt = worldNow();
+        return { kind: 'write', value: {
+                attemptId, url: row.url, body: row.body, headers: { ...row.headers },
+            }, write: {
+                operation: 'world_event_delivery.claim', subjectType: deliveryType, subjectId: deliveryId,
+                fields: { delivery_state: 'sending', attempt_count: 1, current_attempt: attemptId },
+                projection: { creates: [{ type: ATTEMPT, id: attemptId, fields: {
+                                delivery_type: deliveryType, delivery_id: deliveryId, attempt: 1,
+                                state: 'sending', started_at: Date.parse(occurredAt), finished_at: null, transport_status: null,
+                            } }] },
+                occurredAt, actor: { kind: 'system' },
+            } };
+    }, root);
+    if (!claim)
+        return;
+    let status = null;
+    try {
+        const answer = await transport(claim.url, claim.body, { ...claim.headers, ...trace });
+        if (typeof answer === 'number' && Number.isInteger(answer) && answer >= 100 && answer <= 599)
+            status = answer;
+    }
+    catch {
+        // A thrown request can have reached the receiver. Preserve uncertainty and
+        // never copy exception strings, response bodies or credentials into history.
+    }
+    const state = status === null ? 'unknown' : status >= 200 && status < 300 ? 'succeeded' : 'failed';
+    const occurredAt = worldNow(), finishedAt = Date.parse(occurredAt);
+    await applyTwinWriteAtomic(service, (resources) => {
+        const attempt = resources.find((r) => r.type === ATTEMPT && r.id === claim.attemptId);
+        if (!attempt || attempt.deleted === true || attempt.state !== 'sending'
+            || attempt.delivery_type !== deliveryType || attempt.delivery_id !== deliveryId)
+            return { kind: 'skip', value: undefined };
+        const row = resources.find((r) => r.type === deliveryType && r.id === deliveryId);
+        const current = row && row.deleted !== true && row.delivery_protocol === 1
+            && row.delivery_state === 'sending' && row.current_attempt === claim.attemptId;
+        return { kind: 'write', value: undefined, write: {
+                operation: 'world_event_delivery.finish', subjectType: ATTEMPT, subjectId: claim.attemptId,
+                fields: { state, finished_at: finishedAt, transport_status: status },
+                ...(current && row ? { projection: { updates: [{ type: deliveryType, id: deliveryId, fields: {
+                                    delivery_state: state, finished_at: finishedAt, transport_status: status,
+                                    // A future manual attempt must not erase earlier positive acceptance.
+                                    accepted_at: state === 'succeeded' ? row.accepted_at ?? finishedAt : row.accepted_at ?? null,
+                                } }] } } : {}),
+                occurredAt, actor: { kind: 'system' },
+            } };
+    }, root);
+}

package/dist/src/events.d.ts

@@ -110,7 +110,8 @@ export type EventsDecl = {
     envelope: unknown;
     /** Where the World's endpoints are kept: one kind, or several (GitHub's repository and organization hooks). */
     endpoints: EndpointsDecl | ReadonlyArray<EndpointsDecl>;
-    /** The bookkeeping type each delivery is kept as (`_webhook_message`): what a World reads to see what was sent. */
+    /** The bookkeeping type each delivery is kept as (`_webhook_message`), otherwise `_world_event_delivery`.
+     *  Queuing and the first transport attempt/outcome are separate retained facts. */
     record?: string;
 };
 /** An event's further envelope values (`$`-named) the pack computes for a write, from the vendor's own state (the
@@ -131,7 +132,7 @@ export type EventWrite = {
  *  it: the pack's `semantics/events.ts`, under the handler contract's read-only context, for each type the write sends
  *  (a Slack message renders as `message` and as `app_mention`). */
 export type EventRender<C> = (ctx: C, write: EventWrite, type: string) => Record<string, unknown>;
-/** A delivery made: where it went and exactly what was sent. */
+/** A rendered delivery packet. Its transport attempt and acceptance are separate retained facts. */
 export type EventDelivery = {
     url: string;
     body: string;
@@ -140,11 +141,11 @@ export type EventDelivery = {
 /** The transport a delivery is made over; the World's by default, a test's own when given. */
 export type EventTransport = (url: string, body: string, headers: Record<string, string>) => Promise<number | void>;
 /** A signature scheme's headers for one delivery: deterministic (the id is derived from the delivery itself). */
-/** `seq` tells apart two identical deliveries at one instant (a frozen World clock): the World's count of deliveries
- *  made before this one, so a receiver that deduplicates by id drops neither. */
-export declare function signEvent(scheme: EventScheme, secret: string, body: string, seconds: number, url: string, seq?: number): Record<string, string>;
+/** `seq` tells apart deliveries at one instant; the declared-event path reserves it durably. `identity` supplies that
+ *  occurrence's namespace. Omitted, existing direct callers retain their deterministic signing contract. */
+export declare function signEvent(scheme: EventScheme, secret: string, body: string, seconds: number, url: string, seq?: number, identity?: string): Record<string, string>;
 /** Every scheme's headers for one delivery, merged. */
-export declare function signEventAll(schemes: EventScheme | ReadonlyArray<EventScheme>, secret: string, body: string, seconds: number, url: string, seq?: number): Record<string, string>;
+export declare function signEventAll(schemes: EventScheme | ReadonlyArray<EventScheme>, secret: string, body: string, seconds: number, url: string, seq?: number, identity?: string): Record<string, string>;
 /** A delivery's signature checked as its receiver checks it (a Standard Webhooks verifier, a timestamp-v1 verifier, a plain
  *  HMAC header): true when one of its signatures is the one the secret makes (constant time), and its timestamp,
  *  when the scheme sends one, is within `tolerance` seconds of `now`. */
@@ -163,8 +164,8 @@ export declare function eventTypeOf(decl: Pick<EventsDecl, 'types' | 'known'>, o
 /** Whether an endpoint's list of event types takes a type: every type when the list is empty, `*` or `<family>.*`
  *  its patterns, else the type itself. */
 export declare function takesEvent(list: unknown, type: string): boolean;
-/** Who watches what the World sends (a walk reading each delivery as its receiver would): told of every delivery as it
- *  is made, before its transport. Set and restored by the walk, as its World store is; unset, nothing watches. */
+/** Who watches signed packets before dispatch (a walk reading each as its receiver would). This is not evidence of
+ *  transport or acceptance. Set and restored by the walk, as its World store is; unset, nothing watches. */
 export type DeliveryObserver = (delivery: EventDelivery & {
     service: string;
 }) => void;

package/dist/src/events.js

@@ -7,9 +7,12 @@
 // Imports stay free of side effects: the delivery's transport (Node's http, the World's egress policy) is loaded when a
 // delivery is made, never when a browser client imports the kernel.
 import { createHash, createHmac } from 'node:crypto';
-import { applyTwinWrite, twinResources } from "./serve.js";
+import { applyTwinWrite, applyTwinWriteAtomic, twinResources } from "./serve.js";
 import { equalSecrets as same, ksuidFrom } from "./signing.js";
 import { deliveryTraceHeaders } from "./trace-context.js";
+import { sendRecordedEvent } from "./event-delivery.js";
+import { getActiveWorldStore, withWorldStore } from "./world-store.js";
+import { worldPaths } from "./storage.js";
 /** Whether an endpoint takes an event by its `match`: every field of one match (any, when several) equal to the event's
  *  value, or, a list, holding it. */
 function matches(row, match, filled) {
@@ -25,16 +28,15 @@ function matches(row, match, filled) {
     });
     return Array.isArray(match) ? match.some(one) : one(match);
 }
-const digest = (s) => createHash('sha256').update(s).digest('hex');
 /** A `webhook-id` scheme's key: the base64 part of the secret, after its prefix when it carries one. */
 const webhookKey = (scheme, secret) => scheme.secretKey === 'utf8' ? Buffer.from(secret, 'utf8') : Buffer.from(scheme.secretPrefix && secret.startsWith(scheme.secretPrefix) ? secret.slice(scheme.secretPrefix.length) : secret, 'base64');
 /** A signature scheme's headers for one delivery: deterministic (the id is derived from the delivery itself). */
-/** `seq` tells apart two identical deliveries at one instant (a frozen World clock): the World's count of deliveries
- *  made before this one, so a receiver that deduplicates by id drops neither. */
-export function signEvent(scheme, secret, body, seconds, url, seq = 0) {
+/** `seq` tells apart deliveries at one instant; the declared-event path reserves it durably. `identity` supplies that
+ *  occurrence's namespace. Omitted, existing direct callers retain their deterministic signing contract. */
+export function signEvent(scheme, secret, body, seconds, url, seq = 0, identity) {
     if (scheme.kind === 'webhook-id') {
         // Svix's `msg_` and a KSUID (its ids' form), derived from the delivery itself
-        const id = `msg_${ksuidFrom(seconds, seq, `${url}|${seconds}|${seq}|${body}`)}`;
+        const id = `msg_${ksuidFrom(seconds, seq, identity ?? `${url}|${seconds}|${seq}|${body}`)}`;
         const p = scheme.prefix.toLowerCase();
         const signature = createHmac('sha256', webhookKey(scheme, secret)).update(`${id}.${seconds}.${body}`, 'utf8').digest('base64');
         return { [`${p}-id`]: id, [`${p}-timestamp`]: String(seconds), [`${p}-signature`]: `v1,${signature}` };
@@ -58,8 +60,24 @@ const hashOf = (scheme, secret, body) => {
 /** What an `hmac` scheme signs: its `signed` template, else `${t}.${body}` with a timestamp header, else the body. */
 const hmacBase = (scheme, seconds, body) => scheme.signed !== undefined ? scheme.signed.replaceAll('{t}', String(seconds)).replaceAll('{body}', body) : scheme.timestampHeader ? `${seconds}.${body}` : body;
 /** Every scheme's headers for one delivery, merged. */
-export function signEventAll(schemes, secret, body, seconds, url, seq = 0) {
-    return Object.assign({}, ...(Array.isArray(schemes) ? schemes : [schemes]).map((scheme) => signEvent(scheme, secret, body, seconds, url, seq)));
+export function signEventAll(schemes, secret, body, seconds, url, seq = 0, identity) {
+    return Object.assign({}, ...(Array.isArray(schemes) ? schemes : [schemes]).map((scheme) => signEvent(scheme, secret, body, seconds, url, seq, identity)));
+}
+/** Reserve occurrences under the same cross-process lock that appends actions. This private retained row is never a
+ *  vendor resource. Deleted event/delivery rows, concurrent renders and restarts cannot give its ordinals back. */
+async function reserveEventOrdinals(service, root, occurredAt, count) {
+    const { value } = await applyTwinWriteAtomic(service, (resources) => {
+        const counter = resources.find((r) => r.type === '_world_event_sequence' && r.id === 'sequence');
+        const last = counter === undefined ? 0 : counter.last_ordinal;
+        if (typeof last !== 'number' || !Number.isSafeInteger(last) || last < 0 || !Number.isSafeInteger(count) || count < 1 || !Number.isSafeInteger(last + count)) {
+            throw new Error('Invalid retained declared-event sequence; occurrence ids cannot be reused.');
+        }
+        return { kind: 'write', value: last + 1, write: {
+                operation: 'world_event_sequence.reserve', subjectType: '_world_event_sequence', subjectId: 'sequence',
+                fields: { last_ordinal: last + count }, input: { clock: true }, occurredAt, actor: { kind: 'system' },
+            } };
+    }, root);
+    return value;
 }
 /** A delivery's signature checked as its receiver checks it (a Standard Webhooks verifier, a timestamp-v1 verifier, a plain
  *  HMAC header): true when one of its signatures is the one the secret makes (constant time), and its timestamp,
@@ -282,11 +300,19 @@ async function deliverEventType(service, decl, write, data, transport, values, t
     const seconds = Math.floor(millis / 1000);
     const eventData = await data(type);
     const extra = values ? await values(type) : {};
-    // the World's count of events kept so far tells apart two identical events at one instant (a frozen clock)
-    const kept = decl.store !== undefined ? all.filter((r) => r.type === decl.store).length : 0;
+    // Reserve one event and at most one delivery per live endpoint before assigning identities. Unused ordinals are
+    // harmless gaps; a failed render/store never gives them back. This is not an atomic originating-write outbox.
+    const ordinal = await reserveEventOrdinals(service, write.root, write.occurredAt, 1 + live.length);
+    // Fresh/forked Worlds can reserve the same ordinal at a pinned clock. Keep
+    // content binding as well as the lineage's occurrence ordinal, so different
+    // event payloads cannot reuse a receiver's event/webhook id across those Worlds.
+    const eventContent = createHash('sha256').update(JSON.stringify({
+        operation: write.operation, type, data: eventData, envelope: decl.envelope,
+        values: extra, request: requestValues(write.request),
+    }), 'utf8').digest('hex');
     const filled = {
         $type: type, $data: eventData,
-        $id: `evt_${ksuidFrom(seconds, kept, `${type}|${write.occurredAt}|${kept}|${JSON.stringify(eventData)}`)}`,
+        $id: `evt_${ksuidFrom(seconds, ordinal, `world-events:v1:${service}:${type}:${ordinal}:${eventContent}`)}`,
         '$time.ms': millis, '$time.s': seconds, '$time.iso': write.occurredAt,
         ...requestValues(write.request),
         ...extra,
@@ -305,31 +331,44 @@ async function deliverEventType(service, decl, write, data, transport, values, t
     const shared = JSON.stringify(envelope);
     const each = perEndpoint(decl.envelope);
     const sent = [];
-    const before = decl.record !== undefined ? all.filter((r) => r.type === decl.record).length : 0;
+    const recorded = [];
     for (const [i, { row, kind }] of endpoints.entries()) {
         const body = each ? JSON.stringify(fillEnvelope(decl.envelope, filled, row)) : shared;
         const url = String(at(row, kind.url));
-        const seq = before + i;
+        const seq = ordinal + 1 + i;
+        const deliveryContent = createHash('sha256').update(url, 'utf8').update('\0').update(body, 'utf8').digest('hex');
+        const identity = `world-events:v1:${service}:${seq}:${deliveryContent}`;
         const extraHeaders = decl.headers ? headersFor(decl.headers, filled, row) : {};
-        const headers = { ...extraHeaders, ...signEventAll(decl.scheme, String(at(row, kind.secret)), body, seconds, url, seq) };
+        const headers = { ...extraHeaders, ...signEventAll(decl.scheme, String(at(row, kind.secret)), body, seconds, url, seq, identity) };
         sent.push({ url, body, headers });
         // kept with the write, by an id of the delivery itself (two made at once never take the same one)
-        if (decl.record !== undefined) {
-            await applyTwinWrite(service, {
-                operation: `${decl.record.slice(1)}.record`, subjectType: decl.record, subjectId: `${decl.record.slice(1)}_${digest(`${url}|${seconds}|${seq}|${body}`).slice(0, 16)}`,
-                fields: { url, body, headers, event_type: type, sent_at: millis }, occurredAt: write.occurredAt, actor: { kind: 'system' },
-            }, write.root);
-        }
+        const record = decl.record ?? '_world_event_delivery';
+        const id = `${record.slice(1)}_v1_${seq}`;
+        await applyTwinWrite(service, {
+            operation: `${record.slice(1)}.record`, subjectType: record, subjectId: id,
+            fields: { url, body, headers, event_type: type, sent_at: millis,
+                delivery_protocol: 1, event_id: String(filled.$id),
+                endpoint_type: kind.storedAs, endpoint_id: String(row.id),
+                delivery_state: 'queued', attempt_count: 0, current_attempt: null,
+                transport_status: null, finished_at: null, accepted_at: null,
+            }, occurredAt: write.occurredAt, actor: { kind: 'system' },
+        }, write.root);
+        recorded.push({ type: record, id });
     }
     // sent after the write's answer, as a vendor sends it: the caller never waits on its receiver, and a receiver that is
     // slow or down fails no request
     // the write's trace is read now, inside its request, and carried on each delivery (W3C trace continuation)
     const trace = deliveryTraceHeaders();
+    // A timer must retain the request's store/root even if another World becomes
+    // active before it runs. Transport completion writes to the same retained state.
+    const store = getActiveWorldStore(), deliveryRoot = worldPaths(service, write.root).root;
     for (const d of sent)
         deliveryObserver?.({ ...d, service });
-    for (const { url, body: payload, headers } of sent)
+    for (const packet of recorded)
         setTimeout(() => {
-            void transport(url, payload, { ...headers, ...trace }).catch(() => { });
+            // Persistence failure leaves a queued/sending claim for explicit recovery;
+            // it must not fail the already-committed vendor write or cause a blind resend.
+            void withWorldStore(store, () => sendRecordedEvent(service, packet.type, packet.id, deliveryRoot, transport, trace)).catch(() => { });
         }, 0);
     return sent;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-core",
-  "version": "3.0.152",
+  "version": "3.0.154",
   "description": "The kernel of Volter World: one log per twin, branches as pointers, checkpoints, the fold that keeps a twin current, the head that performs a write against the vendor, references, and the git plane. A twin package builds on it; the runtime serves it.",
   "keywords": [
     "twin",

package/src/event-delivery.ts

@@ -0,0 +1,76 @@
+// FIRST DECLARED-EVENT OUTCOMES (architecture, "What an author writes, and how").
+// A queued packet is not evidence its receiver answered. Keep the first attempt
+// under the shared action lock; this is not the originating-write outbox or a
+// substitute for a vendor's declared retry/redelivery policy.
+import { applyTwinWriteAtomic } from './serve.ts';
+import { worldNow } from './world-clock.ts';
+import type { EventDelivery, EventTransport } from './events.ts';
+
+const ATTEMPT = '_world_event_delivery_attempt';
+type Claimed = EventDelivery & { attemptId: string };
+
+/** Dispatch one newly recorded packet once. Legacy rows, existing attempts and
+ * interrupted sending claims never turn into an unrequested second send. */
+export async function sendRecordedEvent(
+  service: string,
+  deliveryType: string,
+  deliveryId: string,
+  root: string | undefined,
+  transport: EventTransport,
+  trace: Record<string, string>,
+): Promise<void> {
+  const { value: claim } = await applyTwinWriteAtomic<Claimed | undefined>(service, (resources) => {
+    const row = resources.find((r) => r.type === deliveryType && r.id === deliveryId);
+    if (!row || row.deleted === true || row.delivery_protocol !== 1 || row.delivery_state !== 'queued'
+      || row.attempt_count !== 0 || row.current_attempt !== null) return { kind: 'skip', value: undefined };
+    const attemptId = `${deliveryType}:${deliveryId}:1`;
+    if (resources.some((r) => r.type === ATTEMPT && r.id === attemptId)) return { kind: 'skip', value: undefined };
+    if (typeof row.url !== 'string' || typeof row.body !== 'string'
+      || !row.headers || typeof row.headers !== 'object' || Array.isArray(row.headers)
+      || Object.values(row.headers).some((v) => typeof v !== 'string')) {
+      throw new Error('A retained declared-event packet is incomplete; it cannot be dispatched.');
+    }
+    const occurredAt = worldNow();
+    return { kind: 'write', value: {
+      attemptId, url: row.url, body: row.body, headers: { ...row.headers } as Record<string, string>,
+    }, write: {
+      operation: 'world_event_delivery.claim', subjectType: deliveryType, subjectId: deliveryId,
+      fields: { delivery_state: 'sending', attempt_count: 1, current_attempt: attemptId },
+      projection: { creates: [{ type: ATTEMPT, id: attemptId, fields: {
+        delivery_type: deliveryType, delivery_id: deliveryId, attempt: 1,
+        state: 'sending', started_at: Date.parse(occurredAt), finished_at: null, transport_status: null,
+      } }] },
+      occurredAt, actor: { kind: 'system' as const },
+    } };
+  }, root);
+  if (!claim) return;
+
+  let status: number | null = null;
+  try {
+    const answer = await transport(claim.url, claim.body, { ...claim.headers, ...trace });
+    if (typeof answer === 'number' && Number.isInteger(answer) && answer >= 100 && answer <= 599) status = answer;
+  } catch {
+    // A thrown request can have reached the receiver. Preserve uncertainty and
+    // never copy exception strings, response bodies or credentials into history.
+  }
+  const state = status === null ? 'unknown' : status >= 200 && status < 300 ? 'succeeded' : 'failed';
+  const occurredAt = worldNow(), finishedAt = Date.parse(occurredAt);
+  await applyTwinWriteAtomic(service, (resources) => {
+    const attempt = resources.find((r) => r.type === ATTEMPT && r.id === claim.attemptId);
+    if (!attempt || attempt.deleted === true || attempt.state !== 'sending'
+      || attempt.delivery_type !== deliveryType || attempt.delivery_id !== deliveryId) return { kind: 'skip', value: undefined };
+    const row = resources.find((r) => r.type === deliveryType && r.id === deliveryId);
+    const current = row && row.deleted !== true && row.delivery_protocol === 1
+      && row.delivery_state === 'sending' && row.current_attempt === claim.attemptId;
+    return { kind: 'write', value: undefined, write: {
+      operation: 'world_event_delivery.finish', subjectType: ATTEMPT, subjectId: claim.attemptId,
+      fields: { state, finished_at: finishedAt, transport_status: status },
+      ...(current && row ? { projection: { updates: [{ type: deliveryType, id: deliveryId, fields: {
+        delivery_state: state, finished_at: finishedAt, transport_status: status,
+        // A future manual attempt must not erase earlier positive acceptance.
+        accepted_at: state === 'succeeded' ? row.accepted_at ?? finishedAt : row.accepted_at ?? null,
+      } }] } } : {}),
+      occurredAt, actor: { kind: 'system' as const },
+    } };
+  }, root);
+}

package/src/events.ts

@@ -7,9 +7,12 @@
 // Imports stay free of side effects: the delivery's transport (Node's http, the World's egress policy) is loaded when a
 // delivery is made, never when a browser client imports the kernel.
 import { createHash, createHmac } from 'node:crypto';
-import { applyTwinWrite, twinResources } from './serve.ts';
+import { applyTwinWrite, applyTwinWriteAtomic, twinResources } from './serve.ts';
 import { equalSecrets as same, ksuidFrom } from './signing.ts';
 import { deliveryTraceHeaders } from './trace-context.ts';
+import { sendRecordedEvent } from './event-delivery.ts';
+import { getActiveWorldStore, withWorldStore } from './world-store.ts';
+import { worldPaths } from './storage.ts';
 
 /** How the vendor signs a delivery. */
 export type EventScheme =
@@ -99,7 +102,8 @@ export type EventsDecl = {
   envelope: unknown;
   /** Where the World's endpoints are kept: one kind, or several (GitHub's repository and organization hooks). */
   endpoints: EndpointsDecl | ReadonlyArray<EndpointsDecl>;
-  /** The bookkeeping type each delivery is kept as (`_webhook_message`): what a World reads to see what was sent. */
+  /** The bookkeeping type each delivery is kept as (`_webhook_message`), otherwise `_world_event_delivery`.
+   *  Queuing and the first transport attempt/outcome are separate retained facts. */
   record?: string;
 };
 
@@ -117,25 +121,23 @@ export type EventWrite = { operation: string; storedType: string; body: Record<s
  *  (a Slack message renders as `message` and as `app_mention`). */
 export type EventRender<C> = (ctx: C, write: EventWrite, type: string) => Record<string, unknown>;
 
-/** A delivery made: where it went and exactly what was sent. */
+/** A rendered delivery packet. Its transport attempt and acceptance are separate retained facts. */
 export type EventDelivery = { url: string; body: string; headers: Record<string, string> };
 
 /** The transport a delivery is made over; the World's by default, a test's own when given. */
 export type EventTransport = (url: string, body: string, headers: Record<string, string>) => Promise<number | void>;
 
-const digest = (s: string): string => createHash('sha256').update(s).digest('hex');
-
 /** A `webhook-id` scheme's key: the base64 part of the secret, after its prefix when it carries one. */
 const webhookKey = (scheme: { secretPrefix?: string; secretKey?: 'base64' | 'utf8' }, secret: string): Buffer =>
   scheme.secretKey === 'utf8' ? Buffer.from(secret, 'utf8') : Buffer.from(scheme.secretPrefix && secret.startsWith(scheme.secretPrefix) ? secret.slice(scheme.secretPrefix.length) : secret, 'base64');
 
 /** A signature scheme's headers for one delivery: deterministic (the id is derived from the delivery itself). */
-/** `seq` tells apart two identical deliveries at one instant (a frozen World clock): the World's count of deliveries
- *  made before this one, so a receiver that deduplicates by id drops neither. */
-export function signEvent(scheme: EventScheme, secret: string, body: string, seconds: number, url: string, seq = 0): Record<string, string> {
+/** `seq` tells apart deliveries at one instant; the declared-event path reserves it durably. `identity` supplies that
+ *  occurrence's namespace. Omitted, existing direct callers retain their deterministic signing contract. */
+export function signEvent(scheme: EventScheme, secret: string, body: string, seconds: number, url: string, seq = 0, identity?: string): Record<string, string> {
   if (scheme.kind === 'webhook-id') {
     // Svix's `msg_` and a KSUID (its ids' form), derived from the delivery itself
-    const id = `msg_${ksuidFrom(seconds, seq, `${url}|${seconds}|${seq}|${body}`)}`;
+    const id = `msg_${ksuidFrom(seconds, seq, identity ?? `${url}|${seconds}|${seq}|${body}`)}`;
     const p = scheme.prefix.toLowerCase();
     const signature = createHmac('sha256', webhookKey(scheme, secret)).update(`${id}.${seconds}.${body}`, 'utf8').digest('base64');
     return { [`${p}-id`]: id, [`${p}-timestamp`]: String(seconds), [`${p}-signature`]: `v1,${signature}` };
@@ -161,8 +163,25 @@ const hmacBase = (scheme: { timestampHeader?: string; signed?: string }, seconds
   scheme.signed !== undefined ? scheme.signed.replaceAll('{t}', String(seconds)).replaceAll('{body}', body) : scheme.timestampHeader ? `${seconds}.${body}` : body;
 
 /** Every scheme's headers for one delivery, merged. */
-export function signEventAll(schemes: EventScheme | ReadonlyArray<EventScheme>, secret: string, body: string, seconds: number, url: string, seq = 0): Record<string, string> {
-  return Object.assign({}, ...(Array.isArray(schemes) ? schemes : [schemes]).map((scheme: EventScheme) => signEvent(scheme, secret, body, seconds, url, seq)));
+export function signEventAll(schemes: EventScheme | ReadonlyArray<EventScheme>, secret: string, body: string, seconds: number, url: string, seq = 0, identity?: string): Record<string, string> {
+  return Object.assign({}, ...(Array.isArray(schemes) ? schemes : [schemes]).map((scheme: EventScheme) => signEvent(scheme, secret, body, seconds, url, seq, identity)));
+}
+
+/** Reserve occurrences under the same cross-process lock that appends actions. This private retained row is never a
+ *  vendor resource. Deleted event/delivery rows, concurrent renders and restarts cannot give its ordinals back. */
+async function reserveEventOrdinals(service: string, root: string | undefined, occurredAt: string, count: number): Promise<number> {
+  const { value } = await applyTwinWriteAtomic(service, (resources) => {
+    const counter = resources.find((r) => r.type === '_world_event_sequence' && r.id === 'sequence');
+    const last = counter === undefined ? 0 : (counter as Record<string, unknown>).last_ordinal;
+    if (typeof last !== 'number' || !Number.isSafeInteger(last) || last < 0 || !Number.isSafeInteger(count) || count < 1 || !Number.isSafeInteger(last + count)) {
+      throw new Error('Invalid retained declared-event sequence; occurrence ids cannot be reused.');
+    }
+    return { kind: 'write', value: last + 1, write: {
+      operation: 'world_event_sequence.reserve', subjectType: '_world_event_sequence', subjectId: 'sequence',
+      fields: { last_ordinal: last + count }, input: { clock: true }, occurredAt, actor: { kind: 'system' },
+    } };
+  }, root);
+  return value;
 }
 
 /** A delivery's signature checked as its receiver checks it (a Standard Webhooks verifier, a timestamp-v1 verifier, a plain
@@ -287,8 +306,8 @@ const worldTransport: EventTransport = async (url, body, headers) => {
   try { return ((await appFetch(url, { method: 'POST', headers: { 'content-type': 'application/json', ...headers }, body })) as { status: number }).status; } catch { return 0; }
 };
 
-/** Who watches what the World sends (a walk reading each delivery as its receiver would): told of every delivery as it
- *  is made, before its transport. Set and restored by the walk, as its World store is; unset, nothing watches. */
+/** Who watches signed packets before dispatch (a walk reading each as its receiver would). This is not evidence of
+ *  transport or acceptance. Set and restored by the walk, as its World store is; unset, nothing watches. */
 export type DeliveryObserver = (delivery: EventDelivery & { service: string }) => void;
 let deliveryObserver: DeliveryObserver | undefined;
 export function setDeliveryObserver(observer: DeliveryObserver | undefined): DeliveryObserver | undefined {
@@ -386,11 +405,19 @@ async function deliverEventType(
   const seconds = Math.floor(millis / 1000);
   const eventData = await data(type);
   const extra = values ? await values(type) : {};
-  // the World's count of events kept so far tells apart two identical events at one instant (a frozen clock)
-  const kept = decl.store !== undefined ? all.filter((r) => r.type === decl.store).length : 0;
+  // Reserve one event and at most one delivery per live endpoint before assigning identities. Unused ordinals are
+  // harmless gaps; a failed render/store never gives them back. This is not an atomic originating-write outbox.
+  const ordinal = await reserveEventOrdinals(service, write.root, write.occurredAt, 1 + live.length);
+  // Fresh/forked Worlds can reserve the same ordinal at a pinned clock. Keep
+  // content binding as well as the lineage's occurrence ordinal, so different
+  // event payloads cannot reuse a receiver's event/webhook id across those Worlds.
+  const eventContent = createHash('sha256').update(JSON.stringify({
+    operation: write.operation, type, data: eventData, envelope: decl.envelope,
+    values: extra, request: requestValues(write.request),
+  }), 'utf8').digest('hex');
   const filled: Record<string, unknown> = {
     $type: type, $data: eventData,
-    $id: `evt_${ksuidFrom(seconds, kept, `${type}|${write.occurredAt}|${kept}|${JSON.stringify(eventData)}`)}`,
+    $id: `evt_${ksuidFrom(seconds, ordinal, `world-events:v1:${service}:${type}:${ordinal}:${eventContent}`)}`,
     '$time.ms': millis, '$time.s': seconds, '$time.iso': write.occurredAt,
     ...requestValues(write.request),
     ...extra,
@@ -407,29 +434,42 @@ async function deliverEventType(
   const shared = JSON.stringify(envelope);
   const each = perEndpoint(decl.envelope);
   const sent: EventDelivery[] = [];
-  const before = decl.record !== undefined ? all.filter((r) => r.type === decl.record).length : 0;
+  const recorded: Array<{ type: string; id: string }> = [];
   for (const [i, { row, kind }] of endpoints.entries()) {
     const body = each ? JSON.stringify(fillEnvelope(decl.envelope, filled, row)) : shared;
     const url = String(at(row, kind.url));
-    const seq = before + i;
+    const seq = ordinal + 1 + i;
+    const deliveryContent = createHash('sha256').update(url, 'utf8').update('\0').update(body, 'utf8').digest('hex');
+    const identity = `world-events:v1:${service}:${seq}:${deliveryContent}`;
     const extraHeaders = decl.headers ? headersFor(decl.headers, filled, row) : {};
-    const headers = { ...extraHeaders, ...signEventAll(decl.scheme, String(at(row, kind.secret)), body, seconds, url, seq) };
+    const headers = { ...extraHeaders, ...signEventAll(decl.scheme, String(at(row, kind.secret)), body, seconds, url, seq, identity) };
     sent.push({ url, body, headers });
     // kept with the write, by an id of the delivery itself (two made at once never take the same one)
-    if (decl.record !== undefined) {
-      await applyTwinWrite(service, {
-        operation: `${decl.record.slice(1)}.record`, subjectType: decl.record, subjectId: `${decl.record.slice(1)}_${digest(`${url}|${seconds}|${seq}|${body}`).slice(0, 16)}`,
-        fields: { url, body, headers, event_type: type, sent_at: millis }, occurredAt: write.occurredAt, actor: { kind: 'system' },
-      }, write.root);
-    }
+    const record = decl.record ?? '_world_event_delivery';
+    const id = `${record.slice(1)}_v1_${seq}`;
+    await applyTwinWrite(service, {
+      operation: `${record.slice(1)}.record`, subjectType: record, subjectId: id,
+      fields: { url, body, headers, event_type: type, sent_at: millis,
+        delivery_protocol: 1, event_id: String(filled.$id),
+        endpoint_type: kind.storedAs, endpoint_id: String(row.id),
+        delivery_state: 'queued', attempt_count: 0, current_attempt: null,
+        transport_status: null, finished_at: null, accepted_at: null,
+      }, occurredAt: write.occurredAt, actor: { kind: 'system' },
+    }, write.root);
+    recorded.push({ type: record, id });
   }
   // sent after the write's answer, as a vendor sends it: the caller never waits on its receiver, and a receiver that is
   // slow or down fails no request
   // the write's trace is read now, inside its request, and carried on each delivery (W3C trace continuation)
   const trace = deliveryTraceHeaders();
+  // A timer must retain the request's store/root even if another World becomes
+  // active before it runs. Transport completion writes to the same retained state.
+  const store = getActiveWorldStore(), deliveryRoot = worldPaths(service, write.root).root;
   for (const d of sent) deliveryObserver?.({ ...d, service });
-  for (const { url, body: payload, headers } of sent) setTimeout(() => {
-    void transport(url, payload, { ...headers, ...trace }).catch(() => {});
+  for (const packet of recorded) setTimeout(() => {
+    // Persistence failure leaves a queued/sending claim for explicit recovery;
+    // it must not fail the already-committed vendor write or cause a blind resend.
+    void withWorldStore(store, () => sendRecordedEvent(service, packet.type, packet.id, deliveryRoot, transport, trace)).catch(() => {});
   }, 0);
   return sent;
 }