@sekiban/dcb-runtime 0.2.0

package/dist/query/ProjectionQueryStore.js

@@ -0,0 +1,185 @@
+import { projectionIdFor } from "../projection/ProjectionRuntime";
+/** Select a query backing without allowing an HTTP request to provide a store. */
+export function selectQueryBacking(options) {
+    if (options.backing === "memory") {
+        if (options.memory === undefined)
+            throw new Error("A memory query backing is required when backing=memory");
+        return { backing: "memory", store: options.memory };
+    }
+    if (options.materializedView === undefined) {
+        throw new Error("A D1 materialized-view query backing is required when backing=d1-mv");
+    }
+    return { backing: "d1-mv", store: options.materializedView };
+}
+export const chooseQueryBacking = selectQueryBacking;
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+/** V1 SUID ordering is bytewise ordinal, not locale or parsed timestamp order. */
+export function compareSuid(left, right) {
+    const leftBytes = new TextEncoder().encode(left);
+    const rightBytes = new TextEncoder().encode(right);
+    const sharedLength = Math.min(leftBytes.length, rightBytes.length);
+    for (let index = 0; index < sharedLength; index += 1) {
+        const difference = leftBytes[index] - rightBytes[index];
+        if (difference !== 0) {
+            return difference;
+        }
+    }
+    return leftBytes.length - rightBytes.length;
+}
+function tagIdentity(tag, definition) {
+    const parts = tag.split(":");
+    if (parts.length !== 2 || parts.some((part) => part.length === 0) || parts[0] !== definition.tagGroup) {
+        return undefined;
+    }
+    return {
+        tag,
+        tagGroup: parts[0],
+        tagContent: parts[1],
+        tagProjector: definition.tagProjector,
+    };
+}
+/** Internal query entries retain JSON text rather than reconstructing base64. */
+function jsonText(value) {
+    return JSON.stringify(value);
+}
+function stateEntries(checkpoint) {
+    const decoded = JSON.parse(checkpoint.stateJson);
+    if (Array.isArray(decoded)) {
+        if (!decoded.every((entry) => isObject(entry) &&
+            isNonEmptyString(entry.eventId) &&
+            isNonEmptyString(entry.suid) &&
+            typeof entry.payload === "string")) {
+            throw new Error("Projected event-history state was malformed");
+        }
+        return decoded.map((entry) => ({
+            eventId: entry.eventId,
+            suid: entry.suid,
+            payload: entry.payload,
+        }));
+    }
+    // A composed consumer may register a domain projector whose durable state
+    // is not the test event-history array. Preserve the fixed V1 query shape by
+    // exposing one deterministic snapshot entry for that tag projection; the
+    // source SUID remains the checkpoint's opaque ordering fact.
+    if (isObject(decoded)) {
+        return [{
+                eventId: `projection:${checkpoint.projectionId}`,
+                suid: checkpoint.lastSuid,
+                payload: jsonText(decoded),
+            }];
+    }
+    throw new Error("Projected state was malformed");
+}
+function sameEntry(left, right) {
+    return left.suid === right.suid && left.payload === right.payload;
+}
+/**
+ * Builds a query snapshot exclusively from durable read-side checkpoints.
+ * A recently appended tag with no safe checkpoint is deliberately absent,
+ * which keeps an already-open page window stable while SafeWindow holds it.
+ */
+export async function readProjectedSnapshot(store, serviceId, definition) {
+    const entriesByEventId = new Map();
+    let readHead = "";
+    const tags = await store.listProjectionTags(serviceId);
+    for (const tag of tags) {
+        const identity = tagIdentity(tag, definition);
+        if (identity === undefined) {
+            continue;
+        }
+        const checkpoint = await store.readProjectionCheckpoint(serviceId, projectionIdFor(identity));
+        if (checkpoint === undefined) {
+            continue;
+        }
+        // The checkpoint is the authority for both the page rows and its safe
+        // head. In particular, an empty state still contributes its lastSuid.
+        if (compareSuid(checkpoint.lastSuid, readHead) > 0) {
+            readHead = checkpoint.lastSuid;
+        }
+        for (const serialized of stateEntries(checkpoint)) {
+            const entry = serialized;
+            const existing = entriesByEventId.get(entry.eventId);
+            if (existing !== undefined && !sameEntry(existing, entry)) {
+                throw new Error(`Projected EventId ${entry.eventId} has contradictory state`);
+            }
+            entriesByEventId.set(entry.eventId, entry);
+        }
+    }
+    return {
+        entries: [...entriesByEventId.values()].sort((left, right) => {
+            const bySuid = compareSuid(left.suid, right.suid);
+            return bySuid === 0 ? compareSuid(left.eventId, right.eventId) : bySuid;
+        }),
+        readHead,
+    };
+}
+export async function readProjectedEntries(store, serviceId, definition) {
+    return [...(await readProjectedSnapshot(store, serviceId, definition)).entries];
+}
+/** A requested SUID is observed only after a relevant durable source event and
+ * its mapped tag projector checkpoint both prove that observation. A mere
+ * source-row arrival is not enough to fabricate a query result.
+ */
+export async function projectionHasObserved(store, serviceId, definition, requestedSuid) {
+    const source = await store.readAllEvents(serviceId, "");
+    const target = source.find((event) => event.suid === requestedSuid);
+    if (target === undefined) {
+        return false;
+    }
+    for (const tag of target.eventTags) {
+        const identity = tagIdentity(tag, definition);
+        if (identity === undefined) {
+            continue;
+        }
+        const checkpoint = await store.readProjectionCheckpoint(serviceId, projectionIdFor(identity));
+        if (checkpoint !== undefined && compareSuid(checkpoint.lastSuid, requestedSuid) >= 0) {
+            return true;
+        }
+    }
+    return false;
+}
+/** Query rows through the selected backing while preserving typed paging inputs. */
+export async function readRowsFromBacking(selection, serviceId, viewId, definition, options = {}) {
+    if (selection.backing === "d1-mv") {
+        const rows = await selection.store.queryRows(serviceId, viewId, options);
+        return rows.map((row) => {
+            const value = row.value;
+            const eventId = isObject(value) && typeof value.eventId === "string" && value.eventId.length > 0
+                ? value.eventId
+                : row.rowKey;
+            return { eventId, suid: row.sourceSuid, payload: jsonText(value) };
+        }).sort((left, right) => {
+            const bySuid = compareSuid(left.suid, right.suid);
+            return bySuid === 0 ? compareSuid(left.eventId, right.eventId) : bySuid;
+        });
+    }
+    const entries = await readProjectedEntries(selection.store, serviceId, definition);
+    return options.descending === true ? [...entries].reverse() : entries;
+}
+/** Page in the backing when it supports composed SQL, otherwise preserve the legacy port. */
+export async function readRowsPageFromBacking(selection, serviceId, viewId, definition, options) {
+    if (selection.backing === "d1-mv" && selection.store.queryRowsWithTotal !== undefined) {
+        const page = await selection.store.queryRowsWithTotal(serviceId, viewId, options);
+        return {
+            entries: page.rows.map((row) => ({
+                eventId: isObject(row.value) && typeof row.value.eventId === "string" && row.value.eventId.length > 0 ? row.value.eventId : row.rowKey,
+                suid: row.sourceSuid,
+                payload: jsonText(row.value),
+            })),
+            totalCount: page.totalCount,
+            serverPaged: true,
+        };
+    }
+    if (selection.backing === "memory") {
+        const snapshot = await readProjectedSnapshot(selection.store, serviceId, definition);
+        const entries = options.descending === true ? [...snapshot.entries].reverse() : [...snapshot.entries];
+        return { entries, totalCount: entries.length, serverPaged: false, readHead: snapshot.readHead };
+    }
+    const entries = await readRowsFromBacking(selection, serviceId, viewId, definition, options);
+    return { entries, totalCount: entries.length, serverPaged: false };
+}

