@sekiban/dcb-runtime 0.2.0

package/dist/downstream/DownstreamAdapter.js

@@ -0,0 +1,299 @@
+import { BindingExclusionLedgerClient } from "./ExclusionLookup";
+import { InconsistencyDetector } from "./InconsistencyDetector";
+import { processDeliveryCore, } from "./DeliveryCore";
+import { isDownstreamOutboxMessage, systemPipelineClock, } from "./types";
+import { GlobalCompletenessReconciler, globalReceiptAcknowledgement } from "../completeness/GlobalCompletenessReconciler";
+import { observeG60PostAdmission } from "../diagnostics/G60DurableHop";
+import { scopeIdFor } from "../scope/ScopeName";
+import { envServiceIdentity, requireServiceIdentity } from "../service/ServiceIdentityProvider";
+function observeSourceSubstep(observer, input) {
+    observeG60PostAdmission(observer, {
+        stage: "source-tag-acknowledgement",
+        boundary: input.boundary,
+        outcome: input.outcome,
+        serviceId: input.message.serviceId,
+        eventId: input.message.eventId,
+        suid: input.message.suid,
+        attemptId: input.message.attemptId,
+        partitionTag: input.message.tag,
+        transport: input.source,
+        observedAt: Date.now(),
+    });
+}
+function sourceAcknowledgementOptions(env, options) {
+    // D1 itself is the G44 global-array authority. Do not add a rollout flag:
+    // this is an in-place development schema, not a mixed-version protocol.
+    const hasG44Authority = env.D1 !== undefined && env.TAG !== undefined;
+    const sourceAcknowledgement = options.afterGlobalReceipt !== undefined || !hasG44Authority
+        ? options.afterGlobalReceipt
+        : async ({ message, receipt, arrivedAt }) => {
+            const tag = env.TAG.get(scopeIdFor(env.TAG, {
+                serviceId: message.serviceId,
+                doClass: "tag",
+                identity: message.tag,
+            }));
+            const url = new URL("https://downstream.internal/outbox/mark-delivered");
+            url.searchParams.set("__tag", message.tag);
+            url.searchParams.set("__serviceId", message.serviceId);
+            const response = await tag.fetch(new Request(url, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify(globalReceiptAcknowledgement(message, receipt.receivedAt || arrivedAt)),
+            }));
+            if (!response.ok)
+                throw new Error(`source_outbox_receipt_ack_failed:${response.status}`);
+        };
+    const coverage = hasG44Authority
+        ? async ({ message, event, arrivedAt, source }) => {
+            let completed = false;
+            await options.beforeViews?.({ message, event, arrivedAt, source });
+            observeG60PostAdmission(options.durableHopObserver, {
+                stage: "completeness-coverage",
+                boundary: "start",
+                outcome: "started",
+                serviceId: message.serviceId,
+                eventId: message.eventId,
+                suid: message.suid,
+                attemptId: message.attemptId,
+                partitionTag: message.tag,
+                transport: source,
+                observedAt: Date.now(),
+            });
+            try {
+                const decision = await new GlobalCompletenessReconciler(env.D1, env.TAG).coverageForObligation(message.serviceId, message.tag, message.completeness.obligationSequence, arrivedAt);
+                observeG60PostAdmission(options.durableHopObserver, {
+                    stage: "completeness-coverage",
+                    boundary: "end",
+                    outcome: decision.kind,
+                    serviceId: message.serviceId,
+                    eventId: message.eventId,
+                    suid: message.suid,
+                    attemptId: message.attemptId,
+                    partitionTag: message.tag,
+                    transport: source,
+                    observedAt: Date.now(),
+                });
+                completed = true;
+                if (decision.kind !== "SETTLED") {
+                    throw new Error(`global_completeness_${decision.kind}:${decision.health.status}`);
+                }
+            }
+            catch (error) {
+                if (!completed) {
+                    observeG60PostAdmission(options.durableHopObserver, {
+                        stage: "completeness-coverage",
+                        boundary: "end",
+                        outcome: "error",
+                        serviceId: message.serviceId,
+                        eventId: message.eventId,
+                        suid: message.suid,
+                        attemptId: message.attemptId,
+                        partitionTag: message.tag,
+                        transport: source,
+                        observedAt: Date.now(),
+                    });
+                }
+                throw error;
+            }
+        }
+        : options.beforeViews;
+    const observedSourceAcknowledgement = sourceAcknowledgement === undefined
+        ? undefined
+        : async (input) => {
+            observeSourceSubstep(options.durableHopObserver, { ...input, boundary: "start", outcome: "started" });
+            try {
+                await sourceAcknowledgement(input);
+                observeSourceSubstep(options.durableHopObserver, { ...input, boundary: "end", outcome: "acknowledged" });
+            }
+            catch (error) {
+                observeSourceSubstep(options.durableHopObserver, { ...input, boundary: "end", outcome: "error" });
+                throw error;
+            }
+        };
+    const detectorFailure = hasG44Authority
+        ? async ({ message, arrivedAt, error, source }) => {
+            await options.onDetectorFailure?.({ message, arrivedAt, error, source });
+            await new GlobalCompletenessReconciler(env.D1, env.TAG).recordDetectorFailure(message.serviceId, error, arrivedAt);
+        }
+        : options.onDetectorFailure;
+    return {
+        ...options,
+        ...(observedSourceAcknowledgement === undefined ? {} : { afterGlobalReceipt: observedSourceAcknowledgement }),
+        ...(coverage === undefined ? {} : { beforeViews: coverage }),
+        ...(detectorFailure === undefined ? {} : { onDetectorFailure: detectorFailure }),
+    };
+}
+function sharedStore(env, provider) {
+    // The provider creates a request-scoped client. Never retain a client across
+    // Queue or scheduled invocations, or a later handler can attempt I/O on a
+    // stream owned by an earlier request.
+    return provider.create(env);
+}
+async function admitBootstrapRoute(env, serviceId, route) {
+    if (env.BOOTSTRAP === undefined) {
+        if (env.G38_DOORBELL_DELIVERY_ROLE === "receiver") {
+            const error = new Error(`bootstrap_route_binding_missing:${route}`);
+            error.name = "BootstrapRouteBindingMissingError";
+            throw error;
+        }
+        return;
+    }
+    const url = new URL("https://downstream.internal/route/check");
+    url.searchParams.set("__serviceId", serviceId);
+    const admitted = await env.BOOTSTRAP.get(scopeIdFor(env.BOOTSTRAP, {
+        serviceId,
+        doClass: "bootstrap",
+        identity: "coordinator",
+    })).fetch(new Request(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ route }),
+    }));
+    if (!admitted.ok)
+        throw new Error(`bootstrap_route_rejected:${route}`);
+}
+async function withStore(env, options, operation) {
+    if (options.store === undefined && options.storeProvider === undefined) {
+        throw new Error("A downstream store provider is not configured");
+    }
+    const store = options.store ?? sharedStore(env, options.storeProvider);
+    await store.initialize();
+    return operation(store, options.clock ?? systemPipelineClock);
+}
+/**
+ * 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 async function processDownstreamDoorbell(message, env, options = {}) {
+    if (!isDownstreamOutboxMessage(message)) {
+        throw new Error("Doorbell contained an invalid outbox message");
+    }
+    options.durableHopObserver?.observe({
+        stage: "consumer-invocation-started",
+        serviceId: message.serviceId,
+        eventId: message.eventId,
+        suid: message.suid,
+        attemptId: message.attemptId,
+        partitionTag: message.tag,
+        transport: "fast",
+        observedAt: Date.now(),
+    });
+    await admitBootstrapRoute(env, message.serviceId, "fast");
+    return processDeliveryCore(message, "fast", env, sourceAcknowledgementOptions(env, options));
+}
+/** Processes one Queue delivery without exposing Queue state to the core. */
+export async function processDownstreamDelivery(message, env, options = {}) {
+    if (!isDownstreamOutboxMessage(message)) {
+        throw new Error("Downstream Queue contained an invalid outbox message");
+    }
+    options.durableHopObserver?.observe({
+        stage: "consumer-invocation-started",
+        serviceId: message.serviceId,
+        eventId: message.eventId,
+        suid: message.suid,
+        attemptId: message.attemptId,
+        partitionTag: message.tag,
+        transport: "queue",
+        observedAt: Date.now(),
+    });
+    await admitBootstrapRoute(env, message.serviceId, "queue");
+    const outcome = await processDeliveryCore(message, "queue", env, sourceAcknowledgementOptions(env, options));
+    if (outcome.queueDisposition !== "ack") {
+        throw new Error(`downstream_delivery_retry:${outcome.correlationId}`);
+    }
+}
+/**
+ * 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 async function handleDownstreamQueue(batch, env, options = {}) {
+    // Validate each Queue ingress before acquiring a provider. In particular a
+    // non-G32 SUID must not even initialize the downstream store; this keeps
+    // the cutover's abort-before-write guarantee observable for Queue traffic.
+    const valid = [];
+    for (const queued of batch.messages) {
+        if (!isDownstreamOutboxMessage(queued.body)) {
+            console.warn("downstream_queue_delivery", { disposition: "retry-to-dlq" });
+            queued.retry();
+            continue;
+        }
+        valid.push(queued);
+    }
+    if (valid.length === 0)
+        return;
+    await withStore(env, options, async (store, clock) => {
+        for (const queued of valid) {
+            try {
+                options.durableHopObserver?.observe({
+                    stage: "consumer-invocation-started",
+                    serviceId: queued.body.serviceId,
+                    eventId: queued.body.eventId,
+                    suid: queued.body.suid,
+                    attemptId: queued.body.attemptId,
+                    partitionTag: queued.body.tag,
+                    transport: "queue",
+                    observedAt: Date.now(),
+                });
+                await admitBootstrapRoute(env, queued.body.serviceId, "queue");
+                const outcome = await processDeliveryCore(queued.body, "queue", env, {
+                    ...sourceAcknowledgementOptions(env, options),
+                    store,
+                    clock,
+                    g69AdmissionAttempt: {
+                        queueMessageId: queued.id,
+                        waitUntil: options.g69AdmissionAttemptWaitUntil,
+                    },
+                });
+                console.log("downstream_queue_delivery", {
+                    correlationId: outcome.correlationId,
+                    coreDurationMs: outcome.coreDurationMs,
+                    viewDurationsMs: outcome.views.map((view) => ({ id: view.id, durationMs: view.durationMs, status: view.status })),
+                    disposition: outcome.queueDisposition,
+                    failures: outcome.failures.map((failure) => ({ phase: failure.phase, class: failure.class, viewId: failure.viewId, error: failure.error })),
+                });
+                if (outcome.queueDisposition === "ack")
+                    queued.ack();
+                else if (outcome.queueDisposition === "retry-once")
+                    queued.retry();
+                else
+                    queued.retry();
+                // A committed event still needs an event-driven safe-lane kick when
+                // G44 deliberately holds the ordinary views. A stored recordDelivery
+                // result includes idempotent Queue replays; each successful batch is
+                // eligible, while a recordDelivery failure is not. The hook is
+                // notification-only: it is never awaited, so its caller must
+                // register work through waitUntil and return.
+                if (outcome.outcome === "stored" && !outcome.failures.some((failure) => failure.phase === "recordDelivery")) {
+                    try {
+                        options.afterStoredQueueDelivery?.({ message: queued.body, result: outcome });
+                    }
+                    catch (error) {
+                        // A lost kick is recoverable by cron and must never change the
+                        // durable Queue ack/retry decision already made above.
+                        console.warn("safe_lane_kick", {
+                            status: "failed-to-schedule",
+                            error: error instanceof Error ? error.message : String(error),
+                            serviceId: queued.body.serviceId,
+                            eventId: queued.body.eventId,
+                            attemptId: queued.body.attemptId,
+                        });
+                    }
+                }
+            }
+            catch {
+                console.warn("downstream_queue_delivery", { disposition: "retry-to-dlq" });
+                queued.retry();
+            }
+        }
+    });
+}
+/** A scheduled/operator invocation can evaluate a stable pending record without new traffic. */
+export async function stabilizeDownstream(env, options = {}, serviceId, serviceIdentityProvider) {
+    await admitBootstrapRoute(env, serviceId ?? requireServiceIdentity(serviceIdentityProvider ?? envServiceIdentity(env)), "scheduled");
+    await withStore(env, options, async (store, clock) => {
+        const detector = new InconsistencyDetector(store, new BindingExclusionLedgerClient(env.REPAIR_EXCLUSION_LOOKUP));
+        await detector.stabilize(clock, serviceId);
+    });
+}
+export { processDeliveryCore } from "./DeliveryCore";

