@fungi.computer/carrier 0.0.0-stage → 0.0.1

package/dist/inspection.d.ts

@@ -0,0 +1,108 @@
+import * as Schema from "effect/Schema";
+import type { WatchdogSqliteOwner } from "@fungi.computer/watchdog";
+/** One bounded scan; an empty filtered page can still have a continuation. */
+export declare const DeliveryInspectionPageQuerySchema: Schema.Struct<{
+    readonly limit: Schema.withDecodingDefaultType<Schema.Int, never>;
+    readonly after: Schema.optional<Schema.String>;
+}>;
+/** Post can filter dead letters while scanning at most one bounded page. */
+export declare const DeliveryInspectionQuerySchema: Schema.Struct<{
+    readonly view: Schema.Literals<readonly ["receipts", "deadLetters"]>;
+    readonly limit: Schema.withDecodingDefaultType<Schema.Int, never>;
+    readonly after: Schema.optional<Schema.String>;
+}>;
+/** An email receipt page uses the same producer-key pagination. */
+export type DeliveryInspectionPageQuery = Schema.Codec.Encoded<typeof DeliveryInspectionPageQuerySchema>;
+/** Input to one producer-local inspection. Cursors are producer keys, without storage prefixes. */
+export type DeliveryInspectionQuery = Schema.Codec.Encoded<typeof DeliveryInspectionQuerySchema>;
+/** Dispatch evidence deliberately omits the address and event. */
+export declare const PostReceiptSummarySchema: Schema.Union<readonly [Schema.Struct<{
+    readonly key: Schema.String;
+    readonly state: Schema.Literal<"delivered">;
+}>, Schema.Struct<{
+    readonly key: Schema.String;
+    readonly state: Schema.Literal<"pending">;
+    readonly kind: Schema.String;
+    readonly attempts: Schema.Int;
+    readonly nextAttemptAt: Schema.Number;
+}>, Schema.Struct<{
+    readonly key: Schema.String;
+    readonly state: Schema.Literal<"dead">;
+    readonly kind: Schema.String;
+    readonly attempts: Schema.Int;
+    readonly reason: Schema.Literals<readonly ["refused", "exhausted"]>;
+}>]>;
+/** Metadata for one retained Post row. */
+export type PostReceiptSummary = Schema.Schema.Type<typeof PostReceiptSummarySchema>;
+/** Bounded evidence with an explicit distinction between empty and uninitialized storage. */
+export declare const PostInspectionPageSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly status: Schema.Literal<"uninitialized">;
+}>, Schema.Struct<{
+    readonly status: Schema.Literal<"available">;
+    readonly records: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+        readonly key: Schema.String;
+        readonly state: Schema.Literal<"delivered">;
+    }>, Schema.Struct<{
+        readonly key: Schema.String;
+        readonly state: Schema.Literal<"pending">;
+        readonly kind: Schema.String;
+        readonly attempts: Schema.Int;
+        readonly nextAttemptAt: Schema.Number;
+    }>, Schema.Struct<{
+        readonly key: Schema.String;
+        readonly state: Schema.Literal<"dead">;
+        readonly kind: Schema.String;
+        readonly attempts: Schema.Int;
+        readonly reason: Schema.Literals<readonly ["refused", "exhausted"]>;
+    }>]>>;
+    readonly nextCursor: Schema.NullOr<Schema.String>;
+}>]>;
+/** One read of producer-local Post dispatch evidence. */
+export type PostInspectionPage = Schema.Schema.Type<typeof PostInspectionPageSchema>;
+/** Aggregate email evidence without bodies, headers or recipient addresses. */
+export declare const CarrierReceiptSummarySchema: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly status: Schema.Literals<readonly ["queued", "dispatching", "provider_accepted", "outcome_unknown", "rejected", "refused", "expired", "superseded"]>;
+    readonly attempts: Schema.Int;
+    readonly retryAt: Schema.NullOr<Schema.Number>;
+    readonly providerMessageId: Schema.optional<Schema.NonEmptyString>;
+    readonly providerRejection: Schema.optional<Schema.Struct<{
+        readonly code: Schema.NonEmptyString;
+        readonly class: Schema.Literals<readonly ["permanent", "temporary"]>;
+    }>>;
+}>;
+/** Carrier's bounded metadata page; unavailable storage is never reported as empty. */
+export declare const CarrierInspectionPageSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly status: Schema.Literal<"uninitialized">;
+}>, Schema.Struct<{
+    readonly status: Schema.Literal<"available">;
+    readonly records: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.String;
+        readonly status: Schema.Literals<readonly ["queued", "dispatching", "provider_accepted", "outcome_unknown", "rejected", "refused", "expired", "superseded"]>;
+        readonly attempts: Schema.Int;
+        readonly retryAt: Schema.NullOr<Schema.Number>;
+        readonly providerMessageId: Schema.optional<Schema.NonEmptyString>;
+        readonly providerRejection: Schema.optional<Schema.Struct<{
+            readonly code: Schema.NonEmptyString;
+            readonly class: Schema.Literals<readonly ["permanent", "temporary"]>;
+        }>>;
+    }>>;
+    readonly nextCursor: Schema.NullOr<Schema.String>;
+}>]>;
+/** One read of aggregate email dispatch evidence. */
+export type CarrierInspectionPage = Schema.Schema.Type<typeof CarrierInspectionPageSchema>;
+/** Stable inspection errors never include stored cargo or raw SQL failures. */
+export declare class DeliveryInspectionError extends Error {
+    readonly code: "invalid_query" | "unavailable";
+    constructor(code: "invalid_query" | "unavailable");
+}
+/**
+ * Read existing storage without opening a sender, initializing tables, repairing
+ * jobs or arming a wake. The trusted host must admit an operator before calling.
+ */
+export declare function createDeliveryInspection(sql: WatchdogSqliteOwner["sql"]): {
+    /** Read aggregate dispatch evidence without email cargo or recipient addresses. */
+    email(input: DeliveryInspectionPageQuery): CarrierInspectionPage;
+    /** Read Post metadata; filtered pages retain their continuation through other states. */
+    post(input: DeliveryInspectionQuery): PostInspectionPage;
+};

