@you-agent-factory/factory-replay 0.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Port
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,58 @@
+# `@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.

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@you-agent-factory/factory-replay",
+  "version": "0.0.0",
+  "description": "Framework-independent deterministic replay primitives for Factory events.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/portpowered/you-agent-factory.git"
+  },
+  "type": "module",
+  "files": [
+    "README.md",
+    "LICENSE.md",
+    "src"
+  ],
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "dependencies": {
+    "@you-agent-factory/client": "file:../client"
+  }
+}

package/src/activity.js

@@ -0,0 +1,208 @@
+/** @param {string | undefined} explicitID @param {string} name */
+function entityID(explicitID, name) {
+  return explicitID?.trim() || name;
+}
+
+/** @param {string} id */
+function workstationNodeID(id) {
+  return `workstation:${id}`;
+}
+
+/** @param {string} id */
+function resourceNodeID(id) {
+  return `resource:${id}`;
+}
+
+/**
+ * Project active Dispatch and resource occupancy evidence from one selected
+ * canonical replay state without mutating caller-owned data.
+ *
+ * @param {import("./index.d.ts").FactoryActivityProjectionInput} input
+ * @returns {import("./index.d.ts").FactoryActivityProjection}
+ */
+export function projectFactoryActivity(input) {
+  const issues = new Map();
+  const { resourcesByName, workstationsByTransition } = indexFactory(
+    input.factory,
+  );
+
+  const occupiedByResource = new Map();
+  const occupancyEvidenceAvailable = input.activeDispatches.every(
+    (dispatch) => dispatch.resourceNames !== undefined,
+  );
+  const activeDispatches = input.activeDispatches.map((evidence) => {
+    const resolved = workstationsByTransition.get(evidence.transitionId);
+    const resourceIds = [];
+    for (const resourceName of evidence.resourceNames ?? []) {
+      const resource = resourcesByName.get(resourceName);
+      if (!resource) {
+        addIssue(
+          issues,
+          "UNRESOLVED_RESOURCE",
+          `dispatch:${evidence.id}:resource:${resourceName}`,
+          `Dispatch ${evidence.id} refers to unknown resource ${resourceName}.`,
+          evidence.id,
+          resourceName,
+        );
+        continue;
+      }
+      resourceIds.push(resource.id);
+      occupiedByResource.set(
+        resource.id,
+        (occupiedByResource.get(resource.id) ?? 0) + 1,
+      );
+    }
+    if (!resolved) {
+      addIssue(
+        issues,
+        "UNRESOLVED_WORKSTATION",
+        `dispatch:${evidence.id}:workstation:${evidence.transitionId}`,
+        `Dispatch ${evidence.id} refers to unknown workstation transition ${evidence.transitionId}.`,
+        evidence.id,
+        evidence.transitionId,
+      );
+    }
+    const workerName = resolved?.workstation.worker?.trim();
+    const worker = workerName
+      ? (input.factory?.workers ?? []).find(
+          (candidate) =>
+            candidate.name === workerName || candidate.id === workerName,
+        )
+      : undefined;
+    if (workerName && !worker) {
+      addIssue(
+        issues,
+        "UNRESOLVED_WORKER",
+        `dispatch:${evidence.id}:worker:${workerName}`,
+        `Dispatch ${evidence.id} refers to unknown worker ${workerName}.`,
+        evidence.id,
+        workerName,
+      );
+    }
+    return {
+      id: evidence.id,
+      resourceIds: [...resourceIds].sort(),
+      startedTick: evidence.startedTick,
+      transitionId: evidence.transitionId,
+      workIds: [...new Set(evidence.workIds)].sort(),
+      ...(resolved
+        ? {
+            workstationId: resolved.id,
+            workstationNodeId: workstationNodeID(resolved.id),
+          }
+        : {}),
+      ...(worker
+        ? { workerId: entityID(worker.id, worker.name) }
+        : {}),
+    };
+  });
+
+  const resourceOccupancy = projectResourceOccupancy(
+    resourcesByName,
+    occupiedByResource,
+    occupancyEvidenceAvailable,
+    issues,
+  );
+
+  return {
+    activeDispatches: activeDispatches.sort((left, right) =>
+      left.id.localeCompare(right.id),
+    ),
+    activeWorkstationIds: [
+      ...new Set(
+        activeDispatches.flatMap((dispatch) =>
+          dispatch.workstationId ? [dispatch.workstationId] : [],
+        ),
+      ),
+    ].sort(),
+    issues: [...issues.values()].sort((left, right) =>
+      left.id.localeCompare(right.id),
+    ),
+    resourceOccupancy: resourceOccupancy.sort((left, right) =>
+      left.resourceId.localeCompare(right.resourceId),
+    ),
+    selectedTick: input.selectedTick,
+  };
+}
+
+/** @param {import("@you-agent-factory/client").FactoryDefinition | undefined} factory */
+function indexFactory(factory) {
+  const resourcesByName = new Map();
+  const workstationsByTransition = new Map();
+  for (const resource of factory?.resources ?? []) {
+    resourcesByName.set(resource.name, {
+      capacity: Math.max(0, resource.capacity),
+      id: entityID(resource.id, resource.name),
+    });
+  }
+  for (const workstation of factory?.workstations ?? []) {
+    const id = entityID(workstation.id, workstation.name);
+    workstationsByTransition.set(workstation.name, { id, workstation });
+    if (workstation.id?.trim()) {
+      workstationsByTransition.set(workstation.id, { id, workstation });
+    }
+  }
+  return { resourcesByName, workstationsByTransition };
+}
+
+/**
+ * @param {Map<string, {capacity: number, id: string}>} resourcesByName
+ * @param {Map<string, number>} occupiedByResource
+ * @param {boolean} evidenceAvailable
+ * @param {Map<string, import("./index.d.ts").FactoryActivityProjectionIssue>} issues
+ * @returns {import("./index.d.ts").FactoryResourceOccupancyProjection[]}
+ */
+function projectResourceOccupancy(
+  resourcesByName,
+  occupiedByResource,
+  evidenceAvailable,
+  issues,
+) {
+  return [...resourcesByName.values()].map((resource) => {
+    if (!evidenceAvailable) {
+      return {
+        capacity: resource.capacity,
+        evidence: "unavailable",
+        resourceId: resource.id,
+        resourceNodeId: resourceNodeID(resource.id),
+      };
+    }
+    const occupiedQuantity = occupiedByResource.get(resource.id) ?? 0;
+    if (occupiedQuantity > resource.capacity) {
+      addIssue(
+        issues,
+        "RESOURCE_CAPACITY_EXCEEDED",
+        `resource:${resource.id}:capacity-exceeded`,
+        `Resource ${resource.id} has ${occupiedQuantity} occupied units for capacity ${resource.capacity}.`,
+        undefined,
+        resource.id,
+      );
+    }
+    return {
+      availableQuantity: Math.max(0, resource.capacity - occupiedQuantity),
+      capacity: resource.capacity,
+      evidence: "known",
+      occupiedQuantity,
+      resourceId: resource.id,
+      resourceNodeId: resourceNodeID(resource.id),
+    };
+  });
+}
+
+/**
+ * @param {Map<string, import("./index.d.ts").FactoryActivityProjectionIssue>} issues
+ * @param {import("./index.d.ts").FactoryActivityProjectionIssue["code"]} code
+ * @param {string} id
+ * @param {string} message
+ * @param {string | undefined} dispatchId
+ * @param {string | undefined} reference
+ */
+function addIssue(issues, code, id, message, dispatchId, reference) {
+  issues.set(id, {
+    code,
+    id,
+    message,
+    ...(dispatchId ? { dispatchId } : {}),
+    ...(reference ? { reference } : {}),
+  });
+}