package/dist/query/QueryRegistry.d.ts

@@ -0,0 +1,22 @@
+export type QueryEndpoint = "query" | "list-query";
+/**
+ * Query types are deployed values, just like tag-state projectors. HTTP input
+ * selects one of these definitions; it cannot provide a reducer or query
+ * implementation of its own.
+ */
+export interface QueryDefinition {
+    readonly queryType: string;
+    readonly endpoint: QueryEndpoint;
+    readonly tagGroup: string;
+    readonly tagProjector: string;
+    /** MV view id used when the query backing is d1-mv; defaults to the projector id. */
+    readonly materializedViewId?: string;
+    readonly enabled: boolean;
+}
+export declare class QueryRegistry {
+    private readonly definitions;
+    constructor(definitions: readonly QueryDefinition[]);
+    resolve(queryType: string): QueryDefinition | undefined;
+}
+/** The test-only default query mapping; production consumers compose their own domain. */
+export declare const DEPLOYED_QUERY_REGISTRY: QueryRegistry;

package/dist/query/QueryRegistry.js

@@ -0,0 +1,36 @@
+export class QueryRegistry {
+    definitions;
+    constructor(definitions) {
+        const mapped = new Map();
+        for (const definition of definitions) {
+            if (definition.queryType.length === 0 || definition.tagGroup.length === 0 || definition.tagProjector.length === 0) {
+                throw new Error("Query definitions require non-empty queryType, tagGroup, and tagProjector");
+            }
+            if (mapped.has(definition.queryType)) {
+                throw new Error(`Query ${definition.queryType} was registered more than once`);
+            }
+            mapped.set(definition.queryType, definition);
+        }
+        this.definitions = mapped;
+    }
+    resolve(queryType) {
+        return this.definitions.get(queryType);
+    }
+}
+/** The test-only default query mapping; production consumers compose their own domain. */
+export const DEPLOYED_QUERY_REGISTRY = new QueryRegistry([
+    {
+        queryType: "GetTestCountQuery",
+        endpoint: "query",
+        tagGroup: "test",
+        tagProjector: "test-projector",
+        enabled: true,
+    },
+    {
+        queryType: "GetTestListQuery",
+        endpoint: "list-query",
+        tagGroup: "test",
+        tagProjector: "test-projector",
+        enabled: true,
+    },
+]);

