@sekiban/dcb-runtime 0.2.0

package/dist/scope/ScopeName.js

@@ -0,0 +1,67 @@
+/**
+ * The one durable-object physical-name grammar used by the runtime.
+ *
+ * A scope name is deliberately not an application protocol value: C-0 makes
+ * old Durable Object instances unreachable when this grammar changes.  The
+ * service, class, and identity parts remain individually inspectable while
+ * `/` is the only grammar separator.
+ */
+export const DURABLE_OBJECT_SCOPE_CLASSES = Object.freeze([
+    "tag",
+    "tag-state",
+    "allocator",
+    "bootstrap",
+    "journal",
+]);
+export class ScopeNameError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ScopeNameError";
+    }
+}
+/** The existing deploy-time SDT_SERVICE_ID grammar, shared by scope names. */
+export function isScopeServiceId(value) {
+    return typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9._-]{0,95}$/.test(value);
+}
+function isScopeClass(value) {
+    return DURABLE_OBJECT_SCOPE_CLASSES.includes(value);
+}
+function requireScope(scope) {
+    if (!isScopeServiceId(scope.serviceId)) {
+        throw new ScopeNameError("serviceId must be a valid non-empty deployment service identity");
+    }
+    if (!isScopeClass(scope.doClass)) {
+        throw new ScopeNameError("doClass is not a registered Durable Object scope class");
+    }
+    if (scope.identity.length === 0 || scope.identity.includes("/")) {
+        throw new ScopeNameError("identity must be a non-empty string without '/'");
+    }
+    return scope;
+}
+/** Builds the canonical `${serviceId}/${doClass}/${identity}` physical name. */
+export function buildScopeName(scope) {
+    const value = requireScope(scope);
+    return `${value.serviceId}/${value.doClass}/${value.identity}`;
+}
+/** Parses and fully validates one canonical Durable Object physical name. */
+export function parseScopeName(name) {
+    const parts = name.split("/");
+    if (parts.length !== 3) {
+        throw new ScopeNameError("scope name must contain exactly three slash-delimited parts");
+    }
+    return requireScope({
+        serviceId: parts[0],
+        doClass: parts[1],
+        identity: parts[2],
+    });
+}
+export function scopeIdFor(namespace, scope) {
+    return namespace.idFromName(buildScopeName(scope));
+}
+/** A stable component encoding inside the single opaque tag-state identity. */
+export function tagStateScopeIdentity(tag, projectorId) {
+    if (tag.length === 0 || projectorId.length === 0) {
+        throw new ScopeNameError("tag-state scope requires non-empty tag and projector identity");
+    }
+    return `${encodeURIComponent(tag)}:${encodeURIComponent(projectorId)}`;
+}

package/dist/service/ServiceIdentityProvider.d.ts

@@ -0,0 +1,35 @@
+/** Miniflare-only request override. `.test` cannot be a deployed host. */
+export declare const TEST_SERVICE_ID_HEADER = "x-sdt-g9-test-service-id";
+/** Authenticated deployment-verification identity override. */
+export declare const G11_SERVICE_ID_HEADER = "x-sdt-g11-service-id";
+export type ServiceIdentityBehavior = "deployment" | "test-tld-header" | "g11-verification-header";
+export interface ServiceIdentityResolution {
+    readonly serviceId: string;
+    readonly behavior: ServiceIdentityBehavior;
+}
+export interface ServiceIdentityRequestOptions {
+    /** Explicitly enables the authenticated G11 deployment-verification header. */
+    readonly allowG11Verification?: boolean;
+}
+export interface ServiceIdentityProvider {
+    /** Resolve the configured deployment identity without request overrides. */
+    readonly deployment: () => ServiceIdentityResolution;
+    /** Resolve identity for a request, with `.test` and G11 behaviour explicit. */
+    readonly forRequest: (request: Request, options?: ServiceIdentityRequestOptions) => ServiceIdentityResolution;
+}
+export interface ServiceIdentityEnvironment {
+    readonly SDT_SERVICE_ID?: string;
+}
+export declare class ServiceIdentityMissingError extends Error {
+    constructor(message?: string);
+}
+/** The deployed default: the Worker environment is the identity authority. */
+export declare function envServiceIdentity(env: ServiceIdentityEnvironment): ServiceIdentityProvider;
+/**
+ * Host seam for embedding runtimes and tests. It has the same request
+ * behaviour as the environment-backed provider; only its configured source
+ * differs.
+ */
+export declare function injectableServiceIdentity(serviceId: string | undefined | (() => string | undefined)): ServiceIdentityProvider;
+export declare function requireServiceIdentity(provider: ServiceIdentityProvider): string;
+export declare function requestServiceIdentity(request: Request, provider: ServiceIdentityProvider, options?: ServiceIdentityRequestOptions): string;

