@sekiban/dcb-runtime 0.2.0

package/dist/downstream/DeliveryCore.d.ts

@@ -0,0 +1,127 @@
+import type { DeliverySource, DownstreamOutboxMessage, PipelineClock } from "./types";
+import type { StoreProvider } from "../store/provider";
+import type { StoreProviderEnvironment } from "../store/provider";
+import type { GlobalReceiptJoin, PipelineStore, StoredEvent } from "../store/types";
+import type { DeliveryAttemptContext } from "../store/types";
+import { type G60DurableHopObserver } from "../diagnostics/G60DurableHop";
+export type DeliveryViewFailureClass = "retryable-transient" | "duplicate-race" | "nonretryable-definition-poison";
+export type DeliveryViewApplyResult = "applied" | "duplicate-race" | void;
+export interface DeliveryViewInput {
+    readonly message: DownstreamOutboxMessage;
+    readonly event: StoredEvent;
+    readonly arrivedAt: number;
+    readonly source: DeliverySource;
+}
+/**
+ * A view handler owns one view's unsafe observation and atomic apply.  The
+ * delivery core deliberately knows nothing about D1 rows, receipts, or kicks;
+ * this boundary is what lets the Queue and doorbell share exactly one order
+ * of operations.
+ */
+export interface DeliveryViewHandler {
+    readonly id: string;
+    /**
+     * The exceptional unsafe lane is independent of G44 completeness. It may
+     * only be used by a handler whose mutation never advances a safe
+     * checkpoint; omitted means the ordinary completeness-gated lane.
+     */
+    readonly admission?: "independent-unsafe";
+    readonly apply: (input: DeliveryViewInput) => Promise<DeliveryViewApplyResult>;
+    readonly classifyError?: (error: unknown) => DeliveryViewFailureClass;
+}
+export interface DeliveryViewResult {
+    readonly id: string;
+    readonly status: "applied" | "duplicate-race" | "failed";
+    readonly failureClass?: DeliveryViewFailureClass;
+    readonly error?: string;
+    readonly durationMs: number;
+}
+export interface DeliveryCoreFailure {
+    readonly phase: "recordDelivery" | "detector" | "completeness" | "view" | "drain";
+    readonly class: DeliveryViewFailureClass | "retryable-transient";
+    readonly viewId?: string;
+    readonly error: string;
+}
+export interface DeliveryCoreResult {
+    readonly source: DeliverySource;
+    readonly correlationId: string;
+    readonly outcome: "stored" | "suid-collision" | "lineage-mismatch";
+    readonly arrivedAt: number;
+    readonly detectorApplied: boolean;
+    readonly views: readonly DeliveryViewResult[];
+    readonly failures: readonly DeliveryCoreFailure[];
+    readonly coreDurationMs: number;
+    /** The queue wrapper is the only caller that turns this into ack/retry. */
+    readonly queueDisposition: "ack" | "retry-once" | "retry-to-dlq";
+    /** A durable poison finding must reach bounded Queue/DLQ remediation. */
+    readonly queueDispositionReason: "none" | "duplicate-race-retry" | "retryable-transient" | "definition-poison-dlq";
+    /** The fast wrapper never retries or changes outbox state. */
+    readonly fastDisposition: "completed" | "failed";
+}
+export interface DeliveryCoreOptions {
+    readonly clock?: PipelineClock;
+    readonly store?: PipelineStore;
+    readonly storeProvider?: StoreProvider;
+    readonly views?: readonly DeliveryViewHandler[];
+    /** Internal G60 hop observation; it is never a delivery decision input. */
+    readonly durableHopObserver?: G60DurableHopObserver;
+    /** G69 diagnostic ownership only; core admission never awaits this work. */
+    readonly g69AdmissionAttempt?: DeliveryAttemptContext;
+    /** Compatibility hook for callers that have not adopted a view handler yet. */
+    readonly onStored?: (input: {
+        readonly message: DownstreamOutboxMessage;
+        readonly event: StoredEvent;
+        readonly arrivedAt: number;
+        readonly source: DeliverySource;
+    }) => Promise<void>;
+    readonly afterDelivery?: (input: {
+        readonly message: DownstreamOutboxMessage;
+        readonly event: StoredEvent;
+        readonly arrivedAt: number;
+        readonly source: DeliverySource;
+        readonly result: DeliveryCoreResult;
+    }) => Promise<void>;
+    /**
+     * Source acknowledgement is allowed only after D1 has read back an exact
+     * event + committed-membership + receipt join. Queue/doorbell handoff is
+     * intentionally not an acknowledgement authority.
+     */
+    readonly afterGlobalReceipt?: (input: {
+        readonly message: DownstreamOutboxMessage;
+        readonly receipt: GlobalReceiptJoin;
+        readonly arrivedAt: number;
+        readonly source: DeliverySource;
+    }) => Promise<void>;
+    /**
+     * G44's one internal coverage gate.  The receipt remains durable, but a
+     * materialized/live view cannot advance while global completeness is not
+     * proven by a FULL source scan.
+     */
+    readonly beforeViews?: (input: {
+        readonly message: DownstreamOutboxMessage;
+        readonly event: StoredEvent;
+        readonly arrivedAt: number;
+        readonly source: DeliverySource;
+    }) => Promise<void>;
+    /**
+     * G44 records a detector fault before returning. The core still fails
+     * closed even when this observation authority itself is unavailable.
+     */
+    readonly onDetectorFailure?: (input: {
+        readonly message: DownstreamOutboxMessage;
+        readonly arrivedAt: number;
+        readonly source: DeliverySource;
+        readonly error: unknown;
+    }) => Promise<void>;
+    readonly correlationId?: string;
+}
+export interface DeliveryCoreEnvironment extends StoreProviderEnvironment {
+    readonly REPAIR_EXCLUSION_LOOKUP?: Fetcher;
+}
+export type { DeliverySource };
+export declare function deliveryCorrelationId(message: DownstreamOutboxMessage, source: DeliverySource, supplied?: string): string;
+/**
+ * Shared transport-neutral delivery order.  There are intentionally no Queue
+ * message methods, outbox marks, or retry decisions in this function.
+ */
+export declare function processDeliveryCore(message: DownstreamOutboxMessage, source: DeliverySource, env: DeliveryCoreEnvironment, options?: DeliveryCoreOptions): Promise<DeliveryCoreResult>;

