@you-agent-factory/factory-replay 0.0.0 → 0.0.2

package/dist/load.js

@@ -0,0 +1,260 @@
+import { factoryTopologyEntityId, factoryTopologyNodeId, } from "./topology-identity.js";
+const SYSTEM_WORK_TYPE_ID = "__system_time";
+/** Project selected-tick Work State counts and resource occupancy evidence. */
+export function projectFactoryLoad(input) {
+    if (!input.factory) {
+        return {
+            issues: [
+                {
+                    code: "MISSING_FACTORY",
+                    id: "missing-factory",
+                    message: "No Factory load topology is available at the selected tick.",
+                },
+            ],
+            resourceOccupancy: [],
+            selectedTick: input.selectedTick,
+            workStateCounts: [],
+        };
+    }
+    const issues = new Map();
+    const index = indexFactory(input.factory);
+    const workStateCounts = projectWorkStateCounts(input.works, index, issues);
+    const resourceOccupancy = projectResourceOccupancy(input.activeDispatches, index, issues);
+    return {
+        issues: [...issues.values()].sort((left, right) => left.id.localeCompare(right.id)),
+        resourceOccupancy,
+        selectedTick: input.selectedTick,
+        workStateCounts,
+    };
+}
+function indexFactory(factory) {
+    const resources = [...(factory.resources ?? [])]
+        .map((resource) => {
+        const capacity = Number.isFinite(resource.capacity) && resource.capacity >= 0
+            ? resource.capacity
+            : undefined;
+        return {
+            ...(capacity === undefined ? {} : { capacity }),
+            id: factoryTopologyEntityId(resource.id, resource.name),
+            name: resource.name,
+        };
+    })
+        .sort((left, right) => left.id.localeCompare(right.id));
+    const resourcesByName = new Map(resources.map((resource) => [resource.name, resource]));
+    const states = [];
+    const statesByWorkType = new Map();
+    for (const workType of factory.workTypes ?? []) {
+        const workTypeId = factoryTopologyEntityId(workType.id, workType.name);
+        const statesByReference = new Map();
+        for (const state of workType.states) {
+            const stateId = `${workTypeId}:${factoryTopologyEntityId(state.id, state.name)}`;
+            const indexed = {
+                id: stateId,
+                name: state.name,
+                nodeId: factoryTopologyNodeId("work-state", stateId),
+                workTypeId,
+            };
+            states.push(indexed);
+            statesByReference.set(state.name, indexed);
+            if (state.id?.trim())
+                statesByReference.set(state.id, indexed);
+        }
+        statesByWorkType.set(workType.name, statesByReference);
+        if (workType.id?.trim()) {
+            statesByWorkType.set(workType.id, statesByReference);
+        }
+    }
+    states.sort((left, right) => left.nodeId.localeCompare(right.nodeId));
+    return { resources, resourcesByName, states, statesByWorkType };
+}
+function projectWorkStateCounts(works, index, issues) {
+    if (!works) {
+        return index.states.map((state) => ({
+            evidence: "unavailable",
+            workStateId: state.id,
+            workStateNodeId: state.nodeId,
+            workTypeId: state.workTypeId,
+        }));
+    }
+    const workById = groupWorkEvidence(works);
+    const workIdsByState = new Map();
+    for (const [workId, evidence] of workById) {
+        if (evidence.every((work) => work.workTypeId === SYSTEM_WORK_TYPE_ID)) {
+            continue;
+        }
+        const resolved = evidence.map((work) => resolveWorkState(work, index));
+        if (resolved.some((state) => !state)) {
+            const work = evidence.find((item) => !resolveWorkState(item, index));
+            addIssue(issues, {
+                code: "UNRESOLVED_WORK_STATE",
+                id: `work:${workId}:unresolved-state`,
+                message: `Work ${workId} does not identify a known Work State.`,
+                reference: [work?.workTypeId, work?.stateId ?? work?.stateName]
+                    .filter(Boolean)
+                    .join(":"),
+                workId,
+            });
+            continue;
+        }
+        const statesById = new Map(resolved.flatMap((state) => (state ? [[state.nodeId, state]] : [])));
+        if (statesById.size > 1) {
+            addIssue(issues, {
+                code: "CONTRADICTORY_WORK_STATE",
+                id: `work:${workId}:contradictory-state`,
+                message: `Work ${workId} has contradictory selected-tick Work State evidence.`,
+                workId,
+            });
+            continue;
+        }
+        const state = statesById.values().next().value;
+        if (!state)
+            continue;
+        const workIds = workIdsByState.get(state.nodeId) ?? new Set();
+        workIds.add(workId);
+        workIdsByState.set(state.nodeId, workIds);
+    }
+    return index.states.map((state) => {
+        const workIds = [...(workIdsByState.get(state.nodeId) ?? [])].sort();
+        return {
+            count: workIds.length,
+            evidence: "known",
+            workIds,
+            workStateId: state.id,
+            workStateNodeId: state.nodeId,
+            workTypeId: state.workTypeId,
+        };
+    });
+}
+function groupWorkEvidence(works) {
+    const grouped = new Map();
+    for (const work of works) {
+        if (!work.id)
+            continue;
+        const evidence = grouped.get(work.id) ?? [];
+        evidence.push(structuredClone(work));
+        grouped.set(work.id, evidence);
+    }
+    return grouped;
+}
+function resolveWorkState(work, index) {
+    if (!work.workTypeId)
+        return undefined;
+    const states = index.statesByWorkType.get(work.workTypeId);
+    return work.stateId
+        ? states?.get(work.stateId)
+        : work.stateName
+            ? states?.get(work.stateName)
+            : undefined;
+}
+function projectResourceOccupancy(dispatches, index, issues) {
+    const occupiedByResource = new Map();
+    const unavailableResources = new Set();
+    const normalizedDispatches = normalizeDispatchEvidence(dispatches, issues);
+    const evidenceAvailable = normalizedDispatches?.every((dispatch) => dispatch.resourceClaims !== undefined);
+    for (const dispatch of normalizedDispatches ?? []) {
+        for (const claim of dispatch.resourceClaims ?? []) {
+            const resource = index.resourcesByName.get(claim.resourceName);
+            if (!resource) {
+                addIssue(issues, {
+                    code: "UNRESOLVED_RESOURCE_CLAIM",
+                    dispatchId: dispatch.id,
+                    id: `dispatch:${dispatch.id}:resource:${claim.resourceName}`,
+                    message: `Dispatch ${dispatch.id} claims unknown resource ${claim.resourceName}.`,
+                    reference: claim.resourceName,
+                });
+                continue;
+            }
+            const quantity = claim.quantity ?? 1;
+            if (!Number.isFinite(quantity) || quantity <= 0) {
+                unavailableResources.add(resource.id);
+                addIssue(issues, {
+                    code: "CONTRADICTORY_RESOURCE_CLAIM",
+                    dispatchId: dispatch.id,
+                    id: `dispatch:${dispatch.id}:resource:${resource.id}:invalid-quantity`,
+                    message: `Dispatch ${dispatch.id} has an invalid claim quantity for resource ${resource.id}.`,
+                    resourceId: resource.id,
+                });
+                continue;
+            }
+            occupiedByResource.set(resource.id, (occupiedByResource.get(resource.id) ?? 0) + quantity);
+        }
+    }
+    return index.resources.map((resource) => projectOneResource(resource, occupiedByResource.get(resource.id) ?? 0, evidenceAvailable === true && !unavailableResources.has(resource.id), issues));
+}
+function normalizeDispatchEvidence(dispatches, issues) {
+    if (!dispatches)
+        return undefined;
+    const grouped = new Map();
+    for (const dispatch of dispatches) {
+        const evidence = grouped.get(dispatch.id) ?? [];
+        evidence.push(dispatch);
+        grouped.set(dispatch.id, evidence);
+    }
+    const normalized = [];
+    for (const [dispatchId, evidence] of grouped) {
+        const distinct = new Map(evidence.map((item) => [resourceClaimsKey(item.resourceClaims), item]));
+        if (distinct.size > 1) {
+            addIssue(issues, {
+                code: "CONTRADICTORY_RESOURCE_CLAIM",
+                dispatchId,
+                id: `dispatch:${dispatchId}:contradictory-resource-claims`,
+                message: `Dispatch ${dispatchId} has contradictory selected-tick resource claims.`,
+            });
+            normalized.push({ id: dispatchId });
+            continue;
+        }
+        const only = distinct.values().next().value;
+        if (only)
+            normalized.push(only);
+    }
+    return normalized;
+}
+function resourceClaimsKey(claims) {
+    if (!claims)
+        return "unavailable";
+    return [...claims]
+        .map((claim) => `${claim.resourceName}\u0000${claim.quantity ?? 1}`)
+        .sort()
+        .join("\u0001");
+}
+function projectOneResource(resource, occupiedQuantity, occupancyAvailable, issues) {
+    const base = {
+        ...(resource.capacity === undefined ? {} : { capacity: resource.capacity }),
+        capacityEvidence: resource.capacity === undefined
+            ? "unavailable"
+            : "known",
+        resourceId: resource.id,
+        resourceNodeId: factoryTopologyNodeId("resource", resource.id),
+    };
+    if (resource.capacity === undefined) {
+        addIssue(issues, {
+            code: "INVALID_RESOURCE_CAPACITY",
+            id: `resource:${resource.id}:invalid-capacity`,
+            message: `Resource ${resource.id} does not have a valid canonical capacity.`,
+            resourceId: resource.id,
+        });
+    }
+    if (!occupancyAvailable)
+        return { ...base, evidence: "unavailable" };
+    if (resource.capacity !== undefined && occupiedQuantity > resource.capacity) {
+        addIssue(issues, {
+            code: "RESOURCE_CAPACITY_EXCEEDED",
+            id: `resource:${resource.id}:capacity-exceeded`,
+            message: `Resource ${resource.id} has ${occupiedQuantity} occupied units for capacity ${resource.capacity}.`,
+            resourceId: resource.id,
+        });
+    }
+    return {
+        ...base,
+        ...(resource.capacity === undefined
+            ? {}
+            : {
+                availableQuantity: Math.max(0, resource.capacity - occupiedQuantity),
+            }),
+        evidence: "known",
+        occupiedQuantity,
+    };
+}
+function addIssue(issues, issue) {
+    issues.set(issue.id, issue);
+}