package/dist/downstream/ExclusionLookup.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Provider-internal port used by SDT-G6 Branch B.  It is intentionally a
+ * narrow binding client, not a Queue/Cosmos/Postgres adapter.
+ */
+export interface ExclusionLookupInput {
+    attemptId: string;
+    tag: string;
+    eventId: string;
+    suid: string;
+    actor: string;
+    repairEpoch: number;
+}
+export interface ExclusionLookupPort {
+    recordExclusion(input: ExclusionLookupInput): Promise<void>;
+}
+export interface ExclusionLedgerLookupInput {
+    serviceId: string;
+    attemptId: string;
+    tag: string;
+    eventId: string;
+    suid: string;
+}
+/**
+ * Reads the same provider-internal exclusion ledger that SDT-G6 writes. A
+ * missing binding is an unknown path, never an invented exclusion.
+ */
+export declare class BindingExclusionLedgerClient {
+    private readonly binding;
+    constructor(binding: Fetcher | undefined);
+    isExcludedAudited(input: ExclusionLedgerLookupInput): Promise<boolean>;
+}
+export declare class BindingExclusionLookupClient implements ExclusionLookupPort {
+    private readonly binding;
+    constructor(binding: Fetcher | undefined);
+    recordExclusion(input: ExclusionLookupInput): Promise<void>;
+}