package/dist/read/SerializedReadWorker.d.ts

@@ -0,0 +1,36 @@
+import { type ProjectorRegistry } from "../projection/ProjectorRegistry";
+import type { StoreProvider } from "../store/provider";
+import { type ServiceIdentityProvider } from "../service/ServiceIdentityProvider";
+export { TEST_TAG_STATE_PROJECTOR } from "../projection/ProjectorRegistry";
+interface ReadWorkerEnv {
+    TAG: DurableObjectNamespace;
+    /** SQLite-backed cache/replay owner for (serviceId, tag, projector). */
+    TAG_STATE?: DurableObjectNamespace;
+    POSTGRES_URL?: string;
+    HYPERDRIVE?: Hyperdrive;
+    /** Optional explicit D1 provider binding; Postgres remains the default. */
+    D1?: D1Database;
+    /** Set only by an authenticated deployment-verification lane. */
+    G11_VERIFICATION_ENABLED?: string;
+    /** Non-secret service identity configured per deployment. */
+    SDT_SERVICE_ID?: string;
+}
+/**
+ * V1 read surface. Tag-state validates a deploy-time projector and delegates
+ * its cache/replay to TagStateDO. It intentionally does not call the D1
+ * SafeWindow authority: the Tag-local G43 source RPC is the single source on
+ * this path, while latest-sortable retains its existing SafeWindow rule.
+ */
+export declare class SerializedReadWorker {
+    private readonly env;
+    private readonly serviceId;
+    private readonly registry;
+    private readonly storeProvider?;
+    constructor(env: ReadWorkerEnv, serviceId: string, registry?: ProjectorRegistry, storeProvider?: StoreProvider | undefined);
+    handle(request: Request): Promise<Response>;
+    private latestSortable;
+    private tagState;
+    private ensureWindowDeterminate;
+    private readTag;
+}
+export declare function handleSerializedRead(request: Request, env: ReadWorkerEnv, registry?: ProjectorRegistry, storeProvider?: StoreProvider, serviceIdentityProvider?: ServiceIdentityProvider): Promise<Response>;

