@sekiban/dcb-runtime 0.2.0

package/dist/projection/LiveProjectionWorker.d.ts

@@ -0,0 +1,86 @@
+import type { PipelineClock } from "../downstream/types";
+import type { StoreProvider } from "../store/provider";
+import type { PipelineStore } from "../store/types";
+import type { ClosedPrefixCertificate } from "../allocator/types";
+import { type ProjectorRegistry } from "./ProjectorRegistry";
+import { type CatchUpResult, type SafeViewCoverageContext } from "./ProjectionRuntime";
+import { type ServiceIdentityProvider } from "../service/ServiceIdentityProvider";
+export interface LiveProjectionEnv {
+    POSTGRES_URL?: string;
+    HYPERDRIVE?: Hyperdrive;
+    /** Optional explicit D1 provider binding; Postgres remains the default. */
+    D1?: D1Database;
+    /** Non-secret service identity configured per deployment. */
+    SDT_SERVICE_ID?: string;
+    BOOTSTRAP?: DurableObjectNamespace;
+    /** Internal trusted certificate producer; never used on ordinary poll paths. */
+    ALLOCATOR?: DurableObjectNamespace;
+}
+export declare const LIVE_PROJECTION_POLL_OUTCOMES: readonly ["never-invoked", "invoked-and-threw", "invoked-but-no-work", "explicitly-gated", "advanced"];
+export type LiveProjectionPollOutcome = (typeof LIVE_PROJECTION_POLL_OUTCOMES)[number];
+export interface LiveProjectionPollObservation {
+    readonly serviceId: string;
+    readonly projectorId: string;
+    readonly attemptedAt: number;
+    readonly outcome: LiveProjectionPollOutcome;
+    readonly reason: string | null;
+    readonly advancedSourceEvents: number;
+}
+export interface LiveProjectionPollObserver {
+    /** Called before bootstrap admission/store initialization is attempted. */
+    readonly onAttempt?: (input: {
+        readonly env: LiveProjectionEnv;
+        readonly serviceId: string;
+        readonly projectorIds: readonly string[];
+        readonly attemptedAt: number;
+    }) => Promise<void> | void;
+    /** Called once per registered projector after a poll returns or throws. */
+    readonly onOutcome?: (input: LiveProjectionPollObservation & {
+        readonly env: LiveProjectionEnv;
+    }) => Promise<void> | void;
+}
+export interface ProjectionPollOptions {
+    clock?: PipelineClock;
+    store?: PipelineStore;
+    storeProvider?: StoreProvider;
+    registry?: ProjectorRegistry;
+    /** Test-only service isolation; scheduled production polls require SDT_SERVICE_ID. */
+    serviceId?: string;
+    /** Optional single tag scope for queue/HTTP operator catch-up. */
+    tag?: string;
+    /**
+     * Optional G44-proven high-water mark for a scheduled poll. `null` keeps
+     * the poll observable but permits no source advancement on BLOCK/UNSETTLED;
+     * `undefined` retains the unbounded FULL/on-demand behavior.
+     */
+    maximumSuid?: string | null;
+    /**
+     * Explicitly selects the safe-view advance decision. Only this boundary
+     * validates the cached closed-prefix certificate; ordinary callers leave it
+     * false and retain their existing projection behavior.
+     */
+    safeViewAdvance?: boolean;
+    /** Internal spelling retained for callers that already model the gate. */
+    requireClosedPrefixCertificate?: boolean;
+    /** Optional certificate prefix supplied alongside the cached certificate. */
+    closedPrefixSuid?: string | null;
+    /** Consumer-bound allocator certificate for a safe-view decision. */
+    closedPrefixCertificate?: ClosedPrefixCertificate;
+    /** Cached allocator generation used to bind the certificate. */
+    allocatorLineageId?: string;
+    /** Existing G44/G62 proven coverage and start-of-pass handoff. */
+    safeViewCoverage?: SafeViewCoverageContext;
+    serviceIdentityProvider?: ServiceIdentityProvider;
+    /** Observation-only lifecycle sink; it cannot alter projection decisions. */
+    observer?: LiveProjectionPollObserver;
+}
+/**
+ * Scheduled polling entry point. It discovers durable tag memberships and
+ * advances every deploy-time registered projector only through SafeWindow.
+ */
+export declare function pollLiveProjections(env: LiveProjectionEnv, options?: ProjectionPollOptions): Promise<CatchUpResult[]>;
+/**
+ * Internal operational surface; it is deliberately outside the five V1
+ * endpoints and does not advance a projection or write event data.
+ */
+export declare function handleProjectionLag(request: Request, env: LiveProjectionEnv, registry?: ProjectorRegistry, storeProvider?: StoreProvider, serviceIdentityProvider?: ServiceIdentityProvider): Promise<Response>;

