@sekiban/dcb-runtime 0.2.0

package/dist/projection/ProjectionRuntime.js

@@ -0,0 +1,346 @@
+import { DEPLOYED_PROJECTOR_REGISTRY, projectionEventFromTagEvent, } from "./ProjectorRegistry";
+import { decayedLagEstimateMs, MAX_PUBLISHED_SAFE_WINDOW_MS, PUBLISHED_SAFE_WINDOW_MS, safeWindowCeilingExceeded, safeWindowCutoffSuid, isSortableUniqueIdSafeAt, safeWindowMs, } from "../safeWindow";
+import { assertSortableUniqueId, isSortableUniqueId } from "../allocator/SortableUniqueId";
+/** Published V1 read-side SafeWindow. It never authorizes a commit. */
+export { MAX_PUBLISHED_SAFE_WINDOW_MS, PUBLISHED_SAFE_WINDOW_MS, safeWindowCeilingExceeded, safeWindowCutoffSuid, safeWindowMs, };
+const MAX_CHECKPOINT_CAS_RETRIES = 8;
+export class ProjectionCheckpointCorruption extends Error {
+    constructor(cause) {
+        super("Projection checkpoint state failed validation");
+        this.name = "ProjectionCheckpointCorruption";
+        if (cause !== undefined)
+            this.cause = cause;
+    }
+}
+/**
+ * Live projection identities have independent checkpoints. A bounded worker
+ * pool prevents a large retained tag set from monopolizing one cron
+ * invocation while keeping D1/CAS pressure finite and deterministic.
+ */
+export const MAX_LIVE_PROJECTION_CONCURRENCY = 8;
+/**
+ * Validate the allocator fact at the one boundary that decides whether a
+ * safe view may advance.  Callers that only inspect, rebuild, or perform an
+ * ordinary SafeWindow catch-up must not call this function.
+ */
+export function validatedClosedPrefixSuid(options, consumerServiceId) {
+    const certificate = options.closedPrefixCertificate;
+    if (typeof consumerServiceId !== "string" ||
+        consumerServiceId.length === 0 ||
+        typeof certificate !== "object" ||
+        certificate === null ||
+        Array.isArray(certificate)) {
+        throw new Error("ordering_certificate_unavailable");
+    }
+    if (certificate.certificateVersion !== 1 ||
+        certificate.authority !== "allocator-transaction" ||
+        certificate.status !== "ready" ||
+        typeof certificate.serviceId !== "string" ||
+        certificate.serviceId.length === 0 ||
+        typeof certificate.allocatorLineageId !== "string" ||
+        certificate.allocatorLineageId.length === 0 ||
+        !Number.isSafeInteger(certificate.unresolvedCount) ||
+        certificate.unresolvedCount < 0 ||
+        (certificate.closedPrefixSuid !== null && !isSortableUniqueId(certificate.closedPrefixSuid))) {
+        throw new Error("ordering_certificate_unavailable");
+    }
+    if (options.expectedServiceId === undefined || options.expectedAllocatorLineageId === undefined) {
+        throw new Error("ordering_certificate_consumer_unbound");
+    }
+    if (options.expectedServiceId !== consumerServiceId || certificate.serviceId !== consumerServiceId) {
+        throw new Error("ordering_certificate_consumer_mismatch");
+    }
+    if (certificate.allocatorLineageId !== options.expectedAllocatorLineageId) {
+        throw new Error("ordering_certificate_lineage_mismatch");
+    }
+    if (options.closedPrefixSuid !== undefined &&
+        options.closedPrefixSuid !== certificate.closedPrefixSuid) {
+        throw new Error("ordering_certificate_mismatch");
+    }
+    return certificate.closedPrefixSuid;
+}
+/**
+ * Validate the existing completeness handoff independently of the allocator
+ * certificate.  The returned bound is deliberately separate from
+ * `maximumSuid`, whose G44 stop condition remains an independent gate.
+ */
+export function validatedSafeViewCoverageMaximumSuid(context, consumerServiceId) {
+    if (typeof consumerServiceId !== "string" ||
+        consumerServiceId.length === 0 ||
+        typeof context !== "object" ||
+        context === null ||
+        Array.isArray(context)) {
+        throw new Error("ordering_coverage_unavailable");
+    }
+    if (context.authority !== "g44-g62" ||
+        context.startOfPass !== "PROVEN" ||
+        context.serviceId !== consumerServiceId ||
+        typeof context.serviceId !== "string" ||
+        context.serviceId.length === 0 ||
+        !["FULL", "SETTLED", "BLOCK/UNSETTLED"].includes(context.kind) ||
+        (context.frontierSuid !== null && !isSortableUniqueId(context.frontierSuid))) {
+        throw new Error("ordering_coverage_unavailable");
+    }
+    if (context.kind === "FULL") {
+        if (context.frontierSuid !== null)
+            throw new Error("ordering_coverage_unavailable");
+        return undefined;
+    }
+    return context.frontierSuid;
+}
+function compareSuid(left, right) {
+    const leftBytes = new TextEncoder().encode(left);
+    const rightBytes = new TextEncoder().encode(right);
+    const shared = Math.min(leftBytes.length, rightBytes.length);
+    for (let index = 0; index < shared; index += 1) {
+        const difference = leftBytes[index] - rightBytes[index];
+        if (difference !== 0) {
+            return difference;
+        }
+    }
+    return leftBytes.length - rightBytes.length;
+}
+function orderViolationIncident(serviceId, event, previousSuid) {
+    return {
+        serviceId,
+        identityKey: `ORDER_VIOLATION|${serviceId}|${previousSuid}|${event.suid}|${event.eventId}`,
+        classification: "ORDER_VIOLATION",
+        suid: event.suid,
+        eventId: event.eventId,
+        observedAt: event.lastArrivedAt,
+    };
+}
+function stateFromCheckpoint(projector, checkpoint) {
+    if (checkpoint === undefined)
+        return projector.initialState();
+    try {
+        return projector.deserializeState(checkpoint.stateJson);
+    }
+    catch (error) {
+        throw new ProjectionCheckpointCorruption(error);
+    }
+}
+function projectionEventFromStored(event) {
+    assertSortableUniqueId(event.suid);
+    return {
+        eventId: event.eventId,
+        suid: event.suid,
+        payload: event.payload,
+        eventTags: event.eventTags,
+        eventType: event.eventType,
+        provenance: "g32",
+    };
+}
+function checkpointFor(serviceId, projectionId, event, state, projector, updatedAt) {
+    return {
+        serviceId,
+        projectionId,
+        lastSuid: event.suid,
+        stateJson: projector.serializeState(state),
+        version: projector.version(state),
+        updatedAt,
+    };
+}
+export function projectionIdFor(identity) {
+    return `tag-state:${identity.tagGroup}:${identity.tagContent}:${identity.tagProjector}`;
+}
+export { decayedLagEstimateMs };
+/**
+ * Deterministically rebuilds one tag-state from the Tag DO's authoritative
+ * durable event list. This is the on-demand §5.3 catch-up path; it does not
+ * mutate the read-side SafeWindow checkpoint.
+ */
+export function catchUpDurableTagState(projector, events) {
+    const ordered = events.map(projectionEventFromTagEvent).sort((left, right) => compareSuid(left.suid, right.suid));
+    let state = projector.initialState();
+    let previousSuid;
+    for (const event of ordered) {
+        if (previousSuid !== undefined && compareSuid(previousSuid, event.suid) >= 0) {
+            throw new Error("Durable tag event history was not strictly SUID ordered");
+        }
+        state = projector.apply(state, event);
+        previousSuid = event.suid;
+    }
+    return {
+        payload: projector.payload(state),
+        version: projector.version(state),
+        stateJson: projector.serializeState(state),
+    };
+}
+/**
+ * Polls a global SUID source for one tag/projector. Every source event advances
+ * the durable checkpoint, while the registered reducer changes state only for
+ * events whose complete durable tag membership includes the target tag.
+ */
+export class ProjectionRuntime {
+    store;
+    registry;
+    constructor(store, registry = DEPLOYED_PROJECTOR_REGISTRY) {
+        this.store = store;
+        this.registry = registry;
+    }
+    async catchUp(serviceId, identity, nowMs, hooks = {}, options = {}) {
+        const projector = this.registry.resolve(identity.tagProjector);
+        if (projector === undefined) {
+            throw new Error(`Projector ${identity.tagProjector} is not registered`);
+        }
+        const safeViewAdvance = options.requireClosedPrefixCertificate === true;
+        const certifiedClosedPrefixSuid = safeViewAdvance
+            ? validatedClosedPrefixSuid(options, serviceId)
+            : undefined;
+        const coverageMaximumSuid = safeViewAdvance
+            ? validatedSafeViewCoverageMaximumSuid(options.safeViewCoverage, serviceId)
+            : undefined;
+        const dynamicLagBoundMs = await this.store.currentLagBound(serviceId, nowMs);
+        const windowMs = safeWindowMs(dynamicLagBoundMs);
+        if (safeWindowCeilingExceeded(dynamicLagBoundMs)) {
+            const projectionId = projectionIdFor(identity);
+            return {
+                projectorId: identity.tagProjector,
+                tag: identity.tag,
+                checkpoint: await this.store.readProjectionCheckpoint(serviceId, projectionId),
+                dynamicLagBoundMs,
+                safeWindowMs: windowMs,
+                indeterminate: true,
+                advancedSourceEvents: 0,
+                appliedEvents: 0,
+            };
+        }
+        const projectionId = projectionIdFor(identity);
+        for (let retry = 0; retry < MAX_CHECKPOINT_CAS_RETRIES; retry += 1) {
+            let checkpoint = await this.store.readProjectionCheckpoint(serviceId, projectionId);
+            let state = stateFromCheckpoint(projector, checkpoint);
+            const sourceEvents = await this.store.readAllEvents(serviceId, checkpoint?.lastSuid ?? "");
+            let advancedSourceEvents = 0;
+            let appliedEvents = 0;
+            let casConflict = false;
+            let previousSuid = checkpoint?.lastSuid;
+            for (const event of sourceEvents) {
+                if (previousSuid !== undefined && compareSuid(previousSuid, event.suid) >= 0) {
+                    await this.store.appendDeliveryIncident(orderViolationIncident(serviceId, event, previousSuid));
+                    throw new Error("Projection source was not strictly SUID ordered");
+                }
+                if (certifiedClosedPrefixSuid === null || (certifiedClosedPrefixSuid !== undefined && compareSuid(event.suid, certifiedClosedPrefixSuid) > 0)) {
+                    break;
+                }
+                // A G44 BLOCK/UNSETTLED tick may still poll live projections, but it
+                // must remain fenced by the last settled source frontier. `null`
+                // deliberately permits no source advancement; it is not an empty
+                // unbounded frontier.
+                if (options.maximumSuid === null || (options.maximumSuid !== undefined && compareSuid(event.suid, options.maximumSuid) > 0)) {
+                    break;
+                }
+                if (safeViewAdvance && (coverageMaximumSuid === null || (coverageMaximumSuid !== undefined && compareSuid(event.suid, coverageMaximumSuid) > 0))) {
+                    break;
+                }
+                // Stop at the first unsafe source event. Because the source is SUID
+                // ordered, advancing past it could skip a delayed lower SUID.
+                assertSortableUniqueId(event.suid);
+                if (!isSortableUniqueIdSafeAt(event.suid, nowMs, dynamicLagBoundMs)) {
+                    return {
+                        projectorId: identity.tagProjector,
+                        tag: identity.tag,
+                        checkpoint,
+                        dynamicLagBoundMs,
+                        safeWindowMs: windowMs,
+                        indeterminate: false,
+                        advancedSourceEvents,
+                        appliedEvents,
+                    };
+                }
+                const appliesToTag = event.eventTags.includes(identity.tag);
+                const nextState = appliesToTag ? projector.apply(state, projectionEventFromStored(event)) : state;
+                const nextCheckpoint = checkpointFor(serviceId, projectionId, event, nextState, projector, nowMs);
+                await hooks.beforeCheckpoint?.(event, nextCheckpoint);
+                const advanced = await this.store.advanceProjectionCheckpoint({
+                    ...nextCheckpoint,
+                    expectedLastSuid: checkpoint?.lastSuid ?? null,
+                });
+                if (!advanced) {
+                    casConflict = true;
+                    break;
+                }
+                checkpoint = nextCheckpoint;
+                state = nextState;
+                previousSuid = event.suid;
+                advancedSourceEvents += 1;
+                if (appliesToTag) {
+                    appliedEvents += 1;
+                }
+                await hooks.afterCheckpoint?.(event, nextCheckpoint);
+            }
+            if (!casConflict) {
+                return {
+                    projectorId: identity.tagProjector,
+                    tag: identity.tag,
+                    checkpoint,
+                    dynamicLagBoundMs,
+                    safeWindowMs: windowMs,
+                    indeterminate: false,
+                    advancedSourceEvents,
+                    appliedEvents,
+                };
+            }
+        }
+        throw new Error("Projection checkpoint did not converge after concurrent updates");
+    }
+    async pollRegistered(serviceId, nowMs, maximumSuid, closedPrefixSuid, closedPrefixCertificate, requireClosedPrefixCertificate = false, expectedServiceId, expectedAllocatorLineageId, safeViewCoverage) {
+        const safeViewAdvance = requireClosedPrefixCertificate === true;
+        if (safeViewAdvance) {
+            validatedClosedPrefixSuid({
+                closedPrefixSuid,
+                closedPrefixCertificate,
+                expectedServiceId,
+                expectedAllocatorLineageId,
+            }, serviceId);
+            validatedSafeViewCoverageMaximumSuid(safeViewCoverage, serviceId);
+        }
+        const tags = await this.store.listProjectionTags(serviceId);
+        const jobs = [];
+        for (const tag of tags) {
+            for (const projector of this.registry.registered()) {
+                if (tagStateIdentityForPolledTag(tag, projector.id, this.registry) !== undefined)
+                    jobs.push({ tag, projector: projector.id });
+            }
+        }
+        const results = [];
+        let next = 0;
+        const worker = async () => {
+            for (;;) {
+                const index = next;
+                next += 1;
+                const job = jobs[index];
+                if (job === undefined)
+                    return;
+                const identity = tagStateIdentityForPolledTag(job.tag, job.projector, this.registry);
+                if (identity !== undefined) {
+                    const options = safeViewAdvance
+                        ? {
+                            maximumSuid,
+                            closedPrefixSuid,
+                            closedPrefixCertificate,
+                            requireClosedPrefixCertificate: true,
+                            expectedServiceId,
+                            expectedAllocatorLineageId,
+                            safeViewCoverage,
+                        }
+                        : { maximumSuid };
+                    results[index] = await this.catchUp(serviceId, identity, nowMs, {}, options);
+                }
+            }
+        };
+        const workerCount = Math.min(MAX_LIVE_PROJECTION_CONCURRENCY, jobs.length);
+        await Promise.all(Array.from({ length: workerCount }, () => worker()));
+        return results;
+    }
+}
+function tagStateIdentityForPolledTag(tag, projector, registry) {
+    const parts = tag.split(":");
+    if (parts.length !== 2 || parts.some((part) => part.length === 0)) {
+        return undefined;
+    }
+    const [tagGroup, tagContent] = parts;
+    return registry.resolve(projector) === undefined
+        ? undefined
+        : { tag, tagGroup: tagGroup, tagContent: tagContent, tagProjector: projector };
+}