package/dist/downstream/DeliveryCore.js

@@ -0,0 +1,304 @@
+import { BindingExclusionLedgerClient } from "./ExclusionLookup";
+import { InconsistencyDetector } from "./InconsistencyDetector";
+import { resolveDeliveryIdentity } from "../eventIdentity";
+import { systemPipelineClock } from "./types";
+import { observeG60PostAdmission } from "../diagnostics/G60DurableHop";
+function observePostAdmission(observer, message, source, input) {
+    observeG60PostAdmission(observer, {
+        ...input,
+        serviceId: message.serviceId,
+        eventId: message.eventId,
+        suid: message.suid,
+        attemptId: message.attemptId,
+        partitionTag: message.tag,
+        transport: source,
+        observedAt: Date.now(),
+    });
+}
+function errorText(error) {
+    if (error instanceof Error && error.message.length > 0)
+        return error.message;
+    return String(error);
+}
+export function deliveryCorrelationId(message, source, supplied) {
+    return supplied ?? `${source}:${message.serviceId}:${message.eventId}:${message.attemptId}`;
+}
+function defaultFailureClass(error) {
+    const candidate = error;
+    if (candidate.failureClass === "duplicate-race")
+        return "duplicate-race";
+    if (candidate.failureClass === "nonretryable-definition-poison")
+        return "nonretryable-definition-poison";
+    if (candidate.failureClass === "retryable-transient")
+        return "retryable-transient";
+    if (candidate.code === "UNSAFE_DUPLICATE_RACE")
+        return "duplicate-race";
+    if (candidate.retryable === false)
+        return "nonretryable-definition-poison";
+    return "retryable-transient";
+}
+function disposition(failures, source) {
+    // A duplicate race is a blocking Queue outcome: the loser must be delivered
+    // once more so the receipt guard can turn the replay into a durable no-op.
+    // The fast path remains silent-fallback, so its disposition is calculated
+    // from the non-duplicate failures separately below.
+    const blocking = failures.length > 0;
+    const duplicateRaceOnly = blocking && failures.every((failure) => failure.class === "duplicate-race");
+    const poisonOnly = blocking && failures.every((failure) => failure.class === "nonretryable-definition-poison");
+    const fastBlocking = failures.some((failure) => failure.class !== "duplicate-race");
+    return {
+        queueDisposition: !blocking ? "ack" : duplicateRaceOnly ? "retry-once" : "retry-to-dlq",
+        queueDispositionReason: !blocking ? "none" : duplicateRaceOnly ? "duplicate-race-retry" : poisonOnly ? "definition-poison-dlq" : "retryable-transient",
+        fastDisposition: source === "fast" && fastBlocking ? "failed" : "completed",
+    };
+}
+function result(source, message, outcome, arrivedAt, detectorApplied, views, failures, suppliedCorrelationId, startedAt = performance.now()) {
+    return {
+        source,
+        correlationId: deliveryCorrelationId(message, source, suppliedCorrelationId),
+        outcome,
+        arrivedAt,
+        detectorApplied,
+        views,
+        failures,
+        coreDurationMs: Math.max(0, performance.now() - startedAt),
+        ...disposition(failures, source),
+    };
+}
+function providerStore(env, options) {
+    if (options.store !== undefined)
+        return options.store;
+    if (options.storeProvider === undefined)
+        throw new Error("A downstream store provider is not configured");
+    return options.storeProvider.create(env);
+}
+async function applyViewHandlers(views, message, storedEvent, arrivedAt, source, observer) {
+    // The branches are independent atomic batches, so starting them together
+    // bounds fast-path latency by the slowest view while preserving the input
+    // order in the returned oracle.
+    const outcomes = await Promise.all(views.map(async (view) => {
+        const viewStartedAt = performance.now();
+        observePostAdmission(observer, message, source, {
+            stage: "unsafe-view-apply",
+            boundary: "start",
+            outcome: "started",
+            viewId: view.id,
+        });
+        try {
+            const applied = await view.apply({ message, event: storedEvent, arrivedAt, source });
+            const status = applied === "duplicate-race" ? "duplicate-race" : "applied";
+            observePostAdmission(observer, message, source, {
+                stage: "unsafe-view-apply",
+                boundary: "end",
+                outcome: status,
+                viewId: view.id,
+            });
+            return {
+                result: { id: view.id, status, durationMs: Math.max(0, performance.now() - viewStartedAt) },
+                failure: undefined,
+            };
+        }
+        catch (error) {
+            const failureClass = view.classifyError?.(error) ?? defaultFailureClass(error);
+            observePostAdmission(observer, message, source, {
+                stage: "unsafe-view-apply",
+                boundary: "end",
+                outcome: `failed:${failureClass}`,
+                viewId: view.id,
+            });
+            return {
+                result: {
+                    id: view.id,
+                    status: "failed",
+                    failureClass,
+                    error: errorText(error),
+                    durationMs: Math.max(0, performance.now() - viewStartedAt),
+                },
+                failure: { phase: "view", class: failureClass, viewId: view.id, error: errorText(error) },
+            };
+        }
+    }));
+    const results = outcomes.map((outcome) => outcome.result);
+    const failures = outcomes
+        .map((outcome) => outcome.failure)
+        .filter((failure) => failure !== undefined);
+    return { results, failures };
+}
+/**
+ * Shared transport-neutral delivery order.  There are intentionally no Queue
+ * message methods, outbox marks, or retry decisions in this function.
+ */
+export async function processDeliveryCore(message, source, env, options = {}) {
+    const startedAt = performance.now();
+    // Admission is deliberately before initialize/recordDelivery: a malformed
+    // post-G27 envelope cannot create an incident, detector row, or view state.
+    const resolvedIdentity = resolveDeliveryIdentity(message, source);
+    const store = providerStore(env, options);
+    await store.initialize();
+    const clock = options.clock ?? systemPipelineClock;
+    const arrivedAt = clock.now();
+    let outcome;
+    try {
+        // Normative step 1: durable EventStore record before any detector or view.
+        outcome = await store.recordDelivery(message, arrivedAt, source, options.g69AdmissionAttempt);
+        options.durableHopObserver?.observe({
+            stage: "record-delivery-batch-committed",
+            serviceId: message.serviceId,
+            eventId: message.eventId,
+            suid: message.suid,
+            attemptId: message.attemptId,
+            partitionTag: message.tag,
+            transport: source,
+            // D1 recordDelivery returns only after its batch and read-back have
+            // settled; this is the durable post-batch observation boundary.
+            observedAt: Date.now(),
+        });
+    }
+    catch (error) {
+        const failures = [{ phase: "recordDelivery", class: "retryable-transient", error: errorText(error) }];
+        return result(source, message, "stored", arrivedAt, false, [], failures, options.correlationId, startedAt);
+    }
+    // Normative step 2: typed non-stored outcome gate.  Only incident
+    // projection is allowed beyond this point for a collision or lineage miss.
+    if (outcome.outcome !== "stored") {
+        try {
+            await store.projectDeliveryIncidents?.(message.serviceId);
+        }
+        catch (error) {
+            const failures = [{ phase: "detector", class: "retryable-transient", error: errorText(error) }];
+            return result(source, message, outcome.outcome, arrivedAt, false, [], failures, options.correlationId, startedAt);
+        }
+        return result(source, message, outcome.outcome, arrivedAt, false, [], [], options.correlationId, startedAt);
+    }
+    const storedEvent = resolvedIdentity.legacy && outcome.event.eventType === undefined
+        ? outcome.event
+        : {
+            ...outcome.event,
+            eventType: outcome.event.eventType ?? resolvedIdentity.key,
+            provenance: outcome.event.provenance ?? resolvedIdentity.provenance,
+        };
+    const failures = [];
+    const allViews = options.views ?? [];
+    const unsafeViews = allViews.filter((view) => view.admission === "independent-unsafe");
+    const gatedViews = allViews.filter((view) => view.admission !== "independent-unsafe");
+    // G44: D1's atomic batch is followed by an independent join read-back
+    // before a source Tag DO can mark its obligation acknowledged.
+    if (store.readGlobalReceiptJoin !== undefined) {
+        let receipt;
+        observePostAdmission(options.durableHopObserver, message, source, {
+            stage: "post-record-delivery-global-receipt-readback",
+            boundary: "start",
+            outcome: "started",
+        });
+        try {
+            receipt = await store.readGlobalReceiptJoin(message);
+            if (receipt === undefined)
+                throw new Error("global receipt/membership join is absent");
+            observePostAdmission(options.durableHopObserver, message, source, {
+                stage: "post-record-delivery-global-receipt-readback",
+                boundary: "end",
+                outcome: "available",
+            });
+        }
+        catch (error) {
+            observePostAdmission(options.durableHopObserver, message, source, {
+                stage: "post-record-delivery-global-receipt-readback",
+                boundary: "end",
+                outcome: "error",
+            });
+            failures.push({ phase: "recordDelivery", class: "retryable-transient", error: errorText(error) });
+            return result(source, message, "stored", arrivedAt, false, [], failures, options.correlationId, startedAt);
+        }
+        if (options.afterGlobalReceipt !== undefined) {
+            try {
+                await options.afterGlobalReceipt({ message, receipt, arrivedAt, source });
+            }
+            catch (error) {
+                failures.push({ phase: "drain", class: "retryable-transient", error: errorText(error) });
+            }
+        }
+    }
+    // G60's exceptional unsafe lane is deliberately after recordDelivery and
+    // the exact global-receipt/source acknowledgement, but before the G44
+    // completeness gate. It writes only unsafe-window rows and kicks; it never
+    // advances a safe checkpoint. Ordinary views remain below the gate.
+    const unsafeViewBatch = await applyViewHandlers(unsafeViews, message, storedEvent, arrivedAt, source, options.durableHopObserver);
+    const viewResults = [...unsafeViewBatch.results];
+    failures.push(...unsafeViewBatch.failures);
+    if (options.beforeViews !== undefined) {
+        try {
+            await options.beforeViews({ message, event: storedEvent, arrivedAt, source });
+        }
+        catch (error) {
+            failures.push({ phase: "completeness", class: "retryable-transient", error: errorText(error) });
+            return result(source, message, "stored", arrivedAt, false, viewResults, failures, options.correlationId, startedAt);
+        }
+    }
+    // Normative step 3: detector only for a stored event.
+    let detectorApplied = false;
+    observePostAdmission(options.durableHopObserver, message, source, {
+        stage: "detector",
+        boundary: "start",
+        outcome: "started",
+    });
+    try {
+        const lagBound = await store.currentLagBound(message.serviceId, arrivedAt);
+        const detector = new InconsistencyDetector(store, new BindingExclusionLedgerClient(env.REPAIR_EXCLUSION_LOOKUP));
+        await detector.observe(message, arrivedAt, lagBound);
+        detectorApplied = true;
+        observePostAdmission(options.durableHopObserver, message, source, {
+            stage: "detector",
+            boundary: "end",
+            outcome: "applied",
+        });
+    }
+    catch (error) {
+        observePostAdmission(options.durableHopObserver, message, source, {
+            stage: "detector",
+            boundary: "end",
+            outcome: "error",
+        });
+        try {
+            await options.onDetectorFailure?.({ message, arrivedAt, source, error });
+        }
+        catch (healthError) {
+            failures.push({
+                phase: "detector",
+                class: "retryable-transient",
+                error: `detector_health_record_failed:${errorText(healthError)}`,
+            });
+        }
+        failures.push({ phase: "detector", class: "retryable-transient", error: errorText(error) });
+        // A detector failure makes global completeness unknown. Do not apply a
+        // view after that failure; an earlier version accumulated the error and
+        // then silently continued into views.apply.
+        return result(source, message, "stored", arrivedAt, false, [], failures, options.correlationId, startedAt);
+    }
+    const views = gatedViews;
+    const gatedViewBatch = await applyViewHandlers(views, message, storedEvent, arrivedAt, source, options.durableHopObserver);
+    viewResults.push(...gatedViewBatch.results);
+    failures.push(...gatedViewBatch.failures);
+    // Compatibility callers still receive their stored-only callback, but it
+    // is after all explicit view branches and before the drain trigger.
+    if (options.onStored !== undefined) {
+        try {
+            await options.onStored({ message, event: storedEvent, arrivedAt, source });
+        }
+        catch (error) {
+            failures.push({ phase: "view", class: "retryable-transient", viewId: "legacy-onStored", error: errorText(error) });
+        }
+    }
+    const preliminary = result(source, message, "stored", arrivedAt, detectorApplied, viewResults, failures, options.correlationId, startedAt);
+    // Normative step 5: the trigger is after all view branches.  The trigger is
+    // not itself a kick-target mutation; that mutation belongs to each view's
+    // single MV-D1 apply batch.
+    if (options.afterDelivery !== undefined && failures.every((failure) => failure.class === "duplicate-race")) {
+        try {
+            await options.afterDelivery({ message, event: storedEvent, arrivedAt, source, result: preliminary });
+        }
+        catch (error) {
+            failures.push({ phase: "drain", class: "retryable-transient", error: errorText(error) });
+        }
+    }
+    return result(source, message, "stored", arrivedAt, detectorApplied, viewResults, failures, options.correlationId, startedAt);
+}

