@atolis-hq/wake 0.2.97 → 0.3.0

package/dist/src/orchestration/domain/supplemental-policy.js

@@ -0,0 +1,61 @@
+import { ActivityOutcomeKind } from '../../activities/index.js';
+import { EventActorKind } from '../../kernel/index.js';
+import { OrchestrationEventType } from '../contracts/events.js';
+import { stageName } from '../contracts/identifiers.js';
+import { ApprovalAuthorityKind, WorkflowStatus } from '../contracts/vocabulary.js';
+import { activation, nextOrdinal, stateDraft } from './decision-events.js';
+export function requestSupplementalActivity(state, request, input) {
+    if (state.status !== WorkflowStatus.Active || state.pendingActivation === undefined)
+        return { kind: 'ignored', reason: 'supplemental commands require an active WorkflowInstance' };
+    return {
+        kind: 'append',
+        events: [
+            stateDraft(state, input, OrchestrationEventType.SupplementalActivityQueued, {
+                activity: request.activity,
+                input: request.input,
+                requestedBy: request.requestedBy,
+            }, 1),
+        ],
+    };
+}
+export function finishSupplemental(events, definition, state, input) {
+    if (input.outcome.kind !== ActivityOutcomeKind.Done) {
+        events.push(stateDraft(state, input, OrchestrationEventType.InstanceBlocked, { reason: `supplemental activity returned ${input.outcome.kind}` }, events.length + 1));
+        return;
+    }
+    if (state.supplementalQueue.length > 0) {
+        requestNextSupplemental(events, state, input);
+        return;
+    }
+    const stage = definition.stages[stageName(state.currentStage)];
+    events.push(stateDraft(state, input, OrchestrationEventType.ActivityRequested, activation(state.workflowInstanceId, nextOrdinal(state), stage.activity, stage.with, {
+        execution: stage.execution,
+        stage: stageName(state.currentStage),
+    }), events.length + 1));
+}
+export function requestNextSupplemental(events, state, input) {
+    const next = state.supplementalQueue[0];
+    events.push(stateDraft(state, input, OrchestrationEventType.SupplementalActivityDequeued, { activity: next.activity, requestedBy: next.requestedBy }, events.length + 1), stateDraft(state, input, OrchestrationEventType.ActivityRequested, activation(state.workflowInstanceId, nextOrdinal(state), next.activity, next.input, {
+        execution: undefined,
+        supplemental: true,
+    }), events.length + 2));
+}
+// A command's `allowedActors` declares acceptance authority (ORCH-APPROVAL-AUTHORITY), not
+// event provenance, so the invoking actor's provenance is resolved to an authority first.
+export function isAuthorisedActor(allowed, actorKind) {
+    const authority = actorAuthority(actorKind);
+    return authority !== null && allowed.includes(authority);
+}
+// Provenance answers who emitted the event; authority answers who may invoke. A provider
+// relays a person typing in a ticket comment, which D16 counts as `human` on any surface.
+// `auto` is never inferred from transport: it requires operator consent, so granting it
+// from an actor kind would escalate authority without one.
+function actorAuthority(actorKind) {
+    switch (actorKind) {
+        case EventActorKind.Operator:
+        case EventActorKind.Integration:
+            return ApprovalAuthorityKind.Human;
+        default:
+            return null;
+    }
+}

package/dist/src/orchestration/domain/transition.js