package/dist/downstream/ExclusionLookup.js

@@ -0,0 +1,50 @@
+/**
+ * Reads the same provider-internal exclusion ledger that SDT-G6 writes. A
+ * missing binding is an unknown path, never an invented exclusion.
+ */
+export class BindingExclusionLedgerClient {
+    binding;
+    constructor(binding) {
+        this.binding = binding;
+    }
+    async isExcludedAudited(input) {
+        if (this.binding === undefined) {
+            return false;
+        }
+        const response = await this.binding.fetch("https://repair-exclusion.internal/exclusions/lookup", {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(input),
+        });
+        if (response.status === 404) {
+            return false;
+        }
+        if (!response.ok) {
+            throw new Error(`Repair exclusion lookup rejected detector with ${response.status}`);
+        }
+        const body = await response.json();
+        if (typeof body !== "object" || body === null || Array.isArray(body)) {
+            throw new Error("Repair exclusion lookup returned an invalid response");
+        }
+        return body.classification === "EXCLUDED_AUDITED";
+    }
+}
+export class BindingExclusionLookupClient {
+    binding;
+    constructor(binding) {
+        this.binding = binding;
+    }
+    async recordExclusion(input) {
+        if (this.binding === undefined) {
+            throw new Error("Repair exclusion lookup binding is not configured");
+        }
+        const response = await this.binding.fetch("https://repair-exclusion.internal/exclusions", {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(input),
+        });
+        if (!response.ok) {
+            throw new Error(`Repair exclusion lookup rejected Branch B with ${response.status}`);
+        }
+    }
+}

