@sekiban/dcb-runtime 0.2.0

package/dist/store/provider.d.ts

@@ -0,0 +1,25 @@
+import type { PipelineStore } from "./types";
+import { type BootstrapStoreAdapter } from "../bootstrap/BootstrapStoreAdapter";
+/** The storage bindings visible to a provider; no provider may inspect request headers. */
+export interface StoreProviderEnvironment {
+    readonly POSTGRES_URL?: string;
+    readonly HYPERDRIVE?: {
+        readonly connectionString?: string;
+    };
+    /** Explicit opt-in D1 binding; the default provider never requires it. */
+    readonly D1?: D1Database;
+    /** Separate opt-in MV D1 binding; never used by the PipelineStore provider. */
+    readonly D1_MV?: D1Database;
+}
+/** Typed composition seam shared by the default Postgres and opt-in adapters. */
+export interface StoreProvider {
+    readonly name: string;
+    readonly isConfigured?: (env: StoreProviderEnvironment) => boolean;
+    create(env: StoreProviderEnvironment): PipelineStore;
+    createBootstrapAdapter?(env: StoreProviderEnvironment): BootstrapStoreAdapter;
+}
+/** The unchanged default composition. It never requires Cosmos bindings or secrets. */
+export declare const POSTGRES_STORE_PROVIDER: StoreProvider;
+export declare function createPostgresStoreProvider(): StoreProvider;
+/** Explicit bootstrap adapter for the concrete Postgres PipelineStore. */
+export declare function createPostgresBootstrapAdapter(store: PipelineStore): BootstrapStoreAdapter;

package/dist/store/provider.js

@@ -0,0 +1,32 @@
+import { PostgresEventStore } from "./PostgresEventStore";
+import { bootstrapEventIdentityMatches, createBootstrapStoreAdapter } from "../bootstrap/BootstrapStoreAdapter";
+function postgresConnectionString(env) {
+    const connectionString = env.HYPERDRIVE?.connectionString ?? env.POSTGRES_URL;
+    if (connectionString === undefined || connectionString.length === 0) {
+        throw new Error("A Hyperdrive binding or POSTGRES_URL is required for the Postgres store");
+    }
+    return connectionString;
+}
+/** The unchanged default composition. It never requires Cosmos bindings or secrets. */
+export const POSTGRES_STORE_PROVIDER = Object.freeze({
+    name: "postgres",
+    isConfigured: (env) => {
+        const connectionString = env.HYPERDRIVE?.connectionString ?? env.POSTGRES_URL;
+        return connectionString !== undefined && connectionString.length > 0;
+    },
+    create(env) {
+        return new PostgresEventStore(postgresConnectionString(env));
+    },
+    createBootstrapAdapter(env) {
+        return createPostgresBootstrapAdapter(this.create(env));
+    },
+});
+export function createPostgresStoreProvider() {
+    return POSTGRES_STORE_PROVIDER;
+}
+/** Explicit bootstrap adapter for the concrete Postgres PipelineStore. */
+export function createPostgresBootstrapAdapter(store) {
+    // Kept in the Postgres composition module so its guard cannot leak into the
+    // Cloudflare-only bundle.
+    return createBootstrapStoreAdapter("postgres", store, (event, record) => bootstrapEventIdentityMatches(event, record));
+}

package/dist/store/types.d.ts

