experimental-a2 0.0.0

package/dist/errors-BJRMd-h6.js

@@ -0,0 +1,23 @@
+//#region src/errors.ts
+var A2Error = class extends Error {
+	code;
+	/** e.g. the Standard Schema issues for INVALID_PAYLOAD */
+	details;
+	constructor(code, message, options) {
+		super(message, options && "cause" in options ? { cause: options.cause } : void 0);
+		this.name = "A2Error";
+		this.code = code;
+		this.details = options?.details;
+	}
+};
+/**
+* Wrap an arbitrary thrown value as LOG_UNAVAILABLE, preserving the
+* original as `cause`. A2Errors pass through untouched — they already
+* carry their own meaning.
+*/
+function asLogUnavailable(err) {
+	if (err instanceof A2Error) return err;
+	return new A2Error("LOG_UNAVAILABLE", "the log backend failed", { cause: err });
+}
+//#endregion
+export { asLogUnavailable as n, A2Error as t };

package/dist/errors-xL_JTXsY.d.ts

@@ -0,0 +1,20 @@
+//#region src/errors.d.ts
+/**
+ * a2 errors — one class, discriminated by `code`.
+ *
+ * See specs/a2-implementation.md §10 and docs/reference/02-errors.mdx.
+ * A single class serializes cleanly across the push-route boundary and
+ * keeps `instanceof` checks working after bundling.
+ */
+type A2ErrorCode = "INVALID_PAYLOAD" | "UNKNOWN_EVENT_TYPE" | "PARTIAL_DUPLICATE_BATCH" | "LOG_UNAVAILABLE" | "LOG_NOT_CONFIGURED";
+declare class A2Error extends Error {
+  readonly code: A2ErrorCode;
+  /** e.g. the Standard Schema issues for INVALID_PAYLOAD */
+  readonly details: unknown;
+  constructor(code: A2ErrorCode, message: string, options?: {
+    details?: unknown;
+    cause?: unknown;
+  });
+}
+//#endregion
+export { A2ErrorCode as n, A2Error as t };

package/dist/http.d.ts

@@ -0,0 +1,44 @@
+import { a as Event } from "./log-Dg1I8NRr.js";
+import { PushedEvent } from "./server.js";
+import { t as A2Error } from "./errors-xL_JTXsY.js";
+//#region src/http.d.ts
+/** The push envelope: what a client POSTs to append events. */
+type PushBody = {
+  sessionId: string;
+  /** Branded: `session.append` accepts these directly (the push route
+   * path); schema validation still happens inside `append`. */
+  events: PushedEvent[];
+};
+/**
+ * Validate the push envelope — `{ sessionId, events }` — throwing
+ * `INVALID_PAYLOAD` on a malformed body. Payload validation against the
+ * machine's schemas happens in `append`, not here.
+ */
+declare function parsePushBody(req: Request): Promise<PushBody>;
+/**
+ * Pipe a live event iterable into an SSE `Response`. Each event is one
+ * frame — `id:` carries the log index, `data:` the JSON event. A
+ * disconnecting client cancels the stream, which closes the underlying
+ * subscription. Two kinds of comment frames ride along: a `: connected`
+ * prelude that flushes headers immediately, and a `: ping` heartbeat
+ * every 15 seconds so clients (and proxies) can tell a quiet stream
+ * from a dead connection — the session client's stall watchdog counts
+ * on it.
+ */
+declare function sseResponse(iterable: AsyncIterable<Event>): Response;
+/**
+ * Serialize an error into the documented wire shape,
+ * `{ error: { code, message, details } }`, with the mapped status
+ * (400 for caller bugs, 503 for LOG_UNAVAILABLE). Non-A2Errors become a
+ * 503 LOG_UNAVAILABLE — from the client's perspective an unknown server
+ * failure is retryable-once, not a protocol contract.
+ */
+declare function errorResponse(error: unknown): Response;
+/**
+ * The other half of the wire pair: rebuild an `A2Error` from a response
+ * body, or null if the body isn't one. Client `push` uses it so both
+ * sides branch on identical codes.
+ */
+declare function deserializeError(body: unknown): A2Error | null;
+//#endregion
+export { PushBody, deserializeError, errorResponse, parsePushBody, sseResponse };

package/dist/http.js