package/dist/service/ServiceIdentityProvider.js

@@ -0,0 +1,56 @@
+import { isScopeServiceId } from "../scope/ScopeName";
+/** Miniflare-only request override. `.test` cannot be a deployed host. */
+export const TEST_SERVICE_ID_HEADER = "x-sdt-g9-test-service-id";
+/** Authenticated deployment-verification identity override. */
+export const G11_SERVICE_ID_HEADER = "x-sdt-g11-service-id";
+export class ServiceIdentityMissingError extends Error {
+    constructor(message = "SDT_SERVICE_ID is required and must be a non-empty deployment service identity") {
+        super(message);
+        this.name = "ServiceIdentityMissingError";
+    }
+}
+function requireServiceId(value) {
+    if (isScopeServiceId(value))
+        return value;
+    throw new ServiceIdentityMissingError();
+}
+function providerFor(readConfiguredServiceId) {
+    const deployment = () => ({
+        serviceId: requireServiceId(readConfiguredServiceId()),
+        behavior: "deployment",
+    });
+    return Object.freeze({
+        deployment,
+        forRequest(request, options = {}) {
+            const hostname = new URL(request.url).hostname;
+            const g11ServiceId = request.headers.get(G11_SERVICE_ID_HEADER);
+            const testServiceId = request.headers.get(TEST_SERVICE_ID_HEADER);
+            const g11Allowed = hostname.endsWith(".test") || options.allowG11Verification === true;
+            if (g11Allowed && isScopeServiceId(g11ServiceId)) {
+                return { serviceId: g11ServiceId, behavior: "g11-verification-header" };
+            }
+            if (hostname.endsWith(".test") && isScopeServiceId(testServiceId)) {
+                return { serviceId: testServiceId, behavior: "test-tld-header" };
+            }
+            return deployment();
+        },
+    });
+}
+/** The deployed default: the Worker environment is the identity authority. */
+export function envServiceIdentity(env) {
+    return providerFor(() => env.SDT_SERVICE_ID);
+}
+/**
+ * Host seam for embedding runtimes and tests. It has the same request
+ * behaviour as the environment-backed provider; only its configured source
+ * differs.
+ */
+export function injectableServiceIdentity(serviceId) {
+    return providerFor(typeof serviceId === "function" ? serviceId : () => serviceId);
+}
+export function requireServiceIdentity(provider) {
+    return provider.deployment().serviceId;
+}
+export function requestServiceIdentity(request, provider, options = {}) {
+    return provider.forRequest(request, options).serviceId;
+}

package/dist/store/CosmosEventStore.d.ts