@@ -0,0 +1,205 @@
+import type { DeliverySource, DownstreamOutboxMessage } from "../downstream/types";
+import type { EventProvenance } from "../eventIdentity";
+/** A provider must reject canonical-key-only identity divergence before any durable write. */
+export declare class CanonicalEventIdentityConflictError extends Error {
+    readonly provider: string;
+    readonly eventId: string;
+    readonly code: string;
+    constructor(provider: string, eventId: string, message?: string);
+}
+export interface DeliveryLagRecord {
+    serviceId: string;
+    eventId: string;
+    tag: string;
+    enqueuedAt: number;
+    arrivedAt: number;
+    lagMs: number;
+}
+export interface StoredEvent {
+    serviceId: string;
+    /** C# logical-record Id; eventId remains the runtime alias. */
+    id: string;
+    eventId: string;
+    /** C# logical-record SortableUniqueId; suid remains the runtime alias. */
+    sortableUniqueId: string;
+    suid: string;
+    /** Byte-identical decoded UTF-8 JSON text. */
+    payload: string;
+    /** C# logical-record Tags in source emission order. */
+    tags: string[];
+    /** Complete durable tag membership, retained from the outbox envelope. */
+    eventTags: string[];
+    /** C# durable EventType = eventPayloadName. */
+    eventType: string;
+    timestamp: string;
+    /** C# DbEvent keeps serialized metadata nullable for imported historical rows. */
+    causationId: string | null;
+    correlationId: string | null;
+    executedUser: string | null;
+    /** G32 internal provenance; it is never persisted in dcb_events. */
+    provenance: EventProvenance;
+    /** G43 source digest retained by the global receipt authority when present. */
+    eventDigest?: string;
+    firstArrivedAt: number;
+    lastArrivedAt: number;
+    maxDeliveryLagMs: number;
+    arrivals: DeliveryLagRecord[];
+}
+/** Per-invocation diagnostic ownership; never part of admission semantics. */
+export interface DeliveryAttemptContext {
+    /** The platform Queue wrapper identity, when the caller has one. */
+    readonly queueMessageId?: string | null;
+    /** Registers diagnostic work with the current invocation lifetime. */
+    readonly waitUntil?: (promise: Promise<void>) => void;
+}
+export declare const DELIVERY_INCIDENT_CLASSIFICATIONS: readonly ["SUID_COLLISION", "ORDER_VIOLATION", "LINEAGE_MISMATCH", "ORDERING_DETECTOR_UNKNOWN"];
+export type DeliveryIncidentClassification = (typeof DELIVERY_INCIDENT_CLASSIFICATIONS)[number];
+/** A durable, idempotent fact for a poisoned delivery or provider ordering defect. */
+export interface DeliveryIncident {
+    serviceId: string;
+    identityKey: string;
+    classification: DeliveryIncidentClassification;
+    suid?: string;
+    existingEventId?: string;
+    incomingEventId?: string;
+    eventId?: string;
+    boundLineageId?: string;
+    incomingLineageId?: string;
+    observedAt: number;
+}
+export type DeliveryOutcome = {
+    outcome: "stored";
+    kind: "stored";
+    event: StoredEvent;
+    duplicate?: boolean;
+    mutationEvidence?: "first-admission" | "duplicate-admission" | "unverified";
+} | {
+    outcome: "suid-collision";
+    kind: "suid-collision";
+    incident: DeliveryIncident;
+} | {
+    outcome: "lineage-mismatch";
+    kind: "lineage-mismatch";
+    incident: DeliveryIncident;
+};
+/** A receipt is useful only when this complete event/membership join matches. */
+export interface GlobalReceiptJoin {
+    readonly serviceId: string;
+    readonly eventId: string;
+    readonly partitionTag: string;
+    readonly obligationSequence: number;
+    readonly eventDigest: string;
+    readonly membershipTag: string;
+    readonly receivedAt: number;
+}
+/**
+ * A projection checkpoint stores both its opaque projector state and its
+ * source SUID position. They advance atomically so a restarted poller cannot
+ * double-apply an event that was already reflected in durable state.
+ */
+export interface ProjectionCheckpoint {
+    serviceId: string;
+    projectionId: string;
+    lastSuid: string;
+    stateJson: string;
+    version: number;
+    updatedAt: number;
+}
+export interface ProjectionCheckpointAdvance {
+    serviceId: string;
+    projectionId: string;
+    /** Null means this is the first checkpoint for the projection. */
+    expectedLastSuid: string | null;
+    lastSuid: string;
+    stateJson: string;
+    version: number;
+    updatedAt: number;
+}
+export interface ProjectionLag {
+    serviceId: string;
+    projectionId: string;
+    tag: string;
+    checkpointSuid: string;
+    headSuid: string;
+    behindEvents: number;
+}
+export interface PendingArrivalRecord {
+    serviceId: string;
+    attemptId: string;
+    eventId: string;
+    suid: string;
+    expectedPaths: string[];
+    observedPaths: string[];
+    firstObservedAt: number;
+    lagBoundMs: number;
+}
+export type InconsistencyClassification = "MISSING_STABLE" | "EXCLUDED_AUDITED" | "RESOLVED_LATE";
+export interface InconsistencyFinding {
+    serviceId: string;
+    eventId: string;
+    path: string;
+    classification: InconsistencyClassification;
+    firstObservedAt: number;
+    lagBoundMs: number;
+    observedAt: number;
+}
+/** Adapter-only persistence port. The detector deliberately does not receive it. */
+export interface EventStore {
+    initialize(): Promise<void>;
+    recordDelivery(message: DownstreamOutboxMessage, arrivedAt: number, deliverySource?: DeliverySource, attemptContext?: DeliveryAttemptContext): Promise<DeliveryOutcome>;
+    readAllEvents(serviceId: string, since: string): Promise<StoredEvent[]>;
+    currentLagBound(serviceId: string, nowMs?: number): Promise<number>;
+    /** Conformance-only read diagnostic; production callers must not use it. */
+    lagBoundDiagnostics?(serviceId: string, nowMs: number): Promise<{
+        serviceIdUsed: string;
+        dynamicLagBoundMs: number;
+        rowFound: boolean;
+        rawEstimateMs: number | null;
+        rawObservedAt: number | null;
+        nowMs: number;
+    }>;
+    /** Cosmos uses this optional retryable async landing projection. */
+    projectDeliveryIncidents?(serviceId?: string): Promise<number>;
+    /**
+     * G44 source acknowledgement must be based on this read-back join, never
+     * on a transport acknowledgement or a receipt row by itself.
+     */
+    readGlobalReceiptJoin?(message: DownstreamOutboxMessage): Promise<GlobalReceiptJoin | undefined>;
+}
+/** Detector-only persistence port. It cannot write event rows by construction. */
+export interface DetectorStore {
+    upsertPending(message: DownstreamOutboxMessage, firstObservedAt: number, lagBoundMs: number): Promise<PendingArrivalRecord>;
+    listPending(serviceId?: string): Promise<PendingArrivalRecord[]>;
+    appendFinding(finding: InconsistencyFinding): Promise<void>;
+    hasFinding(serviceId: string, eventId: string, path: string, classification: InconsistencyClassification): Promise<boolean>;
+    listFindings(serviceId?: string, eventId?: string): Promise<InconsistencyFinding[]>;
+    appendDeliveryIncident(incident: DeliveryIncident): Promise<void>;
+    hasDeliveryIncident(serviceId: string, identityKey: string): Promise<boolean>;
+    listDeliveryIncidents(serviceId?: string): Promise<DeliveryIncident[]>;
+}
+/**
+ * Read-only event consumption plus durable checkpoint operations. This port
+ * intentionally omits recordDelivery, keeping SafeWindow projection unable to
+ * write event data by construction.
+ */
+export interface ProjectionStore {
+    readAllEvents(serviceId: string, since: string): Promise<StoredEvent[]>;
+    /** Optional D1-backed detector for a newly admitted lower SUID. */
+    findLateLowerSuid?(serviceId: string, checkpointSuid: string, checkpointUpdatedAt: number): Promise<StoredEvent | undefined>;
+    /** Structured detector result; unknown evidence must not become a refusal. */
+    findLateLowerSuidEvidence?(serviceId: string, checkpointSuid: string, checkpointUpdatedAt: number, generation?: number): Promise<{
+        readonly kind: "late-lower-suid" | "replay" | "miss" | "unknown";
+        readonly event?: StoredEvent;
+        readonly reason?: string;
+        /** Duration of the bounded detector query, when the provider measures it. */
+        readonly durationMs?: number;
+    }>;
+    currentLagBound(serviceId: string, nowMs?: number): Promise<number>;
+    listProjectionTags(serviceId: string): Promise<string[]>;
+    readProjectionCheckpoint(serviceId: string, projectionId: string): Promise<ProjectionCheckpoint | undefined>;
+    advanceProjectionCheckpoint(input: ProjectionCheckpointAdvance): Promise<boolean>;
+    projectionLag(serviceId: string, projectionId: string, tag: string): Promise<ProjectionLag>;
+    /** Catch-up must persist an ORDER_VIOLATION before failing closed. */
+    appendDeliveryIncident(incident: DeliveryIncident): Promise<void>;
+}
+export type PipelineStore = EventStore & DetectorStore & ProjectionStore;