@@ -0,0 +1,119 @@
+import { t as A2Error } from "./errors-BJRMd-h6.js";
+import { r as STREAM_TIMINGS } from "./internal-Dm8Ejnud.js";
+import { a as eventToWire, n as errorStatus, r as errorToWire, t as errorFromWire } from "./wire-2QpU1EtJ.js";
+//#region src/http.ts
+/**
+* a2/http — route-side transport helpers (specs/a2-api.md §9–10).
+*
+* `sseResponse` pipes a `session.stream()` iterable into a server-sent
+* events Response; `parsePushBody` validates the push envelope;
+* `errorResponse`/`deserializeError` are the A2Error wire pair the push
+* route and the client's `push` share.
+*/
+const invalid = (message) => new A2Error("INVALID_PAYLOAD", `malformed push body: ${message}`);
+/**
+* Validate the push envelope — `{ sessionId, events }` — throwing
+* `INVALID_PAYLOAD` on a malformed body. Payload validation against the
+* machine's schemas happens in `append`, not here.
+*/
+async function parsePushBody(req) {
+	let body;
+	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 } = body;
+	if (typeof sessionId !== "string" || sessionId.length === 0) throw invalid("sessionId must be a non-empty string");
+	if (!Array.isArray(events) || events.length === 0) throw invalid("events must be a non-empty array");
+	return {
+		sessionId,
+		events: events.map((event, i) => {
+			if (event === null || typeof event !== "object") throw invalid(`events[${i}] must be an object`);
+			const { type, payload, id } = event;
+			if (typeof type !== "string" || type.length === 0) throw invalid(`events[${i}].type must be a non-empty string`);
+			if (id !== void 0 && typeof id !== "string") throw invalid(`events[${i}].id must be a string when present`);
+			const out = {
+				type,
+				payload
+			};
+			if (id !== void 0) out.id = id;
+			return out;
+		})
+	};
+}
+/**
+* Pipe a live event iterable into an SSE `Response`. Each event is one
+* frame — `id:` carries the log index, `data:` the JSON event. A
+* disconnecting client cancels the stream, which closes the underlying
+* subscription. Two kinds of comment frames ride along: a `: connected`
+* prelude that flushes headers immediately, and a `: ping` heartbeat
+* every 15 seconds so clients (and proxies) can tell a quiet stream
+* from a dead connection — the session client's stall watchdog counts
+* on it.
+*/
+function sseResponse(iterable) {
+	const iterator = iterable[Symbol.asyncIterator]();
+	const encoder = new TextEncoder();
+	let heartbeat;
+	const stopHeartbeat = () => {
+		if (heartbeat !== void 0) clearInterval(heartbeat);
+		heartbeat = void 0;
+	};
+	const stream = new ReadableStream({
+		start(controller) {
+			controller.enqueue(encoder.encode(": connected\n\n"));
+			heartbeat = setInterval(() => {
+				try {
+					controller.enqueue(encoder.encode(": ping\n\n"));
+				} catch {
+					stopHeartbeat();
+				}
+			}, STREAM_TIMINGS.sseHeartbeatMs);
+			heartbeat.unref?.();
+		},
+		async pull(controller) {
+			const { value, done } = await iterator.next();
+			if (done) {
+				stopHeartbeat();
+				controller.close();
+				return;
+			}
+			controller.enqueue(encoder.encode(`id: ${value.index}\ndata: ${JSON.stringify(eventToWire(value))}\n\n`));
+		},
+		async cancel() {
+			stopHeartbeat();
+			await iterator.return?.();
+		}
+	});
+	return new Response(stream, {
+		status: 200,
+		headers: {
+			"content-type": "text/event-stream",
+			"cache-control": "no-cache, no-transform",
+			connection: "keep-alive"
+		}
+	});
+}
+/**
+* Serialize an error into the documented wire shape,
+* `{ error: { code, message, details } }`, with the mapped status
+* (400 for caller bugs, 503 for LOG_UNAVAILABLE). Non-A2Errors become a
+* 503 LOG_UNAVAILABLE — from the client's perspective an unknown server
+* failure is retryable-once, not a protocol contract.
+*/
+function errorResponse(error) {
+	const a2error = error instanceof A2Error ? error : new A2Error("LOG_UNAVAILABLE", "internal error", { cause: error });
+	return Response.json(errorToWire(a2error), { status: errorStatus(a2error.code) });
+}
+/**
+* The other half of the wire pair: rebuild an `A2Error` from a response
+* body, or null if the body isn't one. Client `push` uses it so both
+* sides branch on identical codes.
+*/
+function deserializeError(body) {
+	return errorFromWire(body);
+}
+//#endregion
+export { deserializeError, errorResponse, parsePushBody, sseResponse };

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import { a as ReducerOptions, c as ReducerBuilder, i as EventDefs, l as StandardSchemaV1, n as Contract, o as contract, r as ContractEvent, s as Reducer, t as AppendInput } from "./contract-DL8btVd9.js";
+import { a as Event } from "./log-Dg1I8NRr.js";
+import { i as A2Telemetry, n as A2SpanHandle, r as A2SpanName, t as A2AttributeValue } from "./telemetry-C78al20p.js";
+import { n as A2ErrorCode, t as A2Error } from "./errors-xL_JTXsY.js";
+export { type A2AttributeValue, A2Error, type A2ErrorCode, type A2SpanHandle, type A2SpanName, type A2Telemetry, type AppendInput, type Contract, type ContractEvent, type Event, type EventDefs, type Reducer, type ReducerBuilder, type ReducerOptions, type StandardSchemaV1, contract };