package/dist/downstream/InconsistencyDetector.d.ts

@@ -0,0 +1,27 @@
+import type { DownstreamOutboxMessage, PipelineClock } from "./types";
+import type { DetectorStore } from "../store/types";
+export declare const MIN_STABILITY_HORIZON_MS = 20000;
+export interface ExclusionLedgerInput {
+    serviceId: string;
+    attemptId: string;
+    eventId: string;
+    suid: string;
+    tag: string;
+}
+export interface ExclusionLedgerPort {
+    isExcludedAudited(input: ExclusionLedgerInput): Promise<boolean>;
+}
+/**
+ * This component owns only pending/finding facts. Event rows are written by
+ * the adapter before this detector is invoked and are intentionally absent
+ * from DetectorStore.
+ */
+export declare class InconsistencyDetector {
+    private readonly store;
+    private readonly exclusions;
+    constructor(store: DetectorStore, exclusions: ExclusionLedgerPort);
+    observe(message: DownstreamOutboxMessage, arrivedAt: number, dynamicLagBoundMs: number): Promise<void>;
+    stabilize(clock: PipelineClock, serviceId?: string): Promise<void>;
+    private classifyKnownExclusions;
+    private resolveLateArrivals;
+}

package/dist/downstream/InconsistencyDetector.js