package/dist/projection/LiveProjectionWorker.js

@@ -0,0 +1,240 @@
+import { systemPipelineClock } from "../downstream/types";
+import { DEPLOYED_PROJECTOR_REGISTRY, tagStateIdentityFrom, } from "./ProjectorRegistry";
+import { projectionIdFor, ProjectionRuntime, safeWindowMs, validatedClosedPrefixSuid, validatedSafeViewCoverageMaximumSuid, } from "./ProjectionRuntime";
+import { scopeIdFor } from "../scope/ScopeName";
+import { envServiceIdentity, requireServiceIdentity } from "../service/ServiceIdentityProvider";
+export const LIVE_PROJECTION_POLL_OUTCOMES = [
+    "never-invoked",
+    "invoked-and-threw",
+    "invoked-but-no-work",
+    "explicitly-gated",
+    "advanced",
+];
+function sharedStore(env, provider) {
+    // Provider clients are request-scoped in workerd; a retained client can
+    // otherwise be used by a later cron/Queue request.
+    return provider.create(env);
+}
+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);
+}
+async function acquireClosedPrefixCertificate(env, serviceId) {
+    if (env.ALLOCATOR === undefined) {
+        throw new Error("ordering_certificate_unavailable");
+    }
+    const url = new URL("https://projection.internal/__internal/g77/certificate");
+    url.searchParams.set("serviceId", serviceId);
+    const response = await env.ALLOCATOR.get(scopeIdFor(env.ALLOCATOR, {
+        serviceId,
+        doClass: "allocator",
+        identity: "allocator",
+    })).fetch(new Request(url));
+    if (!response.ok) {
+        throw new Error("ordering_certificate_unavailable");
+    }
+    return response.json();
+}
+async function admitBootstrapRoute(env, serviceId) {
+    if (env.BOOTSTRAP === undefined)
+        return;
+    const url = new URL("https://projection.internal/route/check");
+    url.searchParams.set("__serviceId", serviceId);
+    const admitted = await env.BOOTSTRAP.get(scopeIdFor(env.BOOTSTRAP, {
+        serviceId,
+        doClass: "bootstrap",
+        identity: "coordinator",
+    })).fetch(new Request(url, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ route: "projection-rebuild" }) }));
+    if (!admitted.ok)
+        throw new Error("bootstrap_route_rejected:projection-rebuild");
+}
+function boundedErrorReason(error) {
+    const value = error instanceof Error ? error.message : String(error);
+    return value.length > 256 ? `${value.slice(0, 253)}...` : value;
+}
+async function notifyObserver(observer, callback, input) {
+    // Health persistence is deliberately ancillary: a D1 diagnostic outage must
+    // never change commit/projection semantics or turn a successful poll into a
+    // failed scheduled invocation.
+    try {
+        if (callback === "onAttempt") {
+            await observer?.onAttempt?.(input);
+        }
+        else {
+            await observer?.onOutcome?.(input);
+        }
+    }
+    catch {
+        // The next health read will retain the last durable observation and its
+        // reason; projection advancement remains governed by the existing fences.
+    }
+}
+async function notifyOutcomes(observer, serviceId, projectorIds, attemptedAt, results, maximumSuid, env, error) {
+    if (observer?.onOutcome === undefined)
+        return;
+    const byProjector = new Map();
+    for (const result of results) {
+        const values = byProjector.get(result.projectorId) ?? [];
+        values.push(result);
+        byProjector.set(result.projectorId, values);
+    }
+    for (const projectorId of projectorIds) {
+        const projectorResults = byProjector.get(projectorId) ?? [];
+        let outcome = "invoked-but-no-work";
+        let reason = null;
+        let advancedSourceEvents = 0;
+        if (error !== undefined) {
+            outcome = "invoked-and-threw";
+            reason = boundedErrorReason(error);
+        }
+        else {
+            advancedSourceEvents = projectorResults.reduce((total, result) => total + result.advancedSourceEvents, 0);
+            if (advancedSourceEvents > 0) {
+                outcome = "advanced";
+            }
+            else if (projectorResults.some((result) => result.indeterminate)) {
+                outcome = "explicitly-gated";
+                reason = "safe_window_ceiling_exceeded";
+            }
+            else if (maximumSuid !== undefined) {
+                outcome = "explicitly-gated";
+                reason = maximumSuid === null ? "retained_frontier_unproven" : "retained_frontier_fence";
+            }
+        }
+        await notifyObserver(observer, "onOutcome", {
+            serviceId,
+            projectorId,
+            attemptedAt,
+            outcome,
+            reason,
+            advancedSourceEvents,
+            env,
+        });
+    }
+}
+/**
+ * Scheduled polling entry point. It discovers durable tag memberships and
+ * advances every deploy-time registered projector only through SafeWindow.
+ */
+export async function pollLiveProjections(env, options = {}) {
+    if (options.store === undefined && options.storeProvider === undefined) {
+        throw new Error("A projection store provider is not configured");
+    }
+    const serviceId = options.serviceId ?? requireServiceIdentity(options.serviceIdentityProvider ?? envServiceIdentity(env));
+    const registry = options.registry ?? DEPLOYED_PROJECTOR_REGISTRY;
+    const projectorIds = registry.registered().map((projector) => projector.id);
+    const safeViewAdvance = options.safeViewAdvance === true || options.requireClosedPrefixCertificate === true;
+    const closedPrefixCertificate = safeViewAdvance
+        ? options.closedPrefixCertificate ?? await acquireClosedPrefixCertificate(env, serviceId)
+        : undefined;
+    const closedPrefixSuid = safeViewAdvance
+        ? validatedClosedPrefixSuid({
+            closedPrefixSuid: options.closedPrefixSuid,
+            closedPrefixCertificate,
+            expectedServiceId: serviceId,
+            expectedAllocatorLineageId: options.allocatorLineageId,
+        }, serviceId)
+        : undefined;
+    if (safeViewAdvance) {
+        validatedSafeViewCoverageMaximumSuid(options.safeViewCoverage, serviceId);
+    }
+    const attemptedAt = (options.clock ?? systemPipelineClock).now();
+    await notifyObserver(options.observer, "onAttempt", { env, serviceId, projectorIds, attemptedAt });
+    try {
+        await admitBootstrapRoute(env, serviceId);
+        const store = options.store ?? sharedStore(env, options.storeProvider);
+        await store.initialize();
+        const runtime = new ProjectionRuntime(store, registry);
+        if (options.tag !== undefined) {
+            const results = [];
+            for (const projector of registry.registered()) {
+                const identity = tagStateIdentityFrom(`${options.tag}:${projector.id}`, registry);
+                if (identity.value !== undefined) {
+                    if (safeViewAdvance) {
+                        results.push(await runtime.catchUp(serviceId, identity.value, attemptedAt, {}, {
+                            maximumSuid: options.maximumSuid,
+                            closedPrefixSuid,
+                            closedPrefixCertificate,
+                            requireClosedPrefixCertificate: true,
+                            expectedServiceId: serviceId,
+                            expectedAllocatorLineageId: options.allocatorLineageId,
+                            safeViewCoverage: options.safeViewCoverage,
+                        }));
+                    }
+                    else {
+                        results.push(await runtime.catchUp(serviceId, identity.value, attemptedAt, {}, { maximumSuid: options.maximumSuid }));
+                    }
+                }
+            }
+            await notifyOutcomes(options.observer, serviceId, projectorIds, attemptedAt, results, options.maximumSuid, env);
+            return results;
+        }
+        if (safeViewAdvance) {
+            const results = await runtime.pollRegistered(serviceId, attemptedAt, options.maximumSuid, closedPrefixSuid, closedPrefixCertificate, true, serviceId, options.allocatorLineageId, options.safeViewCoverage);
+            await notifyOutcomes(options.observer, serviceId, projectorIds, attemptedAt, results, options.maximumSuid, env);
+            return results;
+        }
+        const results = await runtime.pollRegistered(serviceId, attemptedAt, options.maximumSuid);
+        await notifyOutcomes(options.observer, serviceId, projectorIds, attemptedAt, results, options.maximumSuid, env);
+        return results;
+    }
+    catch (error) {
+        await notifyOutcomes(options.observer, serviceId, projectorIds, attemptedAt, [], options.maximumSuid, env, error);
+        throw error;
+    }
+}
+/**
+ * Internal operational surface; it is deliberately outside the five V1
+ * endpoints and does not advance a projection or write event data.
+ */
+export async function handleProjectionLag(request, env, registry = DEPLOYED_PROJECTOR_REGISTRY, storeProvider, serviceIdentityProvider) {
+    if (request.method !== "GET") {
+        return error(405, "validation_error", "Projection lag requires GET");
+    }
+    const query = new URL(request.url).searchParams;
+    const tagStateId = query.get("tagStateId");
+    const serviceId = query.get("serviceId") || requireServiceIdentity(serviceIdentityProvider ?? envServiceIdentity(env));
+    const pollRequested = query.get("poll") === "1";
+    if (tagStateId === null || tagStateId.length === 0) {
+        return error(400, "validation_error", "tagStateId is required");
+    }
+    const parsed = tagStateIdentityFrom(tagStateId, registry);
+    if (parsed.value === undefined) {
+        return error(400, "validation_error", parsed.error ?? "Invalid tagStateId");
+    }
+    try {
+        if (storeProvider === undefined) {
+            return error(503, "projection_unavailable", "A projection store provider is not configured");
+        }
+        const store = sharedStore(env, storeProvider);
+        await store.initialize();
+        if (pollRequested) {
+            // The operator probe names one tag-state. Catch up only that identity;
+            // polling every registered tag here can exceed an HTTP request lifetime
+            // on a large service-scoped conformance run.
+            const runtime = new ProjectionRuntime(store, registry);
+            await runtime.catchUp(serviceId, parsed.value, Date.now());
+        }
+        const projectionId = projectionIdFor(parsed.value);
+        const [lag, dynamicLagBoundMs] = await Promise.all([
+            store.projectionLag(serviceId, projectionId, parsed.value.tag),
+            store.currentLagBound(serviceId, Date.now()),
+        ]);
+        return json({
+            tagStateId,
+            checkpointSuid: lag.checkpointSuid,
+            headSuid: lag.headSuid,
+            behindEvents: lag.behindEvents,
+            dynamicLagBoundMs,
+            safeWindowMs: safeWindowMs(dynamicLagBoundMs),
+        });
+    }
+    catch {
+        return error(503, "projection_unavailable", "Projection lag storage is unavailable");
+    }
+}

