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

package/LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Port
+Copyright (c) 2026-2026 Andreas Abdi
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,58 +1,90 @@
 # `@you-agent-factory/factory-replay`
 
-Framework-independent, deterministic Factory-event replay primitives.
-
-The package accepts public `FactoryEvent` aliases from
-`@you-agent-factory/client`, canonicalizes event history by logical tick,
-sequence, event time, and id, accepts each event id once, and reconstructs a
-caller-defined Factory world at either the latest or an explicit historical
-logical tick. The caller supplies a pure reducer and projection adapter, so the
-package has no React, Zustand, browser, network, session-routing, persistence,
-or diagnostics dependencies.
-
-`createFactoryReplayCheckpoint` and `advanceFactoryReplay` support live replay
-from an accepted tail. Callers provide state-clone and selected-tick adapters;
-the kernel applies only unseen events after the checkpoint tick in canonical
-order and never mutates the supplied checkpoint.
-
-`projectFactoryTopologyAtTick` reconstructs the latest public Factory topology
-at or before an explicit logical tick. `projectFactoryTopology` projects an
-already selected `FactoryDefinition`. Both operations return deterministically
-ordered resource, worker, workstation, Work Type, and Work State nodes plus
-canonical connections. Node and connection IDs follow the public graph ID
-contract, and connection endpoints include renderer-compatible handle IDs.
-References that cannot be resolved are omitted from the connection collection
-and returned as structured projection issues, so consumers never receive a
-dangling edge.
-
-Canonical initial and replacement topology events retain durable IDs for
-resources, workers, workstations, Work Types, and Work States, plus authored
-worker and workstation resource requirements. This lets recordings preserve
-stable graph identity and both resource connection kinds even when public
-entity names change. Internal resource availability arcs present in canonical
-workstation IO are excluded from public Work-State routes and do not create
-false unresolved-connection issues.
-
-`projectFactoryActivityAtTick` reconstructs active customer Dispatches,
-affected workstations, consumed Work IDs, workers, and resource occupancy from
-canonical event history. Consumers that already hold selected replay evidence
-can call `projectFactoryActivity` directly. Occupancy reports known occupied
-and available quantities, or explicitly reports unavailable evidence when an
-active Dispatch lacks resource facts; it never turns missing evidence into a
-fabricated zero occupancy.
-
-`projectFactoryWorkProgressAtTick` reconstructs known customer Work and active
-Dispatch consumption at an explicit logical tick, then assigns every Work ID
-to exactly one of failed, completed, active, queued, or unclassified. The
-classification applies that precedence once, excludes internal time Work, and
-uses `unclassified` when partial event or topology evidence cannot safely
-determine a lifecycle category. `projectFactoryWorkProgress` exposes the same
-pure partition for consumers that already hold selected replay evidence.
-
-The hosted dashboard projects these three public read models from its selected
-checkpoint-safe replay state and exposes them together on the timeline world as
-`factoryReplay`. The production timeline projector also derives the legacy
-dashboard topology/runtime compatibility fields from the shared topology,
-activity, occupancy, and Work-progress decisions. Petri-shaped structures
-remain reducer evidence and supplemental dashboard diagnostics, not a second
-public topology or progress classifier.
+Framework-independent replay utilities for UI-local Factory consumers. The
+package deterministically orders and accepts Factory events, reconstructs
+reducer-owned state at a logical tick, advances immutable checkpoints, and
+projects customer Work into exclusive progress categories.
+
+See the [public package family guide](https://github.com/portpowered/you-agent-factory/blob/main/ui/packages/README.md)
+for the complete layer ordering, packed consumer paths, and execution support
+boundary.
+
+The package consumes Factory contracts from `@you-agent-factory/client` as
+types only. Its runtime has no React, React Flow, Zustand, dashboard, network,
+event-stream, or browser-storage dependency.
+
+## Usage
+
+Import the public entry point and provide a reducer for the state your consumer
+owns:
+
+```ts
+import {
+  projectFactoryStateAtTick,
+  type FactoryReplayReducer,
+} from "@you-agent-factory/factory-replay";
+
+const result = projectFactoryStateAtTick({ events, reducer, tick: 12 });
+```
+
+Hosts that retain only a selected-tick domain checkpoint can use
+`projectFactoryWorldAtTick` and `advanceFactoryReplay`. Those APIs keep domain
+state cloning, tick assignment, and world projection explicit while retaining
+only accepted event IDs in the checkpoint rather than replay history.
+
+## High-volume replay evidence
+
+`ui/src/features/timeline/state/timeline/performance/replay-retained-memory.test.ts`
+replays a deterministic 10,000-event recording through `advanceFactoryReplay`.
+It budgets the UTF-8 serialized retained checkpoint at 2,000,000 bytes and
+verifies the final tick, Work totals, and topology state after an incremental
+same-tick tail containing duplicate input. Replaying the full recording from
+that checkpoint must retain exactly the same bytes and return the same final
+world without reapplying events; the earlier historical world must remain
+unchanged. The caller-owned recording fixture is deliberately excluded from
+the retained measurement: `advanceFactoryReplay` retains only its compact
+checkpoint. The harness uses no wall-clock or process-heap assertions, which
+are not deterministic across CI runtimes, and reports the measured and maximum
+byte counts when the retained bound is exceeded.
+
+Use `projectFactoryWorkProgressAtTick` when canonical event history is the
+source for Work progress, or `projectFactoryWorkProgress` when the consumer
+already has explicit selected-tick evidence.
+Progress classification follows failed, completed, active, queued, then
+unclassified precedence. Active Dispatch evidence is ended by responses,
+interruptions, and terminal reconciliation events, using the same lifecycle
+rules as Dispatch overlays.
+
+Use `projectFactoryTopologyAtTick` to reconstruct the last canonical Factory
+topology effective at a selected tick. Use `projectFactoryTopology` when the
+consumer already has the selected-tick Factory definition. Both return stable,
+sorted public node and connection identities without mutating caller data.
+`FACTORY_TOPOLOGY_RELATIONSHIPS` is the shared semantic node-kind and handle
+vocabulary for renderers. Invalid relationship endpoints return a fail-closed
+result with structured issues and no partial graph.
+
+Use `projectFactoryLoadAtTick` to reconstruct distinct customer Work counts and
+resource occupancy from canonical events, or `projectFactoryLoad` with explicit
+selected-tick evidence. Count and occupancy entries reference the same stable
+Work State and resource node IDs as the topology projection. Missing evidence
+is reported as unavailable rather than fabricated as zero; dangling,
+contradictory, invalid-capacity, and over-capacity evidence remains visible
+through deterministic structured issues.
+
+Use `projectFactoryActivityAtTick` to reconstruct active Dispatch overlays
+after all canonically ordered events at a selected tick, or
+`projectFactoryActivity` with explicit selected-tick evidence. Overlays use
+stable Dispatch and Work projection IDs, reference known worker, workstation,
+resource, and topology-connection IDs, and expose unavailable Work, resource,
+or route evidence without inventing endpoints. Completion, interruption, and
+terminal reconciliation remove activity and release occupancy.
+
+## Distribution verification
+
+Run `bun run verify` from this directory to typecheck and test the package,
+produce clean ESM runtime and declaration output, validate the runtime boundary,
+inspect the exact registry tarball inventory, and install both the packed client
+and replay packages in a clean temporary consumer. The installed consumer
+compiles against the public topology, semantic handle, issue, overlay, load,
+and progress contracts, then verifies that repeated projections remain pure
+and reproducible across caller-owned presentation changes.

package/dist/activity-contract.d.ts

@@ -0,0 +1,62 @@
+import type { FactoryDefinition, FactoryEvent } from "@you-agent-factory/client";
+import type { FactoryResourceOccupancyProjection } from "./load-contract.js";
+export interface FactoryDispatchRouteEvidence {
+    stateId?: string;
+    stateName?: string;
+    workTypeId?: string;
+}
+export interface FactoryActiveDispatchEvidence {
+    id: string;
+    inputRoutes?: readonly FactoryDispatchRouteEvidence[];
+    resourceNames?: readonly string[];
+    startedTick: number;
+    transitionId?: string;
+    workIds?: readonly string[];
+}
+export interface FactoryDispatchOverlayEvidenceStatus {
+    resources: "known" | "unavailable";
+    route: "known" | "unavailable";
+    work: "known" | "unavailable";
+    worker: "known" | "unavailable";
+    workstation: "known" | "unavailable";
+}
+export interface FactoryDispatchOverlayProjection {
+    connectionIds: string[];
+    dispatchId: string;
+    evidence: FactoryDispatchOverlayEvidenceStatus;
+    id: string;
+    resourceIds?: string[];
+    resourceNodeIds?: string[];
+    startedTick: number;
+    transitionId?: string;
+    workerId?: string;
+    workerNodeId?: string;
+    workIds?: string[];
+    workProjectionIds?: string[];
+    workstationId?: string;
+    workstationNodeId?: string;
+}
+export interface FactoryActivityProjectionIssue {
+    code: "CONTRADICTORY_DISPATCH_EVIDENCE" | "INVALID_RESOURCE_CAPACITY" | "MISSING_FACTORY" | "RESOURCE_CAPACITY_EXCEEDED" | "UNAVAILABLE_TOPOLOGY_PATH" | "UNRESOLVED_RESOURCE" | "UNRESOLVED_ROUTE" | "UNRESOLVED_WORKER" | "UNRESOLVED_WORKSTATION";
+    dispatchId?: string;
+    id: string;
+    message: string;
+    reference?: string;
+    resourceId?: string;
+}
+export interface FactoryActivityProjection {
+    activeDispatchOverlays: FactoryDispatchOverlayProjection[];
+    activeWorkstationNodeIds: string[];
+    issues: FactoryActivityProjectionIssue[];
+    resourceOccupancy: FactoryResourceOccupancyProjection[];
+    selectedTick: number;
+}
+export interface FactoryActivityProjectionInput {
+    activeDispatches: readonly FactoryActiveDispatchEvidence[];
+    factory?: FactoryDefinition;
+    selectedTick: number;
+}
+export interface FactoryActivityAtTickInput {
+    events: readonly FactoryEvent[];
+    tick: number;
+}

package/dist/activity-contract.js

@@ -0,0 +1 @@
+export {};

package/dist/activity-replay.d.ts

@@ -0,0 +1,3 @@
+import type { FactoryActivityAtTickInput, FactoryActivityProjection } from "./activity-contract.js";
+/** Reconstruct active Dispatch overlays after all canonical events at one tick. */
+export declare function projectFactoryActivityAtTick(input: FactoryActivityAtTickInput): FactoryActivityProjection;

package/dist/activity-replay.js

@@ -0,0 +1,165 @@
+import { projectFactoryActivity } from "./activity.js";
+import { canonicalizeFactoryEvents } from "./replay.js";
+/** Reconstruct active Dispatch overlays after all canonical events at one tick. */
+export function projectFactoryActivityAtTick(input) {
+    const state = {
+        activeDispatches: new Map(),
+        works: new Map(),
+    };
+    for (const event of canonicalizeFactoryEvents(input.events)) {
+        if (event.context.tick > input.tick)
+            break;
+        applyActivityEvent(state, event);
+    }
+    return projectFactoryActivity({
+        activeDispatches: [...state.activeDispatches.values()],
+        factory: state.factory,
+        selectedTick: input.tick,
+    });
+}
+function applyActivityEvent(state, event) {
+    const payload = objectRecord(event.payload);
+    if (event.type === "INITIAL_STRUCTURE_REQUEST" ||
+        event.type === "FACTORY_CHANGE") {
+        const factory = objectRecord(payload?.factory);
+        if (factory)
+            state.factory = structuredClone(factory);
+        return;
+    }
+    if (event.type === "WORK_REQUEST") {
+        for (const value of arrayValue(payload?.works)) {
+            const work = workRouteEvidence(value, state.factory);
+            if (work)
+                state.works.set(work.id, work);
+        }
+        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" ||
+        event.type === "DISPATCH_INTERRUPTED") {
+        if (event.context.dispatchId) {
+            state.activeDispatches.delete(event.context.dispatchId);
+        }
+        return;
+    }
+    if (event.type === "DISPATCH_RECONCILED") {
+        const status = payload?.reconciledStatus;
+        if (event.context.dispatchId &&
+            (status === "COMPLETED" ||
+                status === "FAILED" ||
+                status === "INTERRUPTED")) {
+            state.activeDispatches.delete(event.context.dispatchId);
+        }
+    }
+}
+function applyWorkStateChange(state, payload) {
+    if (typeof payload?.workId !== "string" || !payload.workId)
+        return;
+    const previous = state.works.get(payload.workId);
+    state.works.set(payload.workId, {
+        id: payload.workId,
+        ...(typeof payload.toState === "string"
+            ? { stateName: payload.toState }
+            : {}),
+        ...(typeof payload.workTypeName === "string"
+            ? { workTypeId: payload.workTypeName }
+            : previous?.workTypeId
+                ? { workTypeId: previous.workTypeId }
+                : {}),
+    });
+}
+function applyDispatchRequest(state, event, payload) {
+    const transitionId = typeof payload?.transitionId === "string"
+        ? payload.transitionId
+        : undefined;
+    if (transitionId?.startsWith("__system_time:"))
+        return;
+    const inputValues = Array.isArray(payload?.inputs)
+        ? payload.inputs
+        : undefined;
+    const inputIds = (inputValues ?? []).flatMap((value) => {
+        const input = objectRecord(value);
+        return typeof input?.workId === "string" && input.workId
+            ? [input.workId]
+            : [];
+    });
+    const hasCompleteInputEvidence = inputValues !== undefined && inputIds.length === inputValues.length;
+    const hasWorkEvidence = event.context.workIds !== undefined || hasCompleteInputEvidence;
+    const workIds = hasWorkEvidence
+        ? [...new Set([...(event.context.workIds ?? []), ...inputIds])]
+        : undefined;
+    const resourceValues = Array.isArray(payload?.resources)
+        ? payload.resources
+        : undefined;
+    const resourceNames = resourceValues?.flatMap((value) => {
+        const resource = objectRecord(value);
+        return typeof resource?.name === "string" && resource.name
+            ? [resource.name]
+            : [];
+    });
+    const completeResources = resourceNames !== undefined &&
+        resourceNames.length === resourceValues?.length;
+    const inputRoutes = workIds?.flatMap((workId) => {
+        const route = state.works.get(workId);
+        return route ? [withoutId(route)] : [];
+    });
+    const completeRoutes = inputRoutes !== undefined && inputRoutes.length === workIds?.length;
+    const dispatchId = event.context.dispatchId ?? `incomplete:${event.id}`;
+    state.activeDispatches.set(dispatchId, {
+        id: dispatchId,
+        ...(completeRoutes ? { inputRoutes } : {}),
+        ...(completeResources ? { resourceNames } : {}),
+        startedTick: event.context.tick,
+        ...(transitionId ? { transitionId } : {}),
+        ...(workIds ? { workIds } : {}),
+    });
+}
+function workRouteEvidence(value, factory) {
+    const work = objectRecord(value);
+    if (typeof work?.workId !== "string" || !work.workId)
+        return undefined;
+    const state = objectRecord(work.state);
+    const evidence = {
+        id: work.workId,
+        ...(typeof state?.id === "string" ? { stateId: state.id } : {}),
+        ...(typeof state?.name === "string" ? { stateName: state.name } : {}),
+        ...(typeof work.workTypeName === "string"
+            ? { workTypeId: work.workTypeName }
+            : {}),
+    };
+    if (evidence.stateId || evidence.stateName || !evidence.workTypeId) {
+        return evidence;
+    }
+    const workType = factory?.workTypes?.find((candidate) => candidate.name === evidence.workTypeId ||
+        candidate.id === evidence.workTypeId);
+    const initial = workType?.states.find((candidate) => candidate.type === "INITIAL");
+    return initial
+        ? {
+            ...evidence,
+            ...(initial.id?.trim() ? { stateId: initial.id } : {}),
+            stateName: initial.name,
+        }
+        : evidence;
+}
+function withoutId(work) {
+    return {
+        ...(work.stateId ? { stateId: work.stateId } : {}),
+        ...(work.stateName ? { stateName: work.stateName } : {}),
+        ...(work.workTypeId ? { workTypeId: work.workTypeId } : {}),
+    };
+}
+function objectRecord(value) {
+    return value !== null && typeof value === "object"
+        ? value
+        : undefined;
+}
+function arrayValue(value) {
+    return Array.isArray(value) ? value : [];
+}

package/dist/activity.d.ts

@@ -0,0 +1,7 @@
+import type { FactoryActivityProjection, FactoryActivityProjectionInput } from "./activity-contract.js";
+/** Build the stable public identity of one active Dispatch overlay. */
+export declare function factoryDispatchOverlayId(dispatchId: string): string;
+/** Build the stable public identity used when an overlay references Work. */
+export declare function factoryWorkProjectionId(workId: string): string;
+/** Project selected-tick active Dispatch overlays and their topology activity. */
+export declare function projectFactoryActivity(input: FactoryActivityProjectionInput): FactoryActivityProjection;