package/dist/inspection.js

@@ -0,0 +1,188 @@
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Schema from "effect/Schema";
+import { PostRowSchema } from "./post.js";
+import { CarrierStatusSchema } from "./internal/receipt-schema.js";
+const Key = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(256));
+/** One bounded scan; an empty filtered page can still have a continuation. */
+export const DeliveryInspectionPageQuerySchema = Schema.Struct({
+    limit: Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 64 })).pipe(Schema.withDecodingDefaultType(Effect.succeed(32))),
+    after: Schema.optional(Key),
+});
+/** Post can filter dead letters while scanning at most one bounded page. */
+export const DeliveryInspectionQuerySchema = Schema.Struct({
+    ...DeliveryInspectionPageQuerySchema.fields,
+    view: Schema.Literals(["receipts", "deadLetters"]),
+});
+/** Dispatch evidence deliberately omits the address and event. */
+export const PostReceiptSummarySchema = Schema.Union([
+    Schema.Struct({ key: Key, state: Schema.Literal("delivered") }),
+    Schema.Struct({
+        key: Key,
+        state: Schema.Literal("pending"),
+        kind: Key,
+        attempts: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+        nextAttemptAt: Schema.Number.check(Schema.isGreaterThanOrEqualTo(0)),
+    }),
+    Schema.Struct({
+        key: Key,
+        state: Schema.Literal("dead"),
+        kind: Key,
+        attempts: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+        reason: Schema.Literals(["refused", "exhausted"]),
+    }),
+]);
+/** Bounded evidence with an explicit distinction between empty and uninitialized storage. */
+export const PostInspectionPageSchema = Schema.Union([
+    Schema.Struct({ status: Schema.Literal("uninitialized") }),
+    Schema.Struct({
+        status: Schema.Literal("available"),
+        records: Schema.Array(PostReceiptSummarySchema).check(Schema.isMaxLength(64)),
+        nextCursor: Schema.NullOr(Key),
+    }),
+]);
+/** Aggregate email evidence without bodies, headers or recipient addresses. */
+export const CarrierReceiptSummarySchema = Schema.Struct({
+    id: Key,
+    status: CarrierStatusSchema,
+    attempts: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+    retryAt: Schema.NullOr(Schema.Number.check(Schema.isGreaterThanOrEqualTo(0))),
+    providerMessageId: Schema.optional(Schema.NonEmptyString.check(Schema.isMaxLength(1024))),
+    providerRejection: Schema.optional(Schema.Struct({
+        code: Schema.NonEmptyString.check(Schema.isMaxLength(64)),
+        class: Schema.Literals(["permanent", "temporary"]),
+    })),
+});
+/** Carrier's bounded metadata page; unavailable storage is never reported as empty. */
+export const CarrierInspectionPageSchema = Schema.Union([
+    Schema.Struct({ status: Schema.Literal("uninitialized") }),
+    Schema.Struct({
+        status: Schema.Literal("available"),
+        records: Schema.Array(CarrierReceiptSummarySchema).check(Schema.isMaxLength(64)),
+        nextCursor: Schema.NullOr(Key),
+    }),
+]);
+/** Stable inspection errors never include stored cargo or raw SQL failures. */
+export class DeliveryInspectionError extends Error {
+    code;
+    constructor(code) {
+        super(`Delivery inspection ${code}`);
+        this.code = code;
+    }
+}
+const StoredPost = Schema.Struct({ key: Schema.String, value: PostRowSchema });
+const StoredEmail = Schema.Struct({
+    id: Key,
+    status: CarrierStatusSchema,
+    attempts: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+    retry_at: Schema.NullOr(Schema.Number.check(Schema.isGreaterThanOrEqualTo(0))),
+    provider_id: Schema.NullOr(Schema.NonEmptyString.check(Schema.isMaxLength(1024))),
+    error_code: Schema.NullOr(Schema.NonEmptyString.check(Schema.isMaxLength(64))),
+    error_class: Schema.NullOr(Schema.Literals(["permanent", "temporary"])),
+});
+const hasTable = (sql, name) => sql
+    .exec("SELECT 1 FROM sqlite_master WHERE type='table' AND name=? LIMIT 1", name)
+    .toArray().length === 1;
+/**
+ * Read existing storage without opening a sender, initializing tables, repairing
+ * jobs or arming a wake. The trusted host must admit an operator before calling.
+ */
+export function createDeliveryInspection(sql) {
+    return {
+        /** Read aggregate dispatch evidence without email cargo or recipient addresses. */
+        email(input) {
+            const parsed = Schema.decodeUnknownExit(DeliveryInspectionPageQuerySchema, { onExcessProperty: "error" })(input);
+            if (Exit.isFailure(parsed))
+                throw new DeliveryInspectionError("invalid_query");
+            const query = parsed.value;
+            try {
+                if (!hasTable(sql, "carrier_emails"))
+                    return { status: "uninitialized" };
+                const rows = Schema.decodeUnknownSync(Schema.Array(StoredEmail))(sql
+                    .exec("SELECT id,status,attempts,retry_at,provider_id,error_code,error_class FROM carrier_emails WHERE id>? ORDER BY id LIMIT ?", query.after ?? "", query.limit)
+                    .toArray());
+                return Schema.decodeUnknownSync(CarrierInspectionPageSchema)({
+                    status: "available",
+                    records: rows.map((row) => {
+                        const receipt = {
+                            id: row.id,
+                            status: row.status,
+                            attempts: row.attempts,
+                            retryAt: row.retry_at,
+                        };
+                        if (row.provider_id !== null)
+                            return { ...receipt, providerMessageId: row.provider_id };
+                        if (row.error_code !== null && row.error_class !== null)
+                            return {
+                                ...receipt,
+                                providerRejection: {
+                                    code: row.error_code,
+                                    class: row.error_class,
+                                },
+                            };
+                        return receipt;
+                    }),
+                    nextCursor: rows.length === query.limit ? rows.at(-1)?.id : null,
+                });
+            }
+            catch {
+                throw new DeliveryInspectionError("unavailable");
+            }
+        },
+        /** Read Post metadata; filtered pages retain their continuation through other states. */
+        post(input) {
+            const parsed = Schema.decodeUnknownExit(DeliveryInspectionQuerySchema, {
+                onExcessProperty: "error",
+            })(input);
+            if (Exit.isFailure(parsed))
+                throw new DeliveryInspectionError("invalid_query");
+            const query = parsed.value;
+            try {
+                if (!hasTable(sql, "carrier_post_rows"))
+                    return { status: "uninitialized" };
+                const rows = Schema.decodeUnknownSync(Schema.Array(StoredPost))(sql
+                    .exec("SELECT key,value FROM carrier_post_rows WHERE key LIKE 'post:%' AND key>? ORDER BY key LIMIT ?", `post:${query.after ?? ""}`, query.limit)
+                    .toArray());
+                const records = rows.flatMap(({ key, value }) => {
+                    if (query.view === "deadLetters" && value.state !== "dead")
+                        return [];
+                    const receiptKey = key.slice("post:".length);
+                    switch (value.state) {
+                        case "delivered":
+                            return [{ key: receiptKey, state: value.state }];
+                        case "pending":
+                            return [
+                                {
+                                    key: receiptKey,
+                                    state: value.state,
+                                    kind: value.envelope.kind,
+                                    attempts: value.attempts,
+                                    nextAttemptAt: value.nextAttemptAt,
+                                },
+                            ];
+                        case "dead":
+                            return [
+                                {
+                                    key: receiptKey,
+                                    state: value.state,
+                                    kind: value.envelope.kind,
+                                    attempts: value.attempts,
+                                    reason: value.reason,
+                                },
+                            ];
+                    }
+                });
+                return Schema.decodeUnknownSync(PostInspectionPageSchema)({
+                    status: "available",
+                    records,
+                    nextCursor: rows.length === query.limit
+                        ? rows.at(-1)?.key.slice("post:".length)
+                        : null,
+                });
+            }
+            catch {
+                throw new DeliveryInspectionError("unavailable");
+            }
+        },
+    };
+}