package/dist/store/types.js

@@ -0,0 +1,18 @@
+/** A provider must reject canonical-key-only identity divergence before any durable write. */
+export class CanonicalEventIdentityConflictError extends Error {
+    provider;
+    eventId;
+    code = "CANONICAL_EVENT_IDENTITY_CONFLICT";
+    constructor(provider, eventId, message) {
+        super(message ?? `${provider} EventId ${eventId} conflicts with its canonical event identity`);
+        this.provider = provider;
+        this.eventId = eventId;
+        this.name = "CanonicalEventIdentityConflictError";
+    }
+}
+export const DELIVERY_INCIDENT_CLASSIFICATIONS = [
+    "SUID_COLLISION",
+    "ORDER_VIOLATION",
+    "LINEAGE_MISMATCH",
+    "ORDERING_DETECTOR_UNKNOWN",
+];

package/dist/tag/EventDigest.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Runtime implementation of the packet-owned G43 eventDigest v2 byte
+ * contract. The companion checker deliberately reimplements this framing
+ * from `contracts/g43-digest-spec.json`; do not share helpers with it.
+ */
+export declare const EVENT_DIGEST_DOMAIN_SEPARATOR = "sekiban-dcb-ts/eventDigest/v2";
+export interface EventDigestInput {
+    readonly serviceId: string;
+    readonly eventId: string;
+    readonly sortableUniqueId: string;
+    readonly eventType: string;
+    /** Exact persisted UTC spelling; this encoder never reparses it. */
+    readonly timestamp: string;
+    readonly allocatorLineageId?: string;
+    readonly attemptId: string;
+    readonly declaredTagSet: readonly string[];
+    /** Exact persisted payload bytes. Never decoded or text-normalised. */
+    readonly payload: Uint8Array;
+    /** Closed, explicitly excluded delivery-envelope fields. */
+    readonly causationId?: unknown;
+    readonly correlationId?: unknown;
+    readonly executedUser?: unknown;
+}
+export declare class EventDigestValidationError extends TypeError {
+    constructor(message: string);
+}
+/**
+ * Canonical set semantics are intentionally byte based: sorting uses UTF-8
+ * code units and exact byte-equal duplicates collapse to one element. Empty
+ * tag strings are representable by the byte contract even though normal tag
+ * admission rejects them before an event reaches this encoder.
+ */
+export declare function canonicalDeclaredTagSet(tags: readonly string[]): readonly string[];
+/**
+ * Produces the exact preimage bytes that are stored alongside an obligation.
+ * The caller can retain these canonical bytes while `eventDigestHex` hashes
+ * them without applying a second serialization.
+ */
+export declare function eventDigestBytes(input: EventDigestInput): Uint8Array;
+export declare function eventDigestHex(input: EventDigestInput): Promise<string>;