package/dist/progress.d.ts

@@ -0,0 +1,44 @@
+import type { FactoryDefinition, FactoryEvent } from "@you-agent-factory/client";
+export type FactoryWorkStateCategory = "FAILED" | "INITIAL" | "PROCESSING" | "TERMINAL";
+export type FactoryWorkProgressCategory = "failed" | "completed" | "active" | "queued" | "unclassified";
+export interface FactoryWorkProgressStateEvidence {
+    category?: FactoryWorkStateCategory;
+    id?: string;
+    name?: string;
+}
+export interface FactoryWorkProgressEvidence {
+    id: string;
+    state?: FactoryWorkProgressStateEvidence;
+    workTypeId?: string;
+}
+export interface FactoryWorkProgressItem {
+    id: string;
+    stateId?: string;
+    stateName?: string;
+    workTypeId?: string;
+}
+export type FactoryWorkProgressCounts = Record<FactoryWorkProgressCategory, number>;
+export interface FactoryWorkProgressProjection {
+    active: FactoryWorkProgressItem[];
+    completed: FactoryWorkProgressItem[];
+    counts: FactoryWorkProgressCounts;
+    failed: FactoryWorkProgressItem[];
+    queued: FactoryWorkProgressItem[];
+    selectedTick: number;
+    total: number;
+    unclassified: FactoryWorkProgressItem[];
+}
+export interface FactoryWorkProgressProjectionInput {
+    activeWorkIds: readonly string[];
+    factory?: FactoryDefinition;
+    selectedTick: number;
+    works: readonly FactoryWorkProgressEvidence[];
+}
+export interface FactoryWorkProgressAtTickInput {
+    events: readonly FactoryEvent[];
+    tick: number;
+}
+/** Partition customer Work into one mutually exclusive progress category. */
+export declare function projectFactoryWorkProgress(input: FactoryWorkProgressProjectionInput): FactoryWorkProgressProjection;
+/** Reconstruct and exclusively classify customer Work at one logical tick. */
+export declare function projectFactoryWorkProgressAtTick(input: FactoryWorkProgressAtTickInput): FactoryWorkProgressProjection;

