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

package/dist/replay.js

@@ -0,0 +1,144 @@
+function cloneFactoryEvent(event) {
+    return JSON.parse(JSON.stringify(event));
+}
+function canonicalValue(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map(canonicalValue).join(",")}]`;
+    }
+    if (value !== null && typeof value === "object") {
+        const entries = Object.entries(value).sort(([left], [right]) => left.localeCompare(right));
+        return `{${entries
+            .map(([key, item]) => `${JSON.stringify(key)}:${canonicalValue(item)}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "undefined";
+}
+function compareAcceptedEvents(left, right) {
+    const tickDifference = left.context.tick - right.context.tick;
+    if (tickDifference !== 0)
+        return tickDifference;
+    const effectiveSequenceDifference = (left.context.sessionSequence ?? left.context.sequence) -
+        (right.context.sessionSequence ?? right.context.sequence);
+    if (effectiveSequenceDifference !== 0)
+        return effectiveSequenceDifference;
+    const eventLogSequenceDifference = left.context.sequence - right.context.sequence;
+    if (eventLogSequenceDifference !== 0)
+        return eventLogSequenceDifference;
+    const timeDifference = left.context.eventTime.localeCompare(right.context.eventTime);
+    if (timeDifference !== 0)
+        return timeDifference;
+    const idDifference = left.id.localeCompare(right.id);
+    if (idDifference !== 0)
+        return idDifference;
+    return canonicalValue(left).localeCompare(canonicalValue(right));
+}
+/**
+ * Return one immutable, canonically ordered accepted history. When an ID is
+ * repeated, the canonically earliest event owns that ID.
+ */
+export function canonicalizeFactoryEvents(events) {
+    const acceptedEventIds = new Set();
+    return [...events].sort(compareAcceptedEvents).filter((event) => {
+        if (acceptedEventIds.has(event.id))
+            return false;
+        acceptedEventIds.add(event.id);
+        return true;
+    });
+}
+/** Reconstruct reducer-owned state for a current or fixed logical tick. */
+export function initializeFactoryReplay(input) {
+    const events = canonicalizeFactoryEvents(input.events);
+    const latestTick = events.reduce((latest, event) => Math.max(latest, event.context.tick), 0);
+    const selectedTick = input.selection.mode === "current" ? latestTick : input.selection.tick;
+    const appliedEvents = events.filter((event) => event.context.tick <= selectedTick);
+    let state = input.reducer.createState(selectedTick);
+    for (const event of appliedEvents) {
+        state = input.reducer.applyEvent(state, event);
+    }
+    return {
+        acceptedEventIds: new Set(appliedEvents.map(({ id }) => id)),
+        appliedEvents,
+        events,
+        latestTick,
+        selectedTick,
+        selection: input.selection,
+        state,
+    };
+}
+/** Advance an immutable checkpoint with unseen accepted events through a tick. */
+export function advanceFactoryReplayCheckpoint(input) {
+    const checkpointEventIds = new Set(input.checkpoint.acceptedEventIds);
+    const eligibleTail = canonicalizeFactoryEvents(input.tail).filter((event) => event.context.tick <= input.tick && !checkpointEventIds.has(event.id));
+    const events = canonicalizeFactoryEvents([
+        ...input.checkpoint.appliedEvents.map(cloneFactoryEvent),
+        ...eligibleTail.map(cloneFactoryEvent),
+    ]).filter((event) => event.context.tick <= input.tick);
+    let state = input.reducer.createState(input.tick);
+    for (const event of events) {
+        state = input.reducer.applyEvent(state, event);
+    }
+    const acceptedEventIds = new Set(events.map(({ id }) => id));
+    return {
+        acceptedEventIds,
+        appliedEvents: [...events],
+        events,
+        latestTick: events.reduce((latest, event) => Math.max(latest, event.context.tick), 0),
+        selectedTick: input.tick,
+        selection: { mode: "fixed", tick: input.tick },
+        state,
+    };
+}
+/** Reconstruct reducer-owned state at one explicit logical tick. */
+export function projectFactoryStateAtTick(input) {
+    return initializeFactoryReplay({
+        events: input.events,
+        reducer: input.reducer,
+        selection: { mode: "fixed", tick: input.tick },
+    });
+}
+/** Create an independent compact checkpoint from a selected-tick projection. */
+export function createFactoryReplayWorldCheckpoint(result, cloneState) {
+    return {
+        acceptedEventIDs: result.appliedEvents.map((event) => event.id),
+        selectedTick: result.selectedTick,
+        state: cloneState(result.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 function advanceFactoryReplay(input) {
+    const acceptedEventIDs = new Set(input.checkpoint.acceptedEventIDs);
+    const appliedEvents = canonicalizeFactoryEvents(input.events).filter((event) => {
+        if (acceptedEventIDs.has(event.id) ||
+            event.context.tick < input.checkpoint.selectedTick ||
+            event.context.tick > input.tick) {
+            return false;
+        }
+        acceptedEventIDs.add(event.id);
+        return true;
+    });
+    let state = input.setSelectedTick(input.cloneState(input.checkpoint.state), input.tick);
+    for (const event of appliedEvents) {
+        state = input.reducer.applyEvent(state, event);
+    }
+    return {
+        appliedEvents,
+        checkpoint: {
+            acceptedEventIDs: [...acceptedEventIDs],
+            selectedTick: input.tick,
+            state: input.cloneState(state),
+        },
+        latestTick: appliedEvents.reduce((latest, event) => Math.max(latest, event.context.tick), input.checkpoint.selectedTick),
+        selectedTick: input.tick,
+        state,
+        world: input.reducer.projectWorld(state),
+    };
+}
+/** Reconstruct a consumer-owned world at one explicit logical tick. */
+export function projectFactoryWorldAtTick(input) {
+    const result = projectFactoryStateAtTick(input);
+    return { ...result, world: input.reducer.projectWorld(result.state) };
+}

package/dist/topology-connection.d.ts

@@ -0,0 +1,3 @@
+import type { FactoryTopologyConnectionCandidate, FactoryTopologyConnectionResult, FactoryTopologyNode } from "./topology-contract.js";
+/** Validate and project one relationship using the public semantic vocabulary. */
+export declare function projectFactoryTopologyConnection(nodes: readonly FactoryTopologyNode[], candidate: FactoryTopologyConnectionCandidate): FactoryTopologyConnectionResult;

package/dist/topology-connection.js

@@ -0,0 +1,80 @@
+import { FACTORY_TOPOLOGY_RELATIONSHIPS } from "./topology-contract.js";
+function invalidEndpointIssue(candidate, endpoint, reason, expectedNodeKind, handleId) {
+    const connectionId = `${candidate.kind}:${candidate.sourceNodeId ?? candidate.sourceReference}->${candidate.targetNodeId ?? candidate.targetReference}`;
+    const nodeId = endpoint === "source" ? candidate.sourceNodeId : candidate.targetNodeId;
+    const id = `invalid-endpoint:${connectionId}:${endpoint}:${reason}`;
+    return {
+        code: "INVALID_CONNECTION_ENDPOINT",
+        connectionId,
+        connectionKind: candidate.kind,
+        endpoint,
+        endpointReason: reason,
+        expectedNodeKind,
+        handleId,
+        id,
+        message: `Invalid ${endpoint} endpoint for ${candidate.kind} connection ${connectionId}: ${reason}.`,
+        nodeId,
+        sourceReference: candidate.sourceReference,
+        targetReference: candidate.targetReference,
+    };
+}
+/** Validate and project one relationship using the public semantic vocabulary. */
+export function projectFactoryTopologyConnection(nodes, candidate) {
+    if (!Object.hasOwn(FACTORY_TOPOLOGY_RELATIONSHIPS, candidate.kind)) {
+        const connectionId = `${candidate.kind}:${candidate.sourceNodeId ?? candidate.sourceReference}->${candidate.targetNodeId ?? candidate.targetReference}`;
+        return {
+            issue: {
+                code: "UNSUPPORTED_CONNECTION_KIND",
+                connectionId,
+                connectionKind: candidate.kind,
+                id: `unsupported-connection:${connectionId}`,
+                message: `Unsupported Factory topology connection kind ${candidate.kind}.`,
+                sourceReference: candidate.sourceReference,
+                targetReference: candidate.targetReference,
+            },
+            ok: false,
+        };
+    }
+    const kind = candidate.kind;
+    const relationship = FACTORY_TOPOLOGY_RELATIONSHIPS[kind];
+    const nodesById = new Map(nodes.map((node) => [node.id, node]));
+    for (const endpoint of ["source", "target"]) {
+        const endpointContract = relationship[endpoint];
+        const endpointNodeId = endpoint === "source" ? candidate.sourceNodeId : candidate.targetNodeId;
+        const node = endpointNodeId ? nodesById.get(endpointNodeId) : undefined;
+        if (!node) {
+            return {
+                issue: invalidEndpointIssue(candidate, endpoint, "MISSING_NODE", endpointContract.nodeKind, endpointContract.handleId),
+                ok: false,
+            };
+        }
+        if (node.kind !== endpointContract.nodeKind) {
+            return {
+                issue: invalidEndpointIssue(candidate, endpoint, "NODE_KIND_MISMATCH", endpointContract.nodeKind, endpointContract.handleId),
+                ok: false,
+            };
+        }
+        if (!node.handles.some((handle) => handle.id === endpointContract.handleId && handle.role === endpoint)) {
+            return {
+                issue: invalidEndpointIssue(candidate, endpoint, "MISSING_HANDLE", endpointContract.nodeKind, endpointContract.handleId),
+                ok: false,
+            };
+        }
+    }
+    const id = `${kind}:${candidate.sourceNodeId}->${candidate.targetNodeId}`;
+    return {
+        connection: {
+            id,
+            kind,
+            source: {
+                handleId: relationship.source.handleId,
+                nodeId: candidate.sourceNodeId,
+            },
+            target: {
+                handleId: relationship.target.handleId,
+                nodeId: candidate.targetNodeId,
+            },
+        },
+        ok: true,
+    };
+}

package/dist/topology-contract.d.ts

@@ -0,0 +1,187 @@
+import type { FactoryDefinition, FactoryEvent } from "@you-agent-factory/client";
+export type FactoryTopologyNodeKind = "resource" | "worker" | "work-state" | "work-type" | "workstation";
+/**
+ * The canonical relationship vocabulary used to declare node handles and
+ * project connection endpoints. Renderers can use this same value to render
+ * handles without maintaining a parallel mapping.
+ */
+export declare const FACTORY_TOPOLOGY_RELATIONSHIPS: {
+    readonly "worker-assignment": {
+        readonly source: {
+            readonly handleId: "worker-assignment-source";
+            readonly nodeKind: "worker";
+        };
+        readonly target: {
+            readonly handleId: "worker-assignment-target";
+            readonly nodeKind: "workstation";
+        };
+    };
+    readonly "worker-resource": {
+        readonly source: {
+            readonly handleId: "worker-resource-source";
+            readonly nodeKind: "resource";
+        };
+        readonly target: {
+            readonly handleId: "worker-input-target";
+            readonly nodeKind: "worker";
+        };
+    };
+    readonly "workstation-input": {
+        readonly source: {
+            readonly handleId: "workstation-input-source";
+            readonly nodeKind: "work-state";
+        };
+        readonly target: {
+            readonly handleId: "workstation-input-target";
+            readonly nodeKind: "workstation";
+        };
+    };
+    readonly "workstation-on-continue": {
+        readonly source: {
+            readonly handleId: "workstation-on-continue-source";
+            readonly nodeKind: "workstation";
+        };
+        readonly target: {
+            readonly handleId: "work-state-input-target";
+            readonly nodeKind: "work-state";
+        };
+    };
+    readonly "workstation-on-failure": {
+        readonly source: {
+            readonly handleId: "workstation-on-failure-source";
+            readonly nodeKind: "workstation";
+        };
+        readonly target: {
+            readonly handleId: "work-state-input-target";
+            readonly nodeKind: "work-state";
+        };
+    };
+    readonly "workstation-on-rejection": {
+        readonly source: {
+            readonly handleId: "workstation-on-rejection-source";
+            readonly nodeKind: "workstation";
+        };
+        readonly target: {
+            readonly handleId: "work-state-input-target";
+            readonly nodeKind: "work-state";
+        };
+    };
+    readonly "workstation-output": {
+        readonly source: {
+            readonly handleId: "workstation-output-source";
+            readonly nodeKind: "workstation";
+        };
+        readonly target: {
+            readonly handleId: "work-state-input-target";
+            readonly nodeKind: "work-state";
+        };
+    };
+    readonly "workstation-resource": {
+        readonly source: {
+            readonly handleId: "workstation-resource-source";
+            readonly nodeKind: "resource";
+        };
+        readonly target: {
+            readonly handleId: "workstation-resource-target";
+            readonly nodeKind: "workstation";
+        };
+    };
+    readonly "work-type-state": {
+        readonly source: {
+            readonly handleId: "work-type-state-source";
+            readonly nodeKind: "work-type";
+        };
+        readonly target: {
+            readonly handleId: "work-type-state-target";
+            readonly nodeKind: "work-state";
+        };
+    };
+};
+export type FactoryTopologyConnectionKind = keyof typeof FACTORY_TOPOLOGY_RELATIONSHIPS;
+export type FactoryTopologyHandleId = (typeof FACTORY_TOPOLOGY_RELATIONSHIPS)[FactoryTopologyConnectionKind]["source" | "target"]["handleId"];
+export interface FactoryTopologyHandle {
+    id: FactoryTopologyHandleId;
+    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" | "INVALID_CONNECTION_ENDPOINT" | "MISSING_FACTORY" | "UNSUPPORTED_CONNECTION_KIND";
+    connectionId?: string;
+    connectionKind?: string;
+    endpoint?: "source" | "target";
+    endpointReason?: "MISSING_HANDLE" | "MISSING_NODE" | "NODE_KIND_MISMATCH";
+    expectedNodeKind?: FactoryTopologyNodeKind;
+    handleId?: string;
+    id: string;
+    message: string;
+    nodeId?: string;
+    sourceReference?: string;
+    targetReference?: string;
+}
+export interface FactoryTopologyProjection {
+    connections: FactoryTopologyConnection[];
+    issues: FactoryTopologyProjectionIssue[];
+    nodes: FactoryTopologyNode[];
+    ok: boolean;
+    selectedTick: number;
+}
+export interface FactoryTopologyConnectionCandidate {
+    kind: string;
+    sourceNodeId?: string;
+    sourceReference: string;
+    targetNodeId?: string;
+    targetReference: string;
+}
+export type FactoryTopologyConnectionResult = {
+    connection: FactoryTopologyConnection;
+    issue?: never;
+    ok: true;
+} | {
+    connection?: never;
+    issue: FactoryTopologyProjectionIssue;
+    ok: false;
+};
+export interface FactoryTopologyProjectionInput {
+    factory?: FactoryDefinition;
+    selectedTick: number;
+}
+export interface FactoryTopologyAtTickInput {
+    events: readonly FactoryEvent[];
+    tick: number;
+}
+export {};

package/dist/topology-contract.js

@@ -0,0 +1,67 @@
+/**
+ * The canonical relationship vocabulary used to declare node handles and
+ * project connection endpoints. Renderers can use this same value to render
+ * handles without maintaining a parallel mapping.
+ */
+export const FACTORY_TOPOLOGY_RELATIONSHIPS = {
+    "worker-assignment": {
+        source: { handleId: "worker-assignment-source", nodeKind: "worker" },
+        target: {
+            handleId: "worker-assignment-target",
+            nodeKind: "workstation",
+        },
+    },
+    "worker-resource": {
+        source: { handleId: "worker-resource-source", nodeKind: "resource" },
+        target: { handleId: "worker-input-target", nodeKind: "worker" },
+    },
+    "workstation-input": {
+        source: { handleId: "workstation-input-source", nodeKind: "work-state" },
+        target: {
+            handleId: "workstation-input-target",
+            nodeKind: "workstation",
+        },
+    },
+    "workstation-on-continue": {
+        source: {
+            handleId: "workstation-on-continue-source",
+            nodeKind: "workstation",
+        },
+        target: { handleId: "work-state-input-target", nodeKind: "work-state" },
+    },
+    "workstation-on-failure": {
+        source: {
+            handleId: "workstation-on-failure-source",
+            nodeKind: "workstation",
+        },
+        target: { handleId: "work-state-input-target", nodeKind: "work-state" },
+    },
+    "workstation-on-rejection": {
+        source: {
+            handleId: "workstation-on-rejection-source",
+            nodeKind: "workstation",
+        },
+        target: { handleId: "work-state-input-target", nodeKind: "work-state" },
+    },
+    "workstation-output": {
+        source: {
+            handleId: "workstation-output-source",
+            nodeKind: "workstation",
+        },
+        target: { handleId: "work-state-input-target", nodeKind: "work-state" },
+    },
+    "workstation-resource": {
+        source: {
+            handleId: "workstation-resource-source",
+            nodeKind: "resource",
+        },
+        target: {
+            handleId: "workstation-resource-target",
+            nodeKind: "workstation",
+        },
+    },
+    "work-type-state": {
+        source: { handleId: "work-type-state-source", nodeKind: "work-type" },
+        target: { handleId: "work-type-state-target", nodeKind: "work-state" },
+    },
+};

package/dist/topology-identity.d.ts

@@ -0,0 +1,5 @@
+import type { FactoryTopologyNodeKind } from "./topology-contract.js";
+/** Resolve the durable public identity used by every topology projection. */
+export declare function factoryTopologyEntityId(explicitId: string | undefined, name: string): string;
+/** Build the renderer-facing node identity for one canonical Factory entity. */
+export declare function factoryTopologyNodeId(kind: FactoryTopologyNodeKind, entityId: string): string;

package/dist/topology-identity.js

@@ -0,0 +1,8 @@
+/** Resolve the durable public identity used by every topology projection. */
+export function factoryTopologyEntityId(explicitId, name) {
+    return explicitId?.trim() || name;
+}
+/** Build the renderer-facing node identity for one canonical Factory entity. */
+export function factoryTopologyNodeId(kind, entityId) {
+    return `${kind}:${entityId}`;
+}

package/dist/topology.d.ts

@@ -0,0 +1,9 @@
+import type { FactoryTopologyAtTickInput, FactoryTopologyProjection, FactoryTopologyProjectionInput } from "./topology-contract.js";
+export { projectFactoryTopologyConnection } from "./topology-connection.js";
+export type { FactoryResourceTopologyNode, FactoryTopologyAtTickInput, FactoryTopologyConnection, FactoryTopologyConnectionCandidate, FactoryTopologyConnectionEndpoint, FactoryTopologyConnectionKind, FactoryTopologyConnectionResult, FactoryTopologyHandle, FactoryTopologyHandleId, FactoryTopologyNode, FactoryTopologyNodeKind, FactoryTopologyProjection, FactoryTopologyProjectionInput, FactoryTopologyProjectionIssue, FactoryWorkerTopologyNode, FactoryWorkStateTopologyNode, FactoryWorkstationTopologyNode, FactoryWorkTypeTopologyNode, } from "./topology-contract.js";
+export { FACTORY_TOPOLOGY_RELATIONSHIPS } from "./topology-contract.js";
+export { factoryTopologyEntityId, factoryTopologyNodeId, } from "./topology-identity.js";
+/** Project one public Factory definition without mutating caller-owned data. */
+export declare function projectFactoryTopology(input: FactoryTopologyProjectionInput): FactoryTopologyProjection;
+/** Reconstruct the last canonical Factory topology effective at one tick. */
+export declare function projectFactoryTopologyAtTick(input: FactoryTopologyAtTickInput): FactoryTopologyProjection;