package/dist/read/SerializedReadWorker.js

@@ -0,0 +1,225 @@
+import { DEPLOYED_PROJECTOR_REGISTRY, tagStateIdentitySyntaxFrom, } from "../projection/ProjectorRegistry";
+import { safeWindowCeilingExceeded } from "../projection/ProjectionRuntime";
+import { scopeIdFor, tagStateScopeIdentity } from "../scope/ScopeName";
+import { envServiceIdentity, requestServiceIdentity, } from "../service/ServiceIdentityProvider";
+export { TEST_TAG_STATE_PROJECTOR } from "../projection/ProjectorRegistry";
+class ReadFailure extends Error {
+    failingSubCall;
+    diagnostic;
+    constructor(failingSubCall, cause, diagnostic) {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        super(message);
+        this.failingSubCall = failingSubCall;
+        this.diagnostic = diagnostic;
+        this.name = cause instanceof Error ? cause.name : "UnknownError";
+    }
+}
+function json(body, status = 200) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { "content-type": "application/json; charset=utf-8" },
+    });
+}
+function error(status, code, message) {
+    return json({ error: message, code }, status);
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function tagFromBody(value) {
+    return isObject(value) && isNonEmptyString(value.tag)
+        ? { value: value.tag }
+        : { error: "tag must be a non-empty string" };
+}
+function tagStateIdentityFromBody(value) {
+    if (!isObject(value) || !isNonEmptyString(value.tagStateId)) {
+        return { error: "tagStateId must be a non-empty string" };
+    }
+    return tagStateIdentitySyntaxFrom(value.tagStateId);
+}
+/**
+ * V1 read surface. Tag-state validates a deploy-time projector and delegates
+ * its cache/replay to TagStateDO. It intentionally does not call the D1
+ * SafeWindow authority: the Tag-local G43 source RPC is the single source on
+ * this path, while latest-sortable retains its existing SafeWindow rule.
+ */
+export class SerializedReadWorker {
+    env;
+    serviceId;
+    registry;
+    storeProvider;
+    constructor(env, serviceId, registry = DEPLOYED_PROJECTOR_REGISTRY, storeProvider) {
+        this.env = env;
+        this.serviceId = serviceId;
+        this.registry = registry;
+        this.storeProvider = storeProvider;
+    }
+    async handle(request) {
+        const path = new URL(request.url).pathname;
+        if (request.method !== "POST") {
+            return error(404, "read_route_not_found", "Read routes require POST");
+        }
+        let body;
+        try {
+            body = await request.json();
+        }
+        catch {
+            return error(400, "validation_error", "Read request must be JSON");
+        }
+        try {
+            if (path === "/api/sekiban/serialized/tag-latest-sortable") {
+                return await this.latestSortable(body);
+            }
+            if (path === "/api/sekiban/serialized/tag-state") {
+                return await this.tagState(body);
+            }
+            return error(404, "read_route_not_found", "Read route was not found");
+        }
+        catch (caught) {
+            const body = { error: "Read could not determine the durable tag state", code: "internal_error" };
+            if (this.env.G11_VERIFICATION_ENABLED === "true" && caught instanceof ReadFailure) {
+                body.detail = {
+                    errorClass: caught.name,
+                    message: caught.message,
+                    failingSubCall: caught.failingSubCall,
+                    ...caught.diagnostic,
+                };
+            }
+            return json(body, 500);
+        }
+    }
+    async latestSortable(body) {
+        const parsed = tagFromBody(body);
+        if (parsed.value === undefined) {
+            return error(400, "validation_error", parsed.error ?? "Invalid tag-latest-sortable request");
+        }
+        await this.ensureWindowDeterminate();
+        const record = await this.readTag(parsed.value);
+        return json({
+            // Tag existence is the durable Tag record's fact, not a proxy for the
+            // record having emitted an event.  A created/identified tag can have an
+            // empty head and must still be observable as existing.
+            exists: record !== undefined,
+            lastSortableUniqueId: record?.head ?? "",
+        });
+    }
+    async tagState(body) {
+        const parsed = tagStateIdentityFromBody(body);
+        if (parsed.value === undefined) {
+            return error(400, "validation_error", parsed.error ?? "Invalid tag-state request");
+        }
+        const identity = parsed.value;
+        let projector;
+        try {
+            projector = this.registry.resolve(identity.tagProjector);
+        }
+        catch {
+            return error(503, "tag_state_projector_registry_failure", "Tag-state projector registry is unavailable");
+        }
+        if (projector === undefined) {
+            return error(404, "tag_state_unknown_projector", "Tag-state projector is not registered");
+        }
+        if (this.env.TAG_STATE === undefined) {
+            return error(503, "tag_state_source_frontier_failure", "Tag-state cache binding is unavailable");
+        }
+        const stateObject = this.env.TAG_STATE.get(scopeIdFor(this.env.TAG_STATE, {
+            serviceId: this.serviceId,
+            doClass: "tag-state",
+            identity: tagStateScopeIdentity(identity.tag, identity.tagProjector),
+        }));
+        let cached;
+        try {
+            cached = await stateObject.fetch(new Request("https://tag-state.internal/read", {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({
+                    serviceId: this.serviceId,
+                    tag: identity.tag,
+                    projectorId: identity.tagProjector,
+                }),
+            }));
+        }
+        catch {
+            return error(503, "tag_state_source_frontier_failure", "Tag-state source cache could not be reached");
+        }
+        if (cached.status !== 200)
+            return cached;
+        let projected;
+        try {
+            projected = await cached.json();
+        }
+        catch {
+            return error(503, "tag_state_cache_corrupt", "Tag-state cache returned an invalid result");
+        }
+        if (projected.kind !== "ready" || typeof projected.payload !== "string" ||
+            !Number.isSafeInteger(projected.version) || typeof projected.lastSortedUniqueId !== "string" ||
+            projected.projectorVersion !== projector.projectorVersion) {
+            return error(503, "tag_state_cache_corrupt", "Tag-state cache returned an inconsistent result");
+        }
+        return json({
+            payload: projected.payload,
+            version: projected.version,
+            lastSortedUniqueId: projected.lastSortedUniqueId,
+            tagGroup: identity.tagGroup,
+            tagContent: identity.tagContent,
+            tagProjector: identity.tagProjector,
+            tagPayloadName: projector.tagPayloadName,
+            projectorVersion: projector.projectorVersion,
+        });
+    }
+    async ensureWindowDeterminate() {
+        // Direct unit tests can exercise Tag DO determinacy with only TAG. The
+        // default provider has no backing store in that fixture. An explicit
+        // provider (including Cosmos) is always checked when it is configured.
+        if (this.storeProvider === undefined || this.storeProvider.isConfigured?.(this.env) === false) {
+            return;
+        }
+        try {
+            const store = this.storeProvider.create(this.env);
+            await store.initialize();
+            const nowMs = Date.now();
+            const diagnostic = await store.lagBoundDiagnostics?.(this.serviceId, nowMs);
+            const dynamicLagBoundMs = diagnostic?.dynamicLagBoundMs ?? await store.currentLagBound(this.serviceId, nowMs);
+            if (safeWindowCeilingExceeded(dynamicLagBoundMs)) {
+                throw new ReadFailure("ensureWindowDeterminate", new Error("Read-side SafeWindow ceiling exceeded; durable state is indeterminate"), diagnostic);
+            }
+        }
+        catch (caught) {
+            if (caught instanceof ReadFailure)
+                throw caught;
+            throw new ReadFailure("ensureWindowDeterminate", caught);
+        }
+    }
+    async readTag(tag) {
+        const url = new URL("https://serialized-read.internal/state");
+        url.searchParams.set("__tag", tag);
+        url.searchParams.set("__serviceId", this.serviceId);
+        const tagObject = this.env.TAG.get(scopeIdFor(this.env.TAG, {
+            serviceId: this.serviceId,
+            doClass: "tag",
+            identity: tag,
+        }));
+        try {
+            const response = await tagObject.fetch(new Request(url));
+            if (response.status === 404)
+                return undefined;
+            if (response.status !== 200)
+                throw new Error("Tag state lookup failed");
+            const record = (await response.json());
+            if (record.tag !== tag)
+                throw new Error("Tag identity changed during read");
+            return record;
+        }
+        catch (caught) {
+            throw new ReadFailure("readTag", caught);
+        }
+    }
+}
+export async function handleSerializedRead(request, env, registry = DEPLOYED_PROJECTOR_REGISTRY, storeProvider, serviceIdentityProvider) {
+    return new SerializedReadWorker(env, requestServiceIdentity(request, serviceIdentityProvider ?? envServiceIdentity(env), {
+        allowG11Verification: env.G11_VERIFICATION_ENABLED === "true",
+    }), registry, storeProvider).handle(request);
+}

package/dist/repair/RepairWorker.d.ts

@@ -0,0 +1,72 @@
+import type { ExclusionLookupPort } from "../downstream/ExclusionLookup";
+import { type CommitTraceClock, type CommitTraceProviderAdapter, type CommitTraceSink, type NativeTracing } from "../trace/CommitTrace";
+export type RepairMode = "dry-run" | "execute";
+/** Private repair.test interruption points, one for each durable saga boundary. */
+export type RepairFault = "after-lease-before-prepare" | "after-prepare-before-apply" | "after-apply-before-observation" | "after-verify-before-audit" | "after-audit-before-clear" | "after-clear-before-final-observation";
+export interface RepairWorkerEnv {
+    JOURNAL: DurableObjectNamespace;
+    TAG: DurableObjectNamespace;
+    SDT_SERVICE_ID?: string;
+}
+/** Observation seams only; repair RPC and durable facts are unchanged. */
+export interface RepairWorkerHooks {
+    commitTraceSink?: CommitTraceSink;
+    commitTraceClock?: CommitTraceClock;
+    commitTraceProvider?: CommitTraceProviderAdapter;
+    nativeTracing?: NativeTracing;
+}
+export interface RepairExecutionInput {
+    attemptIds: string[];
+    tags: string[];
+    actor: string;
+    owner: string;
+    mode: RepairMode;
+    maxItems: number;
+    checkpoint?: string;
+    fault?: RepairFault;
+}
+export interface RepairExecutionResult {
+    mode: RepairMode;
+    dryRun: boolean;
+    checkpoint: string | null;
+    processed: number;
+    rolledForward: number;
+    excludedAudited: number;
+    failedClosed: number;
+    cleared: number;
+    interrupted?: RepairFault;
+    pending: number;
+}
+declare class RepairWorkerFailure extends Error {
+}
+/**
+ * Per-request repair coordinator.  The only authority it trusts is a fresh
+ * Tag DO fact read; Journal records are append-only observations.
+ */
+export declare class RepairWorker {
+    private readonly env;
+    private readonly exclusions;
+    /** Tests and embedding hosts may supply a fixed identity explicitly. */
+    private readonly serviceId;
+    private readonly hooks;
+    constructor(env: RepairWorkerEnv, exclusions: ExclusionLookupPort, 
+    /** Tests and embedding hosts may supply a fixed identity explicitly. */
+    serviceId?: string, hooks?: RepairWorkerHooks);
+    execute(input: RepairExecutionInput): Promise<RepairExecutionResult>;
+    private executeTraced;
+    private enumerate;
+    private ensureLease;
+    private activeScope;
+    private unionScope;
+    private apply;
+    private audit;
+    private observe;
+    private recordClearedObservations;
+    private journalFor;
+    private tagFor;
+    private journalGet;
+    private journalPost;
+    private tagFacts;
+    private tagPost;
+}
+export { RepairWorkerFailure };