package/dist/projection/ProjectorRegistry.d.ts

@@ -0,0 +1,51 @@
+import type { TagEvent } from "../tag/types";
+export declare const TEST_TAG_STATE_PROJECTOR = "test-projector";
+export interface ProjectionEvent {
+    eventId: string;
+    suid: string;
+    payload: string;
+    eventTags: readonly string[];
+    eventType: string;
+    provenance: "g32";
+}
+/**
+ * Projectors are TypeScript values registered at deploy time. The HTTP input
+ * can select only an already registered ID; it can never install code or a
+ * reducer dynamically.
+ */
+export interface TagStateProjector {
+    readonly id: string;
+    readonly tagPayloadName: string;
+    readonly projectorVersion: string;
+    initialState(): unknown;
+    apply(state: unknown, event: ProjectionEvent): unknown;
+    serializeState(state: unknown): string;
+    deserializeState(serialized: string): unknown;
+    payload(state: unknown): string;
+    version(state: unknown): number;
+}
+export interface TagStateIdentity {
+    tag: string;
+    tagGroup: string;
+    tagContent: string;
+    tagProjector: string;
+}
+export declare class ProjectorRegistry {
+    private readonly projectors;
+    constructor(projectors: readonly TagStateProjector[]);
+    resolve(projectorId: string): TagStateProjector | undefined;
+    registered(): readonly TagStateProjector[];
+}
+/** The test-only default registry; production consumers compose their own domain. */
+export declare const DEPLOYED_TAG_STATE_PROJECTORS: readonly TagStateProjector[];
+export declare const DEPLOYED_PROJECTOR_REGISTRY: ProjectorRegistry;
+/** Parse the public tag-state identifier without consulting a projector authority. */
+export declare function tagStateIdentitySyntaxFrom(tagStateId: string): {
+    value?: TagStateIdentity;
+    error?: string;
+};
+export declare function tagStateIdentityFrom(tagStateId: string, registry?: ProjectorRegistry): {
+    value?: TagStateIdentity;
+    error?: string;
+};
+export declare function projectionEventFromTagEvent(event: TagEvent): ProjectionEvent;