package/dist/progress.js

@@ -0,0 +1,278 @@
+import { canonicalizeFactoryEvents } from "./replay.js";
+const SYSTEM_WORK_TYPE_ID = "__system_time";
+/** Partition customer Work into one mutually exclusive progress category. */
+export function projectFactoryWorkProgress(input) {
+    const statesByWorkType = indexWorkStates(input.factory);
+    const activeWorkIds = new Set(input.activeWorkIds);
+    const worksById = new Map();
+    for (const evidence of input.works) {
+        if (!evidence.id || evidence.workTypeId === SYSTEM_WORK_TYPE_ID)
+            continue;
+        worksById.set(evidence.id, structuredClone(evidence));
+    }
+    const projection = {
+        active: [],
+        completed: [],
+        counts: { active: 0, completed: 0, failed: 0, queued: 0, unclassified: 0 },
+        failed: [],
+        queued: [],
+        selectedTick: input.selectedTick,
+        total: worksById.size,
+        unclassified: [],
+    };
+    const works = [...worksById.values()].sort((left, right) => left.id.localeCompare(right.id));
+    for (const evidence of works) {
+        const state = resolveState(evidence, statesByWorkType);
+        const item = {
+            id: evidence.id,
+            ...(evidence.workTypeId ? { workTypeId: evidence.workTypeId } : {}),
+            ...(state?.id ? { stateId: state.id } : {}),
+            ...(state?.name ? { stateName: state.name } : {}),
+        };
+        const category = classifyWork(state?.category, activeWorkIds.has(evidence.id));
+        projection[category].push(item);
+        projection.counts[category] += 1;
+    }
+    return projection;
+}
+/** Reconstruct and exclusively classify customer Work at one logical tick. */
+export function projectFactoryWorkProgressAtTick(input) {
+    const state = {
+        activeDispatches: new Map(),
+        initialWorkIds: new Set(),
+        works: new Map(),
+    };
+    const events = canonicalizeFactoryEvents(input.events).filter((event) => event.context.tick <= input.tick);
+    for (const event of events)
+        applyProgressEvent(state, event);
+    return projectFactoryWorkProgress({
+        activeWorkIds: [...state.activeDispatches.values()].flat(),
+        factory: state.factory,
+        selectedTick: input.tick,
+        works: [...state.works.values()].map((work) => {
+            const initialState = state.initialWorkIds.has(work.id)
+                ? initialStateForWork(state.factory, work.workTypeId)
+                : undefined;
+            return initialState ? { ...work, state: initialState } : work;
+        }),
+    });
+}
+function applyProgressEvent(state, event) {
+    const payload = objectRecord(event.payload);
+    if (event.type === "INITIAL_STRUCTURE_REQUEST" ||
+        event.type === "FACTORY_CHANGE") {
+        if (objectRecord(payload?.factory)) {
+            state.factory = structuredClone(payload?.factory);
+        }
+        return;
+    }
+    if (event.type === "WORK_REQUEST") {
+        for (const work of arrayValue(payload?.works)) {
+            mergeEventWork(state.works, work);
+            const record = objectRecord(work);
+            if (typeof record?.workId === "string") {
+                if (objectRecord(record.state)) {
+                    state.initialWorkIds.delete(record.workId);
+                }
+                else {
+                    state.initialWorkIds.add(record.workId);
+                }
+            }
+        }
+        return;
+    }
+    if (event.type === "WORK_STATE_CHANGE") {
+        applyWorkStateChange(state, payload);
+        return;
+    }
+    if (event.type === "DISPATCH_REQUEST") {
+        applyDispatchRequest(state, event, payload);
+        return;
+    }
+    if (event.type === "DISPATCH_RESPONSE") {
+        applyDispatchResponse(state, event, payload);
+        return;
+    }
+    if (event.type === "DISPATCH_INTERRUPTED") {
+        endDispatch(state, event);
+        return;
+    }
+    if (event.type === "DISPATCH_RECONCILED") {
+        const status = payload?.reconciledStatus;
+        if (status === "COMPLETED" ||
+            status === "FAILED" ||
+            status === "INTERRUPTED") {
+            endDispatch(state, event);
+        }
+    }
+}
+function applyWorkStateChange(state, payload) {
+    if (typeof payload?.workId !== "string" || !payload.workId)
+        return;
+    const previous = state.works.get(payload.workId) ?? { id: payload.workId };
+    state.initialWorkIds.delete(payload.workId);
+    state.works.set(payload.workId, {
+        ...previous,
+        ...(typeof payload.workTypeName === "string"
+            ? { workTypeId: payload.workTypeName }
+            : {}),
+        ...(typeof payload.toState === "string"
+            ? { state: { name: payload.toState } }
+            : {}),
+    });
+}
+function applyDispatchRequest(state, event, payload) {
+    const dispatchId = event.context.dispatchId;
+    const transitionId = payload?.transitionId;
+    if (typeof transitionId === "string" &&
+        transitionId.startsWith("__system_time:")) {
+        return;
+    }
+    const inputIds = arrayValue(payload?.inputs).flatMap((input) => {
+        const record = objectRecord(input);
+        return typeof record?.workId === "string" && record.workId
+            ? [record.workId]
+            : [];
+    });
+    const workIds = [
+        ...new Set([...(event.context.workIds ?? []), ...inputIds].filter(Boolean)),
+    ];
+    for (const workId of workIds) {
+        if (!state.works.has(workId))
+            state.works.set(workId, { id: workId });
+    }
+    if (dispatchId)
+        state.activeDispatches.set(dispatchId, workIds);
+}
+function applyDispatchResponse(state, event, payload) {
+    const dispatchId = event.context.dispatchId;
+    const consumedIds = dispatchId
+        ? (state.activeDispatches.get(dispatchId) ?? [])
+        : [];
+    if (dispatchId)
+        state.activeDispatches.delete(dispatchId);
+    const transitionId = payload?.transitionId;
+    if (typeof transitionId !== "string" ||
+        !transitionId.startsWith("__system_time:")) {
+        for (const workId of event.context.workIds ?? []) {
+            if (workId && !state.works.has(workId)) {
+                state.works.set(workId, { id: workId });
+            }
+        }
+    }
+    const outputWorks = arrayValue(payload?.outputWork);
+    const outputIds = new Set(outputWorks.flatMap((work) => {
+        const record = objectRecord(work);
+        return typeof record?.workId === "string" ? [record.workId] : [];
+    }));
+    for (const workId of consumedIds) {
+        const previous = state.works.get(workId);
+        if (!previous || outputIds.has(workId))
+            continue;
+        state.initialWorkIds.delete(workId);
+        if (previous.state?.category !== "FAILED" &&
+            previous.state?.category !== "TERMINAL") {
+            state.works.set(workId, {
+                id: previous.id,
+                ...(previous.workTypeId ? { workTypeId: previous.workTypeId } : {}),
+            });
+        }
+    }
+    for (const work of outputWorks) {
+        mergeEventWork(state.works, work);
+        const record = objectRecord(work);
+        if (typeof record?.workId === "string") {
+            state.initialWorkIds.delete(record.workId);
+        }
+    }
+}
+function endDispatch(state, event) {
+    if (event.context.dispatchId) {
+        state.activeDispatches.delete(event.context.dispatchId);
+    }
+}
+function indexWorkStates(factory) {
+    const statesByWorkType = new Map();
+    for (const workType of factory?.workTypes ?? []) {
+        const states = new Map();
+        for (const state of workType.states) {
+            const indexed = { ...state, category: state.type };
+            states.set(state.name, indexed);
+            if (state.id?.trim())
+                states.set(state.id, indexed);
+        }
+        statesByWorkType.set(workType.name, states);
+        if (workType.id?.trim())
+            statesByWorkType.set(workType.id, states);
+    }
+    return statesByWorkType;
+}
+function resolveState(evidence, statesByWorkType) {
+    if (evidence.state?.category || !evidence.workTypeId)
+        return evidence.state;
+    const states = statesByWorkType.get(evidence.workTypeId);
+    const indexed = evidence.state?.name
+        ? states?.get(evidence.state.name)
+        : evidence.state?.id
+            ? states?.get(evidence.state.id)
+            : undefined;
+    return indexed ?? evidence.state;
+}
+function initialStateForWork(factory, workTypeId) {
+    if (!workTypeId)
+        return undefined;
+    const workType = factory?.workTypes?.find((candidate) => candidate.name === workTypeId || candidate.id === workTypeId);
+    const state = workType?.states.find((candidate) => candidate.type === "INITIAL");
+    return state ? { ...state, category: state.type } : undefined;
+}
+function mergeEventWork(works, value) {
+    const record = objectRecord(value);
+    if (typeof record?.workId !== "string" || !record.workId)
+        return;
+    const previous = works.get(record.workId) ?? { id: record.workId };
+    const stateRecord = objectRecord(record.state);
+    const state = stateRecord
+        ? {
+            ...(typeof stateRecord.id === "string" ? { id: stateRecord.id } : {}),
+            ...(typeof stateRecord.name === "string"
+                ? { name: stateRecord.name }
+                : {}),
+            ...(isWorkStateCategory(stateRecord.type)
+                ? { category: stateRecord.type }
+                : {}),
+        }
+        : previous.state;
+    works.set(record.workId, {
+        ...previous,
+        ...(typeof record.workTypeName === "string"
+            ? { workTypeId: record.workTypeName }
+            : {}),
+        ...(state ? { state } : {}),
+    });
+}
+function classifyWork(stateCategory, active) {
+    if (stateCategory === "FAILED")
+        return "failed";
+    if (stateCategory === "TERMINAL")
+        return "completed";
+    if (active)
+        return "active";
+    if (stateCategory === "INITIAL" || stateCategory === "PROCESSING") {
+        return "queued";
+    }
+    return "unclassified";
+}
+function isWorkStateCategory(value) {
+    return (value === "FAILED" ||
+        value === "INITIAL" ||
+        value === "PROCESSING" ||
+        value === "TERMINAL");
+}
+function objectRecord(value) {
+    return value !== null && typeof value === "object"
+        ? value
+        : undefined;
+}
+function arrayValue(value) {
+    return Array.isArray(value) ? value : [];
+}