package/dist/downstream/Doorbell.d.ts

@@ -0,0 +1,43 @@
+import type { DownstreamOutboxMessage } from "./types";
+export type DeliveryClass = "immediate-preferred" | "queued";
+export type DirectDoorbellDegradation = "fail-fast" | "queued-degraded";
+export type DirectDoorbellReceiverMode = "separate" | "self";
+export type DirectDoorbellFailureKind = "non-2xx" | "throw" | "timeout" | "cancel";
+/** Structural RPC surface used by a non-public Worker service binding. */
+export interface DownstreamDoorbellBinding {
+    deliver(message: DownstreamOutboxMessage): Promise<unknown>;
+}
+export interface DirectDoorbellDeploymentConfig {
+    readonly deliveryClass: DeliveryClass;
+    readonly domainViewDeliveryClasses?: Readonly<Record<string, DeliveryClass>>;
+    readonly enabled: boolean;
+    readonly allowedViews: readonly string[];
+    readonly maxServiceBindingInvocations: number;
+    readonly degradation: DirectDoorbellDegradation;
+    readonly receiverMode: DirectDoorbellReceiverMode;
+    readonly selfBindingPreflightProof: boolean;
+}
+export interface DirectDoorbellPreflightResult {
+    readonly status: "ready" | "queued-degraded" | "fail-fast" | "disabled";
+    readonly reason: string;
+    readonly estimatedInvocations: number;
+    readonly topologyInvocations: number;
+    readonly allowedViews: readonly string[];
+}
+export declare const MAX_SERVICE_BINDING_INVOCATIONS_PER_REQUEST = 32;
+export declare function classifyDirectDoorbellFailure(error: unknown): DirectDoorbellFailureKind;
+/** Resolve the domain-owned half of the two-layer opt-in. */
+export declare function readDomainDeliveryClass(env: Record<string, unknown>, fallback?: DeliveryClass): DeliveryClass;
+/** Resolve the deployment half of the two-layer opt-in without touching a V1 body. */
+export declare function readDirectDoorbellConfig(env: Record<string, unknown>, domainDeliveryClass?: DeliveryClass, domainViewDeliveryClasses?: Readonly<Record<string, DeliveryClass>>): DirectDoorbellDeploymentConfig;
+/**
+ * Deployment preflight is intentionally pure so CI can exercise it without a
+ * live Worker. The conservative topology count is retained even when the
+ * default separate receiver reduces actual per-request recursion risk.
+ */
+export declare function preflightDirectDoorbell(config: DirectDoorbellDeploymentConfig, configuredImmediateViewCount?: number): DirectDoorbellPreflightResult;
+export declare function selectDirectDoorbellViews<T extends {
+    readonly id: string;
+}>(views: readonly T[], config: DirectDoorbellDeploymentConfig): readonly T[];
+/** Stable bytes used by local and deployed byte-equality oracles. */
+export declare function downstreamEnvelopeBytes(message: DownstreamOutboxMessage): string;