@@ -0,0 +1,55 @@
+import { OrchestrationEventType, WatchGateVerdictSignal } from '../contracts/events.js';
+import { ApprovalAuthorityKind, TransitionTargetKind } from '../contracts/vocabulary.js';
+import { activation, nextOrdinal, stateDraft } from './decision-events.js';
+export function finishRoute(events, definition, state, input, route) {
+    if (route.watchGates !== undefined) {
+        const gate = route.watchGates[0];
+        events.push(stateDraft(state, input, OrchestrationEventType.SignalWaitStarted, {
+            signalKind: WatchGateVerdictSignal,
+            from: Object.freeze([
+                { kind: ApprovalAuthorityKind.Watch, watch: gate.watch },
+                { kind: ApprovalAuthorityKind.Human },
+            ]),
+            resume: route.target,
+            onRejectResume: gate.onRejectTarget,
+        }, events.length + 1));
+        return;
+    }
+    if (route.await !== undefined) {
+        events.push(stateDraft(state, input, OrchestrationEventType.SignalWaitStarted, { signalKind: route.await.signal, from: route.await.from, resume: route.await.resume }, events.length + 1));
+        return;
+    }
+    if (route.target.kind !== TransitionTargetKind.Stage) {
+        resumeToTarget(events, definition, state, input, route.target);
+        return;
+    }
+    const count = (state.repeatCounts[route.id] ?? 0) + 1;
+    if (route.repeat !== undefined) {
+        if (count > route.repeat.max) {
+            events.push(stateDraft(state, input, OrchestrationEventType.InstanceBlocked, { reason: `repeat.max exceeded for ${route.id}` }, events.length + 1));
+            return;
+        }
+        events.push(stateDraft(state, input, OrchestrationEventType.RepeatCounted, { routeId: route.id, count }, events.length + 1));
+    }
+    pushStageEntry(events, definition, state, input, route.target.stage);
+}
+function pushStageEntry(events, definition, state, input, stageName) {
+    const stage = definition.stages[stageName];
+    events.push(stateDraft(state, input, OrchestrationEventType.StageEntered, { stage: stageName }, events.length + 1), stateDraft(state, input, OrchestrationEventType.ActivityRequested, activation(state.workflowInstanceId, nextOrdinal(state), stage.activity, stage.with, {
+        execution: stage.execution,
+        stage: stageName,
+    }), events.length + 2));
+}
+// Shared by a route with no gate (target reached directly) and a resumed wait
+// (target reached after an accepted signal); neither carries repeat counting.
+export function resumeToTarget(events, definition, state, input, target) {
+    if (target.kind === TransitionTargetKind.Complete) {
+        events.push(stateDraft(state, input, OrchestrationEventType.InstanceCompleted, {}, events.length + 1));
+        return;
+    }
+    if (target.kind === TransitionTargetKind.AwaitSignal) {
+        events.push(stateDraft(state, input, OrchestrationEventType.SignalWaitStarted, { signalKind: target.signal }, events.length + 1));
+        return;
+    }
+    pushStageEntry(events, definition, state, input, target.stage);
+}

package/dist/src/orchestration/domain/workflow-graph.js

@@ -0,0 +1,41 @@
+import { stageName } from '../contracts/identifiers.js';
+import { TransitionTargetKind } from '../contracts/vocabulary.js';
+function edges(stages, name) {
+    return Object.values(stages[name].on).flatMap((route) => route.target.kind === TransitionTargetKind.Stage ? [route.target.stage] : []);
+}
+export function assertReachable(entry, stages) {
+    const reached = new Set();
+    const visit = (name) => {
+        if (reached.has(name))
+            return;
+        reached.add(name);
+        for (const target of edges(stages, name))
+            visit(target);
+    };
+    visit(entry);
+    const missing = Object.keys(stages).filter((name) => !reached.has(name));
+    if (missing.length > 0)
+        throw new Error(`Unreachable workflow stage: ${missing.join(', ')}`);
+}
+export function assertCyclesBounded(stages) {
+    for (const [from, stage] of Object.entries(stages)) {
+        for (const route of Object.values(stage.on)) {
+            if (route.target.kind === TransitionTargetKind.Stage &&
+                canReach(stages, route.target.stage, stageName(from)) &&
+                route.repeat === undefined)
+                throw new Error(`Cycle-closing route ${route.id} requires repeat.max`);
+        }
+    }
+}
+function canReach(stages, from, target) {
+    const seen = new Set();
+    const visit = (name) => {
+        if (name === target)
+            return true;
+        if (seen.has(name))
+            return false;
+        seen.add(name);
+        return edges(stages, name).some(visit);
+    };
+    return visit(from);
+}

