@streamsy/serve 0.0.0-tegami-trusted-publish-setup → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Gareth Andrew
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,108 @@
-# Placeholder package
-  
-  This empty package was published by [Tegami](https://tegami.fuma-nama.dev) to configure npm trusted publishing.
-  
-  The real package contents will be published via CI with OIDC.
-  
+# @streamsy/serve
+
+Effect HttpRouter routes for streams, Durable State and JSON values, plus Bun,
+Node, Deno and Cloudflare host glue and durable action delivery. Requires Effect
+`4.0.1`.
+
+```ts
+import { Layer, Schema } from "effect";
+import { BunRuntime } from "@effect/platform-bun";
+import { Http, Streamsy, MemoryStorage } from "@streamsy/core";
+import { Serve } from "@streamsy/serve";
+import { listener } from "@streamsy/serve/bun";
+
+class Events extends Streamsy.json<Events>()("Readme/Events", "events/:seat", {
+  params: { seat: Schema.String },
+  schema: Schema.String,
+}) {}
+const streams = Streamsy.group(Events);
+const App = Layer.mergeAll(
+  Http.routes(streams, { prefix: "/streams", access: "full" }),
+  Serve.mount(Events, "/feed/:seat"),
+);
+const Server = Serve.layer(App).pipe(
+  Layer.provide(MemoryStorage.layer(streams)),
+  Layer.provide(listener({ port: 3000 })),
+);
+BunRuntime.runMain(Layer.launch(Server), { teardown: Serve.teardown });
+```
+
+`Serve.stream(address)` and `Serve.state(address)` return response Effects.
+State serves changes from `-1`, with no snapshot. `Serve.value(schema, effect)`
+serves canonical JSON with a deterministic ETag. Map `Projection.read` to serve
+custom values; an unsaved projection returns its declared initial value.
+An absent stream answers 404. Reads create no stream, checkpoint or state row.
+
+`Serve.params(Stream)` decodes path parameters. `Serve.mount(Stream, path)`
+mounts a declared stream or state. `Serve.route(path, handler)` owns all methods:
+GET and HEAD read; others return 405 with `allow: GET, HEAD`, unless CORS
+middleware answers a preflight. Handlers also compose inside app routes and
+`HttpApiBuilder.handleRaw`. Their respondable errors remain catchable.
+Auth can provide a service from which the handler builds an address.
+Protect the protocol routes too when their underlying data is private.
+
+Bun's listener defaults to `idleTimeout: 0`. Route handlers are interruptible
+on the pinned Effect/Bun router; client abort releases a parked long poll.
+The Node listener keeps the `node:http` defaults, which do not cut a parked
+long poll or an SSE body, and takes `server` options for `createServer`. The
+Deno listener needs no timeout setting. On Deno, run `nodeSqliteCompat` before
+an `@effect/sql-sqlite-node` client opens: Deno's `DatabaseSync` lacks the
+`enableLoadExtension` method that the driver calls.
+The caller owns the Layer scope. Tests or custom hosts can use Effect's
+`HttpRouter.toWebHandler(App)` and must call its `dispose` at shutdown.
+
+### Long-running hosts and shutdown
+
+`Serve.layer(App, options)` is `HttpRouter.serve(App, options)` with the drain
+for live readers built in. It takes the options of `HttpRouter.serve`, plus
+`drainTimeout` (default 2 seconds). Without a drain, closing the serve layer
+interrupts every handler: a parked long poll gets an empty `503` and an open
+SSE body is reset with no final event. With `Serve.layer`, the shutdown order
+is:
+
+1. The drain signals every live read. A parked long poll answers `204` with
+   `Stream-Next-Offset`, `Stream-Up-To-Date` and a fresh `Stream-Cursor`, the
+   same as a long-poll timeout. An open SSE body ends after its last whole
+   batch, which ends with a control event.
+2. The drain waits until no live read is running, or until `drainTimeout`
+   passes. A live request that arrives in this window gets the same reply at
+   once.
+3. The serve layer closes and interrupts any handler that is still running.
+4. Storage closes, then the listener stops.
+
+`Serve.teardown` is the exit policy for `runMain`. An interrupt-only exit, such
+as a stop by `SIGINT` or `SIGTERM`, exits 0 in place of Effect's 130. Any other
+exit keeps `Runtime.defaultTeardown`, so a startup failure stays non-zero.
+Both live in the root entry and depend on no runtime. A host subpath gives only
+the listener.
+
+The Durable Object host does not get a stop signal and uses neither.
+
+| Entry                                                                | Exports                                                                                                                                                            |
+| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `.`                                                                  | `Serve.stream`, `Serve.state`, `Serve.value`, `Serve.params`, `Serve.route`, `Serve.mount`, `Serve.layer`, `Serve.teardown`; errors and types; `PublicErrorSchema` |
+| `/contract`                                                          | Effect-free headers, public errors/decoder, canonical JSON, fingerprints                                                                                           |
+| `/bun`                                                               | `listener`, its options and defaults                                                                                                                               |
+| `/node`                                                              | `listener`, its options and defaults                                                                                                                               |
+| `/deno`                                                              | `listener`, its options and defaults; `nodeSqliteCompat`                                                                                                           |
+| `/cloudflare`                                                        | `StreamsyObject`, placement router/rules, alarm service                                                                                                            |
+| `/alchemy`                                                           | `objectHandlers`, placement router/rules, alarm service                                                                                                            |
+| `/action`                                                            | Unchanged action declarations                                                                                                                                      |
+| `/action/errors`, `/action/outbox`, `/action/runtime`, `/action/sql` | Action delivery and backing APIs; `createSqlOutboxBacking` runs on SQLite, Postgres and MySQL                                                                      |
+
+Twelve physical entries form six groups. Action's existing Sink names remain.
+State/stream recovery is `replay-from-start`; state consumers clear their local
+collection before replay. Old sink headers and snapshot reset exports are gone.
+Fingerprints cover route/address metadata and an optional `contract` revision;
+change that revision when codec behavior changes without metadata changing.
+Fingerprints are change detectors, not authorization or cryptographic identities.
+
+The value contract header is `x-streamsy-value-contract` (`VALUE_CONTRACT_HEADER`
+in `/contract`), and `Serve.value` options are `ValueOptions`. A projection's
+served state comes from `Projection.read(declaration.at(params))`.
+
+Guides: [Serve routes](https://streamsy.dev/docs/http/serve),
+[Protocol routes](https://streamsy.dev/docs/http/routes),
+[Cloudflare](https://streamsy.dev/docs/hosting/cloudflare),
+[Host contract](https://streamsy.dev/docs/hosting/host-contract),
+[Alchemy](https://streamsy.dev/docs/hosting/cloudflare#alchemy).

package/dist/action/contract.d.ts

@@ -0,0 +1,100 @@
+//#region src/action/contract.d.ts
+/**
+ * The action-sink declaration.
+ *
+ * A `stateSink` publishes a relation as data a consumer reads. An `actionSink`
+ * does the opposite: it turns changes to a relation into *external effects* —
+ * a notification, a webhook, a mail — which the world observes once and cannot
+ * un-observe. That asymmetry is the whole design. A published row can be
+ * republished; a delivered effect cannot be undelivered, so the contract is
+ * built around a durable outbox, a deterministic idempotency key, a bounded
+ * serialized retry policy, and a dead-letter terminus.
+ *
+ * The declaration is inert data. It names the relation it observes, the handler
+ * that performs the effect, the payload's wire boundary, and the delivery
+ * policy. It contains no I/O and no runtime state.
+ */
+/** The part of a keyed relation an action sink needs: the key its rows are declared by. */
+export interface ActionSinkRelation<Key extends string = string> {
+  readonly key: Key;
+}
+/**
+ * One change to the observed relation.
+ *
+ * This is structurally the engine's `Change`, restated here so the declaration
+ * surface does not drag the IR package into every consumer of a sink contract.
+ */
+export type ActionSinkChange<Row, Key = string> = {
+  readonly kind: "enter";
+  readonly key: Key;
+  readonly after: Row;
+} | {
+  readonly kind: "update";
+  readonly key: Key;
+  readonly before: Row;
+  readonly after: Row;
+} | {
+  readonly kind: "exit";
+  readonly key: Key;
+  readonly before: Row;
+};
+/** The handler an action sink is bound to, by name and version. */
+export interface ActionSinkHandlerRef {
+  readonly name: string;
+  readonly version: number;
+}
+/**
+ * The bounded retry policy.
+ *
+ * `maxAttempts` counts *total* attempts, so `maxAttempts: 1` means deliver once
+ * and dead-letter on failure. Backoff is exponential and clamped, and it is
+ * computed rather than scheduled: the outbox stores the next attempt instant,
+ * so a restart resumes the same policy instead of restarting it.
+ */
+export interface ActionSinkDeliveryPolicy {
+  readonly maxAttempts: number;
+  readonly initialBackoffMs: number;
+  readonly backoffFactor: number;
+  readonly maxBackoffMs: number;
+}
+/** The durable payload's wire boundary: JSON text in the outbox, a typed value in the handler. */
+export interface ActionSinkPayloadCodec<Payload> {
+  readonly encode: (payload: Payload) => string;
+  readonly decode: (value: unknown) => Payload;
+}
+export interface ActionSinkSpec<Payload, From extends ActionSinkRelation = ActionSinkRelation> {
+  readonly name: string;
+  readonly from: From;
+  readonly handler: ActionSinkHandlerRef;
+  readonly payload: ActionSinkPayloadCodec<Payload>;
+  /**
+   * The delivery's durable identity.
+   *
+   * It must be a pure function of durable facts, because it is the only thing
+   * standing between a retried enqueue and a second real-world effect. Two
+   * enqueues that describe the same fact must produce the same key.
+   */
+  readonly idempotencyKey: (payload: Payload) => string;
+  /** Which serialized lane the delivery belongs to. Usually the relation's partition. */
+  readonly partitionBy: (payload: Payload) => string;
+  readonly delivery: ActionSinkDeliveryPolicy;
+}
+export interface CheckedActionSink<Payload, From extends ActionSinkRelation = ActionSinkRelation> extends ActionSinkSpec<Payload, From> {
+  readonly kind: "checked-action-sink";
+  /** The observed relation's declared key, carried so consumers read one key, not two. */
+  readonly key: From["key"];
+  /**
+   * The contract's identity.
+   *
+   * It covers the sink name, the relation key, the handler reference and the
+   * delivery policy — every part a consumer or an operator can observe. It
+   * deliberately does not cover the declared functions: a closure has no honest
+   * hash, and pretending otherwise would make the fingerprint a decoration.
+   */
+  readonly fingerprint: string;
+}
+export declare function defineActionSink<Payload, From extends ActionSinkRelation>(spec: ActionSinkSpec<Payload, From>): CheckedActionSink<Payload, From>;
+/** The next backoff, in milliseconds, after `attempts` failed attempts. */
+export declare function backoffAfter(policy: ActionSinkDeliveryPolicy, attempts: number): number;
+export type PayloadOf<Sink> = Sink extends CheckedActionSink<infer Payload, infer _From> ? Payload : never;
+//#endregion

package/dist/action/contract.js

@@ -0,0 +1,28 @@
+import { contractFingerprint } from "../contract.js";
+//#region src/action/contract.ts
+function defineActionSink(spec) {
+	if (!Number.isInteger(spec.delivery.maxAttempts) || spec.delivery.maxAttempts < 1) throw new TypeError(`action sink ${spec.name} must declare at least one delivery attempt`);
+	if (spec.delivery.backoffFactor < 1) throw new TypeError(`action sink ${spec.name} must not shrink its backoff`);
+	if (spec.delivery.initialBackoffMs < 0 || spec.delivery.maxBackoffMs < spec.delivery.initialBackoffMs) throw new TypeError(`action sink ${spec.name} declares an impossible backoff window`);
+	const key = spec.from.key;
+	const fingerprint = contractFingerprint({
+		name: spec.name,
+		key,
+		handler: { ...spec.handler },
+		delivery: Object.fromEntries(Object.entries(spec.delivery).map(([name, value]) => [name, Number.isFinite(value) ? value : String(value)]))
+	});
+	return Object.freeze({
+		...spec,
+		kind: "checked-action-sink",
+		key,
+		fingerprint
+	});
+}
+/** The next backoff, in milliseconds, after `attempts` failed attempts. */
+function backoffAfter(policy, attempts) {
+	const exponent = Math.max(0, attempts - 1);
+	const raw = policy.initialBackoffMs * policy.backoffFactor ** exponent;
+	return Math.min(policy.maxBackoffMs, Math.round(raw));
+}
+//#endregion
+export { backoffAfter, defineActionSink };

package/dist/action/errors.d.ts

@@ -0,0 +1,35 @@
+import { Schema } from "effect";
+import * as Cause$1 from "effect/Cause";
+//#region src/action/errors.d.ts
+export declare const ACTION_SINK_ERROR_TAGS: readonly ["ActionSinkDeliveryFailure", "OutboxUnavailable"];
+export type ActionSinkErrorTag = (typeof ACTION_SINK_ERROR_TAGS)[number];
+/** The durable outbox could not be read or written. Never a delivery outcome. */
+type OutboxUnavailableSchema = Schema.TaggedStruct<"OutboxUnavailable", {
+  readonly operation: Schema.String;
+  readonly detail: Schema.String;
+}>;
+declare const OutboxUnavailableBase: Schema.Class<OutboxUnavailable, OutboxUnavailableSchema, Cause$1.YieldableError>;
+export declare class OutboxUnavailable extends OutboxUnavailableBase {}
+/**
+ * A handler refused one delivery.
+ *
+ * `retryable` is the handler's own judgement. A handler that knows the failure
+ * cannot change says so, and the runtime dead-letters immediately instead of
+ * spending the whole retry budget on an outcome that is already settled.
+ */
+type ActionSinkDeliveryFailureSchema = Schema.TaggedStruct<"ActionSinkDeliveryFailure", {
+  readonly handler: Schema.String;
+  readonly idempotencyKey: Schema.String;
+  readonly detail: Schema.String;
+  readonly retryable: Schema.Boolean;
+}>;
+declare const ActionSinkDeliveryFailureBase: Schema.Class<ActionSinkDeliveryFailure, ActionSinkDeliveryFailureSchema, Cause$1.YieldableError>;
+export declare class ActionSinkDeliveryFailure extends ActionSinkDeliveryFailureBase {
+  static retryable(handler: string, idempotencyKey: string, detail: string): ActionSinkDeliveryFailure;
+  static permanent(handler: string, idempotencyKey: string, detail: string): ActionSinkDeliveryFailure;
+}
+/** Why one outbox entry stopped being retried. */
+export declare const DEAD_LETTER_REASONS: readonly ["attempts-exhausted", "permanent", "payload-poison"];
+export type DeadLetterReason = (typeof DEAD_LETTER_REASONS)[number];
+//#endregion
+export {};

package/dist/action/errors.js

@@ -0,0 +1,51 @@
+import { Schema } from "effect";
+//#region src/action/errors.ts
+/**
+* Typed action-sink failures.
+*
+* An action sink has two failure domains and they are deliberately separate.
+* `OutboxUnavailable` is a storage failure: the durable outbox itself could not
+* be read or written, and no delivery decision can be trusted until it
+* recovers. `ActionSinkDeliveryFailure` is a *handler* outcome: the delivery was
+* attempted and the external effect refused it. The first is an operational
+* error the host reports; the second is ordinary traffic for the retry policy
+* and never leaves the delivery loop.
+*/
+const ACTION_SINK_ERROR_TAGS = ["ActionSinkDeliveryFailure", "OutboxUnavailable"];
+const OutboxUnavailableBase = Schema.TaggedError()("OutboxUnavailable", {
+	operation: Schema.String,
+	detail: Schema.String
+});
+var OutboxUnavailable = class extends OutboxUnavailableBase {};
+const ActionSinkDeliveryFailureBase = Schema.TaggedError()("ActionSinkDeliveryFailure", {
+	handler: Schema.String,
+	idempotencyKey: Schema.String,
+	detail: Schema.String,
+	retryable: Schema.Boolean
+});
+var ActionSinkDeliveryFailure = class ActionSinkDeliveryFailure extends ActionSinkDeliveryFailureBase {
+	static retryable(handler, idempotencyKey, detail) {
+		return new ActionSinkDeliveryFailure({
+			handler,
+			idempotencyKey,
+			detail,
+			retryable: true
+		});
+	}
+	static permanent(handler, idempotencyKey, detail) {
+		return new ActionSinkDeliveryFailure({
+			handler,
+			idempotencyKey,
+			detail,
+			retryable: false
+		});
+	}
+};
+/** Why one outbox entry stopped being retried. */
+const DEAD_LETTER_REASONS = [
+	"attempts-exhausted",
+	"permanent",
+	"payload-poison"
+];
+//#endregion
+export { ACTION_SINK_ERROR_TAGS, ActionSinkDeliveryFailure, DEAD_LETTER_REASONS, OutboxUnavailable };

package/dist/action/outbox.d.ts

@@ -0,0 +1,67 @@
+import { DeadLetterReason, OutboxUnavailable } from "./errors.js";
+import { Context, Effect, Layer, Option } from "effect";
+//#region src/action/outbox.d.ts
+export type OutboxEntryState = "pending" | "delivered" | "dead";
+export interface OutboxEntry {
+  /** Monotonic enqueue order. Delivery walks a lane in this order. */
+  readonly id: number;
+  readonly sink: string;
+  readonly partitionId: string;
+  readonly idempotencyKey: string;
+  /** The declared payload, as the JSON text that was durably written. */
+  readonly payload: string;
+  readonly state: OutboxEntryState;
+  /** Attempts already spent. Zero until the first delivery is tried. */
+  readonly attempts: number;
+  /** The earliest instant this entry may be attempted again. */
+  readonly nextAttemptAtMs: number;
+  readonly lastError: string | undefined;
+  readonly deadLetterReason: DeadLetterReason | undefined;
+  readonly enqueuedAtMs: number;
+  readonly settledAtMs: number | undefined;
+}
+/** One decision to deliver, before it has an identity in the outbox. */
+export interface OutboxDraft {
+  readonly sink: string;
+  readonly partitionId: string;
+  readonly idempotencyKey: string;
+  readonly payload: string;
+  readonly enqueuedAtMs: number;
+}
+export interface OutboxEnqueueReport {
+  readonly enqueued: number;
+  /** Drafts whose sink and idempotency key were already durable. Never a second effect. */
+  readonly absorbed: number;
+}
+/** The durable storage boundary for one outbox implementation. */
+export interface OutboxBacking {
+  readonly enqueue: (drafts: readonly OutboxDraft[]) => Effect.Effect<OutboxEnqueueReport, OutboxUnavailable>;
+  /** Pending deadline in one lane or the whole sink. Settled entries are excluded. */
+  readonly nextDue: (sink: string, partitionId: string | undefined,
+  /** Read the oldest pending entry's deadline for strict enqueue order. */
+  ordered?: boolean) => Effect.Effect<Option.Option<number>, OutboxUnavailable>;
+  /** Pending entries in one lane whose next attempt instant has arrived, in enqueue order. */
+  readonly claimDue: (sink: string, partitionId: string | undefined, nowMs: number, limit: number,
+  /** Include the future head so an ordered pass cannot skip a retry. */
+  ordered?: boolean) => Effect.Effect<readonly OutboxEntry[], OutboxUnavailable>;
+  readonly markDelivered: (id: number, attempts: number, atMs: number) => Effect.Effect<void, OutboxUnavailable>;
+  readonly reschedule: (id: number, attempts: number, nextAttemptAtMs: number, detail: string) => Effect.Effect<void, OutboxUnavailable>;
+  readonly deadLetter: (id: number, attempts: number, reason: DeadLetterReason, detail: string, atMs: number) => Effect.Effect<void, OutboxUnavailable>;
+  readonly list: (sink: string, partitionId: string | undefined) => Effect.Effect<readonly OutboxEntry[], OutboxUnavailable>;
+}
+export interface OutboxStoreService extends OutboxBacking {}
+declare const OutboxStore_base: Context.ServiceClass<OutboxStore, "streamsy/action-sink/OutboxStore", OutboxStoreService>;
+export declare class OutboxStore extends OutboxStore_base {}
+/** Lift one durable backing into the service every runtime asks for. */
+export declare function outboxStore(backing: OutboxBacking): OutboxStoreService;
+export declare const outboxStoreLayer: (backing: OutboxBacking) => Layer.Layer<OutboxStore>;
+/**
+ * The in-memory backing.
+ *
+ * It is not a stub. It enforces the same sink-and-key uniqueness and the same
+ * lane ordering as SQLite, so a declaration that behaves one way on the memory
+ * host behaves the same way on the durable one.
+ */
+export declare function makeMemoryOutboxBacking(): OutboxBacking;
+//#endregion
+export {};

package/dist/action/outbox.js

@@ -0,0 +1,109 @@
+import "./errors.js";
+import { Context, Effect, Layer, Option } from "effect";
+//#region src/action/outbox.ts
+/**
+* The durable outbox.
+*
+* An action sink cannot enqueue by holding work in memory: the process that
+* decided to deliver is the same process that can die before delivering. So the
+* decision to deliver is written down first, in the same durable step as the
+* fact that caused it, and delivery is a separate, resumable pass over what was
+* written.
+*/
+var OutboxStore = class extends Context.Service()("streamsy/action-sink/OutboxStore") {};
+/** Lift one durable backing into the service every runtime asks for. */
+function outboxStore(backing) {
+	return OutboxStore.of(backing);
+}
+const outboxStoreLayer = (backing) => Layer.sync(OutboxStore, () => outboxStore(backing));
+/**
+* The in-memory backing.
+*
+* It is not a stub. It enforces the same sink-and-key uniqueness and the same
+* lane ordering as SQLite, so a declaration that behaves one way on the memory
+* host behaves the same way on the durable one.
+*/
+function makeMemoryOutboxBacking() {
+	const entries = /* @__PURE__ */ new Map();
+	const identities = /* @__PURE__ */ new Map();
+	let nextId = 1;
+	const replace = (id, patch) => {
+		const existing = entries.get(id);
+		if (existing === void 0) throw new Error(`outbox entry ${id} does not exist`);
+		entries.set(id, {
+			...existing,
+			...patch
+		});
+	};
+	const ordered = () => [...entries.values()].toSorted((left, right) => left.id - right.id);
+	return {
+		enqueue: (drafts) => Effect.sync(() => {
+			let enqueued = 0;
+			let absorbed = 0;
+			for (const draft of drafts) {
+				const sinkIdentities = identities.get(draft.sink);
+				if (sinkIdentities?.has(draft.idempotencyKey) === true) {
+					absorbed += 1;
+					continue;
+				}
+				const id = nextId;
+				nextId += 1;
+				if (sinkIdentities === void 0) identities.set(draft.sink, /* @__PURE__ */ new Set([draft.idempotencyKey]));
+				else sinkIdentities.add(draft.idempotencyKey);
+				entries.set(id, {
+					id,
+					sink: draft.sink,
+					partitionId: draft.partitionId,
+					idempotencyKey: draft.idempotencyKey,
+					payload: draft.payload,
+					state: "pending",
+					attempts: 0,
+					nextAttemptAtMs: draft.enqueuedAtMs,
+					lastError: void 0,
+					deadLetterReason: void 0,
+					enqueuedAtMs: draft.enqueuedAtMs,
+					settledAtMs: void 0
+				});
+				enqueued += 1;
+			}
+			return {
+				enqueued,
+				absorbed
+			};
+		}),
+		nextDue: (sink, partitionId, inOrder = false) => Effect.sync(() => {
+			const pending = ordered().filter((entry) => entry.sink === sink && entry.state === "pending" && (partitionId === void 0 || entry.partitionId === partitionId));
+			const first = pending[0];
+			return first === void 0 ? Option.none() : Option.some(inOrder ? first.nextAttemptAtMs : pending.reduce((at, entry) => Math.min(at, entry.nextAttemptAtMs), Infinity));
+		}),
+		claimDue: (sink, partitionId, nowMs, limit, inOrder = false) => Effect.sync(() => ordered().filter((entry) => entry.sink === sink && entry.state === "pending" && (inOrder || entry.nextAttemptAtMs <= nowMs) && (partitionId === void 0 || entry.partitionId === partitionId)).slice(0, limit)),
+		markDelivered: (id, attempts, atMs) => Effect.sync(() => {
+			replace(id, {
+				state: "delivered",
+				attempts,
+				settledAtMs: atMs,
+				lastError: void 0
+			});
+		}),
+		reschedule: (id, attempts, nextAttemptAtMs, detail) => Effect.sync(() => {
+			replace(id, {
+				state: "pending",
+				attempts,
+				nextAttemptAtMs,
+				lastError: detail
+			});
+		}),
+		deadLetter: (id, attempts, reason, detail, atMs) => Effect.sync(() => {
+			replace(id, {
+				state: "dead",
+				attempts,
+				lastError: detail,
+				deadLetterReason: reason,
+				settledAtMs: atMs
+			});
+		}),
+		list: (sink, partitionId) => Effect.sync(() => ordered().filter((entry) => entry.sink === sink && (partitionId === void 0 || entry.partitionId === partitionId)))
+	};
+}
+//#endregion
+export { OutboxStore, makeMemoryOutboxBacking, outboxStore, outboxStoreLayer };

package/dist/action/runtime.d.ts

@@ -0,0 +1,80 @@
+import { ActionSinkRelation, CheckedActionSink } from "./contract.js";
+import { ActionSinkDeliveryFailure, OutboxUnavailable } from "./errors.js";
+import { OutboxDraft, OutboxStore } from "./outbox.js";
+import { t as Wakeup } from "../wakeup-BtnMEjLv.js";
+import { Effect } from "effect";
+//#region src/action/runtime.d.ts
+/** One attempt at one delivery, as the handler sees it. */
+export interface ActionSinkDelivery<Payload> {
+  readonly entryId: number;
+  readonly sink: string;
+  readonly partitionId: string;
+  /**
+   * The delivery's durable identity.
+   *
+   * A handler that has already accepted this key must accept it again without
+   * repeating the effect. Delivery is at-least-once by construction — the
+   * process can die between a successful handler call and the outbox write that
+   * records it — so absorbing a repeat is the handler's half of the contract.
+   */
+  readonly idempotencyKey: string;
+  /** One-based: `1` on the first attempt. */
+  readonly attempt: number;
+  readonly payload: Payload;
+}
+export interface ActionSinkHandler<Payload, Requirements = never> {
+  readonly deliver: (delivery: ActionSinkDelivery<Payload>) => Effect.Effect<void, ActionSinkDeliveryFailure, Requirements>;
+}
+/** How a handler refuses the delivery it was given, without restating its own identity. */
+export interface RefuseDelivery {
+  /** The effect may still succeed later: the runtime spends another attempt. */
+  readonly retryable: (detail: string) => ActionSinkDeliveryFailure;
+  /** The effect can never succeed for this payload: the runtime dead-letters it now. */
+  readonly permanent: (detail: string) => ActionSinkDeliveryFailure;
+}
+/**
+ * Bind a delivery function to a sink's declared handler.
+ *
+ * A handler's own dependencies stay ordinary Effect requirements, so a host
+ * supplies them with a layer and the declaration never mentions the transport:
+ * the same sink delivers through a real notifier in the host and through a
+ * recording fake in a test, with no branch in between.
+ */
+export declare function actionSinkHandler<Payload, From extends ActionSinkRelation, Requirements = never>(sink: CheckedActionSink<Payload, From>, deliver: (delivery: ActionSinkDelivery<Payload>, refuse: RefuseDelivery) => Effect.Effect<void, ActionSinkDeliveryFailure, Requirements>): ActionSinkHandler<Payload, Requirements>;
+export interface DrainOptions {
+  /** Restrict the pass to one lane. Omitted, it drains every lane of the sink. */
+  readonly partitionId?: string;
+  /** Upper bound on entries claimed by one pass. */
+  readonly limit?: number;
+  /** A future retry blocks every later pending entry in the drained scope. */
+  readonly ordered?: boolean;
+}
+export interface DrainReport {
+  readonly sink: string;
+  /** Entries this pass attempted. An ordered pass does not count the future head it read. */
+  readonly claimed: number;
+  readonly delivered: number;
+  /** Entries that failed and are scheduled for another attempt. */
+  readonly retried: number;
+  readonly deadLettered: number;
+}
+export declare const DEFAULT_DRAIN_LIMIT = 100;
+/** Lower declared payloads to outbox drafts. Pure, so a caller can write them transactionally. */
+export declare function draftsFor<Payload, From extends ActionSinkRelation>(sink: CheckedActionSink<Payload, From>, payloads: readonly Payload[], enqueuedAtMs: number): readonly OutboxDraft[];
+/**
+ * Deliver due entries serially, applying the declared retry policy and optional strict order.
+ *
+ * Each sink's permit is not reentrant. A handler must not drain its own sink.
+ */
+export declare const drain: <Payload, From extends ActionSinkRelation, Requirements = never>(sink: CheckedActionSink<Payload, From>, handler: ActionSinkHandler<Payload, Requirements>, options?: DrainOptions) => Effect.Effect<DrainReport, OutboxUnavailable, OutboxStore | Requirements>;
+/**
+ * The wakeup for one action outbox. The host entry does not load action code.
+ *
+ * Its name is `streamsy/outbox/<sink>` or `streamsy/outbox/<sink>/<partition>`,
+ * with each part URI-encoded so a sink named `a/b` cannot collide with a lane.
+ * A pass that fills its limit reports more work, so a backlog is not backed off.
+ */
+export declare const OutboxWakeup: {
+  make: <Payload, From extends ActionSinkRelation, R = never>(sink: CheckedActionSink<Payload, From>, handler: ActionSinkHandler<Payload, R>, options?: DrainOptions) => Wakeup<OutboxStore | R>;
+};
+//#endregion