@@ -0,0 +1,126 @@
+import type { DeliverySource, DownstreamOutboxMessage } from "../downstream/types";
+import { type DeliveryIncident, type DeliveryOutcome, type DetectorStore, type EventStore, type InconsistencyClassification, type InconsistencyFinding, type PendingArrivalRecord, type ProjectionCheckpoint, type ProjectionCheckpointAdvance, type ProjectionLag, type ProjectionStore, type StoredEvent } from "./types";
+type JsonObject = Record<string, unknown>;
+export interface CosmosDocumentRecord<T extends JsonObject = JsonObject> {
+    document: T;
+    etag?: string;
+}
+/** Minimal document operations used by the adapter; it is also the fault-test seam. */
+export interface CosmosDocumentClient {
+    initialize(): Promise<void>;
+    read<T extends JsonObject>(container: string, id: string, partitionKey: string): Promise<CosmosDocumentRecord<T> | undefined>;
+    create<T extends JsonObject>(container: string, document: T, partitionKey: string): Promise<CosmosDocumentRecord<T>>;
+    replace<T extends JsonObject>(container: string, document: T, partitionKey: string, etag?: string): Promise<boolean>;
+    /** Optional fault-test seam; the adapter deliberately never calls it. */
+    delete?(container: string, id: string, partitionKey: string): Promise<boolean>;
+    query<T extends JsonObject>(container: string, query: string, parameters: readonly {
+        name: string;
+        value: unknown;
+    }[], partitionKey?: string): Promise<CosmosDocumentRecord<T>[]>;
+}
+export type CosmosWriteBoundary = "event" | "lag" | "pending" | "finding" | "checkpoint" | "incident" | "incident-projection";
+export interface CosmosContainerNames {
+    readonly events: string;
+    readonly lagEstimates: string;
+    readonly pendingArrivals: string;
+    readonly findings: string;
+    readonly checkpoints: string;
+}
+/** Sekiban.Dcb CosmosEvent's immutable logical-record partition. */
+export declare const COSMOS_EVENT_PARTITION_KEY_PATH: "/pk";
+/** TS-only auxiliary documents retain a service-local partition. */
+export declare const COSMOS_AUXILIARY_PARTITION_KEY_PATH: "/serviceId";
+/** @deprecated Kept as an alias for auxiliary-container callers. */
+export declare const COSMOS_PARTITION_KEY_PATH: "/serviceId";
+export declare const DEFAULT_COSMOS_CONTAINERS: CosmosContainerNames;
+export interface CosmosContainerDefinition {
+    readonly name: string;
+    readonly partitionKeyPath: typeof COSMOS_EVENT_PARTITION_KEY_PATH | typeof COSMOS_AUXILIARY_PARTITION_KEY_PATH;
+    readonly partitionKeyValue: (serviceId: string, id?: string) => string;
+}
+/**
+ * The layout is data rather than a comment so every adapter initialization and
+ * contract fixture can inspect the same five service-partitioned containers.
+ */
+export declare function cosmosContainerDefinitions(containers?: CosmosContainerNames): readonly CosmosContainerDefinition[];
+export interface CosmosStoreOptions {
+    /** Cosmos account endpoint, including the trailing slash when supplied. */
+    readonly endpoint?: string;
+    /** Base64 account key. It is supplied by the runtime secret boundary only. */
+    readonly key?: string;
+    readonly database?: string;
+    readonly containers?: Partial<CosmosContainerNames>;
+    readonly fetcher?: typeof fetch;
+    readonly client?: CosmosDocumentClient;
+    readonly beforeWrite?: (boundary: CosmosWriteBoundary) => void | Promise<void>;
+}
+export declare class CosmosClientError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/** V1 SUIDs are opaque byte strings; never use locale or numeric ordering. */
+export declare function compareCosmosSuid(left: string, right: string): number;
+/** Fetch-based Cosmos SQL API client; it uses only Web APIs available in workerd. */
+export declare class CosmosRestClient implements CosmosDocumentClient {
+    private initialized;
+    private readonly endpoint;
+    private readonly key;
+    private readonly database;
+    private readonly fetcher;
+    private readonly containers;
+    constructor(options: Required<Pick<CosmosStoreOptions, "endpoint" | "key" | "database">> & Pick<CosmosStoreOptions, "fetcher" | "containers">);
+    initialize(): Promise<void>;
+    read<T extends JsonObject>(container: string, id: string, partitionKey: string): Promise<CosmosDocumentRecord<T> | undefined>;
+    create<T extends JsonObject>(container: string, document: T, partitionKey: string): Promise<CosmosDocumentRecord<T>>;
+    replace<T extends JsonObject>(container: string, document: T, partitionKey: string, etag?: string): Promise<boolean>;
+    query<T extends JsonObject>(container: string, query: string, parameters: readonly {
+        name: string;
+        value: unknown;
+    }[], partitionKey?: string): Promise<CosmosDocumentRecord<T>[]>;
+    private ensureResource;
+    private request;
+    private errorFrom;
+}
+export declare class CosmosEventStore implements EventStore, DetectorStore, ProjectionStore {
+    private initialized;
+    private readonly client;
+    private readonly containers;
+    private readonly beforeWrite?;
+    constructor(options: CosmosStoreOptions);
+    initialize(): Promise<void>;
+    recordDelivery(message: DownstreamOutboxMessage, arrivedAt: number, deliverySource?: DeliverySource): Promise<DeliveryOutcome>;
+    readAllEvents(serviceId: string, since: string): Promise<StoredEvent[]>;
+    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>;
+    upsertPending(message: DownstreamOutboxMessage, firstObservedAt: number, lagBoundMs: number): Promise<PendingArrivalRecord>;
+    listPending(serviceId?: string): Promise<PendingArrivalRecord[]>;
+    appendFinding(finding: InconsistencyFinding): Promise<void>;
+    appendDeliveryIncident(incident: DeliveryIncident): Promise<void>;
+    hasDeliveryIncident(serviceId: string, identityKey: string): Promise<boolean>;
+    listDeliveryIncidents(serviceId?: string): Promise<DeliveryIncident[]>;
+    /** Retryable async projection from the same-partition incident landing. */
+    projectDeliveryIncidents(serviceId?: string): Promise<number>;
+    private readLineageBinding;
+    private bindLineage;
+    /**
+     * Cosmos has no cross-document unique index. A same-partition SUID binding
+     * is the equivalent guard: the first EventId reserves the opaque SUID and
+     * every later delivery reuses or rejects that reservation before event
+     * mutation. Historical rows are still checked by eventDocuments above.
+     */
+    private reserveSuid;
+    private persistIncident;
+    private projectIncident;
+    hasFinding(serviceId: string, eventId: string, path: string, classification: InconsistencyClassification): Promise<boolean>;
+    listFindings(serviceId?: string, eventId?: string): Promise<InconsistencyFinding[]>;
+    private eventDocuments;
+    private eventOps;
+    private mutateEvent;
+    private mutateEventOps;
+    private updateLag;
+    private ready;
+}
+export {};