experimental-a2 0.20.0 → 0.22.0

package/src/presence-recovery.ts

@@ -1,4 +1,5 @@
 import type { PresencePatch } from './contract.ts'
+import { presenceTombstones } from './presence-tombstones.ts'
 import type { PresenceRow } from './store.ts'
 
 type Field = Pick<PresenceRow, 'participant' | 'field' | 'seen' | 'at'>
@@ -22,6 +23,7 @@ export function presenceRecovery({
   update(patch: PresencePatch): void
 } {
   const fields = new Map<string, Field>()
+  const deleted = presenceTombstones()
   const reading = new Set<Set<string>>()
   let generation = 0
   let latest: Promise<PresenceRow[]> | undefined
@@ -49,11 +51,14 @@ export function presenceRecovery({
       const rows = await read()
       if (!isActive()) return rows
       if (run !== generation) return latest!
+      // A row older than its field's deletion must not resurrect it.
+      const current = rows.filter((row) => !deleted.outranks(row))
       const live = new Set<string>()
-      for (const row of rows) {
+      for (const row of current) {
         const id = key(row)
         live.add(id)
         if (changed.has(id)) continue
+        deleted.drop(row)
         remember(row)
         if (reconcile)
           deliver({
@@ -68,6 +73,7 @@ export function presenceRecovery({
           if (live.has(id) || changed.has(id) || fields.get(id) !== prior)
             continue
           fields.delete(id)
+          deleted.keep(prior)
           deliver({
             participant: prior.participant,
             values: { [prior.field]: null },
@@ -76,7 +82,7 @@ export function presenceRecovery({
           })
         }
       }
-      return rows
+      return current
     } finally {
       reading.delete(changed)
       if (reading.size === 0) latest = undefined
@@ -102,18 +108,19 @@ export function presenceRecovery({
     update(patch) {
       for (const [field, value] of Object.entries(patch.values)) {
         if (value === undefined) continue
-        const id = key({ participant: patch.participant, field })
+        const write = { participant: patch.participant, field, at: patch.at }
+        const id = key(write)
         const previous = fields.get(id)
         if (previous && previous.at.getTime() > patch.at.getTime()) continue
+        if (deleted.outranks(write)) continue
         for (const changed of reading) changed.add(id)
-        if (value === null) fields.delete(id)
-        else
-          remember({
-            participant: patch.participant,
-            field,
-            seen: patch.seen,
-            at: patch.at,
-          })
+        if (value === null) {
+          fields.delete(id)
+          deleted.keep(write)
+        } else {
+          deleted.drop(write)
+          remember({ ...write, seen: patch.seen })
+        }
       }
     },
   }

package/src/presence-tombstones.ts

@@ -0,0 +1,52 @@
+import { PRESENCE_TIMINGS } from './internal.ts'
+
+type PresenceField = { participant: string; field: string }
+type PresenceWrite = PresenceField & { at: Date }
+
+/**
+ * The deletion stamps a presence applier keeps per (participant, field),
+ * so a null keeps beating older sets that arrive after it. Each lives
+ * `PRESENCE_TIMINGS.tombstoneMs` of local receipt time and is pruned
+ * lazily on use, without timers.
+ */
+export type PresenceTombstones = {
+  /** Whether the field's deletion is strictly newer than the write. */
+  outranks(write: PresenceWrite): boolean
+  /** Keep the deletion; the caller has already ordered it past any prior one. */
+  keep(deletion: PresenceWrite): void
+  /** Forget the field's deletion once a write at or past it applies. */
+  drop(field: PresenceField): void
+}
+
+const key = ({ participant, field }: PresenceField): string =>
+  JSON.stringify([participant, field])
+
+export function presenceTombstones(): PresenceTombstones {
+  // Insertion order is receipt order, so pruning stops at the first
+  // tombstone still inside the window.
+  const stamps = new Map<string, { atMs: number; keptAtMs: number }>()
+  const prune = (): void => {
+    const cutoff = Date.now() - PRESENCE_TIMINGS.tombstoneMs
+    for (const [id, stamp] of stamps) {
+      if (stamp.keptAtMs > cutoff) return
+      stamps.delete(id)
+    }
+  }
+  return {
+    outranks(write) {
+      if (stamps.size === 0) return false
+      prune()
+      const stamp = stamps.get(key(write))
+      return stamp !== undefined && stamp.atMs > write.at.getTime()
+    },
+    keep(deletion) {
+      prune()
+      const id = key(deletion)
+      stamps.delete(id)
+      stamps.set(id, { atMs: deletion.at.getTime(), keptAtMs: Date.now() })
+    },
+    drop(field) {
+      if (stamps.size > 0) stamps.delete(key(field))
+    },
+  }
+}

package/src/push-envelope.ts

@@ -77,6 +77,13 @@ export function parsePresenceSibling(
   return out
 }
 
+/** The longest event id a push may carry: ids are indexed, and Postgres's index rows have a limit. */
+const MAX_PUSHED_ID = 256
+
+/** A UUIDv5, the shape of the ids A2 derives (deterministic-id.ts). */
+const DERIVED_ID =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-5[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+
 /** The events half of the envelope, shared by the POST body and socket
  * `push` frames so INVALID_PAYLOAD shapes have one implementation. */
 export function parsePushEvents(events: unknown): ParsedPushEvent[] {
@@ -94,6 +101,19 @@ export function parsePushEvents(events: unknown): ParsedPushEvent[] {
     if (id !== undefined && typeof id !== 'string') {
       throw invalid(`events[${i}].id must be a string when present`)
     }
+    if (id !== undefined && (id.length === 0 || id.length > MAX_PUSHED_ID)) {
+      throw invalid(
+        `events[${i}].id must be 1-${MAX_PUSHED_ID} characters when present`,
+      )
+    }
+    // A2 derives the ids of what consumers append, return, and schedule as
+    // UUIDv5s, from inputs a caller can know: one pushed first into the same
+    // session would take its place. Callers' own ids are v4 (crypto.randomUUID) or v8 (idempotentId).
+    if (id !== undefined && DERIVED_ID.test(id)) {
+      throw invalid(
+        `events[${i}].id is shaped like the ids A2 derives for consumers (a UUIDv5); use crypto.randomUUID() or idempotentId()`,
+      )
+    }
     const out: { type: string; payload: unknown; id?: string } = {
       type,
       payload,

package/src/runtime-consumer.ts

@@ -0,0 +1,10 @@
+/**
+ * `consumer()` for A2's own runtimes (actors, the AI runtime): their names
+ * sit under the reserved `a2.` prefix, and their child ids leave the name
+ * out, as the handler tables they replaced had. Not a public entry point.
+ */
+import { runtimeConsumerFactory } from './internal.ts'
+import type { consumer } from './server.ts'
+
+export const runtimeConsumer = ((options: never) =>
+  runtimeConsumerFactory.define!(options)) as typeof consumer

package/src/scheduler-task.ts

@@ -5,7 +5,7 @@ export type ScheduledEvent = {
   payload: unknown
 }
 
-/** A durable wake-up for pending handler work. */
+/** A durable wake-up for pending consumer work. */
 export type SchedulerDrainTask = {
   version: 1
   kind: 'drain'
@@ -26,7 +26,7 @@ export type SchedulerAppendTask = {
   /** Earliest useful delivery as epoch milliseconds. */
   dueAt: number
   events: readonly ScheduledEvent[]
-  /** The scheduling handler's event; delivery skips once it is cleared. */
+  /** The scheduling consumer's event; delivery skips once it is cleared. */
   originIndex?: number
 }
 

package/src/scheduler-vercel.ts

@@ -14,7 +14,7 @@
  *   the configured deployment scope for sending and receiving.
  * - `handler(...servers)` is the delivery route: look up the server for
  *   the contract named in the message and drain it. Settled drains ack;
- *   contention, handler failure, and a drain that throws after arming its
+ *   contention, consumer failure, and a drain that throws after arming its
  *   successor all ack once a later watchdog is durable.
  *
  * `@vercel/queue` is an optional peer dependency, imported lazily. The

package/src/server.browser.ts

@@ -2,7 +2,7 @@
  * The browser build of experimental-a2/server. There isn't one — on purpose.
  * Contracts and reducers (from `experimental-a2`) and the session client (from
  * `experimental-a2/client` / `experimental-a2/react`) are the isomorphic surface; the server is
- * where handlers and storage live. This module existing in a client
+ * where consumers and storage live. This module existing in a client
  * bundle means a `'use client'` file (or something it imports)
  * value-imported your server module.
  */