experimental-a2 0.3.0 → 0.5.0

package/src/internal.ts

@@ -0,0 +1,426 @@
+/**
+ * Private seams shared by a2 entry points and a2's own tests. Not exported
+ * from the package. Nothing here is public API.
+ */
+
+import type { ScheduledEvent } from './scheduler-task.ts'
+import type { A2Scheduler, DrainableServer } from './server.ts'
+
+export type DrainOutcome = 'busy' | 'stalled' | 'settled'
+
+/**
+ * A null-prototype record for maps keyed by caller-controlled strings
+ * (participant ids, presence field names). On a normal object,
+ * assigning to '__proto__' rewrites the prototype instead of creating
+ * an own property — the prototype-pollution class. Null-prototype
+ * objects still satisfy Record types and JSON.stringify cleanly.
+ */
+export function nullProtoRecord<T extends object>(): T {
+  return Object.create(null) as T
+}
+
+/**
+ * ECMA-262's maximum Date value (±8.64e15 ms). A presence stamp past
+ * it becomes an Invalid Date whose toISOString throws — one hostile
+ * stamp would poison every subscriber's snapshot frame — so both
+ * seams bound `at` to the representable range.
+ */
+export const MAX_DATE_MS = 8_640_000_000_000_000
+
+/**
+ * Participant ids that collide with Object.prototype plumbing.
+ * Null-prototype construction already defuses them, but they are
+ * rejected at both seams (`parsePushBody`, `setPresence`) so a hostile
+ * id never propagates into userland maps either.
+ */
+export const RESERVED_PARTICIPANT_IDS: ReadonlySet<string> = new Set([
+  '__proto__',
+  'constructor',
+  'prototype',
+])
+
+export type DrainResult = {
+  settled: boolean
+  outcome: DrainOutcome
+  /** Existing successor arm a scheduler callback may join before acking. */
+  schedulerArm?: Promise<void>
+}
+
+export type ServerInternals = {
+  /**
+   * Await every in-flight background drain this machine has scheduled,
+   * including ones scheduled while waiting. Lets tests flush the
+   * fire-and-forget inline path deterministically — no sleeps.
+   */
+  settle(): Promise<void>
+  /** The public `server.drain()` result deliberately remains `{ settled }`. */
+  schedulerDrain(
+    sessionId: string,
+    opts?: { watchdogDueAt?: number },
+  ): Promise<DrainResult>
+  /** Deliver a scheduler-owned delayed append through the normal root path. */
+  schedulerAppend(
+    sessionId: string,
+    events: readonly ScheduledEvent[],
+  ): Promise<void>
+}
+
+export const serverInternals: WeakMap<object, ServerInternals> = new WeakMap()
+
+type ServerSchedulerBinding = {
+  scheduler: A2Scheduler | undefined
+}
+
+/** Scheduler configuration captured only for servers made by `createServer`. */
+export const serverSchedulerBindings: WeakMap<object, ServerSchedulerBinding> =
+  new WeakMap()
+
+const objectLike = (value: unknown): value is object =>
+  (typeof value === 'object' && value !== null) || typeof value === 'function'
+
+/** The ambient value delivered to `handlerContext` during a tool execution. */
+export type AmbientToolScope = {
+  /** Executing server identity; a test scope from `runWithHandlerContext` has none. */
+  contract?: { readonly name: string }
+  context: unknown
+}
+
+/**
+ * Structural AsyncLocalStorage surface for the ambient tool scope. The
+ * instance is created by the server-only AI entry point (the only place
+ * `node:async_hooks` may be imported) and shared through a global
+ * symbol slot, so `handlerContext` in the isomorphic AI entry point and
+ * independently bundled A2 copies all read the same scope.
+ */
+export type AmbientToolScopeStorage = {
+  getStore(): AmbientToolScope | undefined
+  run<R>(store: AmbientToolScope, callback: () => R): R
+}
+
+const TOOL_SCOPE_STORAGE = Symbol.for('experimental-a2.ai.tool-scope')
+
+export function ambientToolScopeStorage(): AmbientToolScopeStorage | undefined {
+  const value = Reflect.get(globalThis, TOOL_SCOPE_STORAGE)
+  if (
+    !objectLike(value) ||
+    typeof Reflect.get(value, 'getStore') !== 'function' ||
+    typeof Reflect.get(value, 'run') !== 'function'
+  ) {
+    return undefined
+  }
+  return value as AmbientToolScopeStorage
+}
+
+export function installAmbientToolScopeStorage(
+  create: () => AmbientToolScopeStorage,
+): AmbientToolScopeStorage {
+  const existing = ambientToolScopeStorage()
+  if (existing !== undefined) return existing
+  const storage = create()
+  Reflect.set(globalThis, TOOL_SCOPE_STORAGE, storage)
+  return storage
+}
+
+export type SchedulerSendFailureDisposition = 'retryable' | 'terminal'
+
+type SchedulerSendFailureMarker = {
+  readonly version: 1
+  readonly pending: SchedulerSendFailureDisposition[]
+  readonly active: SchedulerSendFailureDisposition[]
+}
+
+const SCHEDULER_SEND_FAILURE = Symbol.for(
+  'experimental-a2.scheduler.send-failure',
+)
+
+const schedulerSendFailureMarker = (
+  value: unknown,
+): SchedulerSendFailureMarker | undefined => {
+  if (!objectLike(value)) return undefined
+  const marker = Reflect.get(value, SCHEDULER_SEND_FAILURE)
+  if (
+    !objectLike(marker) ||
+    Reflect.get(marker, 'version') !== 1 ||
+    !Array.isArray(Reflect.get(marker, 'pending')) ||
+    !Array.isArray(Reflect.get(marker, 'active'))
+  ) {
+    return undefined
+  }
+  return marker as SchedulerSendFailureMarker
+}
+
+const schedulerFailureObject = (error: unknown): object => {
+  if (
+    objectLike(error) &&
+    (schedulerSendFailureMarker(error) !== undefined ||
+      Object.isExtensible(error))
+  ) {
+    return error
+  }
+  return new Error(String(error), { cause: error })
+}
+
+const schedulerSendFailureState = (
+  error: object,
+): SchedulerSendFailureMarker => {
+  const existing = schedulerSendFailureMarker(error)
+  if (existing !== undefined) return existing
+  const marker: SchedulerSendFailureMarker = {
+    version: 1,
+    pending: [],
+    active: [],
+  }
+  Object.defineProperty(error, SCHEDULER_SEND_FAILURE, {
+    value: marker,
+    enumerable: false,
+    configurable: true,
+    writable: false,
+  })
+  return marker
+}
+
+const clearSchedulerSendFailureState = (
+  error: object,
+  marker: SchedulerSendFailureMarker,
+): void => {
+  if (marker.pending.length === 0 && marker.active.length === 0) {
+    Reflect.deleteProperty(error, SCHEDULER_SEND_FAILURE)
+  }
+}
+
+/**
+ * Classify an adapter error before throwing it. Unclassified adapter failures
+ * are retryable because the caller cannot know whether a remote send landed.
+ */
+export function classifySchedulerSendFailure(
+  error: unknown,
+  disposition: SchedulerSendFailureDisposition,
+): unknown {
+  const classified = schedulerFailureObject(error)
+  schedulerSendFailureState(classified).pending.push(disposition)
+  return classified
+}
+
+/** Consume a pending adapter classification and count this rejected send. */
+export function markSchedulerSendFailure(error: unknown): unknown {
+  const marked = schedulerFailureObject(error)
+  const marker = schedulerSendFailureState(marked)
+  marker.active.push(marker.pending.pop() ?? 'retryable')
+  return marked
+}
+
+export function consumeSchedulerSendFailure(
+  error: unknown,
+): SchedulerSendFailureDisposition | undefined {
+  if (!objectLike(error)) return undefined
+  const marker = schedulerSendFailureMarker(error)
+  const disposition = marker?.active.pop()
+  if (marker !== undefined) clearSchedulerSendFailureState(error, marker)
+  return disposition
+}
+
+const isDrainableServer = (value: unknown): value is DrainableServer => {
+  if (value === null || typeof value !== 'object') return false
+  const contract = Reflect.get(value, 'contract')
+  return (
+    contract !== null &&
+    typeof contract === 'object' &&
+    typeof Reflect.get(contract, 'name') === 'string' &&
+    typeof Reflect.get(value, 'drain') === 'function'
+  )
+}
+
+/**
+ * Validate the server list captured by a scheduler route at construction time.
+ * Built-in adapters keep their low-level target seam structural for custom
+ * integrations. The application-facing `schedulerHandler` uses strict mode
+ * so only servers made by this A2 copy reach a configured adapter.
+ */
+export function assertSchedulerTargets(
+  servers: readonly unknown[],
+  options: { allowStructural: boolean },
+): asserts servers is readonly DrainableServer[] {
+  const contracts = new Set<string>()
+  for (const target of servers) {
+    if (!isDrainableServer(target)) {
+      throw new TypeError('a2 scheduler: expected a server from createServer()')
+    }
+    const name = target.contract.name
+    if (contracts.has(name)) {
+      throw new TypeError(
+        `a2 scheduler: duplicate server contract '${name}' in one handler`,
+      )
+    }
+    contracts.add(name)
+
+    const binding = serverSchedulerBindings.get(target)
+    if (!binding) {
+      if (!options.allowStructural) {
+        throw new TypeError(
+          `a2 scheduler: server for contract '${name}' was not created by createServer()`,
+        )
+      }
+      continue
+    }
+  }
+}
+
+/** Require every real server to share one exact configured scheduler. */
+export function assertServerSchedulerBindings(
+  scheduler: A2Scheduler,
+  servers: readonly DrainableServer[],
+): void {
+  for (const server of servers) {
+    const binding = serverSchedulerBindings.get(server)
+    if (!binding?.scheduler) {
+      throw new TypeError(
+        `a2 scheduler: server for contract '${server.contract.name}' has no scheduler configured`,
+      )
+    }
+    if (binding.scheduler !== scheduler) {
+      throw new TypeError(
+        `a2 scheduler: server for contract '${server.contract.name}' is configured with a different scheduler instance`,
+      )
+    }
+  }
+}
+
+/** Resolve the scheduler privately bound to a real A2 server. */
+export function schedulerForServer(server: unknown): A2Scheduler {
+  if (!isDrainableServer(server)) {
+    throw new TypeError('a2 scheduler: expected a server from createServer()')
+  }
+  const binding = serverSchedulerBindings.get(server)
+  if (!binding) {
+    throw new TypeError(
+      `a2 scheduler: server for contract '${server.contract.name}' was not created by createServer()`,
+    )
+  }
+  if (!binding.scheduler) {
+    throw new TypeError(
+      `a2 scheduler: server for contract '${server.contract.name}' has no scheduler configured`,
+    )
+  }
+  return binding.scheduler
+}
+
+/**
+ * Drain timing knobs. Mutable only as a white-box test seam. Claim
+ * heartbeats run on real timers, so tests shrink these to keep suites
+ * fast. Production always uses the defaults.
+ */
+export const DRAIN_TIMINGS: {
+  /** How long a claim lives without renewal. */
+  claimTtlMs: number
+  /** Heartbeat cadence while a handler is running. */
+  claimHeartbeatMs: number
+  /** Base delay before retrying a failed renewal while the lease lives. */
+  renewRetryMs: number
+  /** Delay between a claim's expiry and its scheduler watchdog. */
+  watchdogGraceMs: number
+  /** Maximum time a top-level append waits for its initial scheduler arm. */
+  schedulerArmTimeoutMs: number
+} = {
+  claimTtlMs: 5_000,
+  claimHeartbeatMs: 2_000,
+  renewRetryMs: 400,
+  watchdogGraceMs: 1_000,
+  schedulerArmTimeoutMs: 2_000,
+}
+
+/**
+ * Stream liveness knobs — the server-side SSE heartbeat and the
+ * client-side stall watchdog. Paired by design: the client declares a
+ * connection dead after roughly two missed heartbeats. Mutable only as
+ * a white-box test seam; production always uses the defaults.
+ */
+/**
+ * Poll cadence for the poll-based store streams (sqlite, postgres) —
+ * owned, not configurable: adaptive polling removed the operator's
+ * reason to tune it (the floor keeps active streams smooth; the
+ * ceiling bounds idle cost). Mutable only as a white-box test seam so
+ * suites don't wait out real idle gaps.
+ */
+export const POLL_TIMINGS: {
+  /** Gap between polls while a session is producing events. */
+  activeFloorMs: number
+  /** The idle ceiling — the longest gap between polls. */
+  idleCeilingMs: number
+} = {
+  activeFloorMs: 25,
+  idleCeilingMs: 250,
+}
+
+/**
+ * Safety-read cadence for the notify-driven redis live stream. A
+ * parked feed re-reads the store at this interval even without a
+ * pub/sub wake-up, so a lost notification (subscriber reconnect gap,
+ * dropped PUBLISH) costs latency, never an event. Mutable only as a
+ * white-box test seam.
+ */
+export const NOTIFY_TIMINGS: {
+  safetyReadMs: number
+} = {
+  safetyReadMs: 10_000,
+}
+
+export const STREAM_TIMINGS: {
+  /** Cadence of `: ping` comment frames from `sseResponse`. */
+  sseHeartbeatMs: number
+  /** How far ahead of an invocation deadline an SSE response closes. */
+  sseDeadlineGraceMs: number
+  /** Client: silence longer than this means the connection is dead. */
+  stallTimeoutMs: number
+  /** Client reconnect backoff: first retry delay, doubling per attempt. */
+  reconnectBaseMs: number
+  /** Client reconnect backoff ceiling. */
+  reconnectMaxMs: number
+} = {
+  sseHeartbeatMs: 15_000,
+  sseDeadlineGraceMs: 1_000,
+  stallTimeoutMs: 35_000,
+  reconnectBaseMs: 500,
+  reconnectMaxMs: 5_000,
+}
+
+/**
+ * WebSocket down-pump backpressure — `sessionsSocket` parks its pull
+ * loop while the socket reports more buffered bytes than the
+ * high-water mark and re-checks on the poll cadence, so a slow reader
+ * applies backpressure to the store subscription instead of buffering
+ * without bound in the socket. Acks and heartbeats stay exempt: they
+ * are small and correctness-relevant. Mutable only as a white-box test
+ * seam.
+ */
+export const SOCKET_TIMINGS: {
+  highWaterMarkBytes: number
+  resumePollMs: number
+  /** Up-lane bound: concurrent push/presence handlers per socket. POST
+   * gets per-request platform limits for free; the socket must bring
+   * its own. Over the cap, pushes are answered with a retryable error
+   * ack and presence frames are shed (that plane repaints). */
+  maxInFlightMessages: number
+  /** Hard ceiling on `bufferedAmount`: past it the peer is a
+   * non-reader (acks and pings are park-exempt, so only a peer that
+   * never reads can reach it) and the socket closes 1008. */
+  disconnectWaterMarkBytes: number
+} = {
+  highWaterMarkBytes: 1_048_576,
+  resumePollMs: 25,
+  maxInFlightMessages: 32,
+  disconnectWaterMarkBytes: 8_388_608,
+}
+
+/**
+ * Client presence send cadence — a leading send immediately, then at
+ * most one merged send per interval (~15Hz). Owned, not configurable
+ * (decision #36's rule): coupling the cadence to the POST ack tied
+ * remote cursor smoothness to RTT, and the ack serves no correctness
+ * purpose on a fire-and-forget LWW plane. Mutable only as a white-box
+ * test seam.
+ */
+export const PRESENCE_TIMINGS: {
+  sendIntervalMs: number
+} = {
+  sendIntervalMs: 66,
+}

