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

package/dist/runtime-reference-evidence.d.ts

@@ -0,0 +1,9 @@
+import type { FactoryEvent } from "@you-agent-factory/client";
+import type { FactoryEmulatorRuntimeReferenceProvenance, FactoryEmulatorRuntimeReferenceTick } from "./runtime-reference.js";
+type FrozenEvidence = Readonly<{
+    provenance: FactoryEmulatorRuntimeReferenceProvenance;
+    ticks: readonly FactoryEmulatorRuntimeReferenceTick[];
+    orderedEventKinds: readonly FactoryEvent["type"][];
+}>;
+export declare const frozenRuntimeReferenceEvidence: Readonly<Record<string, FrozenEvidence>>;
+export {};

package/dist/runtime-reference-evidence.js

@@ -0,0 +1,193 @@
+const source = (anchor) => ({
+    kind: "public-documentation",
+    source: `docs/reference/${anchor} (pre-existing public runtime behavior documentation)`,
+});
+const semantics = (overrides = {}) => ({
+    dispatchChoices: [],
+    consumedWork: [],
+    outcomes: [],
+    routes: [],
+    terminalStates: [],
+    replayProjection: [],
+    ...overrides,
+});
+const tick = (logicalTick, eventKinds, values = {}) => ({
+    logicalTick,
+    eventKinds,
+    semantics: semantics(values),
+});
+const ordered = (ticks) => ticks.flatMap(({ eventKinds }) => eventKinds);
+const bootstrap = () => tick(0, ["RUN_REQUEST", "INITIAL_STRUCTURE_REQUEST", "SESSION_STARTED"]);
+const submitted = (projection, kinds = ["WORK_REQUEST"]) => tick(1, kinds, { replayProjection: projection });
+const dispatch = (logicalTick, choices, projection, terminalStates = []) => tick(logicalTick, choices.map(() => "DISPATCH_REQUEST"), { dispatchChoices: choices, terminalStates, replayProjection: projection });
+const response = (logicalTick, consumedWork, outcomes, routes, terminalStates, projection, kinds = []) => tick(logicalTick, kinds.length === 0
+    ? outcomes.map(() => "DISPATCH_RESPONSE")
+    : kinds, {
+    consumedWork,
+    outcomes,
+    routes,
+    terminalStates,
+    replayProjection: projection,
+});
+const input = ["input:task:ready"];
+const parallel = ["first:task:ready", "second:task:ready"];
+const contention = [
+    "first:task:ready",
+    "second:task:ready",
+    "third:task:ready",
+];
+const dependencies = ["blocked:task:ready", "prerequisite:task:ready"];
+// This is intentionally independent, literal expected evidence. Do not derive it from Factory or scenario inputs.
+export const frozenRuntimeReferenceEvidence = {
+    "basic-execution": (() => {
+        const ticks = [
+            bootstrap(),
+            submitted(input),
+            dispatch(2, ["execute:input"], input),
+            response(3, ["input"], ["ACCEPTED"], ['task:done:"frozen input"'], ["task:done"], input),
+        ];
+        return {
+            provenance: source("workstations.md#agent_run-execution"),
+            ticks,
+            orderedEventKinds: ordered(ticks),
+        };
+    })(),
+    repeaters: (() => {
+        const ticks = [
+            bootstrap(),
+            submitted(input),
+            dispatch(2, ["execute:input"], input),
+            response(3, ["input"], ["CONTINUE"], ['task:ready:"frozen input"'], [], input),
+            dispatch(4, ["execute:input/execute/0"], input),
+            response(5, ["input"], ["ACCEPTED"], ['task:done:"frozen input"'], ["task:done"], input),
+        ];
+        return {
+            provenance: source("workstations.md#repeater-workstations"),
+            ticks,
+            orderedEventKinds: ordered(ticks),
+        };
+    })(),
+    routing: (() => {
+        const ticks = [
+            bootstrap(),
+            submitted(input),
+            dispatch(2, ["execute:input"], input),
+            response(3, ["input"], ["REJECTED"], ['task:failed:"frozen input"'], ["task:failed"], input),
+        ];
+        return {
+            provenance: source("workstations.md#topology-fields"),
+            ticks,
+            orderedEventKinds: ordered(ticks),
+        };
+    })(),
+    "logical-moves": (() => {
+        const ticks = [
+            bootstrap(),
+            submitted(input),
+            dispatch(2, ["execute:input"], input),
+            response(3, ["input"], ["ACCEPTED"], ['task:ready:"worker output"'], [], input),
+            response(4, ["input"], ["ACCEPTED"], ['task:done:"worker output"'], ["task:done"], input),
+        ];
+        return {
+            provenance: source("workstations.md#behavior-versus-type"),
+            ticks,
+            orderedEventKinds: ordered(ticks),
+        };
+    })(),
+    "multi-input-output": (() => {
+        const projection = ["input-two:task:ready", "input:task:ready"];
+        const ticks = [
+            bootstrap(),
+            submitted(projection),
+            dispatch(2, ["execute:input,input-two"], projection),
+            response(3, ["input", "input-two"], ["ACCEPTED"], ['task:done:"frozen input"', 'task:done:"frozen input"'], ["task:done", "task:done"], projection),
+        ];
+        return {
+            provenance: source("workstations.md#topology-fields"),
+            ticks,
+            orderedEventKinds: ordered(ticks),
+        };
+    })(),
+    propagation: (() => {
+        const ticks = [
+            bootstrap(),
+            submitted(input),
+            dispatch(2, ["execute:input"], input),
+            response(3, ["input"], ["ACCEPTED"], ['task:done:"frozen input"'], ["task:done"], input),
+        ];
+        return {
+            provenance: source("workstations.md#work-payload-propagation"),
+            ticks,
+            orderedEventKinds: ordered(ticks),
+        };
+    })(),
+    "parallel-dispatch": (() => {
+        const ticks = [
+            bootstrap(),
+            submitted(parallel),
+            dispatch(2, ["execute:first", "execute:second"], parallel),
+            response(3, ["first", "second"], ["ACCEPTED", "ACCEPTED"], ['task:done:"first frozen input"', 'task:done:"second frozen input"'], ["task:done", "task:done"], parallel),
+        ];
+        return {
+            provenance: source("workstations.md#agent_run-execution"),
+            ticks,
+            orderedEventKinds: ordered(ticks),
+        };
+    })(),
+    "simultaneous-completion": (() => {
+        const ticks = [
+            bootstrap(),
+            submitted(parallel),
+            dispatch(2, ["execute:first", "execute:second"], parallel),
+            response(3, ["first", "second"], ["ACCEPTED", "ACCEPTED"], ['task:done:"first frozen input"', 'task:done:"second frozen input"'], ["task:done", "task:done"], parallel),
+        ];
+        return {
+            provenance: source("workstations.md#agent_run-execution"),
+            ticks,
+            orderedEventKinds: ordered(ticks),
+        };
+    })(),
+    "resource-contention": (() => {
+        const ticks = [
+            bootstrap(),
+            submitted(contention),
+            dispatch(2, ["execute:first", "execute:third"], contention),
+            response(3, ["first", "third"], ["ACCEPTED", "ACCEPTED"], ['task:done:"first frozen input"', 'task:done:"third frozen input"'], ["task:done", "task:done"], contention),
+            dispatch(4, ["execute:second"], contention, ["task:done", "task:done"]),
+            response(5, ["second"], ["ACCEPTED"], ['task:done:"second frozen input"'], ["task:done", "task:done", "task:done"], contention),
+        ];
+        return {
+            provenance: source("workstations.md#current-contract"),
+            ticks,
+            orderedEventKinds: ordered(ticks),
+        };
+    })(),
+    "depends-on-release": (() => {
+        const ticks = [
+            bootstrap(),
+            submitted(dependencies, ["WORK_REQUEST", "RELATIONSHIP_CHANGE_REQUEST"]),
+            dispatch(2, ["execute:prerequisite"], dependencies),
+            response(3, ["prerequisite"], ["ACCEPTED"], ['task:done:"prerequisite"'], ["task:done"], dependencies),
+            dispatch(4, ["execute:blocked"], dependencies, ["task:done"]),
+            response(5, ["blocked"], ["ACCEPTED"], ['task:done:"blocked"'], ["task:done", "task:done"], dependencies),
+        ];
+        return {
+            provenance: source("relationships.md#depends_on"),
+            ticks,
+            orderedEventKinds: ordered(ticks),
+        };
+    })(),
+    "depends-on-terminal-failure": (() => {
+        const ticks = [
+            bootstrap(),
+            submitted(dependencies, ["WORK_REQUEST", "RELATIONSHIP_CHANGE_REQUEST"]),
+            dispatch(2, ["execute:prerequisite"], dependencies),
+            response(3, ["prerequisite"], ["FAILED"], ['task:failed:"prerequisite"'], ["task:failed", "task:failed"], dependencies, ["DISPATCH_RESPONSE", "WORK_STATE_CHANGE"]),
+        ];
+        return {
+            provenance: source("relationships.md#depends_on"),
+            ticks,
+            orderedEventKinds: ordered(ticks),
+        };
+    })(),
+};

