@sekiban/dcb-runtime 0.2.0

package/dist/composition.d.ts

@@ -0,0 +1,123 @@
+import type { DomainDefinition } from "@sekiban/dcb-core";
+import { type CommitWorkerEnv, type CommitWorkerHooks } from "./commit/CommitWorker";
+import type { DeliveryClass } from "./downstream/Doorbell";
+import { ProjectorRegistry } from "./projection/ProjectorRegistry";
+import { QueryRegistry, type QueryEndpoint } from "./query/QueryRegistry";
+/** A query value accepted by the public runtime composition surface. */
+export interface RuntimeQueryDefinition {
+    readonly queryType?: string;
+    readonly id?: string;
+    readonly name?: string;
+    readonly endpoint?: QueryEndpoint;
+    readonly tagGroup: string;
+    readonly tagProjector: string;
+    readonly materializedViewId?: string;
+    readonly enabled?: boolean;
+}
+/** Values which affect registration, never the serialized V1 wire format. */
+export interface RuntimeWorkerConfig {
+    /** Domain layer of the two-layer direct-delivery opt-in. */
+    readonly deliveryClass?: DeliveryClass;
+    readonly queries?: readonly RuntimeQueryDefinition[];
+    readonly queryDefinitions?: readonly RuntimeQueryDefinition[];
+    readonly projectorPayloadNames?: Readonly<Record<string, string>>;
+    readonly tagPayloadNames?: Readonly<Record<string, string>>;
+}
+/** A command already normalized by the authoring-to-runtime bridge. */
+export interface RuntimeCommandLike {
+    readonly id: string;
+    readonly name: string;
+    readonly parseInput: (value: unknown) => unknown;
+    readonly execute: (value: unknown, options?: unknown) => unknown | Promise<unknown>;
+    readonly handle: (value: unknown, options?: unknown) => unknown | Promise<unknown>;
+}
+/** Runtime command registry exposed by composition, without importing dcb-domain. */
+export declare class RuntimeCommandRegistry {
+    private readonly byId;
+    constructor(values?: readonly unknown[]);
+    resolve(id: string): RuntimeCommandLike | undefined;
+    list(): readonly RuntimeCommandLike[];
+    execute(id: string, value: unknown, options?: unknown): unknown | Promise<unknown>;
+}
+export interface RuntimeComposition {
+    readonly projectors: ProjectorRegistry;
+    readonly queries: QueryRegistry;
+    readonly commands: RuntimeCommandRegistry;
+}
+/** Structural bridge returned by @sekiban/dcb-domain without a reverse package import. */
+export interface RuntimeDomainLike {
+    readonly events?: readonly {
+        readonly eventPayloadName: string;
+        readonly parse?: (payload: unknown) => unknown;
+    }[];
+    readonly commands?: readonly unknown[];
+    readonly projectors?: readonly unknown[];
+    readonly queries?: readonly RuntimeQueryDefinition[];
+}
+/** Registered domain parsers are the exact-case admission authority. */
+export declare function registeredEventParsers(domain: DomainDefinition | RuntimeDomainLike | undefined): Readonly<Record<string, (payload: unknown) => unknown>>;
+export interface RuntimeCommitCandidateLike {
+    readonly kind: "candidate-envelope";
+    readonly now: string | number | bigint;
+    readonly events: readonly {
+        readonly eventType: string;
+        readonly eventName: string;
+        readonly payload: unknown;
+        readonly tags: readonly {
+            readonly id: string;
+        }[];
+        readonly ordinal: string;
+    }[];
+    readonly tags: readonly {
+        readonly id: string;
+    }[];
+    readonly readClaims: readonly {
+        readonly kind: "state" | "exists";
+        readonly projectorId?: string;
+        readonly tag: {
+            readonly id: string;
+        };
+        readonly head: string | null;
+    }[];
+}
+export interface RuntimeCommitAllocationLike {
+    readonly candidates: readonly {
+        readonly ordinal: string;
+        readonly suid: string;
+    }[];
+    readonly allocatorLineageId?: string;
+    readonly attemptId?: string;
+}
+export type RuntimeCommitPortResult = {
+    readonly kind: "accepted";
+} | {
+    readonly kind: "consistency-conflict";
+} | {
+    readonly kind: "unknown";
+    readonly error?: unknown;
+    readonly attemptId?: string;
+} | {
+    readonly kind: "rejected";
+    readonly reason?: string;
+    readonly code?: string;
+};
+export interface RuntimeCommitPort {
+    readonly commit: (candidate: RuntimeCommitCandidateLike, allocation?: RuntimeCommitAllocationLike) => Promise<RuntimeCommitPortResult>;
+}
+export interface RuntimeCommitPortOptions {
+    readonly requestUrl?: string;
+    readonly hooks?: Omit<CommitWorkerHooks, "registeredEventParsers">;
+    readonly registeredEventParsers?: Readonly<Record<string, (payload: unknown) => unknown>>;
+}
+/**
+ * Adapt the composed command port to the existing serialized commit Worker.
+ * The Worker owns admission, tag reservation/acquire, allocation, append, and
+ * response mapping; this adapter is intentionally only a transport seam.
+ */
+export declare function createRuntimeCommitPort(env: CommitWorkerEnv, options?: RuntimeCommitPortOptions): RuntimeCommitPort;
+/**
+ * Build the two private registries used by the HTTP runtime. The registries
+ * intentionally never cross the package entrypoint; consumers provide only
+ * immutable dcb-core definition values and registration metadata.
+ */
+export declare function composeRuntime(domain: DomainDefinition | RuntimeDomainLike | undefined, config?: RuntimeWorkerConfig): RuntimeComposition;

