@fungi.computer/carrier 0.0.0-stage → 0.0.1

package/docs/api/post.md

@@ -0,0 +1,620 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/carrier**](README.md)
+
+---
+
+[@fungi.computer/carrier](README.md) / post
+
+# post
+
+## Classes
+
+### PostError
+
+Post rejected an unknown route or conflicting key.
+
+#### Extends
+
+- `YieldableError`\<`this`\> & `object` & `Readonly`\<\{ `message`: `string`;
+  \}\>
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new PostError(message): PostError;
+```
+
+###### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `message` | `string` |
+
+###### Returns
+
+[`PostError`](#posterror)
+
+###### Overrides
+
+```ts
+Data.TaggedError("PostError")<{
+  readonly message: string;
+}>.constructor
+```
+
+#### Properties
+
+##### message
+
+```ts
+message: string;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("PostError").message;
+```
+
+## Type Aliases
+
+### PostDeliveryResult
+
+```ts
+type PostDeliveryResult =
+  | "accepted"
+  | "duplicate"
+  | "refused"
+  | Readonly<{
+      status: "accepted" | "duplicate";
+      cursor: number;
+    }>
+  | Readonly<{
+      status: "accepted" | "duplicate" | "refused";
+      receipt: Schema.Json;
+    }>;
+```
+
+Receiver's idempotent admission decision.
+
+---
+
+### PostOutboxStore
+
+```ts
+type PostOutboxStore<E> = Readonly<{
+  put: (key, value) => Effect.Effect<void, E>;
+  read: (key) => Effect.Effect<string | undefined, E>;
+  list: (
+    limit,
+    afterKey?,
+  ) => Effect.Effect<
+    readonly Readonly<{
+      key: string;
+      value: string;
+    }>[],
+    E
+  >;
+  delete: (key) => Effect.Effect<void, E>;
+}>;
+```
+
+Durable, string-backed rows. A delivered receipt must outlive source replay.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `E`            |
+
+---
+
+### PostOutbox
+
+```ts
+type PostOutbox<M, E> = Readonly<{
+  enqueue: (message, at?) => Effect.Effect<number | undefined, E>;
+  drain: () => Effect.Effect<void, E>;
+  deadLetters: (limit, afterKey?) => Effect.Effect<M[], E>;
+}>;
+```
+
+Bounded generic delivery owned by Post.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `M`            |
+| `E`            |
+
+---
+
+### PostEnvelope
+
+```ts
+type PostEnvelope = Schema.Schema.Type<typeof PostEnvelopeSchema>;
+```
+
+One addressed event identified by the producer's stable key.
+
+---
+
+### PostRow
+
+```ts
+type PostRow = Schema.Schema.Type<typeof PostRowSchema>;
+```
+
+Pending row, terminal receipt, or dead letter.
+
+---
+
+### PostRoute
+
+```ts
+type PostRoute<A, E, D, AI, EI, DI> = Readonly<{
+  addressKind: string;
+  address: Schema.Codec<A, AI>;
+  event: Schema.Codec<E, EI>;
+  name: (address) => string;
+  namespace: Readonly<{
+     getByName: (name) => Readonly<{
+        deliver: (envelope) => Promise<PostDeliveryResult>;
+     }>;
+  }>;
+}> &
+  | Readonly<{
+  prepare: Readonly<{
+     event: Schema.Codec<D, DI>;
+     run: (address, intent, signal) => Promise<D>;
+  }>;
+  onDelivered?: (address, event) => void;
+  onCursor?: (address, event, cursor) => void;
+  onRefused?: (address, event) => void;
+}>
+  | Readonly<{
+  prepare?: undefined;
+  onDelivered?: (address, event) => void;
+  onCursor?: (address, event, cursor) => void;
+  onRefused?: (address, event) => void;
+}>;
+```
+
+Schema-correlated ordinary events or prepared delivery facts.
+
+#### Type Parameters
+
+| Type Parameter | Default type |
+| -------------- | ------------ |
+| `A`            | -            |
+| `E`            | -            |
+| `D`            | `E`          |
+| `AI`           | `A`          |
+| `EI`           | `E`          |
+| `DI`           | `EI`         |
+
+---
+
+### PostRegistryRoute
+
+```ts
+type PostRegistryRoute = Readonly<{
+  addressKind: string;
+  address: Schema.Codec<unknown, unknown>;
+  event: Schema.Codec<unknown, unknown>;
+  encodeEnvelope: (envelope) => PostEnvelope;
+  parseDelivery: (envelope) => PostEnvelope;
+  prepareEnvelope?: (envelope, signal) => Promise<PostEnvelope>;
+  recordDelivered?: (envelope) => void;
+  nameOf: (envelope) => string;
+  namespace: PostRoute<never, never>["namespace"];
+  recordCursor?: (envelope, cursor) => void;
+  recordRefused?: (envelope) => void;
+}>;
+```
+
+Runtime operations that preserve the route's schema evidence.
+
+---
+
+### PostRuntime
+
+```ts
+type PostRuntime<R> = Readonly<{
+  send: <K>(input) => void;
+  execute: (job) => Promise<
+    Readonly<{
+      kind: "completed";
+    }>
+  >;
+  enqueueDue: (limit?, afterKey?) => Promise<string | undefined>;
+  deadLetters: (
+    limit?,
+    afterKey?,
+  ) => Readonly<{
+    letters: readonly Readonly<{
+      key: string;
+      reason: "refused" | "exhausted";
+      envelope: PostEnvelope;
+      attempts: number;
+    }>[];
+    nextCursor: string | undefined;
+  }>;
+  latest: <K>(
+    kind,
+    address,
+  ) =>
+    | Readonly<{
+        key: string;
+        row: PostRow;
+      }>
+    | undefined;
+  retry: (key) => Promise<void>;
+  read: (key) => PostRow | undefined;
+  nextWake: () => number | null;
+}>;
+```
+
+One producer's Post operations.
+
+#### Type Parameters
+
+| Type Parameter                                                                |
+| ----------------------------------------------------------------------------- |
+| `R` _extends_ `Record`\<`string`, [`PostRegistryRoute`](#postregistryroute)\> |
+
+## Variables
+
+### PostDeliveryResultSchema
+
+```ts
+const PostDeliveryResultSchema: Union<
+  readonly [
+    Literals<readonly ["accepted", "duplicate", "refused"]>,
+    Struct<{
+      status: Literals<readonly ["accepted", "duplicate"]>;
+      cursor: Int;
+    }>,
+    Struct<{
+      status: Literals<readonly ["accepted", "duplicate", "refused"]>;
+      receipt: Codec<Json, Json, never, never>;
+    }>,
+  ]
+>;
+```
+
+Accepted receipt, revision cursor, or permanent refusal returned by a receiver.
+
+---
+
+### PostEnvelopeSchema
+
+```ts
+const PostEnvelopeSchema: Struct<{
+  key: String;
+  kind: String;
+  address: Unknown;
+  event: Unknown;
+}>;
+```
+
+Wire envelope parsed at the durable row and receiver boundaries.
+
+---
+
+### PostRowSchema
+
+```ts
+const PostRowSchema: fromJsonString<
+  Union<
+    readonly [
+      Struct<{
+        state: Literal<"pending">;
+        envelope: Struct<{
+          key: String;
+          kind: String;
+          address: Unknown;
+          event: Unknown;
+        }>;
+        attempts: Int;
+        nextAttemptAt: Number;
+        jobId: optional<String>;
+        delivery: optional<
+          Struct<{
+            key: String;
+            kind: String;
+            address: Unknown;
+            event: Unknown;
+          }>
+        >;
+        nextKey: optional<String>;
+      }>,
+      Struct<{
+        state: Literal<"delivered">;
+        receipt: optional<Codec<Json, Json, never, never>>;
+        nextKey: optional<String>;
+      }>,
+      Struct<{
+        state: Literal<"dead">;
+        envelope: Struct<{
+          key: String;
+          kind: String;
+          address: Unknown;
+          event: Unknown;
+        }>;
+        attempts: Int;
+        reason: Literals<readonly ["refused", "exhausted"]>;
+        receipt: optional<Codec<Json, Json, never, never>>;
+        delivery: optional<
+          Struct<{
+            key: String;
+            kind: String;
+            address: Unknown;
+            event: Unknown;
+          }>
+        >;
+        nextKey: optional<String>;
+      }>,
+    ]
+  >
+>;
+```
+
+Persisted Post row parser.
+
+## Functions
+
+### retryDelay()
+
+```ts
+function retryDelay(attempts): number;
+```
+
+BirdDog's retained bounded retry schedule.
+
+#### Parameters
+
+| Parameter  | Type     |
+| ---------- | -------- |
+| `attempts` | `number` |
+
+#### Returns
+
+`number`
+
+---
+
+### makePostOutbox()
+
+```ts
+function makePostOutbox<M, E>(options): PostOutbox<M, E>;
+```
+
+The same bounded delivery and receipt machinery serves Post and BirdDog.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `M`            |
+| `E`            |
+
+#### Parameters
+
+| Parameter | Type                                                                                                                                                                                                                                                                                                                                              |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `options` | `Readonly`\<\{ `message`: `Schema.Codec`\<`M`\>; `key`: (`message`) => `string`; `outbox`: [`PostOutboxStore`](#postoutboxstore)\<`E`\>; `deliver`: (`message`) => `Effect.Effect`\<`boolean`, `E`\>; `scheduleWake`: (`at`) => `Effect.Effect`\<`void`, `E`\>; `now`: () => `number`; `invalidRow`: () => `E`; `encodingFailed`: () => `E`; \}\> |
+
+#### Returns
+
+[`PostOutbox`](#postoutbox)\<`M`, `E`\>
+
+---
+
+### definePostRoute()
+
+#### Call Signature
+
+```ts
+function definePostRoute<A, E, AI, EI>(route): PostRoute<A, E, E, AI, EI, EI> & Omit<Readonly<{
+  addressKind: string;
+  address: Codec<unknown, unknown>;
+  event: Codec<unknown, unknown>;
+  encodeEnvelope: (envelope) => object;
+  parseDelivery: (envelope) => object;
+  prepareEnvelope?: (envelope, signal) => Promise<{
+     key: string;
+     kind: string;
+     address: unknown;
+     event: unknown;
+  }>;
+  recordDelivered?: (envelope) => void;
+  nameOf: (envelope) => string;
+  namespace: Readonly<{
+     getByName: (name) => Readonly<{
+        deliver: (envelope) => Promise<...>;
+     }>;
+  }>;
+  recordCursor?: (envelope, cursor) => void;
+  recordRefused?: (envelope) => void;
+}>, "address" | "event">;
+```
+
+Preserve each route's inferred address and event types in a registry.
+
+##### Type Parameters
+
+| Type Parameter | Default type |
+| -------------- | ------------ |
+| `A`            | -            |
+| `E`            | -            |
+| `AI`           | `A`          |
+| `EI`           | `E`          |
+
+##### Parameters
+
+| Parameter | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `route`   | `Readonly`\<\{ `addressKind`: `string`; `address`: `Codec`\<`A`, `AI`\>; `event`: `Codec`\<`E`, `EI`\>; `name`: (`address`) => `string`; `namespace`: `Readonly`\<\{ `getByName`: (`name`) => `Readonly`\<\{ `deliver`: (`envelope`) => `Promise`\<[`PostDeliveryResult`](#postdeliveryresult)\>; \}\>; \}\>; \}\> & `Readonly`\<\{ `prepare?`: `undefined`; `onDelivered?`: (`address`, `event`) => `void`; `onCursor?`: (`address`, `event`, `cursor`) => `void`; `onRefused?`: (`address`, `event`) => `void`; \}\> |
+
+##### Returns
+
+[`PostRoute`](#postroute)\<`A`, `E`, `E`, `AI`, `EI`, `EI`\> &
+`Omit`\<`Readonly`\<\{ `addressKind`: `string`; `address`: `Codec`\<`unknown`,
+`unknown`\>; `event`: `Codec`\<`unknown`, `unknown`\>; `encodeEnvelope`:
+(`envelope`) => `object`; `parseDelivery`: (`envelope`) => `object`;
+`prepareEnvelope?`: (`envelope`, `signal`) => `Promise`\<\{ `key`: `string`;
+`kind`: `string`; `address`: `unknown`; `event`: `unknown`; \}\>;
+`recordDelivered?`: (`envelope`) => `void`; `nameOf`: (`envelope`) => `string`;
+`namespace`: `Readonly`\<\{ `getByName`: (`name`) => `Readonly`\<\{ `deliver`:
+(`envelope`) => `Promise`\<...\>; \}\>; \}\>; `recordCursor?`: (`envelope`,
+`cursor`) => `void`; `recordRefused?`: (`envelope`) => `void`; \}\>, `"address"`
+\| `"event"`\>
+
+#### Call Signature
+
+```ts
+function definePostRoute<A, E, D, AI, EI, DI>(route): PostRoute<A, E, D, AI, EI, DI> & Omit<Readonly<{
+  addressKind: string;
+  address: Codec<unknown, unknown>;
+  event: Codec<unknown, unknown>;
+  encodeEnvelope: (envelope) => object;
+  parseDelivery: (envelope) => object;
+  prepareEnvelope?: (envelope, signal) => Promise<{
+     key: string;
+     kind: string;
+     address: unknown;
+     event: unknown;
+  }>;
+  recordDelivered?: (envelope) => void;
+  nameOf: (envelope) => string;
+  namespace: Readonly<{
+     getByName: (name) => Readonly<{
+        deliver: (envelope) => Promise<...>;
+     }>;
+  }>;
+  recordCursor?: (envelope, cursor) => void;
+  recordRefused?: (envelope) => void;
+}>, "address" | "event">;
+```
+
+Preserve each route's inferred address and event types in a registry.
+
+##### Type Parameters
+
+| Type Parameter | Default type |
+| -------------- | ------------ |
+| `A`            | -            |
+| `E`            | -            |
+| `D`            | -            |
+| `AI`           | `A`          |
+| `EI`           | `E`          |
+| `DI`           | `EI`         |
+
+##### Parameters
+
+| Parameter | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `route`   | `Readonly`\<\{ `addressKind`: `string`; `address`: `Codec`\<`A`, `AI`\>; `event`: `Codec`\<`E`, `EI`\>; `name`: (`address`) => `string`; `namespace`: `Readonly`\<\{ `getByName`: (`name`) => `Readonly`\<\{ `deliver`: (`envelope`) => `Promise`\<[`PostDeliveryResult`](#postdeliveryresult)\>; \}\>; \}\>; \}\> & `Readonly`\<\{ `prepare`: `Readonly`\<\{ `event`: `Schema.Codec`\<`D`, `DI`\>; `run`: (`address`, `intent`, `signal`) => `Promise`\<`D`\>; \}\>; `onDelivered?`: (`address`, `event`) => `void`; `onCursor?`: (`address`, `event`, `cursor`) => `void`; `onRefused?`: (`address`, `event`) => `void`; \}\> |
+
+##### Returns
+
+[`PostRoute`](#postroute)\<`A`, `E`, `D`, `AI`, `EI`, `DI`\> &
+`Omit`\<`Readonly`\<\{ `addressKind`: `string`; `address`: `Codec`\<`unknown`,
+`unknown`\>; `event`: `Codec`\<`unknown`, `unknown`\>; `encodeEnvelope`:
+(`envelope`) => `object`; `parseDelivery`: (`envelope`) => `object`;
+`prepareEnvelope?`: (`envelope`, `signal`) => `Promise`\<\{ `key`: `string`;
+`kind`: `string`; `address`: `unknown`; `event`: `unknown`; \}\>;
+`recordDelivered?`: (`envelope`) => `void`; `nameOf`: (`envelope`) => `string`;
+`namespace`: `Readonly`\<\{ `getByName`: (`name`) => `Readonly`\<\{ `deliver`:
+(`envelope`) => `Promise`\<...\>; \}\>; \}\>; `recordCursor?`: (`envelope`,
+`cursor`) => `void`; `recordRefused?`: (`envelope`) => `void`; \}\>, `"address"`
+\| `"event"`\>
+
+---
+
+### migratePostEvents()
+
+```ts
+function migratePostEvents<A, AI, B, BI>(options): void;
+```
+
+Migrate persisted ordinary events once, before opening their producer. Carrier
+preserves delivery evidence, ordering and Watchdog job identities. A failed
+decoder or transform rolls back both rows and the migration receipt.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `A`            |
+| `AI`           |
+| `B`            |
+| `BI`           |
+
+#### Parameters
+
+| Parameter | Type                                                                                                                                                                                                            |
+| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `options` | `Readonly`\<\{ `owner`: `WatchdogSqliteOwner`; `id`: `string`; `kind`: `string`; `toKind?`: `string`; `from`: `Schema.Codec`\<`A`, `AI`\>; `to`: `Schema.Codec`\<`B`, `BI`\>; `migrate`: (`event`) => `B`; \}\> |
+
+#### Returns
+
+`void`
+
+---
+
+### createPost()
+
+```ts
+function createPost<R>(options): PostRuntime<R>;
+```
+
+Decode at both persisted and DO boundaries with the route's Effect Schema.
+
+#### Type Parameters
+
+| Type Parameter                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `R` _extends_ `Record`\<`string`, `Readonly`\<\{ `addressKind`: `string`; `address`: `Codec`\<`unknown`, `unknown`\>; `event`: `Codec`\<`unknown`, `unknown`\>; `encodeEnvelope`: (`envelope`) => `object`; `parseDelivery`: (`envelope`) => `object`; `prepareEnvelope?`: (`envelope`, `signal`) => `Promise`\<\{ `key`: `string`; `kind`: `string`; `address`: `unknown`; `event`: `unknown`; \}\>; `recordDelivered?`: (`envelope`) => `void`; `nameOf`: (`envelope`) => `string`; `namespace`: `Readonly`\<\{ `getByName`: (`name`) => `Readonly`\<\{ `deliver`: (`envelope`) => `Promise`\<[`PostDeliveryResult`](#postdeliveryresult)\>; \}\>; \}\>; `recordCursor?`: (`envelope`, `cursor`) => `void`; `recordRefused?`: (`envelope`) => `void`; \}\>\> |
+
+#### Parameters
+
+| Parameter | Type                                                                                                                                                                                                                                   |
+| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `options` | `Readonly`\<\{ `routes`: `R`; `owner`: `WatchdogSqliteOwner`; `transactional`: `WatchdogTransactionalProjection`; `readJob`: `WatchdogRuntime`\[`"read"`\]; `now`: () => `number`; `scheduleWake`: (`at`) => `Promise`\<`void`\>; \}\> |
+
+#### Returns
+
+[`PostRuntime`](#postruntime)\<`R`\>
+
+---
+
+### admitPost()
+
+```ts
+function admitPost<E, I>(options): PostDeliveryResult;
+```
+
+Consumer admission runs inside the receiver's own SQLite transaction.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `E`            |
+| `I`            |
+
+#### Parameters
+
+| Parameter | Type                                                                                                                                                                                                                                   |
+| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `options` | `Readonly`\<\{ `key`: `string`; `event`: `unknown`; `schema`: `Schema.Codec`\<`E`, `I`\>; `hasReceipt`: (`key`) => `boolean`; `apply`: (`event`) => [`PostDeliveryResult`](#postdeliveryresult); `putReceipt`: (`key`) => `void`; \}\> |
+
+#### Returns
+
+[`PostDeliveryResult`](#postdeliveryresult)

package/docs/api/testing.md

@@ -0,0 +1,46 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/carrier**](README.md)
+
+---
+
+[@fungi.computer/carrier](README.md) / testing
+
+# testing
+
+## Type Aliases
+
+### MemoryOutbox
+
+```ts
+type MemoryOutbox = Readonly<{
+  put: (key, value) => Promise<void>;
+  read: (key) => Promise<string | undefined>;
+  list: (
+    limit,
+    afterKey?,
+  ) => Promise<
+    readonly Readonly<{
+      key: string;
+      value: string;
+    }>[]
+  >;
+  delete: (key) => Promise<void>;
+}>;
+```
+
+String-row outbox for deterministic tests and quick starts; no persistence.
+
+## Functions
+
+### createMemoryOutbox()
+
+```ts
+function createMemoryOutbox(): MemoryOutbox;
+```
+
+Create an independent in-process outbox for trusted tests and examples.
+
+#### Returns
+
+[`MemoryOutbox`](#memoryoutbox)