package/dist/src/orchestration/domain/workflow-instance-events.js

@@ -0,0 +1,236 @@
+/* eslint-disable max-lines */
+import { OrchestrationEventType, } from '../contracts/events.js';
+import { ActivityActivationStatus, WorkflowStatus } from '../contracts/vocabulary.js';
+/**
+ * The single source of truth for which orchestration events change a
+ * workflow instance's status, and to what — every other consumer that needs
+ * to reflect status externally (GitHub labels, the operator board, delivery
+ * reactors) must derive from this table rather than hand-matching event
+ * types itself, or it silently falls out of sync whenever a new
+ * status-changing event type is introduced here.
+ */
+export const orchestrationStatusTransitions = {
+    [OrchestrationEventType.ActivityRequested]: WorkflowStatus.Active,
+    [OrchestrationEventType.ActivityWaiting]: WorkflowStatus.Waiting,
+    [OrchestrationEventType.SignalWaitStarted]: WorkflowStatus.Waiting,
+    [OrchestrationEventType.SignalAccepted]: WorkflowStatus.Active,
+    [OrchestrationEventType.InstanceCompleted]: WorkflowStatus.Completed,
+    [OrchestrationEventType.InstanceBlocked]: WorkflowStatus.Blocked,
+    [OrchestrationEventType.InstanceSuperseded]: WorkflowStatus.Superseded,
+};
+export function applyWorkflowInstanceEvent(state, event) {
+    if (isActivityFact(event))
+        return applyActivityFact(state, event);
+    if (isInteractionFact(event))
+        return applyInteractionFact(state, event);
+    if (isLifecycleFact(event))
+        return applyLifecycleFact(state, event);
+    applyCoordinationFact(state, event);
+}
+function isActivityFact(event) {
+    switch (event.eventType) {
+        case OrchestrationEventType.StageEntered:
+        case OrchestrationEventType.ActivityRequested:
+        case OrchestrationEventType.ActivityStarted:
+        case OrchestrationEventType.ActivityOutcomeAccepted:
+        case OrchestrationEventType.ActivityExecutionFailed:
+        case OrchestrationEventType.ActivityWaiting:
+            return true;
+        default:
+            return false;
+    }
+}
+function applyActivityFact(state, event) {
+    switch (event.eventType) {
+        case OrchestrationEventType.StageEntered:
+            state.currentStage = event.payload.stage;
+            return;
+        case OrchestrationEventType.ActivityRequested:
+            applyActivityRequested(state, event.payload);
+            return;
+        case OrchestrationEventType.ActivityStarted:
+            updateActivationStatus(state, event.payload.activationId, ActivityActivationStatus.Running);
+            return;
+        case OrchestrationEventType.ActivityOutcomeAccepted:
+            state.acceptedOutcomes.push(event.payload.activationId);
+            state.lastOutcome = event.payload.outcome;
+            updateActivationStatus(state, event.payload.activationId, ActivityActivationStatus.Completed);
+            return;
+        case OrchestrationEventType.ActivityExecutionFailed:
+            state.acceptedOutcomes.push(event.payload.activationId);
+            updateActivationStatus(state, event.payload.activationId, ActivityActivationStatus.Completed);
+            return;
+        case OrchestrationEventType.ActivityWaiting:
+            applyActivityWaiting(state, event);
+            return;
+        default:
+            assertNever(event);
+    }
+}
+function isInteractionFact(event) {
+    switch (event.eventType) {
+        case OrchestrationEventType.SignalWaitStarted:
+        case OrchestrationEventType.SignalAccepted:
+        case OrchestrationEventType.SupplementalActivityQueued:
+        case OrchestrationEventType.SupplementalActivityDequeued:
+            return true;
+        default:
+            return false;
+    }
+}
+function applyInteractionFact(state, event) {
+    switch (event.eventType) {
+        case OrchestrationEventType.SignalWaitStarted:
+            applySignalWaitStarted(state, event);
+            return;
+        case OrchestrationEventType.SignalAccepted:
+            state.status = orchestrationStatusTransitions[OrchestrationEventType.SignalAccepted];
+            state.acceptedSignalIds.push(event.payload.providerEventId);
+            delete state.waitingFor;
+            return;
+        case OrchestrationEventType.SupplementalActivityQueued:
+            state.supplementalQueue.push(event.payload);
+            return;
+        case OrchestrationEventType.SupplementalActivityDequeued:
+            state.supplementalQueue.shift();
+            return;
+        default:
+            assertNever(event);
+    }
+}
+function isLifecycleFact(event) {
+    switch (event.eventType) {
+        case OrchestrationEventType.RepeatCounted:
+        case OrchestrationEventType.RetryCounted:
+        case OrchestrationEventType.InstanceCompleted:
+        case OrchestrationEventType.InstanceBlocked:
+        case OrchestrationEventType.OperatorRetryRequested:
+        case OrchestrationEventType.InstanceSuperseded:
+            return true;
+        default:
+            return false;
+    }
+}
+function applyLifecycleFact(state, event) {
+    switch (event.eventType) {
+        case OrchestrationEventType.RepeatCounted:
+            state.repeatCounts[event.payload.routeId] = event.payload.count;
+            return;
+        case OrchestrationEventType.RetryCounted:
+            state.retryCounts[event.payload.retryKey] = event.payload.count;
+            return;
+        case OrchestrationEventType.InstanceCompleted:
+            state.status = orchestrationStatusTransitions[OrchestrationEventType.InstanceCompleted];
+            delete state.pendingActivation;
+            delete state.waitingFor;
+            return;
+        case OrchestrationEventType.InstanceBlocked:
+            state.status = orchestrationStatusTransitions[OrchestrationEventType.InstanceBlocked];
+            state.blockReason = event.payload.reason;
+            return;
+        case OrchestrationEventType.OperatorRetryRequested:
+            state.operatorRetryCommandIds.push(event.payload.commandId);
+            return;
+        case OrchestrationEventType.InstanceSuperseded:
+            state.status = orchestrationStatusTransitions[OrchestrationEventType.InstanceSuperseded];
+            return;
+        default:
+            assertNever(event);
+    }
+}
+function applyCoordinationFact(state, event) {
+    switch (event.eventType) {
+        case OrchestrationEventType.InstanceStarted:
+        case OrchestrationEventType.ChildRequested:
+        case OrchestrationEventType.ChildStarted:
+        case OrchestrationEventType.GroupBudgetExhausted:
+            return;
+        case OrchestrationEventType.ChildCompleted:
+            state.childCompletionRecorded = true;
+            return;
+        case OrchestrationEventType.ChildCompletionConsumed:
+            state.acceptedChildCompletionIds.push(event.payload.childWorkflowInstanceId);
+            return;
+        case OrchestrationEventType.CausalActivationRejected:
+            state.causalRejectionIds.push(event.payload.triggerId);
+            return;
+        default:
+            assertNever(event);
+    }
+}
+function applyActivityWaiting(state, event) {
+    state.status = orchestrationStatusTransitions[OrchestrationEventType.ActivityWaiting];
+    state.waitingFor = {
+        signalKind: event.payload.outcome.data.signalKind,
+        intentEventId: event.payload.outcome.data.intentEventId,
+    };
+    state.lastOutcome = event.payload.outcome;
+    updateActivationStatus(state, event.payload.activationId, ActivityActivationStatus.Waiting);
+}
+function applySignalWaitStarted(state, event) {
+    state.status = orchestrationStatusTransitions[OrchestrationEventType.SignalWaitStarted];
+    state.waitingFor = {
+        signalKind: event.payload.signalKind,
+        ...(event.payload.resourceId === undefined ? {} : { resourceId: event.payload.resourceId }),
+        ...(event.payload.revision === undefined ? {} : { revision: event.payload.revision }),
+        ...(event.payload.from === undefined ? {} : { from: event.payload.from }),
+        ...(event.payload.resume === undefined ? {} : { resume: event.payload.resume }),
+        ...(event.payload.onRejectResume === undefined
+            ? {}
+            : { onRejectResume: event.payload.onRejectResume }),
+    };
+}
+function updateActivationStatus(state, activationId, status) {
+    if (state.pendingActivation?.activationId === activationId)
+        state.pendingActivation = { ...state.pendingActivation, status };
+}
+function applyActivityRequested(state, payload) {
+    state.status = orchestrationStatusTransitions[OrchestrationEventType.ActivityRequested];
+    delete state.waitingFor;
+    state.pendingActivation = {
+        activationId: payload.activationId,
+        ordinal: payload.ordinal,
+        activity: payload.activity,
+        ...(payload.stage === undefined ? {} : { stage: payload.stage }),
+        input: payload.input,
+        execution: payload.execution,
+        status: ActivityActivationStatus.Pending,
+        ...(payload.followOnIndex === undefined ? {} : { followOnIndex: payload.followOnIndex }),
+        ...(payload.supplemental === true ? { supplemental: true } : {}),
+    };
+}
+export function immutableWorkflowInstanceView(state) {
+    return {
+        workflowInstanceId: state.workflowInstanceId,
+        workItemId: state.workItemId,
+        workflowName: state.workflowName,
+        orchestrationGroupId: state.orchestrationGroupId,
+        ...(state.parentWorkflowInstanceId === undefined
+            ? {}
+            : { parentWorkflowInstanceId: state.parentWorkflowInstanceId }),
+        ...(state.watchId === undefined ? {} : { watchId: state.watchId }),
+        ...(state.triggerId === undefined ? {} : { triggerId: state.triggerId }),
+        ...(state.causalCycleId === undefined ? {} : { causalCycleId: state.causalCycleId }),
+        ...(state.requestId === undefined ? {} : { requestId: state.requestId }),
+        status: state.status,
+        ...(state.blockReason === undefined ? {} : { blockReason: state.blockReason }),
+        currentStage: state.currentStage,
+        repeatCounts: state.repeatCounts,
+        retryCounts: state.retryCounts,
+        supplementalQueue: state.supplementalQueue,
+        acceptedSignalIds: state.acceptedSignalIds,
+        operatorRetryCommandIds: state.operatorRetryCommandIds,
+        acceptedOutcomes: state.acceptedOutcomes,
+        acceptedChildCompletionIds: state.acceptedChildCompletionIds,
+        causalRejectionIds: state.causalRejectionIds,
+        childCompletionRecorded: state.childCompletionRecorded,
+        ...(state.pendingActivation === undefined
+            ? {}
+            : { pendingActivation: state.pendingActivation }),
+        ...(state.lastOutcome === undefined ? {} : { lastOutcome: state.lastOutcome }),
+        ...(state.waitingFor === undefined ? {} : { waitingFor: state.waitingFor }),
+    };
+}
+function assertNever(value) {
+    throw new Error(`Unhandled WorkflowInstance event: ${JSON.stringify(value)}`);
+}