package/dist/downstream/Doorbell.js

@@ -0,0 +1,137 @@
+export const MAX_SERVICE_BINDING_INVOCATIONS_PER_REQUEST = 32;
+export function classifyDirectDoorbellFailure(error) {
+    const structured = typeof error === "object" && error !== null
+        ? error
+        : {};
+    const status = typeof structured.status === "number"
+        ? structured.status
+        : typeof structured.statusCode === "number" ? structured.statusCode : undefined;
+    if (status !== undefined && (status < 200 || status >= 300))
+        return "non-2xx";
+    const value = String(error).toLowerCase();
+    const code = `${String(structured.code ?? "")} ${String(structured.name ?? "")}`.toLowerCase();
+    if (value.includes("timeout") || value.includes("deadline") || code.includes("timeout"))
+        return "timeout";
+    if (value.includes("cancel") || value.includes("abort") || code.includes("abort"))
+        return "cancel";
+    if (value.includes("non-2xx") || value.includes("http 4") || value.includes("http 5") || value.includes("status 4") || value.includes("status 5"))
+        return "non-2xx";
+    return "throw";
+}
+function envString(env, key) {
+    const value = env[key];
+    return typeof value === "string" ? value : undefined;
+}
+function parseBoolean(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (value === "true")
+        return true;
+    if (value === "false")
+        return false;
+    throw new Error(`${value} is not a boolean deployment setting`);
+}
+function parsePositiveInteger(value, fallback, name) {
+    if (value === undefined || value.length === 0)
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed < 1)
+        throw new Error(`${name} must be a positive safe integer`);
+    return parsed;
+}
+function parseAllowedViews(value) {
+    if (value === undefined || value.trim().length === 0)
+        return [];
+    return [...new Set(value.split(",").map((entry) => entry.trim()).filter((entry) => entry.length > 0))];
+}
+function parseDeliveryClass(value, fallback) {
+    if (value === undefined || value.length === 0)
+        return fallback;
+    if (value === "queued" || value === "immediate-preferred")
+        return value;
+    throw new Error("DOMAIN_DELIVERY_CLASS must be queued or immediate-preferred");
+}
+/** Resolve the domain-owned half of the two-layer opt-in. */
+export function readDomainDeliveryClass(env, fallback = "queued") {
+    return parseDeliveryClass(envString(env, "DOMAIN_DELIVERY_CLASS"), fallback);
+}
+/** Resolve the deployment half of the two-layer opt-in without touching a V1 body. */
+export function readDirectDoorbellConfig(env, domainDeliveryClass, domainViewDeliveryClasses) {
+    // The deployment half starts at DIRECT_DOORBELL. A deployment variable must
+    // not silently override the domain-owned delivery class.
+    const deliveryClass = domainDeliveryClass ?? readDomainDeliveryClass(env);
+    const receiverModeValue = envString(env, "DIRECT_DOORBELL_RECEIVER_MODE") ?? "separate";
+    if (receiverModeValue !== "separate" && receiverModeValue !== "self") {
+        throw new Error("DIRECT_DOORBELL_RECEIVER_MODE must be separate or self");
+    }
+    const degradationValue = envString(env, "DIRECT_DOORBELL_DEGRADATION") ?? "fail-fast";
+    if (degradationValue !== "fail-fast" && degradationValue !== "queued-degraded") {
+        throw new Error("DIRECT_DOORBELL_DEGRADATION must be fail-fast or queued-degraded");
+    }
+    return {
+        deliveryClass,
+        ...(domainViewDeliveryClasses === undefined ? {} : { domainViewDeliveryClasses }),
+        enabled: parseBoolean(envString(env, "DIRECT_DOORBELL"), false),
+        allowedViews: parseAllowedViews(envString(env, "DIRECT_DOORBELL_ALLOWED_VIEWS")),
+        maxServiceBindingInvocations: parsePositiveInteger(envString(env, "DIRECT_DOORBELL_MAX_INVOCATIONS"), MAX_SERVICE_BINDING_INVOCATIONS_PER_REQUEST, "DIRECT_DOORBELL_MAX_INVOCATIONS"),
+        degradation: degradationValue,
+        receiverMode: receiverModeValue,
+        selfBindingPreflightProof: parseBoolean(envString(env, "DIRECT_DOORBELL_SELF_BINDING_PROOF"), false),
+    };
+}
+/**
+ * Deployment preflight is intentionally pure so CI can exercise it without a
+ * live Worker. The conservative topology count is retained even when the
+ * default separate receiver reduces actual per-request recursion risk.
+ */
+export function preflightDirectDoorbell(config, configuredImmediateViewCount = config.allowedViews.length) {
+    const topologyInvocations = Math.max(1, configuredImmediateViewCount + 1);
+    const estimatedInvocations = topologyInvocations;
+    const degrade = (reason) => ({
+        status: config.degradation === "queued-degraded" ? "queued-degraded" : "fail-fast",
+        reason,
+        estimatedInvocations,
+        topologyInvocations,
+        allowedViews: config.allowedViews,
+    });
+    if (config.deliveryClass === "queued") {
+        return {
+            status: "disabled",
+            reason: "domain_delivery_class_queued",
+            estimatedInvocations,
+            topologyInvocations,
+            allowedViews: config.allowedViews,
+        };
+    }
+    if (!config.enabled)
+        return degrade("deployment_direct_doorbell_disabled");
+    if (config.allowedViews.length === 0)
+        return degrade("immediate_preferred_requires_allowed_views");
+    if (config.maxServiceBindingInvocations > MAX_SERVICE_BINDING_INVOCATIONS_PER_REQUEST) {
+        return degrade("configured_service_binding_budget_exceeds_platform_limit");
+    }
+    if (topologyInvocations > config.maxServiceBindingInvocations || topologyInvocations > MAX_SERVICE_BINDING_INVOCATIONS_PER_REQUEST) {
+        return degrade("configured_immediate_view_topology_exceeds_service_binding_budget");
+    }
+    if (config.receiverMode === "self" && !config.selfBindingPreflightProof) {
+        return degrade("self_binding_requires_recursion_and_route_privacy_preflight_proof");
+    }
+    return {
+        status: "ready",
+        reason: "direct_doorbell_capability_ready",
+        estimatedInvocations,
+        topologyInvocations,
+        allowedViews: config.allowedViews,
+    };
+}
+export function selectDirectDoorbellViews(views, config) {
+    if (config.deliveryClass !== "immediate-preferred" || !config.enabled)
+        return [];
+    const allowed = new Set(config.allowedViews);
+    return views.filter((view) => allowed.has(view.id) &&
+        (config.domainViewDeliveryClasses?.[view.id] ?? config.deliveryClass) === "immediate-preferred");
+}
+/** Stable bytes used by local and deployed byte-equality oracles. */
+export function downstreamEnvelopeBytes(message) {
+    return JSON.stringify(message);
+}

