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

package/dist/generated/scenario-schema.js

@@ -0,0 +1,319 @@
+/**
+ * Generated by scripts/generate-scenario-schema.mjs from
+ * schema/scenario.schema.json. Do not edit this file directly.
+ */
+export const generatedScenarioSchema = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://you-agent-factory.dev/schemas/ui/factory-emulator/scenario/v1",
+    "title": "Factory Emulator Scenario v1",
+    "type": "object",
+    "additionalProperties": false,
+    "required": [
+        "schemaVersion",
+        "id",
+        "factory",
+        "seed",
+        "startAt",
+        "rules",
+        "unmatched"
+    ],
+    "properties": {
+        "schemaVersion": {
+            "const": "factory-emulator-scenario/v1"
+        },
+        "id": {
+            "$ref": "#/$defs/stableIdentity"
+        },
+        "factory": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+                "name"
+            ],
+            "properties": {
+                "name": {
+                    "$ref": "#/$defs/nonEmptyText128"
+                }
+            }
+        },
+        "seed": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 256
+        },
+        "startAt": {
+            "type": "string",
+            "format": "date-time",
+            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$"
+        },
+        "rules": {
+            "type": "array",
+            "items": {
+                "$ref": "#/$defs/rule"
+            }
+        },
+        "unmatched": {
+            "$ref": "#/$defs/unmatched"
+        },
+        "initialSubmissions": {
+            "oneOf": [
+                {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/$defs/initialSubmission"
+                    }
+                },
+                {
+                    "$ref": "#/$defs/submissionBatch"
+                }
+            ]
+        }
+    },
+    "$defs": {
+        "stableIdentity": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 128,
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"
+        },
+        "nonEmptyText128": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 128
+        },
+        "plainText": {
+            "type": "string",
+            "maxLength": 65536
+        },
+        "feedbackText": {
+            "type": "string",
+            "maxLength": 4096
+        },
+        "activityLabel": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 120
+        },
+        "inputSelector": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "workType": {
+                    "$ref": "#/$defs/nonEmptyText128"
+                },
+                "state": {
+                    "$ref": "#/$defs/nonEmptyText128"
+                },
+                "name": {
+                    "$ref": "#/$defs/nonEmptyText128"
+                }
+            }
+        },
+        "selector": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "workstation": {
+                    "$ref": "#/$defs/nonEmptyText128"
+                },
+                "worker": {
+                    "$ref": "#/$defs/nonEmptyText128"
+                },
+                "input": {
+                    "$ref": "#/$defs/inputSelector"
+                }
+            }
+        },
+        "cursor": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+                "scope",
+                "input"
+            ],
+            "properties": {
+                "scope": {
+                    "const": "lineage"
+                },
+                "input": {
+                    "const": "rootWorkId"
+                }
+            }
+        },
+        "outcome": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+                "result",
+                "durationMs"
+            ],
+            "properties": {
+                "result": {
+                    "enum": [
+                        "accepted",
+                        "continued",
+                        "rejected",
+                        "failed"
+                    ]
+                },
+                "durationMs": {
+                    "type": "number",
+                    "minimum": 0
+                },
+                "output": {
+                    "$ref": "#/$defs/plainText"
+                },
+                "feedback": {
+                    "$ref": "#/$defs/feedbackText"
+                },
+                "activityLabel": {
+                    "$ref": "#/$defs/activityLabel"
+                },
+                "error": {
+                    "$ref": "#/$defs/feedbackText"
+                }
+            }
+        },
+        "rule": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+                "id",
+                "selector",
+                "cursor",
+                "outcomes",
+                "exhaustion"
+            ],
+            "properties": {
+                "id": {
+                    "$ref": "#/$defs/stableIdentity"
+                },
+                "selector": {
+                    "$ref": "#/$defs/selector"
+                },
+                "cursor": {
+                    "$ref": "#/$defs/cursor"
+                },
+                "outcomes": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "$ref": "#/$defs/outcome"
+                    }
+                },
+                "exhaustion": {
+                    "enum": [
+                        "repeat-last",
+                        "fail"
+                    ]
+                }
+            }
+        },
+        "unmatched": {
+            "oneOf": [
+                {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": [
+                        "behavior"
+                    ],
+                    "properties": {
+                        "behavior": {
+                            "const": "error"
+                        }
+                    }
+                },
+                {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": [
+                        "behavior",
+                        "outcome"
+                    ],
+                    "properties": {
+                        "behavior": {
+                            "const": "outcome"
+                        },
+                        "outcome": {
+                            "$ref": "#/$defs/outcome"
+                        }
+                    }
+                }
+            ]
+        },
+        "initialSubmission": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+                "name",
+                "workType",
+                "state"
+            ],
+            "properties": {
+                "name": {
+                    "$ref": "#/$defs/stableIdentity"
+                },
+                "workType": {
+                    "$ref": "#/$defs/nonEmptyText128"
+                },
+                "state": {
+                    "$ref": "#/$defs/nonEmptyText128"
+                },
+                "input": {
+                    "$ref": "#/$defs/plainText"
+                },
+                "parent": {
+                    "$ref": "#/$defs/stableIdentity"
+                }
+            }
+        },
+        "submissionRelation": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+                "type",
+                "sourceWorkName",
+                "targetWorkName"
+            ],
+            "properties": {
+                "type": {
+                    "enum": [
+                        "DEPENDS_ON",
+                        "PARENT_CHILD",
+                        "SPAWNED_BY"
+                    ]
+                },
+                "sourceWorkName": {
+                    "$ref": "#/$defs/stableIdentity"
+                },
+                "targetWorkName": {
+                    "$ref": "#/$defs/stableIdentity"
+                },
+                "requiredState": {
+                    "$ref": "#/$defs/nonEmptyText128"
+                }
+            }
+        },
+        "submissionBatch": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+                "works"
+            ],
+            "properties": {
+                "works": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/$defs/initialSubmission"
+                    }
+                },
+                "relations": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/$defs/submissionRelation"
+                    }
+                }
+            }
+        }
+    }
+};

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { type FactoryEmulatorCompatibilityIssue, type FactoryEmulatorCompatibilityIssueCode, type FactoryEmulatorCompatibilityResult, inspectFactoryEmulatorCompatibility, writeFactoryEventsIfCompatible, } from "./compatibility.js";
+export { type FactoryEventSink, FactoryEventSinkError, type FactoryEventSinkErrorCode, MemoryFactoryEventSink, type MemoryFactoryEventSinkOptions, } from "./event-sink.js";
+export { RecordingFactoryEventSink, type RecordingFactoryEventSinkOptions, } from "./recording-sink.js";
+export { FACTORY_EMULATOR_RUNTIME_REFERENCE_SCHEMA_VERSION, type FactoryEmulatorRuntimeReference, type FactoryEmulatorRuntimeReferenceIssue, type FactoryEmulatorRuntimeReferenceIssueCode, type FactoryEmulatorRuntimeReferenceProvenance, type FactoryEmulatorRuntimeReferenceSemantics, type FactoryEmulatorRuntimeReferenceTick, loadFactoryEmulatorRuntimeReferences, type SafeParseFactoryEmulatorRuntimeReferenceResult, safeParseFactoryEmulatorRuntimeReference, } from "./runtime-reference.js";
+export { compareFactoryEmulatorRuntimeReference, type FactoryEmulatorRuntimeReferenceComparisonSurface, type FactoryEmulatorRuntimeReferenceConformanceResult, type FactoryEmulatorRuntimeReferenceDivergence, } from "./runtime-reference-conformance.js";
+export { FACTORY_EMULATOR_SCENARIO_SCHEMA_VERSION, type FactoryEmulatorInitialSubmission, type FactoryEmulatorInitialSubmissions, type FactoryEmulatorOutcome, type FactoryEmulatorRule, type FactoryEmulatorRuleSelector, type FactoryEmulatorScenario, type FactoryEmulatorScenarioIssue, type FactoryEmulatorScenarioIssueCode, FactoryEmulatorScenarioValidationError, type FactoryEmulatorSubmissionBatch, type FactoryEmulatorSubmissionRelation, parseFactoryEmulatorScenario, type SafeParseFactoryEmulatorScenarioResult, safeParseFactoryEmulatorScenario, scenarioSchema, } from "./scenario.js";
+export { createFactoryEmulatorSession, DEFAULT_FACTORY_EMULATOR_LIMITS, FACTORY_EMULATOR_LIMIT_HARD_CAPS, type FactoryEmulatorAdvanceReceipt, type FactoryEmulatorBudgetUsage, type FactoryEmulatorCloseReceipt, type FactoryEmulatorCommand, type FactoryEmulatorConfigurationDiagnostic, FactoryEmulatorConfigurationError, FactoryEmulatorDurationError, type FactoryEmulatorExecutionDiagnostic, FactoryEmulatorExecutionPausedError, FactoryEmulatorLifecycleError, type FactoryEmulatorLimits, type FactoryEmulatorNormalizedRelation, FactoryEmulatorPendingCommandError, type FactoryEmulatorPendingTransactionStatus, type FactoryEmulatorResetReceipt, type FactoryEmulatorSession, type FactoryEmulatorSessionCounters, type FactoryEmulatorSessionError, type FactoryEmulatorSessionOptions, type FactoryEmulatorSessionState, type FactoryEmulatorSessionStatus, type FactoryEmulatorSessionWork, type FactoryEmulatorStartReceipt, FactoryEmulatorSubmissionError, type FactoryEmulatorSubmitReceipt, type ResolvedFactoryEmulatorLimits, } from "./session.js";
+export { type FactoryEmulatorReplayedWork, replayFactoryEmulatorSubmissions, } from "./submission-replay.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+export { inspectFactoryEmulatorCompatibility, writeFactoryEventsIfCompatible, } from "./compatibility.js";
+export { FactoryEventSinkError, MemoryFactoryEventSink, } from "./event-sink.js";
+export { RecordingFactoryEventSink, } from "./recording-sink.js";
+export { FACTORY_EMULATOR_RUNTIME_REFERENCE_SCHEMA_VERSION, loadFactoryEmulatorRuntimeReferences, safeParseFactoryEmulatorRuntimeReference, } from "./runtime-reference.js";
+export { compareFactoryEmulatorRuntimeReference, } from "./runtime-reference-conformance.js";
+export { FACTORY_EMULATOR_SCENARIO_SCHEMA_VERSION, FactoryEmulatorScenarioValidationError, parseFactoryEmulatorScenario, safeParseFactoryEmulatorScenario, scenarioSchema, } from "./scenario.js";
+export { createFactoryEmulatorSession, DEFAULT_FACTORY_EMULATOR_LIMITS, FACTORY_EMULATOR_LIMIT_HARD_CAPS, FactoryEmulatorConfigurationError, FactoryEmulatorDurationError, FactoryEmulatorExecutionPausedError, FactoryEmulatorLifecycleError, FactoryEmulatorPendingCommandError, FactoryEmulatorSubmissionError, } from "./session.js";
+export { replayFactoryEmulatorSubmissions, } from "./submission-replay.js";