package/dist/runtime-reference-fixtures.d.ts

@@ -0,0 +1,7 @@
+import type { FactoryEmulatorRuntimeReference } from "./runtime-reference.js";
+/**
+ * Factories and scenarios are executable inputs; expected evidence lives in a
+ * separate immutable declaration so changing either input cannot recompute a
+ * passing expectation.
+ */
+export declare const runtimeReferenceFixtures: readonly FactoryEmulatorRuntimeReference[];

package/dist/runtime-reference-fixtures.js

@@ -0,0 +1,308 @@
+import { frozenRuntimeReferenceEvidence } from "./runtime-reference-evidence.js";
+function cloneFactory(factory) {
+    return JSON.parse(JSON.stringify(factory));
+}
+function firstWorkstation(factory) {
+    const workstation = factory.workstations?.[0];
+    if (workstation === undefined) {
+        throw new Error("Frozen runtime-reference Factory requires a workstation.");
+    }
+    return workstation;
+}
+function scenario(id, factoryName, workstation) {
+    return {
+        schemaVersion: "factory-emulator-scenario/v1",
+        id,
+        factory: { name: factoryName },
+        seed: `${id}-seed`,
+        startAt: "2026-07-18T16:00:00.000Z",
+        initialSubmissions: [
+            {
+                name: "input",
+                workType: "task",
+                state: "ready",
+                input: "frozen input",
+            },
+        ],
+        rules: [
+            {
+                id: "accepted",
+                selector: { workstation },
+                cursor: { scope: "lineage", input: "rootWorkId" },
+                outcomes: [{ result: "accepted", durationMs: 1 }],
+                exhaustion: "repeat-last",
+            },
+        ],
+        unmatched: { behavior: "error" },
+    };
+}
+function standardFactory(name, workstation = "execute") {
+    return {
+        name,
+        orchestrator: { kind: "PETRI" },
+        workTypes: [
+            {
+                name: "task",
+                states: [
+                    { name: "ready", type: "INITIAL" },
+                    { name: "done", type: "TERMINAL" },
+                    { name: "failed", type: "FAILED" },
+                ],
+            },
+        ],
+        workers: [{ name: "worker", type: "AGENT_WORKER" }],
+        workstations: [
+            {
+                name: workstation,
+                type: "AGENT_RUN",
+                worker: "worker",
+                inputs: [{ workType: "task", state: "ready" }],
+                outputs: [{ workType: "task", state: "done" }],
+                onFailure: [{ workType: "task", state: "failed" }],
+            },
+        ],
+    };
+}
+function scenarioWithOutcome(id, factoryName, workstation, outcome) {
+    const base = scenario(id, factoryName, workstation);
+    const [rule] = base.rules;
+    if (rule === undefined)
+        throw new Error("Frozen reference needs a rule.");
+    return { ...base, rules: [{ ...rule, outcomes: [outcome] }] };
+}
+function concurrentScenario(id, factoryName, submissions) {
+    return {
+        ...scenario(id, factoryName, "execute"),
+        initialSubmissions: submissions.map((name) => ({
+            name,
+            workType: "task",
+            state: "ready",
+            input: `${name} frozen input`,
+        })),
+    };
+}
+function dependencyInput(id, title, prerequisiteOutcome) {
+    const factory = standardFactory(`runtime-reference-${id}`);
+    return {
+        id,
+        title,
+        factory,
+        scenario: {
+            ...scenario(id, factory.name, "execute"),
+            initialSubmissions: {
+                works: [
+                    {
+                        name: "blocked",
+                        workType: "task",
+                        state: "ready",
+                        input: "blocked",
+                    },
+                    {
+                        name: "prerequisite",
+                        workType: "task",
+                        state: "ready",
+                        input: "prerequisite",
+                    },
+                ],
+                relations: [
+                    {
+                        type: "DEPENDS_ON",
+                        sourceWorkName: "blocked",
+                        targetWorkName: "prerequisite",
+                        requiredState: "done",
+                    },
+                ],
+            },
+            rules: [
+                {
+                    id: "prerequisite-outcome",
+                    selector: { input: { name: "prerequisite" } },
+                    cursor: { scope: "lineage", input: "rootWorkId" },
+                    outcomes: [
+                        prerequisiteOutcome === "accepted"
+                            ? { result: "accepted", durationMs: 1 }
+                            : {
+                                result: "failed",
+                                durationMs: 1,
+                                error: "prerequisite failed",
+                            },
+                    ],
+                    exhaustion: "repeat-last",
+                },
+                {
+                    id: "blocked-outcome",
+                    selector: { input: { name: "blocked" } },
+                    cursor: { scope: "lineage", input: "rootWorkId" },
+                    outcomes: [{ result: "accepted", durationMs: 1 }],
+                    exhaustion: "repeat-last",
+                },
+            ],
+        },
+    };
+}
+const basic = standardFactory("runtime-reference-basic");
+const repeater = cloneFactory(standardFactory("runtime-reference-repeater"));
+firstWorkstation(repeater).behavior = "REPEATER";
+firstWorkstation(repeater).onContinue = [{ workType: "task", state: "ready" }];
+const repeaterScenario = scenario("repeaters", repeater.name, "execute");
+const [repeaterRule] = repeaterScenario.rules;
+if (repeaterRule === undefined) {
+    throw new Error("Frozen repeater reference needs a rule.");
+}
+const routing = cloneFactory(standardFactory("runtime-reference-routing"));
+firstWorkstation(routing).onRejection = [{ workType: "task", state: "failed" }];
+const propagation = cloneFactory(standardFactory("runtime-reference-propagation"));
+firstWorkstation(propagation).workPropagation = { mode: "PRESERVE_INPUT" };
+const multiInputOutput = cloneFactory(standardFactory("runtime-reference-multi-input-output"));
+const multiInputOutputWorkstation = firstWorkstation(multiInputOutput);
+multiInputOutputWorkstation.inputs.push({ workType: "task", state: "ready" });
+if (multiInputOutputWorkstation.outputs === undefined) {
+    throw new Error("Frozen multi-output reference requires an output route.");
+}
+multiInputOutputWorkstation.outputs.push({ workType: "task", state: "done" });
+const multiInputOutputScenario = scenario("multi-input-output", multiInputOutput.name, "execute");
+if (!Array.isArray(multiInputOutputScenario.initialSubmissions)) {
+    throw new Error("Frozen multi-input reference requires direct submissions.");
+}
+multiInputOutputScenario.initialSubmissions.push({
+    name: "input-two",
+    workType: "task",
+    state: "ready",
+    input: "second frozen input",
+});
+const logicalMove = cloneFactory(standardFactory("runtime-reference-logical-move", "move"));
+const logicalMoveWorkstations = logicalMove.workstations;
+if (logicalMoveWorkstations === undefined) {
+    throw new Error("Frozen logical-move reference requires a workstation.");
+}
+logicalMoveWorkstations[0] = {
+    name: "execute",
+    type: "AGENT_RUN",
+    worker: "worker",
+    inputs: [{ workType: "task", state: "ready" }],
+    outputs: [{ workType: "task", state: "ready" }],
+};
+logicalMoveWorkstations.push({
+    name: "move",
+    type: "LOGICAL_MOVE",
+    worker: "",
+    inputs: [{ workType: "task", state: "ready" }],
+    outputs: [{ workType: "task", state: "done" }],
+    guards: [{ type: "VISIT_COUNT", workstation: "execute", maxVisits: 1 }],
+    workPropagation: { mode: "PRESERVE_INPUT" },
+});
+const parallel = cloneFactory(standardFactory("runtime-reference-parallel"));
+const contention = cloneFactory(standardFactory("runtime-reference-resource-contention"));
+contention.resources = [{ name: "agent-slot", capacity: 2 }];
+firstWorkstation(contention).resources = [{ name: "agent-slot", capacity: 1 }];
+const runtimeReferenceInputs = [
+    {
+        id: "basic-execution",
+        title: "Basic execution",
+        factory: basic,
+        scenario: scenario("basic-execution", basic.name, "execute"),
+    },
+    {
+        id: "repeaters",
+        title: "Repeater continuation",
+        factory: repeater,
+        scenario: {
+            ...repeaterScenario,
+            rules: [
+                {
+                    ...repeaterRule,
+                    outcomes: [
+                        { result: "continued", durationMs: 1 },
+                        { result: "accepted", durationMs: 1 },
+                    ],
+                },
+            ],
+        },
+    },
+    {
+        id: "routing",
+        title: "Outcome routing",
+        factory: routing,
+        scenario: scenarioWithOutcome("routing", routing.name, "execute", {
+            result: "rejected",
+            durationMs: 1,
+        }),
+    },
+    {
+        id: "logical-moves",
+        title: "Logical move",
+        factory: logicalMove,
+        scenario: scenarioWithOutcome("logical-moves", logicalMove.name, "execute", {
+            result: "accepted",
+            durationMs: 1,
+            output: "worker output",
+        }),
+    },
+    {
+        id: "multi-input-output",
+        title: "Multi-input and multi-output",
+        factory: multiInputOutput,
+        scenario: multiInputOutputScenario,
+    },
+    {
+        id: "propagation",
+        title: "Work propagation",
+        factory: propagation,
+        scenario: scenarioWithOutcome("propagation", propagation.name, "execute", {
+            result: "accepted",
+            durationMs: 1,
+            output: "worker output",
+        }),
+    },
+    {
+        id: "parallel-dispatch",
+        title: "Parallel dispatch",
+        factory: parallel,
+        scenario: concurrentScenario("parallel-dispatch", parallel.name, [
+            "first",
+            "second",
+        ]),
+    },
+    {
+        id: "simultaneous-completion",
+        title: "Simultaneous completion",
+        factory: cloneFactory(parallel),
+        scenario: concurrentScenario("simultaneous-completion", parallel.name, [
+            "first",
+            "second",
+        ]),
+    },
+    {
+        id: "resource-contention",
+        title: "Resource contention",
+        factory: contention,
+        scenario: concurrentScenario("resource-contention", contention.name, [
+            "first",
+            "second",
+            "third",
+        ]),
+    },
+    dependencyInput("depends-on-release", "DEPENDS_ON prerequisite release", "accepted"),
+    dependencyInput("depends-on-terminal-failure", "DEPENDS_ON terminal failure cascade", "failed"),
+];
+/**
+ * Factories and scenarios are executable inputs; expected evidence lives in a
+ * separate immutable declaration so changing either input cannot recompute a
+ * passing expectation.
+ */
+export const runtimeReferenceFixtures = runtimeReferenceInputs.map(({ id, title, factory, scenario }) => {
+    const evidence = frozenRuntimeReferenceEvidence[id];
+    if (evidence === undefined) {
+        throw new Error(`Missing frozen runtime-reference evidence for ${id}.`);
+    }
+    return {
+        schemaVersion: "factory-emulator-runtime-reference/v1",
+        id,
+        title,
+        provenance: evidence.provenance,
+        factory,
+        scenario,
+        ticks: evidence.ticks,
+        orderedEventKinds: evidence.orderedEventKinds,
+    };
+});