package/dist/src/orchestration/domain/workflow-instance.js

@@ -0,0 +1,41 @@
+import { OrchestrationEventType } from '../contracts/events.js';
+import { WorkflowStatus } from '../contracts/vocabulary.js';
+import { applyWorkflowInstanceEvent, immutableWorkflowInstanceView, orchestrationStatusTransitions, } from './workflow-instance-events.js';
+export { orchestrationStatusTransitions };
+export function foldWorkflowInstance(events) {
+    const first = events.find((event) => event.eventType === OrchestrationEventType.InstanceStarted);
+    if (first === undefined)
+        return null;
+    const state = {
+        workflowInstanceId: first.stream.id,
+        workItemId: first.payload.workItemId,
+        workflowName: first.payload.workflowName,
+        orchestrationGroupId: first.payload.orchestrationGroupId,
+        ...optionalChildFields(first.payload),
+        status: WorkflowStatus.Active,
+        currentStage: first.payload.entry,
+        repeatCounts: {},
+        retryCounts: {},
+        supplementalQueue: [],
+        acceptedSignalIds: [],
+        operatorRetryCommandIds: [],
+        acceptedOutcomes: [],
+        acceptedChildCompletionIds: [],
+        causalRejectionIds: [],
+        childCompletionRecorded: false,
+    };
+    for (const event of events)
+        applyWorkflowInstanceEvent(state, event);
+    return immutableWorkflowInstanceView(state);
+}
+function optionalChildFields(payload) {
+    return 'parentWorkflowInstanceId' in payload
+        ? {
+            parentWorkflowInstanceId: payload.parentWorkflowInstanceId,
+            watchId: payload.watchId,
+            triggerId: payload.triggerId,
+            causalCycleId: payload.causalCycleId,
+            requestId: payload.requestId,
+        }
+        : {};
+}