package/src/otel.ts

@@ -0,0 +1,59 @@
+/**
+ * experimental-a2/otel — OpenTelemetry adapter for the A2Telemetry interface.
+ *
+ * Peer-depends on `@opentelemetry/api` (optional). Spans nest through
+ * the active context, so with a context manager registered (any real
+ * OTel setup, e.g. `@vercel/otel`) the happy path lands in one trace:
+ * request → a2.append → a2.drain → a2.event → the handler's own spans.
+ */
+
+import {
+  SpanStatusCode,
+  trace,
+  type Span,
+  type Tracer,
+} from '@opentelemetry/api'
+import type { A2Telemetry } from './telemetry.ts'
+
+export type OtelOptions = {
+  /** Bring your own tracer; defaults to `trace.getTracer(tracerName)`. */
+  tracer?: Tracer
+  /** Tracer name for the global provider. Default `'a2'`. */
+  tracerName?: string
+}
+
+const fail = (span: Span, error: unknown): void => {
+  span.recordException(
+    error instanceof Error ? error : new Error(String(error)),
+  )
+  span.setStatus({
+    code: SpanStatusCode.ERROR,
+    message: error instanceof Error ? error.message : String(error),
+  })
+}
+
+export function otel(options: OtelOptions = {}): A2Telemetry {
+  const tracer = options.tracer ?? trace.getTracer(options.tracerName ?? 'a2')
+
+  return {
+    span(name, attributes, fn) {
+      return tracer.startActiveSpan(name, { attributes }, async (span) => {
+        try {
+          return await fn({
+            setAttribute: (key, value) => {
+              span.setAttribute(key, value)
+            },
+            recordError: (error) => {
+              fail(span, error)
+            },
+          })
+        } catch (error) {
+          fail(span, error)
+          throw error
+        } finally {
+          span.end()
+        }
+      })
+    },
+  }
+}

