@sekiban/dcb-runtime 0.2.0

package/dist/diagnostics/G60DurableHop.d.ts

@@ -0,0 +1,99 @@
+/**
+ * SDT-G60 AC1 operational hop ledger.
+ *
+ * This is deliberately separate from sdt.commit/v1 and from every public
+ * response.  The ledger records immutable observations against the stable
+ * event/SUID/attempt identity; it is never consulted by admission, Queue
+ * acknowledgement, projection fencing, or a read response.
+ */
+export declare const G60_HOP_STAGES: readonly ["command-receipt", "tag-append-committed", "outbox-obligation-written", "queue-send-returned", "consumer-invocation-started", "record-delivery-batch-committed", "first-unsafe-visible-read"];
+export type G60HopStage = typeof G60_HOP_STAGES[number];
+export type G60HopTransport = "" | "queue" | "fast" | "import" | "public-read";
+/** Observation-only boundaries inside the interval after recordDelivery. */
+export declare const G60_POST_ADMISSION_STAGES: readonly ["post-record-delivery-global-receipt-readback", "source-tag-acknowledgement", "completeness-coverage", "detector", "unsafe-view-apply"];
+export type G60PostAdmissionStage = typeof G60_POST_ADMISSION_STAGES[number];
+export type G60PostAdmissionBoundary = "start" | "end";
+/** Concrete observation paths for an unsafe materialized-view row write. */
+export declare const G60_UNSAFE_WRITER_PATHS: readonly ["inline-delivery", "scheduled-drain"];
+export type G60UnsafeWriterPath = typeof G60_UNSAFE_WRITER_PATHS[number];
+export type G60UnsafeWriterBoundary = "start" | "end";
+export type G60UnsafeWriterTransport = "" | "queue" | "fast" | "import" | "scheduled";
+export interface G60DurableHopObservation {
+    readonly stage: G60HopStage;
+    readonly serviceId: string;
+    readonly eventId: string;
+    readonly suid: string;
+    readonly attemptId: string;
+    readonly observedAt: number;
+    readonly partitionTag?: string;
+    readonly viewId?: string;
+    readonly transport?: G60HopTransport;
+}
+export interface G60DurableHopObserver {
+    observe(input: G60DurableHopObservation): void;
+    observeSubstep?(input: G60DurablePostAdmissionObservation): void;
+    observeUnsafeWriter?(input: G60DurableUnsafeWriterObservation): void;
+}
+export interface G60DurablePostAdmissionObservation {
+    readonly stage: G60PostAdmissionStage;
+    readonly boundary: G60PostAdmissionBoundary;
+    readonly outcome: string;
+    readonly serviceId: string;
+    readonly eventId: string;
+    readonly suid: string;
+    readonly attemptId: string;
+    readonly observedAt: number;
+    readonly partitionTag?: string;
+    readonly viewId?: string;
+    readonly transport?: G60HopTransport;
+}
+/**
+ * Observation-only boundary at the concrete unsafe MV writer. This table is
+ * separate from the older seven-hop and post-admission tables so the writer
+ * path remains explicit without changing either deployed schema contract.
+ */
+export interface G60DurableUnsafeWriterObservation {
+    readonly writerPath: G60UnsafeWriterPath;
+    readonly boundary: G60UnsafeWriterBoundary;
+    readonly outcome: string;
+    readonly serviceId: string;
+    readonly eventId: string;
+    readonly suid: string;
+    readonly attemptId: string;
+    readonly viewId: string;
+    readonly observedAt: number;
+    readonly transport?: G60UnsafeWriterTransport;
+}
+/** Write one idempotent observation. Replays retain the earliest timestamp. */
+export declare function recordDurableHop(database: D1Database, input: G60DurableHopObservation): Promise<void>;
+/** Append one observation-only post-admission boundary; replays are ignored. */
+export declare function recordDurableHopSubstep(database: D1Database, input: G60DurablePostAdmissionObservation): Promise<void>;
+/** Append one exact unsafe-row writer boundary; replays retain the first row. */
+export declare function recordDurableUnsafeWriterBoundary(database: D1Database, input: G60DurableUnsafeWriterObservation): Promise<void>;
+/**
+ * Deliver one post-admission observation to the active waitUntil-backed
+ * observer. A diagnostic observer is never allowed to change protocol flow.
+ */
+export declare function observeG60PostAdmission(observer: G60DurableHopObserver | undefined, input: G60DurablePostAdmissionObservation): void;
+/** Deliver a concrete writer observation without allowing it to affect flow. */
+export declare function observeG60UnsafeWriter(observer: G60DurableHopObserver | undefined, input: G60DurableUnsafeWriterObservation): void;
+/**
+ * Schedule an observation without extending the application response or
+ * transport loop. The timestamp is captured by the caller at the hop; only
+ * the operational D1 write is deferred to the active Worker invocation.
+ */
+export declare function createG60DurableHopObserver(database: D1Database | undefined, waitUntil: (promise: Promise<unknown>) => void): G60DurableHopObserver | undefined;
+/**
+ * Resolve a public MV row back to the exact source EventId. Prefer the
+ * generation's durable unsafe receipt; if it has already been retired, use
+ * the source D1 point only when the SUID is unambiguous. G32 intentionally
+ * permits SUID collisions, so an ambiguous fallback is censored rather than
+ * attributed to the wrong event.
+ */
+export declare function recordFirstUnsafeVisibleRead(pipelineDatabase: D1Database, materializedViewDatabase: D1Database, input: Readonly<{
+    serviceId: string;
+    viewId: string;
+    suid: string;
+    eventIdHint?: string;
+    observedAt: number;
+}>): Promise<boolean>;