package/dist/src/orchestration/domain/workflow-selector.js

@@ -0,0 +1,21 @@
+import { matchesRequiredValues } from '../../kernel/index.js';
+import { workflowName } from '../contracts/identifiers.js';
+export function compileWorkflowSelectors(selectors) {
+    return selectors.map((selector) => ({
+        match: selector.match,
+        matchMode: selector.matchMode,
+        workflow: workflowName(selector.workflow),
+    }));
+}
+export function selectWorkflow(candidate, selectors, fallback) {
+    return selectors.find((selector) => selectorMatches(selector, candidate))?.workflow ?? fallback;
+}
+function selectorMatches(selector, candidate) {
+    const { match, matchMode } = selector;
+    return (matchesRequiredValues(matchMode, match.tags ?? [], candidate.tags) &&
+        matchesRequiredValues(matchMode, match.kind ?? [], singleton(candidate.kind)) &&
+        matchesRequiredValues(matchMode, match.adapter ?? [], singleton(candidate.adapter)));
+}
+function singleton(value) {
+    return value === undefined ? [] : [value];
+}

package/dist/src/orchestration/index.js

@@ -0,0 +1,19 @@
+export * from './application/orchestration-projection.js';
+export * from './application/orchestration-repository.js';
+export * from './application/orchestration-service.js';
+export * from './application/advance-workflow.js';
+export * from './application/signal-reactor.js';
+export * from './application/watch-reactor.js';
+export * from './contracts/activity-outcome.js';
+export * from './contracts/commands.js';
+export * from './contracts/config.js';
+export * from './contracts/event-decoder.js';
+export * from './contracts/events.js';
+export * from './contracts/identifiers.js';
+export * from './contracts/streams.js';
+export * from './contracts/views.js';
+export * from './contracts/vocabulary.js';
+export * from './domain/compiler.js';
+export * from './domain/interpreter.js';
+export * from './domain/workflow-instance.js';
+export * from './domain/workflow-selector.js';