@@ -0,0 +1,82 @@
+export const MIN_STABILITY_HORIZON_MS = 20_000;
+function sortedUnique(values) {
+    return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+function missingPaths(pending) {
+    const observed = new Set(pending.observedPaths);
+    return pending.expectedPaths.filter((path) => !observed.has(path));
+}
+function finding(pending, path, classification, observedAt) {
+    return {
+        serviceId: pending.serviceId,
+        eventId: pending.eventId,
+        path,
+        classification,
+        firstObservedAt: pending.firstObservedAt,
+        lagBoundMs: pending.lagBoundMs,
+        observedAt,
+    };
+}
+/**
+ * This component owns only pending/finding facts. Event rows are written by
+ * the adapter before this detector is invoked and are intentionally absent
+ * from DetectorStore.
+ */
+export class InconsistencyDetector {
+    store;
+    exclusions;
+    constructor(store, exclusions) {
+        this.store = store;
+        this.exclusions = exclusions;
+    }
+    async observe(message, arrivedAt, dynamicLagBoundMs) {
+        const pending = await this.store.upsertPending({ ...message, eventTags: sortedUnique(message.eventTags) }, arrivedAt, Math.max(MIN_STABILITY_HORIZON_MS, dynamicLagBoundMs));
+        const excluded = await this.classifyKnownExclusions(pending, arrivedAt);
+        await this.resolveLateArrivals(pending, arrivedAt, excluded);
+    }
+    async stabilize(clock, serviceId) {
+        const now = clock.now();
+        for (const pending of await this.store.listPending(serviceId)) {
+            const excluded = await this.classifyKnownExclusions(pending, now);
+            const missing = missingPaths(pending);
+            if (missing.length === 0) {
+                await this.resolveLateArrivals(pending, now, excluded);
+                continue;
+            }
+            if (now < pending.firstObservedAt + Math.max(MIN_STABILITY_HORIZON_MS, pending.lagBoundMs)) {
+                continue;
+            }
+            for (const path of missing) {
+                if (!excluded.has(path)) {
+                    await this.store.appendFinding(finding(pending, path, "MISSING_STABLE", now));
+                }
+            }
+        }
+    }
+    async classifyKnownExclusions(pending, observedAt) {
+        const excluded = new Set();
+        for (const path of missingPaths(pending)) {
+            if (await this.exclusions.isExcludedAudited({
+                serviceId: pending.serviceId,
+                attemptId: pending.attemptId,
+                eventId: pending.eventId,
+                suid: pending.suid,
+                tag: path,
+            })) {
+                excluded.add(path);
+                await this.store.appendFinding(finding(pending, path, "EXCLUDED_AUDITED", observedAt));
+            }
+        }
+        return excluded;
+    }
+    async resolveLateArrivals(pending, observedAt, excluded) {
+        if (missingPaths(pending).length !== 0) {
+            return;
+        }
+        for (const path of pending.expectedPaths) {
+            if (!excluded.has(path) && await this.store.hasFinding(pending.serviceId, pending.eventId, path, "MISSING_STABLE")) {
+                await this.store.appendFinding(finding(pending, path, "RESOLVED_LATE", observedAt));
+            }
+        }
+    }
+}

package/dist/downstream/OutboxDrain.d.ts

@@ -0,0 +1,35 @@
+import { type DownstreamOutboxMessage, type PipelineClock } from "./types";
+import type { G60DurableHopObserver } from "../diagnostics/G60DurableHop";
+export interface OutboxDrainEnv {
+    TAG: DurableObjectNamespace;
+    DOWNSTREAM_QUEUE: Queue<DownstreamOutboxMessage>;
+}
+export interface DrainTagInput {
+    serviceId: string;
+    tag: string;
+}
+/**
+ * The ordinary runtime predates the G44 D1 global-array authority and keeps
+ * its historical transport acknowledgement for its private operational
+ * endpoint.  The Cloudflare-only runtime opts into `global-receipt` below;
+ * that branch is deliberately not selected by a rollout flag.
+ */
+export interface OutboxDrainOptions {
+    readonly acknowledgement?: "transport" | "global-receipt";
+    /** G60 observation is scheduled by the active Worker context. */
+    readonly durableHopObserver?: G60DurableHopObserver;
+}
+export interface DrainResult {
+    serviceId: string;
+    tag: string;
+    delivered: number;
+}
+/**
+ * A row gains its durable enqueuedAt fact before the first send. Queue send
+ * is only transport acceptance: G44 deliberately leaves the source pending
+ * until the receiver has atomically written and read back the global receipt
+ * plus committed-membership join. An interruption therefore replays safely.
+ */
+export declare function drainTagOutbox(input: DrainTagInput, env: OutboxDrainEnv, clock?: PipelineClock, options?: OutboxDrainOptions): Promise<DrainResult>;
+/** Internal operational trigger; it does not alter any V1 public endpoint. */
+export declare function handleOutboxDrainRequest(request: Request, env: OutboxDrainEnv, options?: OutboxDrainOptions): Promise<Response>;

package/dist/downstream/OutboxDrain.js

@@ -0,0 +1,126 @@
+import { outboxIdentity, systemPipelineClock } from "./types";
+import { scopeIdFor } from "../scope/ScopeName";
+function json(body, status = 200) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { "content-type": "application/json; charset=utf-8" },
+    });
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isDrainRequest(value) {
+    return isObject(value) && isNonEmptyString(value.serviceId) && Array.isArray(value.tags) &&
+        value.tags.length > 0 && value.tags.every(isNonEmptyString) && new Set(value.tags).size === value.tags.length;
+}
+function identity(message) {
+    return {
+        attemptId: message.attemptId,
+        eventId: message.eventId,
+        suid: message.suid,
+        allocatorLineageId: message.allocatorLineageId,
+        payload: message.payload,
+        eventType: message.eventType,
+        provenance: message.provenance,
+        timestamp: message.timestamp,
+        causationId: message.causationId,
+        correlationId: message.correlationId,
+        executedUser: message.executedUser,
+        // Legacy transport acknowledgement still has to present the full G43
+        // source fact because TagDurableObject rejects a lossy identity.
+        completeness: message.completeness,
+        enqueuedAt: message.enqueuedAt,
+        deliveredAt: null,
+    };
+}
+async function tagPost(env, input, path, body) {
+    const stub = env.TAG.get(scopeIdFor(env.TAG, {
+        serviceId: input.serviceId,
+        doClass: "tag",
+        identity: input.tag,
+    }));
+    const url = new URL(`https://outbox-drain.internal${path}`);
+    url.searchParams.set("__tag", input.tag);
+    url.searchParams.set("__serviceId", input.serviceId);
+    return stub.fetch(new Request(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+    }));
+}
+/**
+ * A row gains its durable enqueuedAt fact before the first send. Queue send
+ * is only transport acceptance: G44 deliberately leaves the source pending
+ * until the receiver has atomically written and read back the global receipt
+ * plus committed-membership join. An interruption therefore replays safely.
+ */
+export async function drainTagOutbox(input, env, clock = systemPipelineClock, options = {}) {
+    // Queue-triggered draining is an explicit retry attempt. The source's
+    // `next_attempt_at` controls automatic alarm wakes, but must not suppress a
+    // caller that is already actively draining the durable obligation.
+    const pending = await tagPost(env, input, "/outbox/pending", { nowMs: clock.now(), force: true });
+    if (!pending.ok) {
+        throw new Error(`Tag outbox pending read failed with ${pending.status}`);
+    }
+    const body = await pending.json();
+    let delivered = 0;
+    for (const row of body.rows) {
+        await env.DOWNSTREAM_QUEUE.send(row, { contentType: "json" });
+        options.durableHopObserver?.observe({
+            stage: "queue-send-returned",
+            serviceId: input.serviceId,
+            eventId: row.eventId,
+            suid: row.suid,
+            attemptId: row.attemptId,
+            partitionTag: input.tag,
+            transport: "queue",
+            observedAt: clock.now(),
+        });
+        if (options.acknowledgement === "global-receipt") {
+            // G44 Queue handoff is only transport acceptance.  The D1 receiver
+            // performs the source acknowledgement after its atomic event,
+            // membership, and receipt join has been read back.
+            delivered += 1;
+            continue;
+        }
+        const mark = await tagPost(env, input, "/outbox/mark-delivered", {
+            deliveries: [identity(row)],
+            nowMs: clock.now(),
+        });
+        if (!mark.ok) {
+            throw new Error(`Tag outbox delivered mark failed with ${mark.status} for ${outboxIdentity(row)}`);
+        }
+        const markBody = await mark.json();
+        delivered += markBody.marked;
+    }
+    return { ...input, delivered };
+}
+/** Internal operational trigger; it does not alter any V1 public endpoint. */
+export async function handleOutboxDrainRequest(request, env, options = {}) {
+    let body;
+    try {
+        body = await request.json();
+    }
+    catch {
+        return json({ error: "Outbox drain request must be JSON", code: "invalid_outbox_drain_request" }, 400);
+    }
+    if (!isDrainRequest(body)) {
+        return json({ error: "serviceId and unique non-empty tags are required", code: "invalid_outbox_drain_request" }, 400);
+    }
+    try {
+        const results = [];
+        for (const tag of body.tags) {
+            results.push(await drainTagOutbox({ serviceId: body.serviceId, tag }, env, systemPipelineClock, options));
+        }
+        return json({ results });
+    }
+    catch (error) {
+        return json({
+            error: error instanceof Error ? error.message : "Outbox drain failed",
+            code: "outbox_drain_failed",
+        }, 503);
+    }
+}