package/src/index.d.ts

@@ -0,0 +1,324 @@
+import type { FactoryEvent } from "@you-agent-factory/client";
+import type { FactoryDefinition } from "@you-agent-factory/client";
+
+export type FactoryTopologyNodeKind =
+  | "resource"
+  | "worker"
+  | "work-state"
+  | "work-type"
+  | "workstation";
+
+export type FactoryTopologyConnectionKind =
+  | "worker-assignment"
+  | "worker-resource"
+  | "workstation-input"
+  | "workstation-on-continue"
+  | "workstation-on-failure"
+  | "workstation-on-rejection"
+  | "workstation-output"
+  | "workstation-resource"
+  | "work-type-state";
+
+export interface FactoryTopologyHandle {
+  id: string;
+  role: "source" | "target";
+}
+
+interface FactoryTopologyNodeBase {
+  entityId: string;
+  handles: FactoryTopologyHandle[];
+  id: string;
+  kind: FactoryTopologyNodeKind;
+  label: string;
+}
+
+export interface FactoryResourceTopologyNode extends FactoryTopologyNodeBase {
+  capacity: number;
+  kind: "resource";
+}
+
+export interface FactoryWorkerTopologyNode extends FactoryTopologyNodeBase {
+  kind: "worker";
+}
+
+export interface FactoryWorkTypeTopologyNode extends FactoryTopologyNodeBase {
+  kind: "work-type";
+}
+
+export interface FactoryWorkStateTopologyNode extends FactoryTopologyNodeBase {
+  category: NonNullable<FactoryDefinition["workTypes"]>[number]["states"][number]["type"];
+  kind: "work-state";
+  workTypeId: string;
+}
+
+export interface FactoryWorkstationTopologyNode
+  extends FactoryTopologyNodeBase {
+  kind: "workstation";
+}
+
+export type FactoryTopologyNode =
+  | FactoryResourceTopologyNode
+  | FactoryWorkerTopologyNode
+  | FactoryWorkStateTopologyNode
+  | FactoryWorkTypeTopologyNode
+  | FactoryWorkstationTopologyNode;
+
+export interface FactoryTopologyConnectionEndpoint {
+  handleId: string;
+  nodeId: string;
+}
+
+export interface FactoryTopologyConnection {
+  id: string;
+  kind: FactoryTopologyConnectionKind;
+  source: FactoryTopologyConnectionEndpoint;
+  target: FactoryTopologyConnectionEndpoint;
+}
+
+export interface FactoryTopologyProjectionIssue {
+  code: "DUPLICATE_ENTITY_ID" | "MISSING_FACTORY" | "UNRESOLVED_CONNECTION";
+  connectionKind?: FactoryTopologyConnectionKind;
+  id: string;
+  message: string;
+  nodeId?: string;
+  sourceReference?: string;
+  targetReference?: string;
+}
+
+export interface FactoryTopologyProjection {
+  connections: FactoryTopologyConnection[];
+  issues: FactoryTopologyProjectionIssue[];
+  nodes: FactoryTopologyNode[];
+  selectedTick: number;
+}
+
+export interface FactoryTopologyProjectionInput {
+  factory?: FactoryDefinition | undefined;
+  selectedTick: number;
+}
+
+export interface FactoryTopologyAtTickInput {
+  events: readonly FactoryEvent[];
+  tick: number;
+}
+
+export interface FactoryActiveDispatchEvidence {
+  id: string;
+  resourceNames?: readonly string[];
+  startedTick: number;
+  transitionId: string;
+  workIds: readonly string[];
+}
+
+export interface FactoryActiveDispatchProjection {
+  id: string;
+  resourceIds: string[];
+  startedTick: number;
+  transitionId: string;
+  workIds: string[];
+  workerId?: string;
+  workstationId?: string;
+  workstationNodeId?: string;
+}
+
+export interface FactoryResourceOccupancyProjection {
+  availableQuantity?: number;
+  capacity: number;
+  evidence: "known" | "unavailable";
+  occupiedQuantity?: number;
+  occupiedTokenIds?: string[];
+  resourceId: string;
+  resourceNodeId: string;
+}
+
+export interface FactoryActivityProjectionIssue {
+  code:
+    | "RESOURCE_CAPACITY_EXCEEDED"
+    | "UNRESOLVED_RESOURCE"
+    | "UNRESOLVED_WORKER"
+    | "UNRESOLVED_WORKSTATION";
+  dispatchId?: string;
+  id: string;
+  message: string;
+  reference?: string;
+}
+
+export interface FactoryActivityProjection {
+  activeDispatches: FactoryActiveDispatchProjection[];
+  activeWorkstationIds: string[];
+  issues: FactoryActivityProjectionIssue[];
+  resourceOccupancy: FactoryResourceOccupancyProjection[];
+  selectedTick: number;
+}
+
+export interface FactoryActivityProjectionInput {
+  activeDispatches: readonly FactoryActiveDispatchEvidence[];
+  factory?: FactoryDefinition | undefined;
+  selectedTick: number;
+}
+
+export interface FactoryActivityAtTickInput {
+  events: readonly FactoryEvent[];
+  tick: number;
+}
+
+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 | undefined;
+  selectedTick: number;
+  works: readonly FactoryWorkProgressEvidence[];
+}
+
+export interface FactoryWorkProgressAtTickInput {
+  events: readonly FactoryEvent[];
+  tick: number;
+}
+
+export type FactoryReplaySelection =
+  | { mode: "current" }
+  | { mode: "fixed"; tick: number };
+
+export interface FactoryReplayReducer<State, World> {
+  createState(selectedTick: number): State;
+  applyEvent(state: State, event: FactoryEvent): State;
+  projectWorld(state: State): World;
+}
+
+export interface FactoryReplayInitialization<State, World> {
+  events: readonly FactoryEvent[];
+  reducer: FactoryReplayReducer<State, World>;
+  selection: FactoryReplaySelection;
+}
+
+export interface FactoryReplayResult<State, World> {
+  appliedEvents: FactoryEvent[];
+  events: FactoryEvent[];
+  latestTick: number;
+  selectedTick: number;
+  selection: FactoryReplaySelection;
+  state: State;
+  world: World;
+}
+
+export type FactoryReplayStateCloner<State> = (state: State) => State;
+
+export interface FactoryReplayCheckpoint<State> {
+  acceptedEventIDs: readonly string[];
+  selectedTick: number;
+  state: State;
+}
+
+export interface FactoryReplayAdvanceInput<State, World> {
+  checkpoint: FactoryReplayCheckpoint<State>;
+  cloneState: FactoryReplayStateCloner<State>;
+  events: readonly FactoryEvent[];
+  reducer: FactoryReplayReducer<State, World>;
+  setSelectedTick(state: State, tick: number): State;
+  tick: number;
+}
+
+export interface FactoryReplayAdvanceResult<State, World> {
+  appliedEvents: FactoryEvent[];
+  checkpoint: FactoryReplayCheckpoint<State>;
+  latestTick: number;
+  selectedTick: number;
+  state: State;
+  world: World;
+}
+
+export function compareFactoryEvents(
+  left: FactoryEvent,
+  right: FactoryEvent,
+): number;
+
+export function canonicalizeFactoryEvents(
+  events: readonly FactoryEvent[],
+): FactoryEvent[];
+
+export function initializeFactoryReplay<State, World>(
+  input: FactoryReplayInitialization<State, World>,
+): FactoryReplayResult<State, World>;
+
+export function createFactoryReplayCheckpoint<State, World>(
+  result: FactoryReplayResult<State, World>,
+  cloneState: FactoryReplayStateCloner<State>,
+): FactoryReplayCheckpoint<State>;
+
+export function advanceFactoryReplay<State, World>(
+  input: FactoryReplayAdvanceInput<State, World>,
+): FactoryReplayAdvanceResult<State, World>;
+
+export function projectFactoryWorldAtTick<State, World>(
+  input: Omit<FactoryReplayInitialization<State, World>, "selection"> & {
+    tick: number;
+  },
+): FactoryReplayResult<State, World>;
+
+export function projectFactoryTopology(
+  input: FactoryTopologyProjectionInput,
+): FactoryTopologyProjection;
+
+export function projectFactoryTopologyAtTick(
+  input: FactoryTopologyAtTickInput,
+): FactoryTopologyProjection;
+
+export function projectFactoryActivity(
+  input: FactoryActivityProjectionInput,
+): FactoryActivityProjection;
+
+export function projectFactoryActivityAtTick(
+  input: FactoryActivityAtTickInput,
+): FactoryActivityProjection;
+
+export function projectFactoryWorkProgress(
+  input: FactoryWorkProgressProjectionInput,
+): FactoryWorkProgressProjection;
+
+export function projectFactoryWorkProgressAtTick(
+  input: FactoryWorkProgressAtTickInput,
+): FactoryWorkProgressProjection;