package/dist/downstream/DownstreamAdapter.d.ts

@@ -0,0 +1,52 @@
+import { type DeliveryCoreOptions, type DeliveryCoreResult } from "./DeliveryCore";
+import { type DownstreamOutboxMessage } from "./types";
+import { type ServiceIdentityProvider } from "../service/ServiceIdentityProvider";
+export interface DownstreamAdapterEnv {
+    POSTGRES_URL?: string;
+    HYPERDRIVE?: Hyperdrive;
+    /** Optional explicit D1 provider binding; Postgres remains the default. */
+    D1?: D1Database;
+    REPAIR_EXCLUSION_LOOKUP?: Fetcher;
+    BOOTSTRAP?: DurableObjectNamespace;
+    /** Present on the primary/receiver runtime so G44 can acknowledge source. */
+    TAG?: DurableObjectNamespace;
+    /** A receiver service-binding entrypoint must never silently skip admission. */
+    G38_DOORBELL_DELIVERY_ROLE?: string;
+    SDT_SERVICE_ID?: string;
+}
+export interface AfterStoredQueueDeliveryInput {
+    readonly message: DownstreamOutboxMessage;
+    readonly result: DeliveryCoreResult;
+}
+/**
+ * Queue-only hooks run after the shared core has durably recorded the event.
+ * They are deliberately separate from DeliveryCore.afterDelivery: that hook
+ * is a post-view hook and is not reached when the G44 gate is BLOCK/UNSETTLED.
+ */
+export interface DownstreamAdapterOptions extends DeliveryCoreOptions {
+    /**
+     * Notification only. The Queue handler never awaits this callback: the
+     * callback must register any work with the active ExecutionContext.
+     */
+    readonly afterStoredQueueDelivery?: (input: AfterStoredQueueDeliveryInput) => void;
+    /** Invocation owner for bounded G69 diagnostic retention. */
+    readonly g69AdmissionAttemptWaitUntil?: (promise: Promise<void>) => void;
+}
+export type AdapterOptions = DownstreamAdapterOptions;
+/**
+ * Processes one direct delivery through the shared core. The caller receives a
+ * typed result; this function never acknowledges, retries, or marks an
+ * outbox row.
+ */
+export declare function processDownstreamDoorbell(message: unknown, env: DownstreamAdapterEnv, options?: AdapterOptions): Promise<DeliveryCoreResult>;
+/** Processes one Queue delivery without exposing Queue state to the core. */
+export declare function processDownstreamDelivery(message: unknown, env: DownstreamAdapterEnv, options?: AdapterOptions): Promise<void>;
+/**
+ * Queue policy is deliberately limited to the wrapper: the shared core
+ * returns a disposition, and this is the only place that calls ack/retry.
+ */
+export declare function handleDownstreamQueue(batch: MessageBatch<unknown>, env: DownstreamAdapterEnv, options?: AdapterOptions): Promise<void>;
+/** A scheduled/operator invocation can evaluate a stable pending record without new traffic. */
+export declare function stabilizeDownstream(env: DownstreamAdapterEnv, options?: AdapterOptions, serviceId?: string, serviceIdentityProvider?: ServiceIdentityProvider): Promise<void>;
+export { processDeliveryCore } from "./DeliveryCore";
+export type { DeliveryCoreEnvironment, DeliveryCoreFailure, DeliveryCoreOptions, DeliveryCoreResult, DeliverySource, DeliveryViewApplyResult, DeliveryViewFailureClass, DeliveryViewHandler, DeliveryViewInput, DeliveryViewResult, } from "./DeliveryCore";