package/dist/internal/cloudflare-send.d.ts

@@ -0,0 +1,9 @@
+import type { EmailMessageBuilder, SendEmail } from "@cloudflare/workers-types";
+import type { SendEvidence } from "./contracts.js";
+/**
+ * Invoke the native structured binding once, preserving its recipient envelope.
+ * Cloudflare supplies no application idempotency key here. Only a documented
+ * whole-request rejection is reported as such; any other exception cannot
+ * authorize another send.
+ */
+export declare function sendCloudflareEmail(binding: SendEmail, email: EmailMessageBuilder): Promise<SendEvidence>;

package/dist/internal/cloudflare-send.js

@@ -0,0 +1,79 @@
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+// Cloudflare Email Service documents that the Workers binding throws a standard
+// Error carrying a string `code` (Email Service, Workers API, error codes). The
+// installed @cloudflare/workers-types declares no error type, so the documented
+// codes are decoded here. Only codes naming a refusal of the whole request are
+// classified; everything else remains an unknown outcome.
+const Temporary = Schema.Literals([
+    // Quota or temporary service unavailability; documented as retryable.
+    "E_RATE_LIMIT_EXCEEDED",
+    "E_DAILY_LIMIT_EXCEEDED",
+    "E_INTERNAL_SERVER_ERROR",
+]);
+const isTemporary = Schema.is(Temporary);
+const Rejection = Schema.Struct({
+    code: Schema.Union([
+        Temporary,
+        // Request, sender, recipient or header validity; retrying cannot help.
+        Schema.Literals([
+            "E_VALIDATION_ERROR",
+            "E_FIELD_MISSING",
+            "E_TOO_MANY_RECIPIENTS",
+            "E_TOO_MANY_ATTACHMENTS",
+            "E_SENDER_NOT_VERIFIED",
+            "E_RECIPIENT_NOT_ALLOWED",
+            "E_RECIPIENT_SUPPRESSED",
+            "E_SENDER_DOMAIN_NOT_AVAILABLE",
+            "E_CONTENT_TOO_LARGE",
+            "E_HEADER_NOT_ALLOWED",
+            "E_HEADER_USE_API_FIELD",
+            "E_HEADER_VALUE_INVALID",
+            "E_HEADER_VALUE_TOO_LONG",
+            "E_HEADER_NAME_INVALID",
+            "E_HEADERS_TOO_LARGE",
+            "E_HEADERS_TOO_MANY",
+        ]),
+    ]),
+});
+const decodeRejection = Schema.decodeUnknownOption(Rejection);
+// E_DELIVERY_FAILED and undocumented codes stay unknown: an SMTP-stage failure
+// may follow acceptance of some recipients, so it cannot authorize a resend.
+// Their code is kept only as a sanitized log cause; messages are never kept
+// because they may contain mail data.
+const decodeCode = Schema.decodeUnknownOption(Schema.Struct({
+    code: Schema.String.check(Schema.isPattern(/^E_[A-Z_]{1,62}$/u)),
+}));
+/**
+ * Invoke the native structured binding once, preserving its recipient envelope.
+ * Cloudflare supplies no application idempotency key here. Only a documented
+ * whole-request rejection is reported as such; any other exception cannot
+ * authorize another send.
+ */
+export async function sendCloudflareEmail(binding, email) {
+    try {
+        const receipt = await binding.send(email);
+        return {
+            kind: "provider_accepted",
+            providerMessageId: receipt.messageId,
+        };
+    }
+    catch (error) {
+        const rejection = decodeRejection(error);
+        if (Option.isSome(rejection)) {
+            const { code } = rejection.value;
+            return {
+                kind: "provider_rejected",
+                code,
+                class: isTemporary(code) ? "temporary" : "permanent",
+            };
+        }
+        return Option.match(decodeCode(error), {
+            onNone: () => ({
+                kind: "outcome_unknown",
+                cause: error instanceof Error ? "provider_exception" : "non_error_thrown",
+            }),
+            onSome: ({ code }) => ({ kind: "outcome_unknown", cause: code }),
+        });
+    }
+}