package/dist/projection/ProjectionRuntime.d.ts

@@ -0,0 +1,113 @@
+import type { TagEvent } from "../tag/types";
+import type { ClosedPrefixCertificate } from "../allocator/types";
+import type { ProjectionCheckpoint, ProjectionStore, StoredEvent } from "../store/types";
+import { type ProjectorRegistry, type TagStateIdentity, type TagStateProjector } from "./ProjectorRegistry";
+import { decayedLagEstimateMs, MAX_PUBLISHED_SAFE_WINDOW_MS, PUBLISHED_SAFE_WINDOW_MS, safeWindowCeilingExceeded, safeWindowCutoffSuid, safeWindowMs } from "../safeWindow";
+/** Published V1 read-side SafeWindow. It never authorizes a commit. */
+export { MAX_PUBLISHED_SAFE_WINDOW_MS, PUBLISHED_SAFE_WINDOW_MS, safeWindowCeilingExceeded, safeWindowCutoffSuid, safeWindowMs, };
+export declare class ProjectionCheckpointCorruption extends Error {
+    constructor(cause?: unknown);
+}
+/**
+ * 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 declare const MAX_LIVE_PROJECTION_CONCURRENCY = 8;
+export interface ProjectedTagState {
+    payload: string;
+    version: number;
+    stateJson: string;
+}
+export interface CatchUpHooks {
+    /** Test-only crash boundary before the state/checkpoint transaction. */
+    beforeCheckpoint?(event: StoredEvent, checkpoint: ProjectionCheckpoint): Promise<void> | void;
+    /** Test-only crash boundary after the state/checkpoint transaction. */
+    afterCheckpoint?(event: StoredEvent, checkpoint: ProjectionCheckpoint): Promise<void> | void;
+}
+/**
+ * Optional scanner-proven high-water mark for a scheduled live-projection
+ * pass. `null` means that no settled frontier exists, so the pass may run
+ * and observe projection state but cannot advance a source checkpoint.
+ * `undefined` retains the ordinary unbounded caller behaviour used by a
+ * proven FULL scan and by on-demand operator reads.
+ */
+export interface ProjectionCatchUpOptions {
+    readonly maximumSuid?: string | null;
+    /** A prefix already validated by the safe-view decision boundary. */
+    readonly closedPrefixSuid?: string | null;
+    /** Cached allocator authority, validated only for an explicitly safe pass. */
+    readonly closedPrefixCertificate?: ClosedPrefixCertificate;
+    /** Marks this invocation as the certificate-gated safe-view decision. */
+    readonly requireClosedPrefixCertificate?: boolean;
+    /** Consumer identity used to bind the cached certificate. */
+    readonly expectedServiceId?: string;
+    /** Allocator generation expected by the consumer. */
+    readonly expectedAllocatorLineageId?: string;
+    /** Existing G44/G62 proof context for this safe-view pass. */
+    readonly safeViewCoverage?: SafeViewCoverageContext;
+}
+/**
+ * Handoff from the existing G44/G62 coverage path to the one safe-view
+ * decision.  `startOfPass: "PROVEN"` makes the proof domain explicit; FULL is
+ * the only context that may leave the existing maximumSuid bound unbounded.
+ * This runtime validates the handoff and does not mint scanner authority.
+ */
+export type SafeViewCoverageContext = Readonly<{
+    readonly authority: "g44-g62";
+    readonly serviceId: string;
+    readonly startOfPass: "PROVEN";
+    readonly kind: "FULL";
+    readonly frontierSuid: null;
+}> | Readonly<{
+    readonly authority: "g44-g62";
+    readonly serviceId: string;
+    readonly startOfPass: "PROVEN";
+    readonly kind: "SETTLED" | "BLOCK/UNSETTLED";
+    readonly frontierSuid: string | null;
+}>;
+export type ClosedPrefixCertificateValidationOptions = Pick<ProjectionCatchUpOptions, "closedPrefixSuid" | "closedPrefixCertificate" | "expectedServiceId" | "expectedAllocatorLineageId">;
+/**
+ * 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 declare function validatedClosedPrefixSuid(options: ClosedPrefixCertificateValidationOptions, consumerServiceId: string): string | null;
+/**
+ * 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 declare function validatedSafeViewCoverageMaximumSuid(context: SafeViewCoverageContext | undefined, consumerServiceId: string): string | null | undefined;
+export interface CatchUpResult {
+    /** Registered projector and tag identity for scheduled-poll diagnostics. */
+    readonly projectorId: string;
+    readonly tag: string;
+    checkpoint: ProjectionCheckpoint | undefined;
+    dynamicLagBoundMs: number;
+    safeWindowMs: number;
+    /** True means the published 120s ceiling was exceeded; no source event was advanced. */
+    indeterminate: boolean;
+    advancedSourceEvents: number;
+    appliedEvents: number;
+}
+export declare function projectionIdFor(identity: TagStateIdentity): string;
+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 declare function catchUpDurableTagState(projector: TagStateProjector, events: readonly TagEvent[]): ProjectedTagState;
+/**
+ * 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 declare class ProjectionRuntime {
+    private readonly store;
+    private readonly registry;
+    constructor(store: ProjectionStore, registry?: ProjectorRegistry);
+    catchUp(serviceId: string, identity: TagStateIdentity, nowMs: number, hooks?: CatchUpHooks, options?: ProjectionCatchUpOptions): Promise<CatchUpResult>;
+    pollRegistered(serviceId: string, nowMs: number, maximumSuid?: string | null, closedPrefixSuid?: string | null, closedPrefixCertificate?: ClosedPrefixCertificate, requireClosedPrefixCertificate?: boolean, expectedServiceId?: string, expectedAllocatorLineageId?: string, safeViewCoverage?: SafeViewCoverageContext): Promise<CatchUpResult[]>;
+}