@fungi.computer/carrier 0.0.0-stage → 0.0.1

package/docs/api/inspection.md

@@ -0,0 +1,281 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/carrier**](README.md)
+
+---
+
+[@fungi.computer/carrier](README.md) / inspection
+
+# inspection
+
+## Classes
+
+### DeliveryInspectionError
+
+Stable inspection errors never include stored cargo or raw SQL failures.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new DeliveryInspectionError(code): DeliveryInspectionError;
+```
+
+###### Parameters
+
+| Parameter | Type                                 |
+| --------- | ------------------------------------ |
+| `code`    | `"unavailable"` \| `"invalid_query"` |
+
+###### Returns
+
+[`DeliveryInspectionError`](#deliveryinspectionerror)
+
+###### Overrides
+
+```ts
+Error.constructor;
+```
+
+#### Properties
+
+##### code
+
+```ts
+readonly code: "unavailable" | "invalid_query";
+```
+
+## Type Aliases
+
+### DeliveryInspectionPageQuery
+
+```ts
+type DeliveryInspectionPageQuery = Schema.Codec.Encoded<
+  typeof DeliveryInspectionPageQuerySchema
+>;
+```
+
+An email receipt page uses the same producer-key pagination.
+
+---
+
+### DeliveryInspectionQuery
+
+```ts
+type DeliveryInspectionQuery = Schema.Codec.Encoded<
+  typeof DeliveryInspectionQuerySchema
+>;
+```
+
+Input to one producer-local inspection. Cursors are producer keys, without
+storage prefixes.
+
+---
+
+### PostReceiptSummary
+
+```ts
+type PostReceiptSummary = Schema.Schema.Type<typeof PostReceiptSummarySchema>;
+```
+
+Metadata for one retained Post row.
+
+---
+
+### PostInspectionPage
+
+```ts
+type PostInspectionPage = Schema.Schema.Type<typeof PostInspectionPageSchema>;
+```
+
+One read of producer-local Post dispatch evidence.
+
+---
+
+### CarrierInspectionPage
+
+```ts
+type CarrierInspectionPage = Schema.Schema.Type<
+  typeof CarrierInspectionPageSchema
+>;
+```
+
+One read of aggregate email dispatch evidence.
+
+## Variables
+
+### DeliveryInspectionPageQuerySchema
+
+```ts
+const DeliveryInspectionPageQuerySchema: Struct<{
+  limit: withDecodingDefaultType<Int, never>;
+  after: optional<String>;
+}>;
+```
+
+One bounded scan; an empty filtered page can still have a continuation.
+
+---
+
+### DeliveryInspectionQuerySchema
+
+```ts
+const DeliveryInspectionQuerySchema: Struct<{
+  limit: withDecodingDefaultType<Int, never>;
+  after: optional<String>;
+  view: Literals<readonly ["receipts", "deadLetters"]>;
+}>;
+```
+
+Post can filter dead letters while scanning at most one bounded page.
+
+---
+
+### PostReceiptSummarySchema
+
+```ts
+const PostReceiptSummarySchema: Union<
+  readonly [
+    Struct<{
+      key: String;
+      state: Literal<"delivered">;
+    }>,
+    Struct<{
+      key: String;
+      state: Literal<"pending">;
+      kind: String;
+      attempts: Int;
+      nextAttemptAt: Number;
+    }>,
+    Struct<{
+      key: String;
+      state: Literal<"dead">;
+      kind: String;
+      attempts: Int;
+      reason: Literals<readonly ["refused", "exhausted"]>;
+    }>,
+  ]
+>;
+```
+
+Dispatch evidence deliberately omits the address and event.
+
+---
+
+### PostInspectionPageSchema
+
+```ts
+const PostInspectionPageSchema: Union<readonly [Struct<{
+  status: Literal<"uninitialized">;
+}>, Struct<{
+  status: Literal<"available">;
+  records: $Array<Union<readonly [Struct<{
+     key: String;
+     state: Literal<"delivered">;
+   }>, Struct<{
+     key: String;
+     state: Literal<"pending">;
+     kind: String;
+     attempts: Int;
+     nextAttemptAt: Number;
+   }>, Struct<{
+     key: String;
+     state: Literal<"dead">;
+     kind: String;
+     attempts: Int;
+     reason: Literals<readonly [..., ...]>;
+  }>]>>;
+  nextCursor: NullOr<String>;
+}>]>;
+```
+
+Bounded evidence with an explicit distinction between empty and uninitialized
+storage.
+
+---
+
+### CarrierReceiptSummarySchema
+
+```ts
+const CarrierReceiptSummarySchema: Struct<{
+  id: String;
+  status: Literals<
+    readonly [
+      "queued",
+      "dispatching",
+      "provider_accepted",
+      "outcome_unknown",
+      "rejected",
+      "refused",
+      "expired",
+      "superseded",
+    ]
+  >;
+  attempts: Int;
+  retryAt: NullOr<Number>;
+  providerMessageId: optional<NonEmptyString>;
+  providerRejection: optional<
+    Struct<{
+      code: NonEmptyString;
+      class: Literals<readonly ["permanent", "temporary"]>;
+    }>
+  >;
+}>;
+```
+
+Aggregate email evidence without bodies, headers or recipient addresses.
+
+---
+
+### CarrierInspectionPageSchema
+
+```ts
+const CarrierInspectionPageSchema: Union<readonly [Struct<{
+  status: Literal<"uninitialized">;
+}>, Struct<{
+  status: Literal<"available">;
+  records: $Array<Struct<{
+     id: String;
+     status: Literals<readonly ["queued", "dispatching", "provider_accepted", "outcome_unknown", "rejected", "refused", "expired", "superseded"]>;
+     attempts: Int;
+     retryAt: NullOr<Number>;
+     providerMessageId: optional<NonEmptyString>;
+     providerRejection: optional<Struct<{
+        code: NonEmptyString;
+        class: Literals<...>;
+     }>>;
+  }>>;
+  nextCursor: NullOr<String>;
+}>]>;
+```
+
+Carrier's bounded metadata page; unavailable storage is never reported as empty.
+
+## Functions
+
+### createDeliveryInspection()
+
+```ts
+function createDeliveryInspection(sql): object;
+```
+
+Read existing storage without opening a sender, initializing tables, repairing
+jobs or arming a wake. The trusted host must admit an operator before calling.
+
+#### Parameters
+
+| Parameter | Type                                                                                |
+| --------- | ----------------------------------------------------------------------------------- |
+| `sql`     | `Readonly`\<\{ `exec`: (`statement`, ...`bindings`) => `WatchdogSqliteCursor`; \}\> |
+
+#### Returns
+
+| Name      | Type                                                                                                                                                                                                                                                                                                                                                                                                                                               | Description                                                                        |
+| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `email()` | (`input`) => \| \{ `status`: `"uninitialized"`; \} \| \{ `status`: `"available"`; `records`: readonly `object`[]; `nextCursor`: `string` \| `null`; \}                                                                                                                                                                                                                                                                                             | Read aggregate dispatch evidence without email cargo or recipient addresses.       |
+| `post()`  | (`input`) => \| \{ `status`: `"uninitialized"`; \} \| \{ `status`: `"available"`; `records`: readonly ( \| \{ `key`: `string`; `state`: `"delivered"`; \} \| \{ `key`: `string`; `state`: `"pending"`; `kind`: `string`; `attempts`: `number`; `nextAttemptAt`: `number`; \} \| \{ `key`: `string`; `state`: `"dead"`; `kind`: `string`; `attempts`: `number`; `reason`: `"refused"` \| `"exhausted"`; \})[]; `nextCursor`: `string` \| `null`; \} | Read Post metadata; filtered pages retain their continuation through other states. |

package/docs/api/post-d1.md

@@ -0,0 +1,184 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/carrier**](README.md)
+
+---
+
+[@fungi.computer/carrier](README.md) / post-d1
+
+# post-d1
+
+## Type Aliases
+
+### SqlPostOptions
+
+```ts
+type SqlPostOptions<R> = Readonly<{
+  routes: R;
+  failureDetail?: (cause) => string;
+  retry?: Readonly<{
+    maxAttempts: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+  }>;
+  now: () => number;
+  scheduleWake: (at) => Promise<void>;
+}>;
+```
+
+SQL native Carrier runtime configuration; route decisions remain in Post.
+
+#### Type Parameters
+
+| Type Parameter                                                                       |
+| ------------------------------------------------------------------------------------ |
+| `R` _extends_ `Record`\<`string`, [`PostRegistryRoute`](post.md#postregistryroute)\> |
+
+---
+
+### SqlPostRuntime
+
+```ts
+type SqlPostRuntime = Readonly<{
+  execute: (
+    job,
+    signal?,
+  ) => Promise<
+    Readonly<{
+      kind: "completed";
+    }>
+  >;
+  enqueueDue: (limit?, afterKey?) => Promise<string | undefined>;
+  read: (key) => Promise<PostRow | undefined>;
+}>;
+```
+
+Async inspection and Watchdog executor shared by D1 and PostgreSQL.
+
+---
+
+### D1PostSource
+
+```ts
+type D1PostSource = Readonly<{
+  text: string;
+  values: readonly (string | number | null)[];
+}>;
+```
+
+Trusted SELECT yielding post_key, envelope_json, queue_name, next_attempt_at and
+job_id.
+
+---
+
+### D1Post
+
+```ts
+type D1Post = SqlPostRuntime &
+  Readonly<{
+    send: (envelope) => readonly D1PreparedStatement[];
+    sendFromSelect: (source) => readonly D1PreparedStatement[];
+  }>;
+```
+
+Post admission statements; callers commit them with the originating D1 fact.
+
+---
+
+### D1PostErasureStatement
+
+```ts
+type D1PostErasureStatement = Readonly<{
+  text: string;
+  values: readonly (string | number | null)[];
+}>;
+```
+
+Native erasure statement; its values remain bound by the caller's D1 driver.
+
+## Variables
+
+### postD1Schema
+
+```ts
+const postD1Schema: readonly string[];
+```
+
+Carrier-owned D1 schema, applied by the deployment migration owner.
+
+## Functions
+
+### createD1Post()
+
+```ts
+function createD1Post<R>(options): D1Post;
+```
+
+Bind the Post registry to native D1 batch admission and the shared delivery
+engine.
+
+#### 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`](post.md#postdeliveryresult)\>; \}\>; \}\>; `recordCursor?`: (`envelope`, `cursor`) => `void`; `recordRefused?`: (`envelope`) => `void`; \}\>\> |
+
+#### Parameters
+
+| Parameter | Type                                                                                                                                                                                                                                                                                                                                 |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `options` | `Readonly`\<\{ `routes`: `R`; `failureDetail?`: (`cause`) => `string`; `retry?`: `Readonly`\<\{ `maxAttempts`: `number`; `baseDelayMs`: `number`; `maxDelayMs`: `number`; \}\>; `now`: () => `number`; `scheduleWake`: (`at`) => `Promise`\<`void`\>; \}\> & `Readonly`\<\{ `database`: `D1Database`; `watchdog`: `D1Watchdog`; \}\> |
+
+#### Returns
+
+[`D1Post`](#d1post)
+
+---
+
+### prepareD1PostAdmission()
+
+```ts
+function prepareD1PostAdmission(
+  database,
+  source,
+): readonly D1PreparedStatement[];
+```
+
+Prepare conditional envelopes and their jobs inside the producer's D1 batch.
+
+#### Parameters
+
+| Parameter  | Type                            |
+| ---------- | ------------------------------- |
+| `database` | `D1Database`                    |
+| `source`   | [`D1PostSource`](#d1postsource) |
+
+#### Returns
+
+readonly `D1PreparedStatement`[]
+
+---
+
+### purgeD1Post()
+
+```ts
+function purgeD1Post(source): readonly Readonly<{
+  text: string;
+  values: readonly (string | number | null)[];
+}>[];
+```
+
+Remove selected recipient queues, including every envelope and attempt,
+atomically. The trusted SELECT yields queue_name from producer/envelope facts,
+not job state.
+
+#### Parameters
+
+| Parameter | Type                                                |
+| --------- | --------------------------------------------------- |
+| `source`  | [`D1PostErasureStatement`](#d1posterasurestatement) |
+
+#### Returns
+
+readonly `Readonly`\<\{ `text`: `string`; `values`: readonly (`string` \|
+`number` \| `null`)[]; \}\>[]

package/docs/api/post-postgres.md

@@ -0,0 +1,108 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/carrier**](README.md)
+
+---
+
+[@fungi.computer/carrier](README.md) / post-postgres
+
+# post-postgres
+
+## Type Aliases
+
+### PostgresPost
+
+```ts
+type PostgresPost = SqlPostRuntime &
+  Readonly<{
+    send: (client, envelope) => Promise<void>;
+  }>;
+```
+
+Post on PostgreSQL; the producer retains ownership of BEGIN and COMMIT.
+
+---
+
+### PostgresPostErasureStatement
+
+```ts
+type PostgresPostErasureStatement = Readonly<{
+  text: string;
+  values: readonly (string | number | null)[];
+}>;
+```
+
+Parameterized native erasure; the producer controls BEGIN and COMMIT.
+
+## Variables
+
+### postPostgresSchema
+
+```ts
+const postPostgresSchema: readonly string[];
+```
+
+Carrier-owned PostgreSQL schema, applied by the deployment migration owner.
+
+## Functions
+
+### createPostgresPost()
+
+```ts
+function createPostgresPost<R>(options): PostgresPost;
+```
+
+Bind the Post registry to a PostgreSQL owner and the shared delivery engine.
+
+#### 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`](post.md#postdeliveryresult)\>; \}\>; \}\>; `recordCursor?`: (`envelope`, `cursor`) => `void`; `recordRefused?`: (`envelope`) => `void`; \}\>\> |
+
+#### Parameters
+
+| Parameter | Type                                                                                                                                                                                                                                                                                                                                                                     |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `options` | `Readonly`\<\{ `routes`: `R`; `failureDetail?`: (`cause`) => `string`; `retry?`: `Readonly`\<\{ `maxAttempts`: `number`; `baseDelayMs`: `number`; `maxDelayMs`: `number`; \}\>; `now`: () => `number`; `scheduleWake`: (`at`) => `Promise`\<`void`\>; \}\> & `Readonly`\<\{ `database`: `Pick`\<`Pool`, `"query"` \| `"connect"`\>; `watchdog`: `PostgresWatchdog`; \}\> |
+
+#### Returns
+
+[`PostgresPost`](#postgrespost)
+
+---
+
+### purgePostgresPost()
+
+```ts
+function purgePostgresPost(source): readonly Readonly<{
+  text: string;
+  values: readonly (string | number | null)[];
+}>[];
+```
+
+Purge selected recipient queues, including all envelopes and attempts. The
+trusted SELECT yields queue_name from producer/envelope facts, not job state.
+
+#### Parameters
+
+| Parameter | Type                                                            |
+| --------- | --------------------------------------------------------------- |
+| `source`  | [`PostgresPostErasureStatement`](#postgresposterasurestatement) |
+
+#### Returns
+
+readonly `Readonly`\<\{ `text`: `string`; `values`: readonly (`string` \|
+`number` \| `null`)[]; \}\>[]
+
+## References
+
+### SqlPostOptions
+
+Re-exports [SqlPostOptions](post-d1.md#sqlpostoptions)
+
+---
+
+### SqlPostRuntime
+
+Re-exports [SqlPostRuntime](post-d1.md#sqlpostruntime)