package/src/platform.ts

@@ -0,0 +1,60 @@
+/**
+ * Platform seams, read from the ambient request context — the same
+ * channel `@vercel/functions` uses (`Symbol.for('@vercel/request-context')`)
+ * — with no dependency on that package. Where no context exists (local
+ * dev, long-lived servers, other clouds) everything degrades cleanly:
+ * `waitUntil` becomes a no-op (background work is tracked in-process
+ * anyway) and the deadline is unknown (claim watchdogs use their ordinary
+ * TTL window).
+ *
+ * Tests exercise these paths by installing a real context object on the
+ * symbol — simulating the platform contract, not mocking a2.
+ */
+
+type RequestContext = {
+  headers?: Readonly<Record<string, string>>
+  waitUntil?: (promise: Promise<unknown>) => void
+  /**
+   * When the platform will terminate this invocation (epoch ms, ISO
+   * string, or Date) — on Vercel this includes `waitUntil` work.
+   */
+  deadline?: number | string | Date
+}
+
+const SYMBOL_FOR_REQ_CONTEXT = Symbol.for('@vercel/request-context')
+
+function requestContext(): RequestContext {
+  try {
+    const holder = Reflect.get(globalThis, SYMBOL_FOR_REQ_CONTEXT) as
+      { get?: () => RequestContext | undefined } | undefined
+    return holder?.get?.() ?? {}
+  } catch {
+    return {}
+  }
+}
+
+/** The current invocation's Vercel deployment identity, when available. */
+export function platformVercelOidcToken(): string | null {
+  try {
+    const token = requestContext().headers?.['x-vercel-oidc-token']
+    return typeof token === 'string' && token.length > 0 ? token : null
+  } catch {
+    return null
+  }
+}
+
+export function platformWaitUntil(promise: Promise<unknown>): void {
+  try {
+    requestContext().waitUntil?.(promise)
+  } catch {
+    // Best-effort — the promise is tracked in-process either way.
+  }
+}
+
+/** The invocation's termination time in epoch ms, or null if unknowable. */
+export function invocationDeadlineMs(): number | null {
+  const deadline = requestContext().deadline
+  if (deadline === undefined || deadline === null) return null
+  const ms = new Date(deadline as number | string | Date).getTime()
+  return Number.isNaN(ms) ? null : ms
+}