package/dist/index.js

@@ -0,0 +1,3 @@
+import { t as contract } from "./contract-B0kAXoaL.js";
+import { t as A2Error } from "./errors-BJRMd-h6.js";
+export { A2Error, contract };

package/dist/inspection-E7qbD0Xj.js

@@ -0,0 +1,10 @@
+//#region src/inspection.ts
+const serverInspection = /* @__PURE__ */ new WeakMap();
+/** Owned live-inspection cadence; mutable only for white-box tests. */
+const DEVTOOLS_TIMINGS = {
+	activeMs: 250,
+	idleMs: 1e3,
+	heartbeatMs: 15e3
+};
+//#endregion
+export { serverInspection as n, DEVTOOLS_TIMINGS as t };

package/dist/internal-Dm8Ejnud.js

@@ -0,0 +1,36 @@
+//#region src/internal.ts
+const serverInternals = /* @__PURE__ */ new WeakMap();
+/**
+* Drain timing knobs. Mutable only as a white-box test seam — lease
+* heartbeats run on real timers, so tests shrink these to keep suites
+* fast. Production always uses the defaults.
+*/
+const DRAIN_TIMINGS = {
+	leaseTtlMs: 5e3,
+	leaseHeartbeatMs: 2e3,
+	recoveryGraceMs: 1e3,
+	recoveryArmTimeoutMs: 2e3
+};
+/**
+* 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 log 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.
+*/
+const POLL_TIMINGS = {
+	activeFloorMs: 25,
+	idleCeilingMs: 250
+};
+const STREAM_TIMINGS = {
+	sseHeartbeatMs: 15e3,
+	stallTimeoutMs: 35e3
+};
+//#endregion
+export { serverInternals as i, POLL_TIMINGS as n, STREAM_TIMINGS as r, DRAIN_TIMINGS as t };

package/dist/log-Dg1I8NRr.d.ts