package/dist/diagnostics/G60DurableHop.js

@@ -0,0 +1,248 @@
+/**
+ * SDT-G60 AC1 operational hop ledger.
+ *
+ * This is deliberately separate from sdt.commit/v1 and from every public
+ * response.  The ledger records immutable observations against the stable
+ * event/SUID/attempt identity; it is never consulted by admission, Queue
+ * acknowledgement, projection fencing, or a read response.
+ */
+export const G60_HOP_STAGES = [
+    "command-receipt",
+    "tag-append-committed",
+    "outbox-obligation-written",
+    "queue-send-returned",
+    "consumer-invocation-started",
+    "record-delivery-batch-committed",
+    "first-unsafe-visible-read",
+];
+/** Observation-only boundaries inside the interval after recordDelivery. */
+export const G60_POST_ADMISSION_STAGES = [
+    "post-record-delivery-global-receipt-readback",
+    "source-tag-acknowledgement",
+    "completeness-coverage",
+    "detector",
+    "unsafe-view-apply",
+];
+/** Concrete observation paths for an unsafe materialized-view row write. */
+export const G60_UNSAFE_WRITER_PATHS = ["inline-delivery", "scheduled-drain"];
+function nonEmpty(value, field) {
+    if (value.length === 0)
+        throw new Error(`G60 ${field} must be non-empty`);
+}
+function validate(input) {
+    nonEmpty(input.serviceId, "serviceId");
+    nonEmpty(input.eventId, "eventId");
+    nonEmpty(input.suid, "suid");
+    nonEmpty(input.attemptId, "attemptId");
+    if (!Number.isSafeInteger(input.observedAt) || input.observedAt < 0) {
+        throw new Error("G60 observedAt must be a non-negative safe integer");
+    }
+    const partitionTag = input.partitionTag ?? "";
+    const viewId = input.viewId ?? "";
+    const transport = input.transport ?? "";
+    if ((input.stage === "tag-append-committed" || input.stage === "outbox-obligation-written" || input.stage === "queue-send-returned" || input.stage === "consumer-invocation-started") && partitionTag.length === 0) {
+        throw new Error(`G60 ${input.stage} requires partitionTag`);
+    }
+    if (input.stage === "first-unsafe-visible-read" && viewId.length === 0) {
+        throw new Error("G60 first-unsafe-visible-read requires viewId");
+    }
+    if ((input.stage === "queue-send-returned" || input.stage === "consumer-invocation-started" || input.stage === "record-delivery-batch-committed") && transport === "") {
+        throw new Error(`G60 ${input.stage} requires transport`);
+    }
+    return { partitionTag, viewId, transport };
+}
+/** Write one idempotent observation. Replays retain the earliest timestamp. */
+export async function recordDurableHop(database, input) {
+    const normalized = validate(input);
+    await database.prepare(`
+    INSERT INTO serialized_dcb_hop_measurements
+      (service_id, event_id, suid, attempt_id, stage, partition_tag, view_id, transport, observed_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT (service_id, event_id, stage, partition_tag, view_id, transport)
+    DO UPDATE SET observed_at = MIN(serialized_dcb_hop_measurements.observed_at, excluded.observed_at)
+      WHERE serialized_dcb_hop_measurements.suid = excluded.suid
+        AND serialized_dcb_hop_measurements.attempt_id = excluded.attempt_id
+  `).bind(input.serviceId, input.eventId, input.suid, input.attemptId, input.stage, normalized.partitionTag, normalized.viewId, normalized.transport, input.observedAt).run();
+}
+function validatePostAdmission(input) {
+    nonEmpty(input.serviceId, "serviceId");
+    nonEmpty(input.eventId, "eventId");
+    nonEmpty(input.suid, "suid");
+    nonEmpty(input.attemptId, "attemptId");
+    nonEmpty(input.outcome, "outcome");
+    if (!G60_POST_ADMISSION_STAGES.includes(input.stage)) {
+        throw new Error(`G60 unknown post-admission stage: ${input.stage}`);
+    }
+    if (input.boundary !== "start" && input.boundary !== "end") {
+        throw new Error(`G60 post-admission boundary must be start or end: ${input.boundary}`);
+    }
+    if (!Number.isSafeInteger(input.observedAt) || input.observedAt < 0) {
+        throw new Error("G60 post-admission observedAt must be a non-negative safe integer");
+    }
+    const partitionTag = input.partitionTag ?? "";
+    const viewId = input.viewId ?? "";
+    const transport = input.transport ?? "";
+    if (input.stage === "source-tag-acknowledgement" && partitionTag.length === 0) {
+        throw new Error("G60 source-tag-acknowledgement requires partitionTag");
+    }
+    if (input.stage === "unsafe-view-apply" && viewId.length === 0) {
+        throw new Error("G60 unsafe-view-apply requires viewId");
+    }
+    return { partitionTag, viewId, transport };
+}
+/** Append one observation-only post-admission boundary; replays are ignored. */
+export async function recordDurableHopSubstep(database, input) {
+    const normalized = validatePostAdmission(input);
+    await database.prepare(`
+    INSERT OR IGNORE INTO serialized_dcb_hop_submeasurements
+      (service_id, event_id, suid, attempt_id, stage, boundary, outcome,
+       partition_tag, view_id, transport, observed_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).bind(input.serviceId, input.eventId, input.suid, input.attemptId, input.stage, input.boundary, input.outcome, normalized.partitionTag, normalized.viewId, normalized.transport, input.observedAt).run();
+}
+function validateUnsafeWriter(input) {
+    nonEmpty(input.serviceId, "serviceId");
+    nonEmpty(input.eventId, "eventId");
+    nonEmpty(input.suid, "suid");
+    nonEmpty(input.attemptId, "attemptId");
+    nonEmpty(input.viewId, "viewId");
+    nonEmpty(input.outcome, "outcome");
+    if (!G60_UNSAFE_WRITER_PATHS.includes(input.writerPath)) {
+        throw new Error(`G60 unknown unsafe writer path: ${input.writerPath}`);
+    }
+    if (input.boundary !== "start" && input.boundary !== "end") {
+        throw new Error(`G60 unsafe writer boundary must be start or end: ${input.boundary}`);
+    }
+    if (!Number.isSafeInteger(input.observedAt) || input.observedAt < 0) {
+        throw new Error("G60 unsafe writer observedAt must be a non-negative safe integer");
+    }
+    const transport = input.transport ?? "";
+    if (!["", "queue", "fast", "import", "scheduled"].includes(transport)) {
+        throw new Error(`G60 unsafe writer transport is invalid: ${transport}`);
+    }
+    return { transport };
+}
+/** Append one exact unsafe-row writer boundary; replays retain the first row. */
+export async function recordDurableUnsafeWriterBoundary(database, input) {
+    const normalized = validateUnsafeWriter(input);
+    await database.prepare(`
+    INSERT OR IGNORE INTO serialized_dcb_unsafe_writer_boundaries
+      (service_id, event_id, suid, attempt_id, writer_path, boundary,
+       outcome, view_id, transport, observed_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).bind(input.serviceId, input.eventId, input.suid, input.attemptId, input.writerPath, input.boundary, input.outcome, input.viewId, normalized.transport, input.observedAt).run();
+}
+/**
+ * Deliver one post-admission observation to the active waitUntil-backed
+ * observer. A diagnostic observer is never allowed to change protocol flow.
+ */
+export function observeG60PostAdmission(observer, input) {
+    try {
+        observer?.observeSubstep?.(input);
+    }
+    catch {
+        // Observation is never allowed to affect admission, delivery, or reads.
+    }
+}
+/** Deliver a concrete writer observation without allowing it to affect flow. */
+export function observeG60UnsafeWriter(observer, input) {
+    try {
+        observer?.observeUnsafeWriter?.(input);
+    }
+    catch {
+        // Observation is never allowed to affect the unsafe apply or its caller.
+    }
+}
+/**
+ * Schedule an observation without extending the application response or
+ * transport loop. The timestamp is captured by the caller at the hop; only
+ * the operational D1 write is deferred to the active Worker invocation.
+ */
+export function createG60DurableHopObserver(database, waitUntil) {
+    if (database === undefined)
+        return undefined;
+    return Object.freeze({
+        observe(input) {
+            const write = recordDurableHop(database, input).catch(() => undefined);
+            waitUntil(write);
+        },
+        observeSubstep(input) {
+            const write = recordDurableHopSubstep(database, input).catch(() => undefined);
+            waitUntil(write);
+        },
+        observeUnsafeWriter(input) {
+            const write = recordDurableUnsafeWriterBoundary(database, input).catch(() => undefined);
+            waitUntil(write);
+        },
+    });
+}
+function asString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+/**
+ * Resolve a public MV row back to the exact source EventId. Prefer the
+ * generation's durable unsafe receipt; if it has already been retired, use
+ * the source D1 point only when the SUID is unambiguous. G32 intentionally
+ * permits SUID collisions, so an ambiguous fallback is censored rather than
+ * attributed to the wrong event.
+ */
+export async function recordFirstUnsafeVisibleRead(pipelineDatabase, materializedViewDatabase, input) {
+    if (input.suid.length === 0 || input.viewId.length === 0)
+        return false;
+    const receiptRows = await materializedViewDatabase.prepare(`
+    SELECT event_id, suid
+      FROM mv_unsafe_receipts
+     WHERE service_id = ? AND view_id = ? AND suid COLLATE BINARY = ? COLLATE BINARY
+     ORDER BY observed_at ASC, event_id COLLATE BINARY ASC
+  `).bind(input.serviceId, input.viewId, input.suid).all();
+    let eventId;
+    let suid = input.suid;
+    if (input.eventIdHint !== undefined && receiptRows.results.some((row) => row.event_id === input.eventIdHint)) {
+        eventId = input.eventIdHint;
+    }
+    else if (receiptRows.results.length === 1) {
+        eventId = asString(receiptRows.results[0]?.event_id);
+        suid = asString(receiptRows.results[0]?.suid) ?? input.suid;
+    }
+    let attemptId;
+    if (eventId === undefined) {
+        const sourceRows = await pipelineDatabase.prepare(`
+      SELECT event."Id" AS event_id, event."SortableUniqueId" AS suid, ops."AttemptId" AS attempt_id
+        FROM dcb_events AS event
+        JOIN dcb_event_ops AS ops
+          ON ops."ServiceId" = event."ServiceId" AND ops."Id" = event."Id"
+       WHERE event."ServiceId" = ?
+         AND event."SortableUniqueId" COLLATE BINARY = ? COLLATE BINARY
+       ORDER BY event."Id" COLLATE BINARY ASC
+    `).bind(input.serviceId, input.suid).all();
+        if (sourceRows.results.length !== 1)
+            return false;
+        const source = sourceRows.results[0];
+        eventId = asString(source?.event_id);
+        suid = asString(source?.suid) ?? input.suid;
+        attemptId = asString(source?.attempt_id);
+    }
+    if (eventId === undefined)
+        return false;
+    if (attemptId === undefined) {
+        const source = await pipelineDatabase.prepare(`
+      SELECT "AttemptId" AS attempt_id
+        FROM dcb_event_ops
+       WHERE "ServiceId" = ? AND "Id" = ?
+    `).bind(input.serviceId, eventId).first();
+        attemptId = asString(source?.attempt_id);
+    }
+    if (attemptId === undefined)
+        return false;
+    await recordDurableHop(pipelineDatabase, {
+        stage: "first-unsafe-visible-read",
+        serviceId: input.serviceId,
+        eventId,
+        suid,
+        attemptId,
+        viewId: input.viewId,
+        transport: "public-read",
+        observedAt: input.observedAt,
+    });
+    return true;
+}

package/dist/diagnostics/G65Admission.d.ts

@@ -0,0 +1,23 @@
+/**
+ * SDT-G65 admission observations.
+ *
+ * This table is diagnostic only.  It is written through waitUntil after the
+ * bounded derived attempt and is never consulted by commit, Queue, safe-lane,
+ * or projection code.
+ */
+export declare const G65_ADMISSION_CLOCK_ORIGIN: "Date.now epoch ms";
+export declare const G65_ADMISSION_OUTCOMES: readonly ["admitted", "not-admitted", "unknown"];
+export type G65AdmissionOutcome = typeof G65_ADMISSION_OUTCOMES[number];
+export interface G65AdmissionAttemptObservation {
+    readonly serviceId: string;
+    readonly eventId: string;
+    readonly suid: string;
+    readonly attemptId: string;
+    readonly partitionTag: string;
+    readonly deliverySource: "fast";
+    readonly admissionStartedAt: number;
+    readonly admissionFinishedAt: number;
+    readonly outcome: G65AdmissionOutcome;
+    readonly globalCompletionObservedAt: number | null;
+}
+export declare function recordG65AdmissionAttempt(database: D1Database, input: G65AdmissionAttemptObservation): Promise<void>;

package/dist/diagnostics/G65Admission.js

@@ -0,0 +1,43 @@
+/**
+ * SDT-G65 admission observations.
+ *
+ * This table is diagnostic only.  It is written through waitUntil after the
+ * bounded derived attempt and is never consulted by commit, Queue, safe-lane,
+ * or projection code.
+ */
+export const G65_ADMISSION_CLOCK_ORIGIN = "Date.now epoch ms";
+export const G65_ADMISSION_OUTCOMES = ["admitted", "not-admitted", "unknown"];
+function nonEmpty(value, field) {
+    if (value.length === 0)
+        throw new Error(`G65 admission ${field} must be non-empty`);
+}
+function validate(input) {
+    nonEmpty(input.serviceId, "serviceId");
+    nonEmpty(input.eventId, "eventId");
+    nonEmpty(input.suid, "suid");
+    nonEmpty(input.attemptId, "attemptId");
+    nonEmpty(input.partitionTag, "partitionTag");
+    if (!Number.isSafeInteger(input.admissionStartedAt) || input.admissionStartedAt < 0) {
+        throw new Error("G65 admission start must be a non-negative safe integer");
+    }
+    if (!Number.isSafeInteger(input.admissionFinishedAt) || input.admissionFinishedAt < input.admissionStartedAt) {
+        throw new Error("G65 admission finish must be after start");
+    }
+    if (!G65_ADMISSION_OUTCOMES.includes(input.outcome)) {
+        throw new Error(`G65 admission outcome is invalid: ${input.outcome}`);
+    }
+    if (input.globalCompletionObservedAt !== null &&
+        (!Number.isSafeInteger(input.globalCompletionObservedAt) || input.globalCompletionObservedAt < input.admissionStartedAt)) {
+        throw new Error("G65 global completion observation is invalid");
+    }
+}
+export async function recordG65AdmissionAttempt(database, input) {
+    validate(input);
+    await database.prepare(`
+    INSERT OR IGNORE INTO serialized_dcb_g65_admission_attempts
+      (service_id, event_id, suid, attempt_id, partition_tag, delivery_source,
+       admission_started_at, admission_finished_at, outcome,
+       global_completion_observed_at, clock_origin)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).bind(input.serviceId, input.eventId, input.suid, input.attemptId, input.partitionTag, input.deliverySource, input.admissionStartedAt, input.admissionFinishedAt, input.outcome, input.globalCompletionObservedAt, G65_ADMISSION_CLOCK_ORIGIN).run();
+}

package/dist/diagnostics/G65DirectRing.d.ts

@@ -0,0 +1,33 @@
+/**
+ * SDT-G65 AC0 direct-doorbell RING/APPLY ledger.
+ *
+ * A ring is a durable receiver acceptance of the immutable Queue envelope.
+ * Only the ring insert is on the caller's RPC path.  The receiver reads the
+ * retained bytes in its own execution context and runs the existing delivery
+ * core asynchronously; this ledger is never an admission, retry, projection,
+ * or public-response decision.
+ */
+import type { DownstreamOutboxMessage } from "../downstream/types";
+export declare const G65_DIRECT_RING_BUDGET_MS = 100;
+export declare const G65_DIRECT_RING_CLOCK_ORIGIN: "Date.now epoch ms";
+export type G65DirectRingOutcome = "rung" | "duplicate";
+export type G65DirectApplyOutcome = "applied" | "duplicate" | "failed";
+export interface G65DirectRingRecord {
+    readonly serviceId: string;
+    readonly eventId: string;
+    readonly suid: string;
+    readonly attemptId: string;
+    readonly partitionTag: string;
+    readonly messageJson: string;
+    readonly ringStartedAt: number;
+    readonly ringFinishedAt: number;
+    readonly ringOutcome: G65DirectRingOutcome;
+}
+/** Persist the exact immutable envelope before returning the receiver RPC. */
+export declare function recordG65DirectRing(database: D1Database, message: DownstreamOutboxMessage, ringStartedAt: number): Promise<G65DirectRingOutcome>;
+/** Read the exact bytes retained by the receiver ring. */
+export declare function readG65DirectRing(database: D1Database, message: Pick<DownstreamOutboxMessage, "serviceId" | "eventId" | "attemptId">): Promise<DownstreamOutboxMessage | undefined>;
+/** Set the first apply start boundary; duplicate apply attempts do not rewrite it. */
+export declare function markG65DirectApplyStarted(database: D1Database, message: Pick<DownstreamOutboxMessage, "serviceId" | "eventId" | "attemptId">, observedAt: number): Promise<void>;
+/** Set the first terminal apply outcome and timing. */
+export declare function markG65DirectApplyFinished(database: D1Database, message: Pick<DownstreamOutboxMessage, "serviceId" | "eventId" | "attemptId">, observedAt: number, outcome: G65DirectApplyOutcome, error?: string): Promise<void>;

package/dist/diagnostics/G65DirectRing.js

@@ -0,0 +1,85 @@
+/**
+ * SDT-G65 AC0 direct-doorbell RING/APPLY ledger.
+ *
+ * A ring is a durable receiver acceptance of the immutable Queue envelope.
+ * Only the ring insert is on the caller's RPC path.  The receiver reads the
+ * retained bytes in its own execution context and runs the existing delivery
+ * core asynchronously; this ledger is never an admission, retry, projection,
+ * or public-response decision.
+ */
+export const G65_DIRECT_RING_BUDGET_MS = 100;
+export const G65_DIRECT_RING_CLOCK_ORIGIN = "Date.now epoch ms";
+function nonEmpty(value, field) {
+    if (value.length === 0)
+        throw new Error(`G65 direct ring ${field} must be non-empty`);
+}
+function validateMessage(message) {
+    nonEmpty(message.serviceId, "serviceId");
+    nonEmpty(message.eventId, "eventId");
+    nonEmpty(message.suid, "suid");
+    nonEmpty(message.attemptId, "attemptId");
+    nonEmpty(message.tag, "partitionTag");
+}
+function validateTimestamp(value, field) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        throw new Error(`G65 direct ring ${field} must be a non-negative safe integer`);
+}
+/** Persist the exact immutable envelope before returning the receiver RPC. */
+export async function recordG65DirectRing(database, message, ringStartedAt) {
+    validateMessage(message);
+    validateTimestamp(ringStartedAt, "ring start");
+    const result = await database.prepare(`
+    INSERT OR IGNORE INTO serialized_dcb_g65_direct_rings
+      (service_id, event_id, suid, attempt_id, partition_tag, message_json,
+       ring_started_at, ring_finished_at, ring_outcome, apply_outcome)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'rung', NULL)
+  `).bind(message.serviceId, message.eventId, message.suid, message.attemptId, message.tag, JSON.stringify(message), ringStartedAt, ringStartedAt).run();
+    const changes = typeof result.meta?.changes === "number" ? result.meta.changes : undefined;
+    if (changes === 0)
+        return "duplicate";
+    const ringFinishedAt = Date.now();
+    validateTimestamp(ringFinishedAt, "ring finish");
+    if (ringFinishedAt < ringStartedAt)
+        throw new Error("G65 direct ring finish precedes start");
+    await database.prepare(`
+    UPDATE serialized_dcb_g65_direct_rings
+       SET ring_finished_at = ?
+     WHERE service_id = ? AND event_id = ? AND attempt_id = ?
+  `).bind(ringFinishedAt, message.serviceId, message.eventId, message.attemptId).run();
+    return "rung";
+}
+/** Read the exact bytes retained by the receiver ring. */
+export async function readG65DirectRing(database, message) {
+    const row = await database.prepare(`
+    SELECT message_json
+      FROM serialized_dcb_g65_direct_rings
+     WHERE service_id = ? AND event_id = ? AND attempt_id = ?
+  `).bind(message.serviceId, message.eventId, message.attemptId).first();
+    if (typeof row?.message_json !== "string")
+        return undefined;
+    const parsed = JSON.parse(row.message_json);
+    validateMessage(parsed);
+    return parsed;
+}
+/** Set the first apply start boundary; duplicate apply attempts do not rewrite it. */
+export async function markG65DirectApplyStarted(database, message, observedAt) {
+    validateTimestamp(observedAt, "apply start");
+    await database.prepare(`
+    UPDATE serialized_dcb_g65_direct_rings
+       SET apply_started_at = COALESCE(apply_started_at, ?)
+     WHERE service_id = ? AND event_id = ? AND attempt_id = ?
+  `).bind(observedAt, message.serviceId, message.eventId, message.attemptId).run();
+}
+/** Set the first terminal apply outcome and timing. */
+export async function markG65DirectApplyFinished(database, message, observedAt, outcome, error) {
+    validateTimestamp(observedAt, "apply finish");
+    if (outcome.length === 0)
+        throw new Error("G65 direct apply outcome must be non-empty");
+    await database.prepare(`
+    UPDATE serialized_dcb_g65_direct_rings
+       SET apply_finished_at = COALESCE(apply_finished_at, ?),
+           apply_outcome = COALESCE(apply_outcome, ?),
+           apply_error = COALESCE(apply_error, ?)
+     WHERE service_id = ? AND event_id = ? AND attempt_id = ?
+  `).bind(observedAt, outcome, error ?? null, message.serviceId, message.eventId, message.attemptId).run();
+}

package/dist/diagnostics/G69AdmissionAttempt.d.ts

@@ -0,0 +1,43 @@
+/**
+ * SDT-G69 append-only delivery-attempt evidence.
+ *
+ * This ledger is diagnostic only. DeliveryCore, Queue disposition, G44
+ * coverage, and the safe frontier must never read it. A row represents one
+ * call to D1EventStore.recordDelivery, including an idempotent replay or a
+ * typed delivery failure when the diagnostic table itself is available.
+ */
+import type { DeliverySource } from "../downstream/types";
+export type G69AdmissionAttemptStatus = "stored" | "duplicate" | "suid-collision" | "lineage-mismatch" | "failed";
+export interface G69AdmissionAttemptReceipt {
+    readonly serviceId: string;
+    readonly eventId: string;
+    readonly suid: string;
+    readonly tag: string;
+    readonly deliverySource: DeliverySource;
+    /** Platform Queue wrapper identity; null when the transport did not expose one. */
+    readonly queueMessageId: string | null;
+    readonly attemptId: string;
+    readonly allocatorLineageId: string;
+    readonly obligationSequence: number;
+    readonly enqueuedAt: number;
+    readonly observedAt: number;
+    readonly arrivedAt: number;
+    readonly firstArrivedAtBefore: number | null;
+    readonly lastArrivedAtBefore: number | null;
+    readonly firstArrivedAtAfter: number | null;
+    readonly lastArrivedAtAfter: number | null;
+    /** Timestamp at which the diagnostic before-read completed, if observed. */
+    readonly beforeObservedAt: number | null;
+    /** Timestamp captured immediately before the diagnostic after-read. */
+    readonly afterObservedAt: number | null;
+    /** Relates observations to the actual admission mutation, or stays unknown. */
+    readonly observationConsistency: "before-admission" | "before-admission-absent" | "after-admission" | "before-read-failed" | "after-read-failed" | "unverified";
+    /** Mutation-owned classification; never inferred from the diagnostic read. */
+    readonly mutationEvidence: "first-admission" | "duplicate-admission" | "unverified";
+    /** Elapsed diagnostic/receipt preparation cost before the append is issued. */
+    readonly diagnosticDurationMs: number;
+    readonly status: G69AdmissionAttemptStatus;
+    readonly retryReason: string | null;
+}
+/** Best-effort because evidence availability cannot change delivery semantics. */
+export declare function appendG69AdmissionAttempt(database: D1Database, receipt: G69AdmissionAttemptReceipt): Promise<void>;

package/dist/diagnostics/G69AdmissionAttempt.js

@@ -0,0 +1,22 @@
+/** Best-effort because evidence availability cannot change delivery semantics. */
+export async function appendG69AdmissionAttempt(database, receipt) {
+    const insert = database.prepare(`INSERT INTO serialized_dcb_g69_admission_attempts
+       (service_id, event_id, suid, partition_tag, delivery_source,
+        queue_message_id, attempt_id, allocator_lineage_id, obligation_sequence,
+        enqueued_at, observed_at, arrived_at,
+        first_arrived_at_before, last_arrived_at_before,
+        first_arrived_at_after, last_arrived_at_after,
+        before_observed_at, after_observed_at, observation_consistency,
+        mutation_evidence, diagnostic_duration_ms, receipt_status, retry_reason, clock_origin)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).bind(receipt.serviceId, receipt.eventId, receipt.suid, receipt.tag, receipt.deliverySource, receipt.queueMessageId, receipt.attemptId, receipt.allocatorLineageId, receipt.obligationSequence, receipt.enqueuedAt, receipt.observedAt, receipt.arrivedAt, receipt.firstArrivedAtBefore, receipt.lastArrivedAtBefore, receipt.firstArrivedAtAfter, receipt.lastArrivedAtAfter, receipt.beforeObservedAt, receipt.afterObservedAt, receipt.observationConsistency, receipt.mutationEvidence, receipt.diagnosticDurationMs, receipt.status, receipt.retryReason, "Date.now epoch ms");
+    // Keep diagnostic history bounded per service. The receipt is deliberately
+    // outside core admission, so inability to retain it never changes Queue
+    // disposition or the public commit/delivery result.
+    const trim = database.prepare(`DELETE FROM serialized_dcb_g69_admission_attempts
+      WHERE service_id = ?
+        AND sequence NOT IN (
+          SELECT sequence FROM serialized_dcb_g69_admission_attempts
+           WHERE service_id = ? ORDER BY sequence DESC LIMIT 512
+        )`).bind(receipt.serviceId, receipt.serviceId);
+    await database.batch([insert, trim]);
+}