package/src/push-envelope.ts

@@ -0,0 +1,137 @@
+/**
+ * The push envelope's trust boundary — parsing and provenance-branding
+ * for `{ sessionId, events, presence? }`, shared verbatim by the HTTP
+ * POST lane and the socket's push/presence frames so INVALID_PAYLOAD
+ * shapes are one implementation. Internal module — `handle` (and the
+ * socket handler) compose it; it is not part of the public surface.
+ */
+
+import { A2Error } from './errors.ts'
+import { MAX_DATE_MS, RESERVED_PARTICIPANT_IDS } from './internal.ts'
+import type { PushedEvent, PushedPresence } from './server.ts'
+
+export const invalidPushBody = (message: string): A2Error =>
+  new A2Error('INVALID_PAYLOAD', `malformed push body: ${message}`)
+
+const invalid = invalidPushBody
+
+export type PushBody = {
+  sessionId: string
+  /** Branded: `session.append` accepts these directly (the push route
+   * path); schema validation still happens inside `append`. Empty only
+   * for a presence-only push. */
+  events: PushedEvent[]
+  /** Branded like `events`: `session.setPresence` accepts it whole;
+   * field validation still happens inside `setPresence`. */
+  presence?: PushedPresence
+}
+
+export function parsePresenceSibling(
+  value: unknown,
+): PushedPresence | undefined {
+  if (value === undefined) return undefined
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw invalid('presence must be an object when present')
+  }
+  const { participant, values, seen, at } = value as Record<string, unknown>
+  if (typeof participant !== 'string' || participant.length === 0) {
+    throw invalid('presence.participant must be a non-empty string')
+  }
+  if (RESERVED_PARTICIPANT_IDS.has(participant)) {
+    throw invalid(`presence.participant must not be '${participant}'`)
+  }
+  if (values === null || typeof values !== 'object' || Array.isArray(values)) {
+    throw invalid('presence.values must be an object')
+  }
+  if (
+    seen !== undefined &&
+    (typeof seen !== 'number' || !Number.isFinite(seen) || seen < 0)
+  ) {
+    throw invalid('presence.seen must be a non-negative number when present')
+  }
+  if (
+    at !== undefined &&
+    (typeof at !== 'number' ||
+      !Number.isFinite(at) ||
+      at < 0 ||
+      at > MAX_DATE_MS)
+  ) {
+    throw invalid(
+      'presence.at must be a non-negative epoch-milliseconds timestamp within the Date range when present',
+    )
+  }
+  const out: {
+    participant: string
+    values: Record<string, unknown>
+    seen?: number
+    at?: number
+  } = { participant, values: values as Record<string, unknown> }
+  if (seen !== undefined) out.seen = seen
+  if (at !== undefined) out.at = at
+  Object.defineProperty(out, '~a2.pushed', { value: true })
+  return out as PushedPresence
+}
+
+/** The events half of the envelope — shared verbatim by the POST body
+ * and the socket's `push` frames, so the provenance brand and the
+ * INVALID_PAYLOAD shapes are one implementation. */
+export function parsePushEvents(events: unknown): PushedEvent[] {
+  if (!Array.isArray(events) || events.length === 0) {
+    throw invalid('events must be a non-empty array')
+  }
+  return events.map((event, i) => {
+    if (event === null || typeof event !== 'object') {
+      throw invalid(`events[${i}] must be an object`)
+    }
+    const { type, payload, id } = event as Record<string, unknown>
+    if (typeof type !== 'string' || type.length === 0) {
+      throw invalid(`events[${i}].type must be a non-empty string`)
+    }
+    if (id !== undefined && typeof id !== 'string') {
+      throw invalid(`events[${i}].id must be a string when present`)
+    }
+    const out: { type: string; payload: unknown; id?: string } = {
+      type,
+      payload,
+    }
+    if (id !== undefined) out.id = id
+    Object.defineProperty(out, '~a2.pushed', { value: true })
+    return out as PushedEvent
+  })
+}
+
+/**
+ * Validate the push envelope — `{ sessionId, events, presence? }` —
+ * throwing `INVALID_PAYLOAD` on a malformed body. Payload validation
+ * against the machine's schemas happens in `append` and `setPresence`,
+ * not here. Either plane may appear alone: a presence-only push has no
+ * (or empty) `events`.
+ */
+export async function parsePushBody(req: Request): Promise<PushBody> {
+  let body: unknown
+  try {
+    body = await req.json()
+  } catch (cause) {
+    throw new A2Error('INVALID_PAYLOAD', 'push body is not valid JSON', {
+      cause,
+    })
+  }
+  if (body === null || typeof body !== 'object') {
+    throw invalid('expected an object')
+  }
+  const { sessionId, events, presence } = body as Record<string, unknown>
+  if (typeof sessionId !== 'string' || sessionId.length === 0) {
+    throw invalid('sessionId must be a non-empty string')
+  }
+  const parsedPresence = parsePresenceSibling(presence)
+  if (
+    parsedPresence !== undefined &&
+    (events === undefined || (Array.isArray(events) && events.length === 0))
+  ) {
+    return { sessionId, events: [], presence: parsedPresence }
+  }
+  const parsed = parsePushEvents(events)
+  return parsedPresence !== undefined
+    ? { sessionId, events: parsed, presence: parsedPresence }
+    : { sessionId, events: parsed }
+}