@@ -0,0 +1,245 @@
+//#region src/log.d.ts
+/**
+ * The A2Log interface — the storage contract every log backend
+ * implements. See specs/a2-implementation.md §2–3.
+ *
+ * This is the whole storage contract: append, read, the drain markers,
+ * the failure markers, leases, snapshots, and the live stream. Recovery
+ * needs nothing extra — the armed queue message is its own state, and
+ * the log is the only thing it consults.
+ */
+/** A stored event, as the public API exposes it. */
+type Event = {
+  id: string;
+  type: string;
+  payload: unknown;
+  /** Position in the session's log, from 1. */
+  index: number;
+  sessionId: string;
+  createdAt: Date;
+};
+/** The handler dispatch whose append first persisted a child event. */
+type EventCause = {
+  index: number;
+  attempt: number;
+};
+/**
+ * What the log stores: immutable event history, including its causal edge,
+ * plus derived drain and failure bookkeeping. The bookkeeping is disposable;
+ * the event and its cause are not.
+ */
+type StoredEvent = Event & {
+  /** Same-session handler dispatch that appended this event; null means root or legacy unknown. */
+  cause: EventCause | null;
+  /** Adapter clock time recorded by completion or manual skip; null while pending. */
+  processedAt: Date | null;
+  /** Dispatch attempt that completed this event; null for pending or administrative completion. */
+  processedByAttempt: number | null;
+  /** Adapter clock time recorded by the first durable dispatch claim. */
+  firstClaimedAt: Date | null;
+  /** Adapter clock time recorded by the most recent durable dispatch claim. */
+  lastClaimedAt: Date | null;
+  /** Durable dispatch claims, including claims abandoned by hard kills. */
+  attemptCount: number;
+  /** Caught handler failures. This alone drives dead-lettering. */
+  failureCount: number;
+  /** Adapter clock time recorded by the most recent caught handler failure. */
+  lastFailedAt: Date | null;
+  /** Dispatch attempt that produced the most recent caught handler failure. */
+  lastFailedAttempt: number | null;
+  /** The last handler failure, stringified. */
+  lastError: string | null;
+  /** Adapter clock time recorded when dead-lettered; null otherwise. */
+  failedAt: Date | null;
+};
+/** Durable, read-only session metadata for administrative inspection. */
+type StoredSessionSummary = {
+  sessionId: string;
+  eventCount: number;
+  pendingCount: number;
+  failedCount: number;
+  /** Durable dispatch claims across every event in the session. */
+  attemptCount: number;
+  /** Caught handler failures across every event in the session. */
+  failureCount: number;
+  firstEventAt: Date;
+  updatedAt: Date;
+};
+/** Metadata for the latest cached fold of one reducer. */
+type StoredSnapshot = {
+  reducerName: string;
+  index: number;
+  updatedAt: Date;
+};
+/** One consistent cache-plus-tail read for a reducer fold. */
+type LogStateRead = {
+  /** The latest cached fold for this reducer, if one exists. */
+  snapshot: {
+    index: number;
+    state: unknown;
+  } | null;
+  /** Immutable events strictly after `snapshot.index`, or the full log on a miss. */
+  events: Event[];
+};
+type StoredSessionPage = {
+  sessions: StoredSessionSummary[];
+  /** Opaque backend cursor; null means there is no next page. */
+  cursor: string | null;
+};
+/**
+ * Optional read-only administration implemented by A2's shipped logs.
+ * It is separate from the correctness contract so custom logs do not
+ * need to expose storage-wide discovery merely to store and drain events.
+ */
+type A2LogInspection = {
+  listSessions(options: {
+    /** Storage namespace prefix, including the contract separator. */
+    prefix: string;
+    cursor?: string;
+    limit: number;
+  }): Promise<StoredSessionPage>;
+  listSnapshots(sessionId: string): Promise<StoredSnapshot[]>;
+};
+/** The result of atomically claiming the next event in a drain. */
+type LogClaimResult = {
+  outcome: "claimed";
+  event: StoredEvent;
+} | {
+  outcome: "busy";
+} | {
+  outcome: "settled";
+};
+/** A completion may lose to a newer claim or an earlier completion. */
+type LogHandoffResult = LogClaimResult | {
+  outcome: "superseded";
+};
+/** The result of atomically recording a caught handler failure. */
+type FailAttemptResult = {
+  outcome: "failed" | "dead_lettered" | "superseded";
+  failureCount: number;
+};
+/** Input to `A2Log.append` — already validated by the machine. */
+type AppendEvent = {
+  type: string;
+  payload: unknown;
+  /** Caller-supplied idempotency key; generated when absent. */
+  id?: string;
+  /** Internal causal edge supplied atomically by `ctx.append`. */
+  cause?: EventCause;
+};
+/**
+ * An injectable clock. Adapters take one so tests can drive lease
+ * expiry, failure timestamps, and (later) stuck-session detection
+ * deterministically — against real storage, no mocking.
+ */
+type Clock = {
+  now(): Date;
+};
+/** An injectable id source for generated event ids. */
+type IdSource = () => string;
+interface A2Log {
+  /**
+   * Accepts a batch; the batch is atomic — one transaction, consecutive
+   * `index`es, all-or-nothing. The idempotency key covers the whole
+   * operation, not each item: if *every* event's `id` already exists in
+   * this session, this is a retry of a committed batch whose ack was
+   * lost — return the existing rows as success. If only *some* ids
+   * exist, the caller mixed an already-sent batch with fresh events —
+   * always a caller bug — so throw `A2Error('PARTIAL_DUPLICATE_BATCH')`.
+   */
+  append(sessionId: string, events: AppendEvent[]): Promise<StoredEvent[]>;
+  /** Events for one session, oldest first. */
+  read(sessionId: string, opts?: {
+    afterIndex?: number;
+    unprocessedOnly?: boolean;
+  }): Promise<StoredEvent[]>;
+  /**
+   * Atomically selects the first pending event, checks its scope, acquires the
+   * session lease, increments its durable dispatch count, and records the
+   * operation's clock time. A claimed event's `attemptCount` is the 1-based
+   * attempt passed to its handler.
+   */
+  claimNext(options: {
+    sessionId: string;
+    holder: string;
+    ttlMs: number;
+    expiresAtMs?: number;
+    /** Inclusive causal-tree frontier. Omit for a full-session drain. */
+    maxIndex?: number;
+  }): Promise<LogClaimResult>;
+  /**
+   * Atomically marks one event processed only if its attempt is still current
+   * and it has no completion marker. While this holder still owns a live lease,
+   * claims the next pending event. Completion and any claimed successor record
+   * the same adapter clock value.
+   */
+  completeAndClaimNext(options: {
+    sessionId: string;
+    holder: string;
+    completedIndex: number;
+    attempt: number;
+    /** Inclusive causal-tree frontier. Omit for a full-session drain. */
+    maxIndex?: number;
+  }): Promise<LogHandoffResult>;
+  /** The drain-completion marker and drain idempotency check. */
+  markProcessed(sessionId: string, index: number): Promise<void>;
+  /**
+   * Atomically records a caught failure for one claimed attempt. A stale
+   * attempt cannot poison a processed event or a newer dispatch. Accepted
+   * failures record the operation's clock time.
+   */
+  failAttempt(options: {
+    sessionId: string;
+    index: number;
+    attempt: number;
+    error: string;
+    maxFailures: number;
+  }): Promise<FailAttemptResult>;
+  /** Dead-letters the event. */
+  markFailed(sessionId: string, index: number): Promise<void>;
+  /**
+   * Reads a reducer snapshot and its event tail as one consistent adapter
+   * operation. On a cache miss, `snapshot` is null and `events` is the full
+   * log. The snapshot is untrusted; core may reject it and issue a full
+   * `read()` when its state schema no longer accepts the cached value.
+   */
+  readState(sessionId: string, reducerName: string): Promise<LogStateRead>;
+  /**
+   * Writes a disposable reducer cache. Guard this operation so a slower
+   * concurrent writer can never clobber a further-along snapshot
+   * (`where up_to_index < excluded.up_to_index`).
+   */
+  putSnapshot(sessionId: string, reducerName: string, index: number, state: unknown): Promise<void>;
+  /** Read-only operational data used by `a2/devtools/server`. */
+  inspect?: A2LogInspection;
+  /**
+   * One lease per session — serializes processing order for a session,
+   * not individual events. TTL-bounded, never held indefinitely.
+   * Re-acquiring with the same holder renews the TTL.
+   */
+  lease: {
+    acquire(options: {
+      sessionId: string;
+      holder: string;
+      ttlMs: number;
+      /** Optional absolute expiry used for platform-deadline lease windows. */
+      expiresAtMs?: number;
+    }): Promise<boolean>;
+    release(options: {
+      sessionId: string;
+      holder: string;
+    }): Promise<void>;
+  };
+  /**
+   * A live feed of one session's events, starting after `startAt`
+   * (exclusive). Transport is the backend's choice — in-process pub/sub,
+   * polling, LISTEN/NOTIFY — callers never branch on which. The iterable
+   * ends when the consumer calls `return()` (e.g. a disconnecting SSE
+   * client) and must deliver events appended after subscription.
+   */
+  stream(sessionId: string, opts?: {
+    startAt?: number;
+  }): AsyncIterable<Event>;
+}
+//#endregion
+export { Event as a, IdSource as c, LogStateRead as d, StoredEvent as f, StoredSnapshot as h, Clock as i, LogClaimResult as l, StoredSessionSummary as m, A2LogInspection as n, EventCause as o, StoredSessionPage as p, AppendEvent as r, FailAttemptResult as s, A2Log as t, LogHandoffResult as u };

package/dist/log-memory.d.ts

@@ -0,0 +1,11 @@
+import { c as IdSource, i as Clock, t as A2Log } from "./log-Dg1I8NRr.js";
+//#region src/log-memory.d.ts
+type MemoryLogOptions = {
+  /** Injectable clock — every stored timestamp comes from here. */
+  clock?: Clock;
+  /** Injectable id source for generated event ids. */
+  ids?: IdSource;
+};
+declare function memory(options?: MemoryLogOptions): A2Log;
+//#endregion
+export { MemoryLogOptions, memory };