@volter/world-core 3.0.153 → 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;
@@ -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

@@ -10,6 +10,9 @@ import { createHash, createHmac } from 'node:crypto';
 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) {
@@ -328,6 +331,7 @@ async function deliverEventType(service, decl, write, data, transport, values, t
     const shared = JSON.stringify(envelope);
     const each = perEndpoint(decl.envelope);
     const sent = [];
+    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));
@@ -338,22 +342,33 @@ async function deliverEventType(service, decl, write, data, transport, values, t
         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)}_v1_${seq}`,
-                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.153",
+  "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

@@ -10,6 +10,9 @@ import { createHash, createHmac } from 'node:crypto';
 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,7 +121,7 @@ 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. */
@@ -302,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 {
@@ -430,6 +434,7 @@ async function deliverEventType(
   const shared = JSON.stringify(envelope);
   const each = perEndpoint(decl.envelope);
   const sent: EventDelivery[] = [];
+  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));
@@ -440,20 +445,31 @@ async function deliverEventType(
     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)}_v1_${seq}`,
-        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;
 }