package/dist/tag/EventDigest.js

@@ -0,0 +1,158 @@
+/**
+ * Runtime implementation of the packet-owned G43 eventDigest v2 byte
+ * contract. The companion checker deliberately reimplements this framing
+ * from `contracts/g43-digest-spec.json`; do not share helpers with it.
+ */
+export const EVENT_DIGEST_DOMAIN_SEPARATOR = "sekiban-dcb-ts/eventDigest/v2";
+export class EventDigestValidationError extends TypeError {
+    constructor(message) {
+        super(message);
+        this.name = "EventDigestValidationError";
+    }
+}
+const encoder = new TextEncoder();
+const requiredFieldNames = [
+    "serviceId",
+    "eventId",
+    "sortableUniqueId",
+    "eventType",
+    "timestamp",
+    "attemptId",
+    "declaredTagSet",
+    "payload",
+];
+const optionalFieldNames = ["allocatorLineageId"];
+const excludedFieldNames = ["causationId", "correlationId", "executedUser"];
+const allowedFieldNames = new Set([...requiredFieldNames, ...optionalFieldNames, ...excludedFieldNames]);
+function byteCompare(left, right) {
+    const length = Math.min(left.byteLength, right.byteLength);
+    for (let index = 0; index < length; index += 1) {
+        const delta = left[index] - right[index];
+        if (delta !== 0)
+            return delta;
+    }
+    return left.byteLength - right.byteLength;
+}
+function concat(parts) {
+    const length = parts.reduce((total, part) => total + part.byteLength, 0);
+    const bytes = new Uint8Array(length);
+    let offset = 0;
+    for (const part of parts) {
+        bytes.set(part, offset);
+        offset += part.byteLength;
+    }
+    return bytes;
+}
+function lengthPrefix(length) {
+    if (!Number.isSafeInteger(length) || length < 0 || length > 0xffff_ffff) {
+        throw new EventDigestValidationError("eventDigest field length is outside uint32 range");
+    }
+    return Uint8Array.of((length >>> 24) & 0xff, (length >>> 16) & 0xff, (length >>> 8) & 0xff, length & 0xff);
+}
+function utf8(value) {
+    return encoder.encode(value);
+}
+function hasOwn(input, name) {
+    return Object.prototype.hasOwnProperty.call(input, name);
+}
+function requiredUtf8(input, name) {
+    const value = input[name];
+    if (typeof value !== "string") {
+        throw new EventDigestValidationError(`eventDigest required field ${name} is absent or not a string`);
+    }
+    return utf8(value);
+}
+function tagSetBytes(tags) {
+    const canonical = canonicalDeclaredTagSet(tags);
+    return concat(canonical.map((tag) => {
+        const bytes = utf8(tag);
+        return concat([lengthPrefix(bytes.byteLength), bytes]);
+    }));
+}
+/**
+ * Canonical set semantics are intentionally byte based: sorting uses UTF-8
+ * code units and exact byte-equal duplicates collapse to one element. Empty
+ * tag strings are representable by the byte contract even though normal tag
+ * admission rejects them before an event reaches this encoder.
+ */
+export function canonicalDeclaredTagSet(tags) {
+    if (!Array.isArray(tags) || !tags.every((tag) => typeof tag === "string")) {
+        throw new EventDigestValidationError("eventDigest declaredTagSet must contain only strings");
+    }
+    const encoded = tags
+        .map((tag) => ({ tag, bytes: utf8(tag) }))
+        .sort((left, right) => byteCompare(left.bytes, right.bytes));
+    const unique = [];
+    let previous;
+    for (const item of encoded) {
+        if (previous !== undefined && byteCompare(previous, item.bytes) === 0)
+            continue;
+        unique.push(item.tag);
+        previous = item.bytes;
+    }
+    return Object.freeze(unique);
+}
+function assertClosedProjection(input) {
+    for (const name of Object.keys(input)) {
+        if (!allowedFieldNames.has(name)) {
+            throw new EventDigestValidationError(`eventDigest field ${name} is neither included nor explicitly excluded`);
+        }
+    }
+    for (const name of requiredFieldNames) {
+        if (!hasOwn(input, name)) {
+            throw new EventDigestValidationError(`eventDigest required field ${name} is absent`);
+        }
+    }
+    if (!Array.isArray(input.declaredTagSet)) {
+        throw new EventDigestValidationError("eventDigest required field declaredTagSet is absent or invalid");
+    }
+    if (!(input.payload instanceof Uint8Array)) {
+        throw new EventDigestValidationError("eventDigest required field payload is absent or not raw bytes");
+    }
+    if (hasOwn(input, "allocatorLineageId") && typeof input.allocatorLineageId !== "string") {
+        throw new EventDigestValidationError("eventDigest optional field allocatorLineageId must be absent or a string");
+    }
+}
+/** `encodeField` exactly as specified by contracts/g43-digest-spec.json. */
+function encodeField(name, value) {
+    const nameBytes = utf8(name);
+    const present = value === undefined ? Uint8Array.of(0x00) : Uint8Array.of(0x01);
+    const valueBytes = value ?? new Uint8Array();
+    return concat([
+        present,
+        lengthPrefix(nameBytes.byteLength),
+        nameBytes,
+        lengthPrefix(valueBytes.byteLength),
+        valueBytes,
+    ]);
+}
+/**
+ * Produces the exact preimage bytes that are stored alongside an obligation.
+ * The caller can retain these canonical bytes while `eventDigestHex` hashes
+ * them without applying a second serialization.
+ */
+export function eventDigestBytes(input) {
+    assertClosedProjection(input);
+    const fields = [
+        ["serviceId", requiredUtf8(input, "serviceId")],
+        ["eventId", requiredUtf8(input, "eventId")],
+        ["sortableUniqueId", requiredUtf8(input, "sortableUniqueId")],
+        ["eventType", requiredUtf8(input, "eventType")],
+        ["timestamp", requiredUtf8(input, "timestamp")],
+        ["allocatorLineageId", hasOwn(input, "allocatorLineageId") ? utf8(input.allocatorLineageId) : undefined],
+        ["attemptId", requiredUtf8(input, "attemptId")],
+        ["declaredTagSet", tagSetBytes(input.declaredTagSet)],
+        ["payload", input.payload],
+    ];
+    return concat([
+        utf8(EVENT_DIGEST_DOMAIN_SEPARATOR),
+        Uint8Array.of(0x00),
+        ...fields.map(([name, value]) => encodeField(name, value)),
+    ]);
+}
+export async function eventDigestHex(input) {
+    const bytes = eventDigestBytes(input);
+    const source = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+    const digest = await crypto.subtle.digest("SHA-256", source);
+    return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}