package/dist/replay.d.ts

@@ -0,0 +1,98 @@
+import type { FactoryEvent } from "@you-agent-factory/client";
+export interface FactoryReplayFixedSelection {
+    mode: "fixed";
+    tick: number;
+}
+export type FactoryReplaySelection = {
+    mode: "current";
+} | FactoryReplayFixedSelection;
+/** Domain interpretation stays with the consumer; the kernel owns replay semantics. */
+export interface FactoryReplayReducer<State> {
+    applyEvent(state: State, event: FactoryEvent): State;
+    createState(selectedTick: number): State;
+}
+/** A reducer that also maps its domain state into a consumer-owned view. */
+export interface FactoryReplayWorldReducer<State, World> extends FactoryReplayReducer<State> {
+    projectWorld(state: State): World;
+}
+export interface FactoryReplayInitialization<State> {
+    events: readonly FactoryEvent[];
+    reducer: FactoryReplayReducer<State>;
+    selection: FactoryReplaySelection;
+}
+export interface FactoryReplayCheckpoint<State> {
+    acceptedEventIds: ReadonlySet<string>;
+    appliedEvents: readonly FactoryEvent[];
+    selectedTick: number;
+    state: State;
+}
+export interface FactoryReplayCheckpointAdvancement<State> {
+    checkpoint: FactoryReplayCheckpoint<State>;
+    reducer: FactoryReplayReducer<State>;
+    tail: readonly FactoryEvent[];
+    tick: number;
+}
+export interface FactoryReplayResult<State> extends FactoryReplayCheckpoint<State> {
+    acceptedEventIds: Set<string>;
+    appliedEvents: FactoryEvent[];
+    events: FactoryEvent[];
+    latestTick: number;
+    selectedTick: number;
+    selection: FactoryReplaySelection;
+    state: State;
+}
+export interface FactoryReplayWorldResult<State, World> extends FactoryReplayResult<State> {
+    world: World;
+}
+export type FactoryReplayStateCloner<State> = (state: State) => State;
+/**
+ * A compact checkpoint for consumers that retain domain state but not replay
+ * history. Event IDs make repeated tails idempotent without retaining events.
+ */
+export interface FactoryReplayWorldCheckpoint<State> {
+    acceptedEventIDs: readonly string[];
+    selectedTick: number;
+    state: State;
+}
+export interface FactoryReplayWorldAdvanceInput<State, World> {
+    checkpoint: FactoryReplayWorldCheckpoint<State>;
+    cloneState: FactoryReplayStateCloner<State>;
+    events: readonly FactoryEvent[];
+    reducer: FactoryReplayWorldReducer<State, World>;
+    setSelectedTick(state: State, tick: number): State;
+    tick: number;
+}
+export interface FactoryReplayWorldAdvanceResult<State, World> {
+    appliedEvents: FactoryEvent[];
+    checkpoint: FactoryReplayWorldCheckpoint<State>;
+    latestTick: number;
+    selectedTick: number;
+    state: State;
+    world: World;
+}
+/**
+ * Return one immutable, canonically ordered accepted history. When an ID is
+ * repeated, the canonically earliest event owns that ID.
+ */
+export declare function canonicalizeFactoryEvents(events: readonly FactoryEvent[]): FactoryEvent[];
+/** Reconstruct reducer-owned state for a current or fixed logical tick. */
+export declare function initializeFactoryReplay<State>(input: FactoryReplayInitialization<State>): FactoryReplayResult<State>;
+/** Advance an immutable checkpoint with unseen accepted events through a tick. */
+export declare function advanceFactoryReplayCheckpoint<State>(input: FactoryReplayCheckpointAdvancement<State>): FactoryReplayResult<State>;
+/** Reconstruct reducer-owned state at one explicit logical tick. */
+export declare function projectFactoryStateAtTick<State>(input: Omit<FactoryReplayInitialization<State>, "selection"> & {
+    tick: number;
+}): FactoryReplayResult<State>;
+/** Create an independent compact checkpoint from a selected-tick projection. */
+export declare function createFactoryReplayWorldCheckpoint<State, World>(result: FactoryReplayWorldResult<State, World>, cloneState: FactoryReplayStateCloner<State>): FactoryReplayWorldCheckpoint<State>;
+/**
+ * Advance a compact checkpoint with an accepted tail without retaining the
+ * checkpoint's historical events. The explicit clone and tick adapters keep
+ * domain-state ownership with the consumer.
+ */
+export declare function advanceFactoryReplay<State, World>(input: FactoryReplayWorldAdvanceInput<State, World>): FactoryReplayWorldAdvanceResult<State, World>;
+/** Reconstruct a consumer-owned world at one explicit logical tick. */
+export declare function projectFactoryWorldAtTick<State, World>(input: Omit<FactoryReplayInitialization<State>, "selection"> & {
+    reducer: FactoryReplayWorldReducer<State, World>;
+    tick: number;
+}): FactoryReplayWorldResult<State, World>;