package/dist/logical-move.d.ts

@@ -0,0 +1,10 @@
+interface VisitCountGuard {
+    readonly type: string;
+    readonly workstation?: string;
+    readonly maxVisits?: number;
+}
+/** Evaluates the supported inclusive VISIT_COUNT guard set for one lineage. */
+export declare function visitCountGuardsAllow(guards: readonly VisitCountGuard[], visits: Readonly<Record<string, number>>): boolean;
+/** Carries the greatest contributing lineage counts and records this visit. */
+export declare function visitsAfterTransition(inputs: readonly Readonly<Record<string, number>>[], workstation: string): Readonly<Record<string, number>>;
+export {};

package/dist/logical-move.js

@@ -0,0 +1,18 @@
+/** Evaluates the supported inclusive VISIT_COUNT guard set for one lineage. */
+export function visitCountGuardsAllow(guards, visits) {
+    return guards.every(({ type, workstation, maxVisits }) => type === "VISIT_COUNT" &&
+        workstation !== undefined &&
+        maxVisits !== undefined &&
+        (visits[workstation] ?? 0) >= maxVisits);
+}
+/** Carries the greatest contributing lineage counts and records this visit. */
+export function visitsAfterTransition(inputs, workstation) {
+    const visits = {};
+    for (const input of inputs) {
+        for (const [name, count] of Object.entries(input)) {
+            visits[name] = Math.max(visits[name] ?? 0, count);
+        }
+    }
+    visits[workstation] = (visits[workstation] ?? 0) + 1;
+    return visits;
+}

