@sekiban/dcb-runtime 0.2.0

package/dist/tag/TagDurableObject.d.ts

@@ -0,0 +1,286 @@
+import { type TagEvent, type G43TagStateIncrementalPage, type G43TagStateIncrementalRequest } from "./types";
+import type { DownstreamOutboxMessage } from "../downstream/types";
+import type { SourceObligationPage } from "../completeness/types";
+import { type DownstreamDoorbellBinding } from "../downstream/Doorbell";
+import { type NativeTracing } from "../trace/CommitTrace";
+import { type G43SqlMeasurementSnapshot } from "./TagSqlMeasurement";
+declare const MAX_EPOCH: number;
+/**
+ * G65 bounds derived writes, not the durable Tag commit.  The value is short
+ * enough to keep the commit root near the G52 baseline while still allowing a
+ * healthy same-colo D1/doorbell attempt to complete before the response.
+ */
+export declare const G65_DERIVED_WRITE_BUDGET_MS = 300;
+/**
+ * SDT-G98: first-append source-partition registration is on the commit path
+ * when G44 D1 is configured, but cold remote D1 registration routinely needs
+ * more than the doorbell/admission 300 ms budget. Keep registration on its own
+ * measured ceiling so multi-tag first-touch does not invent partial_write.
+ * Chosen from 2026-09-17 live cold-reserve observation (300 ms shared budget
+ * timed out registration) plus margin; refined against cold-loop evidence.
+ */
+export declare const G65_SOURCE_REGISTRATION_BUDGET_MS = 1500;
+export declare const G65_SOURCE_REGISTRATION_MAX_ATTEMPTS = 3;
+export declare const G65_SOURCE_REGISTRATION_RETRY_DELAY_MS = 25;
+export declare const G65_GLOBAL_ADMISSION_HEADER = "x-sdt-global-admission";
+interface TagDurableObjectEnv {
+    /** Global D1 receipt authority used only to verify a source acknowledgement. */
+    D1?: D1Database;
+    DOWNSTREAM_QUEUE?: Queue<DownstreamOutboxMessage>;
+    DOWNSTREAM_DOORBELL?: DownstreamDoorbellBinding;
+    AUTO_DRAIN_OUTBOX?: string;
+    DOMAIN_DELIVERY_CLASS?: string;
+    DIRECT_DOORBELL?: string;
+    DIRECT_DOORBELL_ALLOWED_VIEWS?: string;
+    DIRECT_DOORBELL_MAX_INVOCATIONS?: string;
+    DIRECT_DOORBELL_DEGRADATION?: string;
+    DIRECT_DOORBELL_RECEIVER_MODE?: string;
+    DIRECT_DOORBELL_SELF_BINDING_PROOF?: string;
+}
+/** A mismatched immutable tag identity is a typed 409, not an internal error. */
+export declare class TagIdentityConflict extends Error {
+    constructor();
+}
+export declare class TagDurableObject implements DurableObject {
+    private readonly ctx;
+    private readonly env;
+    private readonly nativeTracing;
+    /** Constructor-scoped observation only; never persisted or used for control. */
+    private readonly activation;
+    /**
+     * Direct unit seams intentionally omit `storage.sql`. They exercise
+     * transport behavior only; deployed and Miniflare Tag DOs always use the
+     * normalized SQL path. Keeping this ephemeral fallback out of durable KV
+     * prevents a TAG_KEY record from remaining a second source of truth.
+     */
+    private fallbackRecord;
+    private fallbackOutboxDeliveries;
+    /** Ephemeral test/evidence seam; never exposed as an HTTP route or stored. */
+    private g43SqlMeasurement;
+    /** Exercises alarm crash boundaries without adding a production control path. */
+    private g43SchedulerFault;
+    constructor(ctx: DurableObjectState, env: TagDurableObjectEnv, nativeTracing?: NativeTracing);
+    fetch(request: Request): Promise<Response>;
+    /** Identity-bound installed/absent inspection for G77 issuance reconciliation. */
+    private inspectG77Target;
+    /** Reconciler-only fence for never-contacted targets; creates durable tombstone state. */
+    private fenceAbsentG77Target;
+    alarm(): Promise<void>;
+    /**
+     * Structural-measurement seam used around a real handler request. The
+     * production wire cannot start it, and it neither changes control flow nor
+     * persists instrumentation. Completion is intentionally separate so the
+     * caller can first consume the response body (the specified boundary).
+     */
+    beginG43SqlMeasurement(): void;
+    completeG43SqlMeasurement(): G43SqlMeasurementSnapshot;
+    /** Test-only fault seam for AC6's transactional re-arm crash boundaries. */
+    setG43SchedulerFaultForTest(fault: "before-rearm" | "after-rearm" | undefined): void;
+    /**
+     * Bounded source seam for the normal incremental TagState source read. Its
+     * direct-DO adapter above is transport-only; this method remains the one
+     * authority for cursor range reads and frozen-frontier completion.
+     */
+    g43ReadAfter(sortableUniqueId: string, limit: number, through?: string): Promise<TagEvent[]>;
+    /**
+     * The bounded normal projection source operation: it reads only events
+     * newer than the supplied checkpoint and folds the fixed result window in
+     * memory. No existing history is reread.
+     */
+    g43TagStateIncrementalCatchUp(input: G43TagStateIncrementalRequest): Promise<G43TagStateIncrementalPage>;
+    /** Full replay remains intentionally linear and is measurement-only info. */
+    g43TagStateRebuild(): Promise<readonly TagEvent[]>;
+    /**
+     * Internal source-authority scanner for the G43 obligation seam.  This is
+     * intentionally a DO RPC surface rather than a Worker route: it adds no
+     * role-facing HTTP API, and it does not share Queue/doorbell failure paths.
+     */
+    g43ScanSourceObligations(tag: string, nowMs: number): Promise<unknown>;
+    /**
+     * G44's private source scanner RPC. It exposes only the normalized source
+     * obligation table, never Queue state or a role-facing Worker route. The
+     * caller fixes `upperBoundSequence` from the source partition registry
+     * before paging, so later commits cannot move a scan frontier mid-pass.
+     */
+    g44ReadSourceObligations(input: Readonly<{
+        serviceId: string;
+        tag: string;
+        upperBoundSequence: number;
+        afterSequence: number;
+        limit: number;
+    }>): Promise<SourceObligationPage>;
+    /**
+     * G44's source acknowledgement guard. A transport success or an unjoined
+     * receipt is deliberately insufficient: the global event, local membership
+     * and exact source-obligation receipt must all be readable together.
+     */
+    private globalReceiptMatches;
+    /**
+     * The first append on a Tag must make its source partition enumerable before
+     * the local event transaction starts. Once the local marker is registered,
+     * later appends never consult or await D1 for this fact; Queue admission is
+     * responsible for advancing the registered obligation sequence.
+     */
+    private ensureSourcePartitionBeforeFirstAppend;
+    private sourcePartitionRegistrationStatus;
+    /**
+     * Refreshes the already-authorized source row with the committed local
+     * obligation sequence without putting D1 back on the response path. The
+     * first-append authority check above is the only registration operation that
+     * may refuse a commit; this post-append watermark is Queue/retry recovery
+     * work and is deliberately handed to waitUntil.
+     */
+    private scheduleSourcePartitionWatermark;
+    private retrySourcePartitionRegistration;
+    private markSourcePartitionRegistration;
+    private registerSourcePartition;
+    private hasG44GlobalArrayAuthority;
+    private readG44GlobalArrayAuthority;
+    private traceCommitActor;
+    /**
+     * Internal Tag reads keep their Cloudflare parent solely from active async
+     * context; G30 does not add a correlation header or alter either /state or
+     * /head-facts just to label telemetry.
+     */
+    private traceCommitReadActor;
+    private jsonBody;
+    private sqlStorage;
+    /**
+     * Rehydrate the legacy response shape only at a state/read boundary.  The
+     * append path below deliberately does not call this method: it reads the
+     * head and candidate identities by index instead of deserializing history.
+     */
+    private readStoredRecord;
+    /**
+     * Reads the scalar commit-response facts without rehydrating `tag_event`.
+     * Keep the identity and control/head consistency checks at this boundary:
+     * an internal caller is not allowed to turn an identity change into a
+     * plausible but stale response.
+     */
+    private readHeadFacts;
+    private obligationArtifact;
+    private ensureSqlTag;
+    private writeCommittedSqlEvent;
+    private writeCommittedSqlMembership;
+    private writeCommittedSqlObligation;
+    private upsertSourcePartitionRegistration;
+    private writeCommittedSqlHead;
+    private writeCommittedSqlReceipt;
+    /**
+     * The normal append path deliberately probes only the indexed rows it needs
+     * (identity/control, this attempt, this reservation, and these candidates).
+     * It never calls `readStoredRecord`, so history size cannot turn append into
+     * a whole-array deserialize/copy/serialize operation.
+     */
+    private appendSql;
+    /**
+     * SQL-native reservation transition. This deliberately reads only the
+     * control, epoch, tombstone, fence and reservation rows that participate in
+     * the transition; it never rehydrates tag_event history just to reserve.
+     */
+    private acquireSql;
+    /**
+     * SQL-native cancel transition. It only mutates reservation/epoch/tombstone
+     * control rows, so a cancellation cannot hide a committed event, membership
+     * or obligation and does not rewrite event history.
+     */
+    private cancelSql;
+    private writeSqlRecord;
+    private nextSqlAlarmDue;
+    private recordFor;
+    private write;
+    private commit;
+    private commitExpiryIfNeeded;
+    private acquire;
+    private cancel;
+    private seal;
+    /**
+     * Coordinator-only import admission.  This is deliberately not a flag on
+     * /append: it never creates an outbox row, never accepts a reservation, and
+     * closes permanently once the coordinator reaches READY.
+     */
+    private bootstrapAppend;
+    private closeBootstrap;
+    private directDoorbellPreflight;
+    private append;
+    /**
+     * Claim and run the opted-in direct unsafe path after the append transaction
+     * has committed, but before the 201 response is returned. The rows are
+     * handed to the Queue drain afterwards so the durable Queue remains the
+     * owner of global admission, ordering, retries, and DLQ recovery.
+     *
+     * A pending-row read can fail independently of the already committed
+     * append. In that case the caller falls back to the ordinary Queue drain;
+     * it never turns a durable acceptance into a response failure.
+     */
+    private directDeliveryBeforeResponse;
+    /**
+     * Attempt the same idempotent D1 admission used by the Queue consumer.
+     * This is a derived write only: the Tag event, outbox obligation, and local
+     * receipt are already durable, and the Queue remains the guarantee.
+     */
+    private globalAdmissionBeforeResponse;
+    private scheduleG65AdmissionAttempt;
+    /**
+     * Bound a derived attempt without cancelling or making its eventual result
+     * part of commit semantics.  The rejection branch is attached immediately
+     * so a late D1/doorbell failure cannot become an unhandled rejection.
+     */
+    private boundedDerivedWrite;
+    /**
+     * The append transaction has durably committed the Tag event, outbox
+     * obligation, and receipt before this handoff is started. A direct delivery
+     * has already run when `preclaimedRows` is present; the retained promise
+     * then performs only the unchanged Queue submission for those same bytes.
+     * With no preclaimed rows this remains the existing waitUntil-backed drain,
+     * including its direct-before-Queue behavior for alarms and fallback paths.
+     */
+    private startAutoDrainBeforeResponse;
+    private deliverDirectRows;
+    private autoDrainOutbox;
+    /** G60 writes are observation-only and stay outside the append/drain result. */
+    private scheduleDurableHop;
+    private confirm;
+    private installFence;
+    private clearFence;
+    /**
+     * Returns Tag-side repair facts only.  Journal observations are deliberately
+     * absent: they are progress telemetry and can never grant repair authority.
+     */
+    private repairFacts;
+    /**
+     * Internal outbox handoff: enqueuedAt is persisted before any Queue send so
+     * a crash after send but before delivered marking replays the same clock
+     * fact. It never changes the immutable event/outbox row.
+     */
+    private pendingOutbox;
+    /**
+     * Source-side obligation scanner.  It deliberately does not call the Queue,
+     * the doorbell, `pendingOutbox`, or any detector.  An obligation therefore
+     * remains visible when delivery is disabled, throws, or has not started.
+     */
+    private scanOutboxObligations;
+    /** Record a retry or terminal poison disposition without changing the source event. */
+    private recordOutboxFailure;
+    /** Marks only a previously enqueued row; repeating a mark is harmless. */
+    private markOutboxDelivered;
+    /**
+     * The delivery handoff reads its universe from `tag_outbox_obligation`.
+     * It does not consult the Queue, a sink receipt, or a runner's expected
+     * count.  Reserving the retry timestamp before the external handoff lets the
+     * single durable scheduler retry a crash/throw without treating delivery as
+     * the authority for obligation existence.
+     */
+    private pendingSqlOutbox;
+    private markSqlOutboxDelivered;
+    private rearmScheduler;
+    private acquireRepairLease;
+    private renewRepairLease;
+    private unionRepairScope;
+    private applyRepair;
+    private auditRepair;
+    private clearRepairFence;
+    private setClockOffset;
+    private runAlarm;
+}
+export { MAX_EPOCH };