package/dist/composition.js

@@ -0,0 +1,237 @@
+import { handleSerializedCommit } from "./commit/CommitWorker";
+import { resolveDeliveryIdentity } from "./eventIdentity";
+import { DEPLOYED_PROJECTOR_REGISTRY, ProjectorRegistry, } from "./projection/ProjectorRegistry";
+import { DEPLOYED_QUERY_REGISTRY, QueryRegistry, } from "./query/QueryRegistry";
+/** Runtime command registry exposed by composition, without importing dcb-domain. */
+export class RuntimeCommandRegistry {
+    byId;
+    constructor(values = []) {
+        const entries = new Map();
+        for (const value of values) {
+            if (!isRuntimeCommandLike(value))
+                throw new Error("Runtime command definitions require id, parseInput, execute, and handle");
+            if (entries.has(value.id))
+                throw new Error(`Duplicate runtime command ${value.id}`);
+            entries.set(value.id, value);
+        }
+        this.byId = entries;
+    }
+    resolve(id) {
+        return this.byId.get(id);
+    }
+    list() {
+        return Object.freeze([...this.byId.values()]);
+    }
+    execute(id, value, options) {
+        const command = this.resolve(id);
+        if (command === undefined)
+            throw new Error(`Runtime command ${id} is not registered`);
+        return command.execute(value, options);
+    }
+}
+/** Registered domain parsers are the exact-case admission authority. */
+export function registeredEventParsers(domain) {
+    const entries = [];
+    for (const event of domain?.events ?? []) {
+        if (typeof event.parse === "function")
+            entries.push([event.eventPayloadName, event.parse]);
+    }
+    return Object.freeze(Object.fromEntries(entries));
+}
+function decodeStoredJson(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+function jsonBytes(value) {
+    const bytes = new TextEncoder().encode(JSON.stringify(value));
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary);
+}
+function isRuntimeBridgedProjector(definition) {
+    return "projectorId" in definition && "reduce" in definition;
+}
+function projectorFromDefinition(definition, config) {
+    const payloadNames = config.projectorPayloadNames ?? config.tagPayloadNames ?? {};
+    const payloadName = payloadNames[definition.id] ?? `${definition.id}State`;
+    const apply = (state, event) => {
+        const payload = decodeStoredJson(event.payload);
+        const identity = resolveDeliveryIdentity({ eventType: event.eventType, provenance: event.provenance }, "queue");
+        const eventName = identity.eventPayloadName;
+        const normalizedEventType = identity.key;
+        // Polling visits every registered projector for each discovered tag. A
+        // projector must therefore turn an event from another family into a
+        // state-preserving no-op before the authored bridge sees it.
+        if (!definition.subscribedEventTypes.includes(normalizedEventType))
+            return state;
+        if (isRuntimeBridgedProjector(definition)) {
+            return definition.apply(state, {
+                eventType: normalizedEventType,
+                eventPayloadName: eventName,
+                payload,
+                eventTags: event.eventTags,
+                provenance: event.provenance,
+            });
+        }
+        return definition.apply(state, {
+            eventName,
+            eventPayloadName: eventName,
+            // The legacy lane is only entered after provenance admission has
+            // proven a pre-G27 row. The authored projector still requires the
+            // canonical eventType field, so normalize that historical name to the
+            // immutable v1 registry identity before calling the real reducer.
+            eventType: normalizedEventType,
+            payload: payload,
+        });
+    };
+    return {
+        id: definition.id,
+        tagPayloadName: payloadName,
+        projectorVersion: String(definition.version),
+        initialState: () => definition.initialState,
+        apply,
+        serializeState: (state) => definition.serializeState(state),
+        deserializeState: (serialized) => definition.deserializeState(serialized),
+        payload: (state) => jsonBytes(state),
+        version: (state) => {
+            if (typeof state === "object" && state !== null && !Array.isArray(state)) {
+                const candidate = state.version;
+                if (typeof candidate === "number" && Number.isSafeInteger(candidate) && candidate >= 0)
+                    return candidate;
+            }
+            return 0;
+        },
+    };
+}
+function queryFromDefinition(value) {
+    const queryType = value.queryType ?? value.id ?? value.name;
+    if (queryType === undefined || queryType.length === 0) {
+        throw new Error("Runtime query definitions require queryType or id");
+    }
+    return {
+        queryType,
+        endpoint: value.endpoint ?? "query",
+        tagGroup: value.tagGroup,
+        tagProjector: value.tagProjector,
+        materializedViewId: value.materializedViewId ?? value.tagProjector,
+        enabled: value.enabled ?? true,
+    };
+}
+function isRuntimeCommandLike(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const candidate = value;
+    return typeof candidate.id === "string" && candidate.id.length > 0 &&
+        typeof candidate.name === "string" && typeof candidate.parseInput === "function" &&
+        typeof candidate.execute === "function" && typeof candidate.handle === "function";
+}
+function encodeJsonPayload(value) {
+    const bytes = new TextEncoder().encode(JSON.stringify(value));
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary);
+}
+function candidateToV1Envelope(candidate) {
+    const eventTags = new Set(candidate.events.flatMap((event) => event.tags.map((tag) => tag.id)));
+    const claims = new Map();
+    for (const claim of candidate.readClaims) {
+        // An observed empty head is the explicit V1 assert-empty sentinel. An
+        // unread/unknown claim remains null and is omitted from the wire.
+        if (eventTags.has(claim.tag.id) && claim.head !== null && !claims.has(claim.tag.id)) {
+            claims.set(claim.tag.id, claim.head);
+        }
+    }
+    return {
+        version: 1,
+        eventCandidates: candidate.events.map((event) => ({
+            payload: encodeJsonPayload(event.payload),
+            eventPayloadName: event.eventName,
+            tags: event.tags.map((tag) => tag.id),
+        })),
+        consistencyTags: [...claims].map(([tag, lastSortableUniqueId]) => ({ tag, lastSortableUniqueId })),
+    };
+}
+async function responseBody(response) {
+    try {
+        const value = await response.clone().json();
+        return typeof value === "object" && value !== null && !Array.isArray(value)
+            ? value
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function attemptIdFromResponse(body) {
+    const writtenEvents = body?.writtenEvents;
+    if (!Array.isArray(writtenEvents))
+        return undefined;
+    const metadata = writtenEvents[0];
+    if (typeof metadata !== "object" || metadata === null || Array.isArray(metadata))
+        return undefined;
+    const eventMetadata = metadata.eventMetadata;
+    if (typeof eventMetadata !== "object" || eventMetadata === null || Array.isArray(eventMetadata))
+        return undefined;
+    const causationId = eventMetadata.causationId;
+    return typeof causationId === "string" && causationId.length > 0 ? causationId : undefined;
+}
+/**
+ * Adapt the composed command port to the existing serialized commit Worker.
+ * The Worker owns admission, tag reservation/acquire, allocation, append, and
+ * response mapping; this adapter is intentionally only a transport seam.
+ */
+export function createRuntimeCommitPort(env, options = {}) {
+    return Object.freeze({
+        commit: async (candidate) => {
+            const request = new Request(options.requestUrl ?? "https://runtime.internal/api/sekiban/serialized/commit", {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify(candidateToV1Envelope(candidate)),
+            });
+            const response = await handleSerializedCommit(request, env, {
+                ...(options.hooks ?? {}),
+                registeredEventParsers: options.registeredEventParsers,
+            });
+            const body = await responseBody(response);
+            if (response.ok)
+                return { kind: "accepted" };
+            const code = typeof body?.code === "string" ? body.code : undefined;
+            if (code === "consistency_conflict" || response.status === 409) {
+                return { kind: "consistency-conflict" };
+            }
+            if (response.status === 504 || response.status >= 500) {
+                return {
+                    kind: "unknown",
+                    ...(attemptIdFromResponse(body) === undefined ? {} : { attemptId: attemptIdFromResponse(body) }),
+                    error: body,
+                };
+            }
+            return {
+                kind: "rejected",
+                ...(code === undefined ? {} : { code }),
+                ...(typeof body?.error === "string" ? { reason: body.error } : {}),
+            };
+        },
+    });
+}
+/**
+ * Build the two private registries used by the HTTP runtime. The registries
+ * intentionally never cross the package entrypoint; consumers provide only
+ * immutable dcb-core definition values and registration metadata.
+ */
+export function composeRuntime(domain, config = {}) {
+    if (domain === undefined && config.queries === undefined && config.queryDefinitions === undefined) {
+        return { projectors: DEPLOYED_PROJECTOR_REGISTRY, queries: DEPLOYED_QUERY_REGISTRY, commands: new RuntimeCommandRegistry() };
+    }
+    const projectors = new ProjectorRegistry((domain?.projectors ?? []).map((value) => projectorFromDefinition(value, config)));
+    const configuredQueries = config.queryDefinitions ?? config.queries;
+    const domainQueries = (domain?.queries ?? []);
+    const queries = new QueryRegistry((configuredQueries ?? domainQueries).map(queryFromDefinition));
+    return { projectors, queries, commands: new RuntimeCommandRegistry(domain?.commands ?? []) };
+}

package/dist/cosmos.d.ts

@@ -0,0 +1,11 @@
+import { CosmosEventStore, type CosmosDocumentClient, type CosmosStoreOptions } from "./store/CosmosEventStore";
+import type { StoreProvider } from "./store/provider";
+import { type BootstrapStoreAdapter } from "./bootstrap/BootstrapStoreAdapter";
+export { CosmosClientError, CosmosEventStore, CosmosRestClient, DEFAULT_COSMOS_CONTAINERS, compareCosmosSuid, } from "./store/CosmosEventStore";
+export type { CosmosContainerNames, CosmosDocumentClient, CosmosDocumentRecord, CosmosStoreOptions, CosmosWriteBoundary, } from "./store/CosmosEventStore";
+export interface CosmosStoreProviderConfig extends Omit<CosmosStoreOptions, "client"> {
+    readonly client?: CosmosDocumentClient;
+}
+/** Explicit opt-in provider; the default runtime composition never reads Cosmos config. */
+export declare function createCosmosStoreProvider(config: CosmosStoreProviderConfig): StoreProvider;
+export declare function createCosmosBootstrapAdapter(store: CosmosEventStore): BootstrapStoreAdapter;