package/dist/recording-sink.d.ts

@@ -0,0 +1,22 @@
+import { type FactoryEvent, type FactoryRecording } from "@you-agent-factory/client";
+import { type FactoryEventSink } from "./event-sink.js";
+export interface RecordingFactoryEventSinkOptions {
+    /** Caller-owned recording metadata. The events collection is owned by the sink. */
+    readonly recording: Omit<FactoryRecording, "events">;
+    /** Maximum number of events retained. A batch that crosses this bound fails whole. */
+    readonly maxEvents: number;
+    /** Optional asynchronous boundary for backpressure or caller-controlled failure injection. */
+    readonly beforeWrite?: (events: readonly FactoryEvent[]) => Promise<void>;
+}
+/**
+ * Bounded, caller-owned canonical Factory recording. Concurrent writes are
+ * processed in call order and each proposed full recording is validated before
+ * the incoming batch becomes visible.
+ */
+export declare class RecordingFactoryEventSink implements FactoryEventSink {
+    #private;
+    constructor(options: RecordingFactoryEventSinkOptions);
+    write(events: readonly FactoryEvent[]): Promise<void>;
+    snapshot(): FactoryRecording;
+    close(): Promise<void>;
+}

package/dist/recording-sink.js

@@ -0,0 +1,122 @@
+import { compareFactoryEvents, safeParseFactoryRecording, } from "@you-agent-factory/client";
+import { FactoryEventSinkError } from "./event-sink.js";
+function cloneValue(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function eventFactoryName(event) {
+    const payload = event.payload;
+    if (typeof payload !== "object" || payload === null)
+        return undefined;
+    const factory = payload.factory;
+    if (typeof factory !== "object" || factory === null)
+        return undefined;
+    const name = factory.name;
+    return typeof name === "string" ? name : undefined;
+}
+function assertUniqueEventIds(events) {
+    const seen = new Set();
+    for (const event of events) {
+        if (seen.has(event.id)) {
+            throw new FactoryEventSinkError("duplicate_event_id", `Factory Event ID ${event.id} is already present in the recording.`);
+        }
+        seen.add(event.id);
+    }
+}
+function assertCanonicalOrder(events) {
+    for (let index = 1; index < events.length; index += 1) {
+        const previous = events[index - 1];
+        const current = events[index];
+        if (previous !== undefined &&
+            current !== undefined &&
+            compareFactoryEvents(previous, current) > 0) {
+            throw new FactoryEventSinkError("invalid_event_order", `Factory Event ${current.id} is not in canonical recording order.`);
+        }
+    }
+}
+function assertConsistentSessionIdentity(events) {
+    const sessionIds = new Set(events
+        .map((event) => event.context.sessionId)
+        .filter((sessionId) => sessionId !== undefined));
+    const hasMissingIdentity = events.some((event) => event.context.sessionId === undefined);
+    if (sessionIds.size > 1 || (sessionIds.size === 1 && hasMissingIdentity)) {
+        throw new FactoryEventSinkError("mixed_session_identity", "Factory recording events must use one consistent Factory Session identity.");
+    }
+}
+function assertConsistentFactoryIdentity(factory, events) {
+    const factoryNames = new Set();
+    if (factory?.name !== undefined)
+        factoryNames.add(factory.name);
+    for (const event of events) {
+        const name = eventFactoryName(event);
+        if (name !== undefined)
+            factoryNames.add(name);
+    }
+    if (factoryNames.size > 1) {
+        throw new FactoryEventSinkError("mixed_factory_identity", "Factory recording metadata and topology events must use one Factory identity.");
+    }
+}
+function validateRecording(recording) {
+    assertUniqueEventIds(recording.events);
+    assertCanonicalOrder(recording.events);
+    assertConsistentFactoryIdentity(recording.factory, recording.events);
+    assertConsistentSessionIdentity(recording.events);
+    const result = safeParseFactoryRecording(recording);
+    if (!result.success) {
+        throw new FactoryEventSinkError("invalid_recording", `Factory recording validation failed: ${result.issues[0]?.message ?? "unknown error"}`);
+    }
+}
+/**
+ * Bounded, caller-owned canonical Factory recording. Concurrent writes are
+ * processed in call order and each proposed full recording is validated before
+ * the incoming batch becomes visible.
+ */
+export class RecordingFactoryEventSink {
+    #metadata;
+    #maxEvents;
+    #beforeWrite;
+    #events = [];
+    #acceptingWrites = true;
+    #tail = Promise.resolve();
+    #closePromise;
+    constructor(options) {
+        if (!Number.isSafeInteger(options.maxEvents) || options.maxEvents < 1) {
+            throw new FactoryEventSinkError("invalid_capacity", "Recording sink maxEvents must be a positive safe integer.");
+        }
+        this.#metadata = cloneValue(options.recording);
+        this.#maxEvents = options.maxEvents;
+        this.#beforeWrite = options.beforeWrite;
+    }
+    write(events) {
+        if (!this.#acceptingWrites) {
+            return Promise.reject(new FactoryEventSinkError("closed", "The event sink is closed."));
+        }
+        if (events.length === 0) {
+            return Promise.reject(new FactoryEventSinkError("empty_batch", "Factory Event batches must be non-empty."));
+        }
+        const proposedBatch = cloneValue(events);
+        const write = this.#tail.then(async () => {
+            await this.#beforeWrite?.(cloneValue(proposedBatch));
+            if (this.#events.length + proposedBatch.length > this.#maxEvents) {
+                throw new FactoryEventSinkError("capacity_exceeded", `The batch would exceed the configured ${this.#maxEvents}-event recording capacity.`);
+            }
+            const proposedRecording = {
+                ...this.#metadata,
+                events: [...this.#events, ...proposedBatch],
+            };
+            validateRecording(proposedRecording);
+            this.#events = proposedRecording.events;
+        });
+        this.#tail = write.catch(() => undefined);
+        return write;
+    }
+    snapshot() {
+        return cloneValue({ ...this.#metadata, events: this.#events });
+    }
+    close() {
+        if (this.#closePromise !== undefined)
+            return this.#closePromise;
+        this.#acceptingWrites = false;
+        this.#closePromise = this.#tail;
+        return this.#closePromise;
+    }
+}

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

@@ -0,0 +1,20 @@
+import type { FactoryEmulatorRuntimeReferenceIssue, FactoryEmulatorRuntimeReferenceSemantics } from "./runtime-reference.js";
+export type FactoryEmulatorRuntimeReferenceComparisonSurface = keyof FactoryEmulatorRuntimeReferenceSemantics | "eventKinds";
+export interface FactoryEmulatorRuntimeReferenceDivergence {
+    readonly fixture: string;
+    readonly logicalTick: number;
+    readonly surface: FactoryEmulatorRuntimeReferenceComparisonSurface;
+    readonly expected: unknown;
+    readonly actual: unknown;
+}
+export type FactoryEmulatorRuntimeReferenceConformanceResult = {
+    readonly matches: true;
+} | {
+    readonly matches: false;
+    readonly validationIssues: readonly FactoryEmulatorRuntimeReferenceIssue[];
+} | {
+    readonly matches: false;
+    readonly divergence: FactoryEmulatorRuntimeReferenceDivergence;
+};
+/** Runs the supported emulator subset and reports its first frozen-reference divergence. */
+export declare function compareFactoryEmulatorRuntimeReference(input: unknown): Promise<FactoryEmulatorRuntimeReferenceConformanceResult>;

package/dist/runtime-reference-conformance.js

@@ -0,0 +1,138 @@
+import { MemoryFactoryEventSink } from "./event-sink.js";
+import { safeParseFactoryEmulatorRuntimeReference } from "./runtime-reference.js";
+import { createFactoryEmulatorSession } from "./session.js";
+import { replayFactoryEmulatorSubmissions } from "./submission-replay.js";
+function normalizedSemantics(reference, events, batch, state) {
+    const terminalStates = new Set((reference.factory.workTypes ?? []).flatMap(({ name, states }) => (states ?? [])
+        .filter(({ type }) => type === "TERMINAL" || type === "FAILED")
+        .map(({ name: state }) => `${name}:${state}`)));
+    const works = "works" in state ? state.works : [];
+    const workByToken = new Map(works.map((work) => [work.tokenId, work]));
+    const dispatched = works.flatMap(({ phase, dispatch }) => phase === "active" && dispatch !== undefined
+        ? [
+            `${dispatch.workstation}:${dispatch.inputTokenIds.map((id) => workByToken.get(id)?.submissionId ?? id).join(",")}`,
+        ]
+        : []);
+    const responses = batch.filter(({ type }) => type === "DISPATCH_RESPONSE");
+    const routed = responses.flatMap(({ payload }) => {
+        const outputWork = payload.outputWork;
+        return Array.isArray(outputWork)
+            ? outputWork.flatMap((work) => {
+                const value = work;
+                return typeof value.workTypeName === "string" &&
+                    typeof value.state?.name === "string"
+                    ? [
+                        `${value.workTypeName}:${value.state.name}:${JSON.stringify(value.payload)}`,
+                    ]
+                    : [];
+            })
+            : [];
+    });
+    return {
+        dispatchChoices: dispatched.sort(),
+        consumedWork: responses
+            .flatMap(({ context }) => context.workIds ?? [])
+            .map((workId) => works.find((work) => work.workId === workId)?.submissionId ?? workId)
+            .sort(),
+        outcomes: responses
+            .map(({ payload }) => String(payload.outcome))
+            .sort(),
+        routes: routed.sort(),
+        terminalStates: works
+            .filter((work) => terminalStates.has(`${work.workType}:${work.state}`))
+            .map((work) => `${work.workType}:${work.state}`)
+            .sort(),
+        replayProjection: replayFactoryEmulatorSubmissions(events)
+            .map((work) => `${work.submissionId}:${work.workType ?? ""}:${work.state ?? ""}`)
+            .sort(),
+    };
+}
+function firstDifference(reference, tick, actual) {
+    for (const surface of [
+        "eventKinds",
+        "dispatchChoices",
+        "consumedWork",
+        "outcomes",
+        "routes",
+        "terminalStates",
+        "replayProjection",
+    ]) {
+        const expectedValue = surface === "eventKinds" ? tick.eventKinds : tick.semantics[surface];
+        const actualValue = surface === "eventKinds" ? actual.eventKinds : actual.semantics[surface];
+        if (JSON.stringify(expectedValue) !== JSON.stringify(actualValue)) {
+            return {
+                fixture: reference.id,
+                logicalTick: tick.logicalTick,
+                surface,
+                expected: expectedValue,
+                actual: actualValue,
+            };
+        }
+    }
+    return undefined;
+}
+/** Runs the supported emulator subset and reports its first frozen-reference divergence. */
+export async function compareFactoryEmulatorRuntimeReference(input) {
+    const parsed = safeParseFactoryEmulatorRuntimeReference(input);
+    if (!parsed.success) {
+        return { matches: false, validationIssues: parsed.issues };
+    }
+    const reference = parsed.data;
+    const sink = new MemoryFactoryEventSink({ maxEvents: 10_000 });
+    const emulator = createFactoryEmulatorSession({
+        factory: reference.factory,
+        scenario: reference.scenario,
+        sink,
+    });
+    const actual = [];
+    let events = [];
+    const append = (batch, state) => {
+        events = [...events, ...batch];
+        actual.push({
+            logicalTick: actual.length,
+            eventKinds: batch.map(({ type }) => type),
+            semantics: normalizedSemantics(reference, events, batch, state),
+        });
+    };
+    const started = await emulator.start();
+    for (const batch of started.batches)
+        append(batch, started.state);
+    while (true) {
+        const advanced = await emulator.advanceToNext();
+        for (const batch of advanced.batches)
+            append(batch, advanced.state);
+        if (advanced.status === "idle")
+            break;
+    }
+    for (const [index, tick] of reference.ticks.entries()) {
+        const observed = actual[index];
+        if (observed === undefined) {
+            return {
+                matches: false,
+                divergence: {
+                    fixture: reference.id,
+                    logicalTick: tick.logicalTick,
+                    surface: "eventKinds",
+                    expected: tick.eventKinds,
+                    actual: undefined,
+                },
+            };
+        }
+        const divergence = firstDifference(reference, tick, observed);
+        if (divergence !== undefined)
+            return { matches: false, divergence };
+    }
+    if (actual.length !== reference.ticks.length) {
+        return {
+            matches: false,
+            divergence: {
+                fixture: reference.id,
+                logicalTick: reference.ticks.length,
+                surface: "eventKinds",
+                expected: undefined,
+                actual: actual[reference.ticks.length]?.eventKinds,
+            },
+        };
+    }
+    return { matches: true };
+}