package/dist/internal/contracts.d.ts

@@ -0,0 +1,94 @@
+import type { WatchdogSqliteOwner } from "@fungi.computer/watchdog";
+import type * as Schema from "effect/Schema";
+import type { CarrierStatusSchema } from "./receipt-schema.js";
+/** One recipient address; display names remain part of the requested envelope. */
+export type Address = string | Readonly<{
+    email: string;
+    name: string;
+}>;
+/** Common content and envelope for one Email. */
+export type Email = Readonly<{
+    from: Address;
+    to?: readonly Address[];
+    cc?: readonly Address[];
+    bcc?: readonly Address[];
+    subject: string;
+    html?: string;
+    text?: string;
+    headers?: Readonly<Record<string, string>>;
+}>;
+/** Source identity and expiry belong to the notification's producer. */
+export type Submission = Email & Readonly<{
+    id: string;
+    sendBefore?: number;
+}>;
+/** A recipient Message is distinct from its Email and provider request. */
+export type Message = Readonly<{
+    id: string;
+    recipient: string;
+    roles: readonly ("to" | "cc" | "bcc")[];
+    status: "unconfirmed";
+}>;
+/** A provider's definite refusal of a whole request: retryable or final. */
+export type ProviderRejection = Readonly<{
+    code: string;
+    class: "permanent" | "temporary";
+}>;
+/**
+ * Durable submission and aggregate dispatch evidence, without credential content.
+ * `refused` means Carrier's per-recipient cap declined the submission before
+ * any provider attempt; `rejected` means the provider definitely refused it
+ * (a permanent rejection, or temporary rejections until retries ran out).
+ * `providerRejection` is the last provider refusal, also while a temporary
+ * rejection waits `queued` for its retry.
+ */
+export type Receipt = Readonly<{
+    id: string;
+    status: Schema.Schema.Type<typeof CarrierStatusSchema>;
+    providerMessageId?: string;
+    providerRejection?: ProviderRejection;
+    messages: readonly Message[];
+}>;
+/**
+ * One transport invocation reports only the evidence it obtained. Report
+ * `provider_rejected` only for a documented refusal of the whole request before
+ * acceptance; `cause` is an optional sanitized provider code for logs.
+ */
+export type SendEvidence = Readonly<{
+    kind: "provider_accepted";
+    providerMessageId: string;
+}> | (Readonly<{
+    kind: "provider_rejected";
+}> & ProviderRejection) | Readonly<{
+    kind: "outcome_unknown";
+    cause?: string;
+}>;
+/** Mechanical host capabilities; commit must durably arm a wake with its mutation. */
+export type Host = Readonly<{
+    /** Commit the synchronous mutation and a durable recovery wake atomically. */
+    commit: <A>(mutation: () => A) => Promise<A>;
+    /** Durably schedule another dispatch/recovery step. */
+    requestWake: () => Promise<void>;
+}>;
+/** Configure a durable owner; business validity remains with the source. */
+export type Options = Readonly<{
+    storage: WatchdogSqliteOwner;
+    host: Host;
+    /** Return the current Unix timestamp in milliseconds for source expiry checks. */
+    now: () => number;
+    /** Return false only for a definitely obsolete source; throw when validity is unavailable. */
+    canSend?: (emailId: string) => Promise<boolean>;
+    /** Make one provider attempt and report only observed evidence; Carrier owns retries. */
+    transport: (email: Email) => Promise<SendEvidence>;
+}>;
+declare const CarrierError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "CarrierError";
+} & Readonly<A>;
+/** Stable failures omit email bodies, tokens and raw provider errors. */
+export declare class CarrierError extends CarrierError_base<{
+    readonly code: "invalid_input" | "conflict" | "unavailable";
+    readonly message: string;
+}> {
+    constructor(code: "invalid_input" | "conflict" | "unavailable");
+}
+export {};