package/dist/projection/ProjectorRegistry.js

@@ -0,0 +1,116 @@
+import { assertSortableUniqueId } from "../allocator/SortableUniqueId";
+export const TEST_TAG_STATE_PROJECTOR = "test-projector";
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function base64Json(value) {
+    const bytes = new TextEncoder().encode(JSON.stringify(value));
+    let binary = "";
+    for (const byte of bytes) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary);
+}
+function eventHistoryStateFrom(value) {
+    if (!Array.isArray(value) ||
+        !value.every((entry) => typeof entry === "object" && entry !== null &&
+            isNonEmptyString(entry.eventId) &&
+            typeof entry.payload === "string" &&
+            isNonEmptyString(entry.suid))) {
+        throw new Error("Event-history projector durable state was malformed");
+    }
+    return value.map((entry) => {
+        const record = entry;
+        return {
+            eventId: record.eventId,
+            payload: record.payload,
+            suid: record.suid,
+        };
+    });
+}
+function eventHistoryProjector(id, tagPayloadName) {
+    return {
+        id,
+        tagPayloadName,
+        projectorVersion: "1",
+        initialState: () => [],
+        apply(state, event) {
+            const current = eventHistoryStateFrom(state);
+            return [...current, { eventId: event.eventId, payload: event.payload, suid: event.suid }];
+        },
+        serializeState(state) {
+            return JSON.stringify(eventHistoryStateFrom(state));
+        },
+        deserializeState(serialized) {
+            return eventHistoryStateFrom(JSON.parse(serialized));
+        },
+        payload(state) {
+            return base64Json(eventHistoryStateFrom(state));
+        },
+        version(state) {
+            return eventHistoryStateFrom(state).length;
+        },
+    };
+}
+const TEST_PROJECTOR = eventHistoryProjector(TEST_TAG_STATE_PROJECTOR, "SerializedDcbTestTagState");
+export class ProjectorRegistry {
+    projectors;
+    constructor(projectors) {
+        const entries = new Map();
+        for (const projector of projectors) {
+            if (entries.has(projector.id)) {
+                throw new Error(`Projector ${projector.id} was registered more than once`);
+            }
+            entries.set(projector.id, projector);
+        }
+        this.projectors = entries;
+    }
+    resolve(projectorId) {
+        return this.projectors.get(projectorId);
+    }
+    registered() {
+        return [...this.projectors.values()];
+    }
+}
+/** The test-only default registry; production consumers compose their own domain. */
+export const DEPLOYED_TAG_STATE_PROJECTORS = [
+    TEST_PROJECTOR,
+];
+export const DEPLOYED_PROJECTOR_REGISTRY = new ProjectorRegistry(DEPLOYED_TAG_STATE_PROJECTORS);
+/** Parse the public tag-state identifier without consulting a projector authority. */
+export function tagStateIdentitySyntaxFrom(tagStateId) {
+    const parts = tagStateId.split(":");
+    if (parts.length !== 3 || !parts.every(isNonEmptyString)) {
+        return { error: "tagStateId must be group:content:projector" };
+    }
+    const [tagGroup, tagContent, tagProjector] = parts;
+    return {
+        value: {
+            tag: `${tagGroup}:${tagContent}`,
+            tagGroup: tagGroup,
+            tagContent: tagContent,
+            tagProjector: tagProjector,
+        },
+    };
+}
+export function tagStateIdentityFrom(tagStateId, registry = DEPLOYED_PROJECTOR_REGISTRY) {
+    const parsed = tagStateIdentitySyntaxFrom(tagStateId);
+    if (parsed.value === undefined)
+        return parsed;
+    const { tagProjector } = parsed.value;
+    if (registry.resolve(tagProjector) === undefined) {
+        return { error: "tagStateId names an unregistered projector" };
+    }
+    return parsed;
+}
+export function projectionEventFromTagEvent(event) {
+    assertSortableUniqueId(event.suid);
+    return {
+        eventId: event.eventId,
+        suid: event.suid,
+        payload: event.payload,
+        eventTags: event.eventTags,
+        eventType: event.eventType,
+        provenance: "g32",
+    };
+}

