@volter/world-core 3.0.152 → 3.0.153

package/dist/src/events.d.ts

@@ -140,11 +140,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`. */

package/dist/src/events.js

@@ -7,7 +7,7 @@
 // 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";
 /** Whether an endpoint takes an event by its `match`: every field of one match (any, when several) equal to the event's
@@ -25,16 +25,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 +57,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 +297,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,18 +328,19 @@ 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;
     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)}`,
+                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);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-core",
-  "version": "3.0.152",
+  "version": "3.0.153",
   "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/events.ts

@@ -7,7 +7,7 @@
 // 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';
 
@@ -123,19 +123,17 @@ export type EventDelivery = { url: string; body: string; headers: Record<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 +159,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
@@ -386,11 +401,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,18 +430,19 @@ 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;
   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)}`,
+        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);
     }