package/dist/src/persistence/application/projection-runner.js

@@ -0,0 +1,79 @@
+export class ProjectionRunner {
+    journal;
+    projections;
+    checkpoints;
+    registered;
+    caughtUpToGlobalPosition;
+    constructor(journal, projections, checkpoints, registered = []) {
+        this.journal = journal;
+        this.projections = projections;
+        this.checkpoints = checkpoints;
+        this.registered = registered;
+    }
+    // One shared journal read for every registered definition, not one per
+    // definition: readAll ultimately re-derives its content-fingerprint via
+    // readdir/stat on every call, so fanning that out per-definition costs a
+    // full filesystem probe per definition on every tick even when nothing
+    // changed. Fetching once and slicing per-checkpoint in memory keeps the
+    // same polling cadence at a fraction of the syscall cost.
+    //
+    // Resident hosts call this on a fast, fixed idle cadence (control-plane
+    // never backs off the internal runner loop, only the external poll), so a
+    // fully idle system still calls this multiple times a second. Without this
+    // short-circuit that means a per-registered-projection checkpoint file
+    // read every call forever, even though nothing changed. Only mark a
+    // position "caught up" once every definition processed fewer than a full
+    // batch — otherwise a backlog bigger than `limit` would get marked caught
+    // up after its first (partial) batch and never finish draining.
+    async runRegisteredOnce(limit = 100) {
+        const allEvents = await this.journal.readAll(0);
+        const latestGlobalPosition = allEvents.at(-1)?.globalPosition ?? 0;
+        if (this.caughtUpToGlobalPosition !== undefined &&
+            latestGlobalPosition <= this.caughtUpToGlobalPosition)
+            return 0;
+        const counts = await Promise.all(this.registered.map((definition) => this.applyFrom(definition, allEvents, limit)));
+        if (counts.every((count) => count < limit))
+            this.caughtUpToGlobalPosition = latestGlobalPosition;
+        return counts.reduce((total, count) => total + count, 0);
+    }
+    async runOnce(definition, limit = 100) {
+        const consumer = `projection:${definition.name}`;
+        const events = await this.journal.readAll(await this.checkpoints.load(consumer), limit);
+        return this.apply(definition, consumer, events);
+    }
+    async applyFrom(definition, allEvents, limit) {
+        const consumer = `projection:${definition.name}`;
+        const checkpoint = await this.checkpoints.load(consumer);
+        const events = allEvents.filter((event) => event.globalPosition > checkpoint).slice(0, limit);
+        return this.apply(definition, consumer, events);
+    }
+    async apply(definition, consumer, events) {
+        for (const event of events) {
+            const selected = definition.select(event);
+            if (selected !== null) {
+                const previous = await this.projections.read(definition.name, selected.key);
+                if ((previous?.lastGlobalPosition ?? 0) < event.globalPosition) {
+                    await this.projections.write({
+                        namespace: definition.name,
+                        key: selected.key,
+                        lastGlobalPosition: event.globalPosition,
+                        value: definition.project(previous?.value ?? definition.initial(selected.key), event),
+                    });
+                }
+            }
+            await this.checkpoints.save(consumer, event.globalPosition);
+        }
+        return events.length;
+    }
+    async rebuild(definition) {
+        await this.projections.clear(definition.name);
+        await this.checkpoints.reset(`projection:${definition.name}`);
+        let total = 0;
+        while (true) {
+            const count = await this.runOnce(definition);
+            total += count;
+            if (count < 100)
+                return total;
+        }
+    }
+}

package/dist/src/persistence/filesystem/file-checkpoint-store.js

@@ -0,0 +1,35 @@
+import { readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { atomicJson, encode } from './file-projection-store.js';
+export class FileCheckpointStore {
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    async load(consumer) {
+        try {
+            const value = JSON.parse(await readFile(this.path(consumer), 'utf8'));
+            if (value.consumer !== consumer ||
+                !Number.isSafeInteger(value.globalPosition) ||
+                value.globalPosition < 0)
+                throw new Error(`Invalid checkpoint: ${consumer}`);
+            return value.globalPosition;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return 0;
+            throw error;
+        }
+    }
+    async save(consumer, globalPosition) {
+        if (globalPosition < (await this.load(consumer)))
+            throw new Error(`Checkpoint regression for ${consumer}`);
+        await atomicJson(this.path(consumer), { consumer, globalPosition });
+    }
+    async reset(consumer) {
+        await rm(this.path(consumer), { force: true });
+    }
+    path(consumer) {
+        return join(this.root, 'checkpoints', `${encode(consumer)}.json`);
+    }
+}