package/dist/query/ProjectionQueryStore.d.ts

@@ -0,0 +1,102 @@
+import type { ProjectionStore } from "../store/types";
+import type { QueryDefinition } from "./QueryRegistry";
+import type { MaterializedViewListOptions, MaterializedViewListPage, MaterializedViewQueryOptions, MaterializedViewOrderingQuarantine, MaterializedViewRow, MaterializedViewWaitForState } from "../mv/MaterializedViewStore";
+import type { UnsafeComposedPage } from "../mv/UnsafeWindowMaterializedView";
+/** The query surface can only inspect durable source and projection facts. */
+export type QueryProjectionStore = Pick<ProjectionStore, "readAllEvents" | "currentLagBound" | "listProjectionTags" | "readProjectionCheckpoint">;
+/**
+ * SDT-G31's source-side wait lookup.  A D1 implementation must distinguish a
+ * missing target from a contradictory target/incident; callers must never
+ * turn either unavailable result into a successful safe-head observation.
+ */
+export type WaitForTargetLookup = {
+    readonly kind: "pending";
+} | {
+    readonly kind: "stored";
+    readonly eventId: string;
+    readonly suid: string;
+} | {
+    readonly kind: "unavailable";
+    readonly reason: "incident" | "suid-contradiction";
+};
+/** Indexed D1 source port used only by the d1-mv waitFor implementation. */
+export interface WaitForTargetSourcePort {
+    readWaitForTarget(serviceId: string, suid: string): Promise<WaitForTargetLookup>;
+}
+/** The backing choice is typed and deploy-time; it never changes the V1 wire. */
+export type QueryBacking = "memory" | "d1-mv";
+export interface MaterializedViewQueryPort {
+    queryRows(serviceId: string, viewId: string, options?: MaterializedViewQueryOptions): Promise<MaterializedViewRow[]>;
+    /** Optional SDT-G23 port. D1 provides one-statement winner/count paging. */
+    queryRowsWithTotal?(serviceId: string, viewId: string, options?: MaterializedViewQueryOptions): Promise<UnsafeComposedPage>;
+    /** SDT-G55's explicit safe/unsafe list port; absent ports retain legacy behavior. */
+    readListPage?(serviceId: string, viewId: string, options?: MaterializedViewListOptions): Promise<MaterializedViewListPage>;
+    /** Target receipt is the unsafe-window wait oracle; global heads are not. */
+    hasTargetReceipt?(serviceId: string, viewId: string, eventId: string, suid: string): Promise<boolean>;
+    /** SDT-G24 active-generation finding; true means every composed read is unavailable. */
+    hasCheckpointAheadFinding?(serviceId: string, viewId: string): Promise<boolean>;
+    /** G69 fail-closed ordering gate; only the active generation can refuse safe reads. */
+    readOrderingQuarantine?(serviceId: string, viewId: string): Promise<MaterializedViewOrderingQuarantine | undefined>;
+    /** Generation snapshot paired with the final safe-read boundary check. */
+    readActiveGeneration?(serviceId: string, viewId: string): Promise<number | undefined>;
+    /**
+     * SDT-G31 active-generation wait facts.  This deliberately combines only
+     * indexed point reads; its receipt is generation/definition-bound and its
+     * hard gates are evaluated before a wait can report success.
+     */
+    readWaitForState?(serviceId: string, viewId: string, target: {
+        readonly eventId?: string;
+        readonly suid: string;
+    }): Promise<MaterializedViewWaitForState>;
+    /** D1-backed implementations may need to verify the versioned schema first. */
+    initialize?: () => Promise<void>;
+}
+export type QueryBackingSelection = {
+    readonly backing: "memory";
+    readonly store: QueryProjectionStore;
+} | {
+    readonly backing: "d1-mv";
+    readonly store: MaterializedViewQueryPort;
+};
+export interface QueryBackingOptions {
+    readonly backing: QueryBacking;
+    readonly memory?: QueryProjectionStore;
+    readonly materializedView?: MaterializedViewQueryPort;
+}
+/** Select a query backing without allowing an HTTP request to provide a store. */
+export declare function selectQueryBacking(options: QueryBackingOptions): QueryBackingSelection;
+export declare const chooseQueryBacking: typeof selectQueryBacking;
+export interface ProjectedQueryEntry {
+    readonly eventId: string;
+    readonly suid: string;
+    readonly payload: string;
+}
+/** V1 SUID ordering is bytewise ordinal, not locale or parsed timestamp order. */
+export declare function compareSuid(left: string, right: string): number;
+export interface ProjectedQuerySnapshot {
+    readonly entries: readonly ProjectedQueryEntry[];
+    /** Greatest checkpoint observed while constructing these exact entries. */
+    readonly readHead: string;
+}
+/**
+ * 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 declare function readProjectedSnapshot(store: QueryProjectionStore, serviceId: string, definition: QueryDefinition): Promise<ProjectedQuerySnapshot>;
+export declare function readProjectedEntries(store: QueryProjectionStore, serviceId: string, definition: QueryDefinition): Promise<ProjectedQueryEntry[]>;
+/** 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 declare function projectionHasObserved(store: QueryProjectionStore, serviceId: string, definition: QueryDefinition, requestedSuid: string): Promise<boolean>;
+/** Query rows through the selected backing while preserving typed paging inputs. */
+export declare function readRowsFromBacking(selection: QueryBackingSelection, serviceId: string, viewId: string, definition: QueryDefinition, options?: MaterializedViewQueryOptions): Promise<ProjectedQueryEntry[]>;
+/** Page in the backing when it supports composed SQL, otherwise preserve the legacy port. */
+export declare function readRowsPageFromBacking(selection: QueryBackingSelection, serviceId: string, viewId: string, definition: QueryDefinition, options: MaterializedViewQueryOptions): Promise<{
+    readonly entries: ProjectedQueryEntry[];
+    readonly totalCount: number;
+    readonly serverPaged: boolean;
+    /** Present for memory pages and observed from the same checkpoints as entries. */
+    readonly readHead?: string;
+}>;