package/dist/internal/contracts.js

@@ -0,0 +1,7 @@
+import * as Data from "effect/Data";
+/** Stable failures omit email bodies, tokens and raw provider errors. */
+export class CarrierError extends Data.TaggedError("CarrierError") {
+    constructor(code) {
+        super({ code, message: `Carrier ${code}` });
+    }
+}

package/dist/internal/owner.d.ts

@@ -0,0 +1,24 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { CarrierError, type Options, type Submission as CarrierSubmission } from "./contracts.js";
+import { CarrierStatusSchema } from "./receipt-schema.js";
+/** One private lifecycle; the public Promise entry only runs these effects. */
+export declare function openOwner(options: Options): {
+    initialize: Effect.Effect<void, CarrierError, never>;
+    send: (input: CarrierSubmission) => Effect.Effect<Readonly<{
+        id: string;
+        status: Schema.Schema.Type<typeof CarrierStatusSchema>;
+        providerMessageId?: string;
+        providerRejection?: import("./contracts.js").ProviderRejection;
+        messages: readonly import("./contracts.js").Message[];
+    }>, CarrierError, never>;
+    tick: Effect.Effect<void, CarrierError, never>;
+    get: (id: string) => Effect.Effect<Readonly<{
+        id: string;
+        status: Schema.Schema.Type<typeof CarrierStatusSchema>;
+        providerMessageId?: string;
+        providerRejection?: import("./contracts.js").ProviderRejection;
+        messages: readonly import("./contracts.js").Message[];
+    }> | undefined, CarrierError, never>;
+    hasPendingWork: Effect.Effect<boolean, CarrierError, never>;
+};