package/dist/runtime-reference.d.ts

@@ -0,0 +1,48 @@
+import type { FactoryDefinition, FactoryEvent } from "@you-agent-factory/client";
+import { type FactoryEmulatorScenario } from "./scenario.js";
+export declare const FACTORY_EMULATOR_RUNTIME_REFERENCE_SCHEMA_VERSION: "factory-emulator-runtime-reference/v1";
+export interface FactoryEmulatorRuntimeReferenceProvenance {
+    readonly source: string;
+    readonly kind: "public-behavior" | "public-documentation" | "public-recording";
+}
+export interface FactoryEmulatorRuntimeReferenceTick {
+    readonly logicalTick: number;
+    readonly eventKinds: readonly FactoryEvent["type"][];
+    readonly semantics: FactoryEmulatorRuntimeReferenceSemantics;
+}
+/** Stable, identity- and time-normalized evidence observed after one logical tick. */
+export interface FactoryEmulatorRuntimeReferenceSemantics {
+    readonly dispatchChoices: readonly string[];
+    readonly consumedWork: readonly string[];
+    readonly outcomes: readonly string[];
+    readonly routes: readonly string[];
+    readonly terminalStates: readonly string[];
+    readonly replayProjection: readonly string[];
+}
+export interface FactoryEmulatorRuntimeReference {
+    readonly schemaVersion: typeof FACTORY_EMULATOR_RUNTIME_REFERENCE_SCHEMA_VERSION;
+    readonly id: string;
+    readonly title: string;
+    readonly provenance: FactoryEmulatorRuntimeReferenceProvenance;
+    readonly factory: FactoryDefinition;
+    readonly scenario: FactoryEmulatorScenario;
+    readonly ticks: readonly FactoryEmulatorRuntimeReferenceTick[];
+    readonly orderedEventKinds: readonly FactoryEvent["type"][];
+}
+export type FactoryEmulatorRuntimeReferenceIssueCode = "invalid_factory" | "invalid_provenance" | "invalid_schema_version" | "invalid_tick_order" | "invalid_value" | "missing_required_data" | "missing_semantics" | "unexpected_event_kind";
+export interface FactoryEmulatorRuntimeReferenceIssue {
+    readonly code: FactoryEmulatorRuntimeReferenceIssueCode;
+    readonly path: readonly (string | number)[];
+    readonly message: string;
+}
+export type SafeParseFactoryEmulatorRuntimeReferenceResult = {
+    readonly success: true;
+    readonly data: FactoryEmulatorRuntimeReference;
+} | {
+    readonly success: false;
+    readonly issues: readonly FactoryEmulatorRuntimeReferenceIssue[];
+};
+/** Validates frozen, package-local evidence before a conformance comparison starts. */
+export declare function safeParseFactoryEmulatorRuntimeReference(input: unknown): SafeParseFactoryEmulatorRuntimeReferenceResult;
+/** Returns detached validated fixtures in their frozen package declaration order. */
+export declare function loadFactoryEmulatorRuntimeReferences(): readonly FactoryEmulatorRuntimeReference[];