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

package/README.md

@@ -1,286 +1,305 @@
-# `@you-agent-factory/factory-emulator`
-
-This package publishes the stable v1 JSON Schema and generated TypeScript
-contract for deterministic Factory-emulator scenarios. The schema is available
-as raw JSON from `@you-agent-factory/factory-emulator/schema`; the root module
-exports `scenarioSchema` and `SUPPORTED_SCENARIO_VERSION`.
-
-Every scenario declares a version, id, deterministic seed, UTC `startAt`,
-ordered rules, and explicit unmatched behavior. Rules use finite scripted
-outcomes with explicit exhaustion behavior. Initial submissions and lineage
-cursors are structurally represented here; the parser validates the scenario
-shape and supported Factory execution subset before emulation begins.
-
-`activityLabel` is optional, limited to 120 characters, and only represents
-transient emulator activity. It is never canonical Factory event content.
-
-The schema under `contracts/factory-emulator/` is authored source. Run
-`npm run generate` from this package to regenerate its committed schema and
-TypeScript artifacts. The TypeScript declarations are derived from the schema's
-properties, required fields, references, variants, and documented runtime
-constraints rather than a separately authored type template. Run
-`make generate-emulator` to verify they are current; when it reports drift,
-regenerate them and commit the resulting artifacts.
-
-## Parsing a scenario for browser emulation
-
-`parseEmulatorScenario(scenario, factory)` is a pure preflight boundary. It
-validates the complete canonical Factory JSON Schema before applying the
-emulator's narrower capability policy, so accepted definitions can be emitted
-in canonical bootstrap events without contract drift. The package carries a
-generated byte-for-byte copy of the canonical Factory schema for this runtime
-validation; `make generate-emulator` checks that copy for freshness.
-The parser returns either the typed authored scenario and supported Factory
-definition, or structured diagnostics with a stable JSON Pointer `path`,
-`code`, `message`, and `expectation`. It never starts emulator activity or
-creates Factory events.
-
-The v1 emulator accepts static Petri Factory topology only. It rejects
-JavaScript orchestration, configured Factory resources or guards, and cron,
-repeater, or poller workstation scheduling before emulation starts. This keeps
-scripted browser behavior deterministic while the runtime support subset grows.
-
-## Rule semantics
-
-Rules are evaluated in authored order; `selectEmulatorRule` returns the first
-matching rule and no later rule can change that result. Parsing rejects a later
-rule only when an earlier rule provably covers its supported domain, including a
-known initial-submission id covered by an earlier work-type rule. It deliberately
-does not report uncertain overlap as shadowing.
-
-`resolveEmulatorScenarioResult(scenario, submission, invocationIndex)` is a
-pure helper for a zero-based invocation count of the selected rule. It returns a
-scripted outcome while one is available, repeats the final outcome only for
-`repeatLast`, delegates only `useUnmatchedBehavior` exhaustion to the explicit
-unmatched behavior, and otherwise returns the explicit exhaustion rejection.
-
-Initial submission ids and rule ids must be unique. Initial submissions and
-work-type matchers must name Factory work types. Lineage cursors may target one
-known initial submission or one earlier `complete` scripted outcome; missing,
-forward, cyclic, and incompatible targets are rejected with diagnostics before
-emulation begins.
-
-## Inspecting support and using examples
-
-`inspectEmulatorSupport()` returns the stable machine-readable v1 capability
-report. It covers the accepted static Factory subset, explicitly unsupported
-Factory behavior, matchers, outcomes, lineage cursors, exhaustion and unmatched
-options, initial-submission constraints, and `activityLabel` limits. The parser
-uses that same Factory support policy, so the report cannot advertise execution
-capabilities that parsing rejects.
-
-`emulatorScenarioExamples` exports a minimal scenario and a multi-rule scenario.
-The latter shows ordered priority matching, initial submissions, a scripted
-lineage cursor, finite exhaustion, explicit unmatched rejection, and transient
-`activityLabel` metadata. Both examples are validated through the public parser.
-
-## Event sink and logical tick runtime
-
-`@you-agent-factory/factory-emulator` provides the transport-neutral,
-caller-owned `FactoryEventSink` contract used by Factory emulator hosts.
-
-`write` accepts one ordered canonical `FactoryEventBatch` asynchronously. Its
-only successful receipt means every event in the supplied order was accepted;
-partial success must reject. `close` is a separate asynchronous operation and
-does not implicitly accept a pending write. The values crossing the contract
-are data-only, structured-cloneable Factory event and receipt shapes, making
-the contract suitable for a future worker or process boundary.
-
-`createMemoryFactoryEventSink({ maxEvents })` retains only the newest complete
-batches that fit its event limit. `createFactoryRecordingSink({ sessionId,
-maxEvents })` produces one finite recording for that session. Both helpers
-structured-clone accepted batches and returned history, reject writes after
-`close`, and preserve each batch atomically when a recording would exceed its
-event bound.
-
-This package intentionally does not own replay history or depend on browser
-timers, React, Zustand, dashboard state, or transport code.
-
-`@you-agent-factory/client` is a peer dependency because it supplies the
-canonical Factory event and recording types. Consumers install both published
-packages; the emulator package does not embed a checkout-relative dependency.
-The peer range remains unconstrained while this dependency is type-only and no
-minimum compatible client release has been established.
-
-`createFactoryEmulator({ initialState, calculateTick, sink })` provides the
-small logical-tick boundary used by an emulator host. It calculates a complete
-batch from a detached committed-state snapshot, waits for `sink.write`, and
-only then commits the calculated next state. A concurrent `advance` rejects
-while the write is unresolved, ensuring no later tick is calculated or
-committed ahead of an unaccepted batch.
-
-If a sink rejects a tick, the emulator retains that detached batch and its
-calculated state as the only pending transaction. The next `advance` retries it
-with the same IDs, timestamps, contents, and order; `reset` explicitly
-discards it. `pending` and `status` expose detached recovery state and the last
-write or close error. An idle emulator remains open. When configured with
-`calculateClose`, `close` writes that caller-supplied terminal lifecycle batch,
-waits for it to be accepted, and then closes the sink. A pending rejected tick
-blocks close so canonical history cannot be skipped. A rejected terminal batch
-is likewise retained unchanged for the next close attempt; after its acceptance
-a failed sink close retries only `sink.close`, never the terminal write.
-
-## Deterministic session start and reset
-
-`createFactoryEmulatorSession({ factory, scenario, sink })` owns one long-lived
-emulator lifecycle. `start()` revalidates the supported Factory and scenario
-before activity, normalizes `startAt` to a UTC instant, then writes an ordered
-topology/run bootstrap batch followed by one normalized initial-submission
-batch. The returned state becomes visible only after those writes are accepted.
-
-Session, request, trace, Work, token, dispatch, completion, and event identities are derived from canonical
-Factory/scenario inputs, the scenario seed, authored submission coordinates,
-authored lineage cursors, and logical sequence. Submitted token identities are
-recorded in `WORK_REQUEST` Work tags. Dispatch completion metadata records both
-the resolved lineage-token anchor and the resulting token identity, while the
-bounded Work snapshot retains the current token identity. The derivation reads
-no ambient time, randomness, locale, or process-global counter. Every startup
-event is stamped at virtual elapsed time zero (`startAt` after UTC normalization).
-
-`reset()` is available after a successful start. It clears runtime Work,
-virtual elapsed time, counters, and rule cursors and returns the session to
-`pre-start` without writing an event. Starting again with the same immutable
-configuration reproduces the original event bytes and committed snapshot;
-changing the seed creates a different deterministic identity stream.
-
-While started, `submit(work)` and `submit([work, ...])` accept the same
-`id`, `workType`, and optional data-only `input` shape as scenario initial
-submissions. The complete submission is detached and validated before the sink
-is called. One accepted batch adds all of its Work in caller order; any invalid
-member rejects the command without events, counter changes, or committed Work.
-Request, trace, Work, and event identities include stable command coordinates,
-so repeated sessions reproduce the same submission stream without relying on
-ambient counters.
-
-Scripted `complete` and `reject` outcomes may set a non-negative integer
-`durationMs`; omission means zero virtual milliseconds. `advanceToNext()`
-commits exactly one scheduler batch: ready Work starts at the current virtual
-instant, while the next step jumps to the earliest deadline and completes all
-dispatches due there in stable Work order. `advanceBy(durationMs)` processes
-each eligible batch through its inclusive target and, when Work remains open,
-ends exactly at that virtual instant. Waiting intervals move the virtual clock
-without synthetic events, while a fully idle session returns an event-free
-no-op receipt and stays open.
-
-All advancement timestamps are derived from normalized scenario `startAt` plus
-integer virtual elapsed milliseconds. The session creates no timers and owns no
-playback speed, pause, visibility, or replay-selection state.
-
-`status()` derives execution state from session facts. A started session with
-ready Work reports `ready`; one with no unfinished Work remains open and reports
-`idle`; unmatched unfinished Work configured to be ignored reports `waiting`.
-During an accepted submission write it reports `active`, while `state()`
-continues to expose only the prior committed snapshot. Once the sink accepts
-the batch, the new Work becomes visible and the session reports `ready` or
-`waiting` from its executable scenario facts.
-
-Every status value also reports the current virtual instant, cumulative
-completed-dispatch, event, and virtual-time usage with configured limits, and a
-bounded summary of any rejected sink transaction. Error details are plain data,
-including sink operation/message or execution-pause diagnostics. Status never
-contains canonical event history, playback controls, timers, visibility state,
-or framework-owned objects.
-
-Configuration and command inputs are validated before runtime ownership and
-must contain only plain objects, dense arrays, `null`, booleans, strings, and
-finite numbers. Structured-cloneable class instances such as `Date`, `Map`,
-`Set`, typed arrays, and regular expressions are rejected as configuration or
-submission errors instead of entering scripted outputs, state, retries, or
-events. Every receipt, status, pending batch, and state snapshot is a fresh
-structured-cloneable data value. Mutating any returned value cannot alter
-committed state or a later retry. The session retains current execution facts
-and at most one bounded recovery transaction; accepted canonical batch history
-belongs exclusively to the caller-owned sink.
-
-Every session command follows the same calculate/write/commit boundary. If a
-logical batch is rejected, `state()` and virtual time remain at the last
-accepted transition, `status()` reports `error`, and `pending()` returns a
-detached copy of the rejected batch. Only the same command with the same input
-may retry that transaction; the retained event values and calculated next
-state are reused without recalculation. `reset()` is the sole command that may
-discard an open rejected transaction.
-
-`close()` is explicit and terminal. It writes one deterministic `RUN_RESPONSE`
-batch at the current virtual instant, commits the closed lifecycle only after
-that batch is accepted, and then awaits `sink.close()`. A terminal write
-rejection retries the same event. If only `sink.close()` rejects, the next
-`close()` retries that operation without writing the terminal event again.
-Non-close commands cannot bypass either recovery state, and all state-changing
-commands reject after a successful close.
-
-## Deterministic execution limits
-
-Sessions enforce cumulative execution limits before a calculated batch reaches
-the sink. Defaults are 1,000 completed dispatches, 10,000 canonical events, and
-3,600,000 virtual milliseconds (one virtual hour). At one virtual instant, at
-most 1,000 scheduler batches may run without virtual-time progress; crossing
-that deterministic threshold is reported as a zero-duration cycle. Finite
-zero-duration chains at or below the threshold still complete normally.
-
-Callers may pass `limits` to `createFactoryEmulatorSession`. The limits object
-must satisfy the same plain-data ownership boundary as Factory and scenario
-configuration: class instances, custom or null prototypes, accessors, and
-cycles are rejected before any property is read or sink activity occurs. The
-accepted input is detached at construction, so later caller mutation cannot
-change execution policy. Every supplied value must be a positive safe integer
-and no greater than the exported
-`FACTORY_EMULATOR_LIMIT_HARD_CAPS`. `maxEvents` has a minimum of 2 because the
-mandatory bootstrap atomically emits `INITIAL_STRUCTURE_REQUEST` and
-`RUN_REQUEST`; smaller configurations fail before sink activity. The defaults
-and hard caps are exported as
-`DEFAULT_FACTORY_EMULATOR_LIMITS` and `FACTORY_EMULATOR_LIMIT_HARD_CAPS`:
-
-| Limit | Minimum | Default | Hard cap |
-| --- | ---: | ---: | ---: |
-| `maxCompletedDispatches` | 1 | 1,000 | 100,000 |
-| `maxEvents` | 2 | 10,000 | 1,000,000 |
-| `maxVirtualElapsedMs` | 1 | 3,600,000 | 31,536,000,000 |
-| `maxZeroDurationBatches` | 1 | 1,000 | 100,000 |
-| `maxSynchronousBatches` | 1 | 100 | 10,000 |
-| `maxSynchronousWorkItems` | 1 | 100 | 10,000 |
-
-Invalid policy fails at session construction, before bootstrap activity. All
-kernel-produced command errors are detached plain-data values with `name`,
-`message`, `code`, and family-specific diagnostic fields, so their complete
-contract survives `structuredClone` across worker and process boundaries.
-Caller-owned sink failures are propagated unchanged and are also projected as
-plain data through `status()`, with non-string or unprintable rejection messages
-normalized to safe strings. A batch that would exceed a cumulative limit is
-not written or committed.
-Instead, the command rejects with `FactoryEmulatorExecutionPausedError`, and
-`status()` reports `error` with a detached `budget-exceeded` or
-`zero-duration-cycle` diagnostic containing the limit name, configured and
-observed values, and current virtual instant. Existing Work remains in its last
-valid phase; the kernel never fabricates failed Work to represent a pause.
-
-Before an atomic scheduler batch is materialized, the session examines at most
-`maxSynchronousWorkItems` retained Work values and then yields with an explicit
-plain-data inspection continuation. That inspection returns the exact candidate
-indexes and lineage lookup consumed by pure calculation, so calculation does
-not rescan retained Work. Replacement materialization and detached command-state
-construction traverse retained Work with the same yield cadence instead of
-performing whole-state clones. The inspection counts at most one eligible Work
-beyond the limit. An oversized ready or due set pauses with a
-`synchronous-work-limit` diagnostic before dispatch/completion events or
-calculated next state are built. Initial and interactive submission batches use
-the same ceiling. Their array cardinality is checked before any member is
-validated or copied; oversized initial input fails session construction and an
-oversized interactive command pauses without sink, state, or pending-transaction
-residue. Cardinality inspection reads the array's own data descriptor inside an
-exception-safe boundary, so throwing, revoked, or otherwise uninspectable proxy
-inputs reject as detached command errors instead of leaking host exceptions.
-Configuration and command detachment failures are normalized through the same
-plain-data error boundary. The shared data-only validator uses an iterative
-traversal capped at 10,000 nodes and 100 levels before cloning, so a single
-deeply nested Work input cannot overflow the host stack or introduce an
-unbounded calculation batch.
-
-After each `maxSynchronousBatches` scheduler calculations, a long command awaits
-a host task boundary. The default uses the runtime task queue without a wall
-timer; hosts may inject `yieldControl` to own worker/process scheduling. Event
-order is unchanged, and the original command stays serialized until it finishes
-or pauses.
-`reset()` clears the pause and all usage counters, reproducing the same boundary
-for the same inputs. `close()` remains available after a safety pause and may
-write its single terminal lifecycle event even when the execution event budget
-is exhausted, ensuring the caller-owned sink can always be released.
+# Factory emulator
+
+`@you-agent-factory/factory-emulator` is a transport-neutral, non-React package
+for deterministic Factory emulator contracts. Scenario parsing validates both
+the package-local schema and references to a caller-supplied UI client
+`FactoryDefinition`.
+
+The hosted Go runtime remains authoritative for Factory execution. This package
+implements only the deterministic browser subset documented in the
+[public package family guide](https://github.com/portpowered/you-agent-factory/blob/main/ui/packages/README.md);
+canonical-event-compatible output
+does not make it a replacement for hosted execution.
+
+```ts
+import factory from "./factory.json" with { type: "json" };
+import scenario from "./scenario.json" with { type: "json" };
+import { parseFactoryEmulatorScenario } from "@you-agent-factory/factory-emulator";
+
+const parsed = parseFactoryEmulatorScenario(scenario, factory);
+```
+
+The parser returns a detached scenario value. `safeParseFactoryEmulatorScenario`
+returns all structure and semantic diagnostics without partially accepting an
+invalid scenario.
+
+Factories can be preflighted against the deterministic v1 execution subset
+before any event history is emitted:
+
+```ts
+import {
+  inspectFactoryEmulatorCompatibility,
+  writeFactoryEventsIfCompatible,
+} from "@you-agent-factory/factory-emulator";
+
+const compatibility = inspectFactoryEmulatorCompatibility(factory);
+if (!compatibility.supported) {
+  console.error(compatibility.diagnostics);
+}
+
+// Incompatible Factories return every diagnostic without calling sink.write.
+await writeFactoryEventsIfCompatible(factory, eventBatch, sink);
+```
+
+The inspector treats an omitted orchestrator as the documented Petri default,
+does not mutate or retain the Factory, and reports stable codes with paths into
+the caller-supplied UI client `FactoryDefinition`.
+
+## Long-lived session lifecycle
+
+Create a framework-independent session from a compatible Factory, a parsed
+scenario, and a caller-owned event sink. Construction revalidates the inputs
+and optional safety limits before any event is written.
+
+```ts
+import {
+  createFactoryEmulatorSession,
+  MemoryFactoryEventSink,
+} from "@you-agent-factory/factory-emulator";
+
+const sink = new MemoryFactoryEventSink({ maxEvents: 10_000 });
+const session = createFactoryEmulatorSession({
+  factory,
+  scenario: parsed,
+  sink,
+});
+
+const before = session.status();
+const started = await session.start();
+await session.submit({
+  name: "follow-up",
+  workType: "ticket",
+  state: "ready",
+  input: "Customer reply",
+});
+
+await session.submit({
+  works: [
+    { name: "reply", workType: "ticket", state: "ready" },
+    { name: "approval", workType: "ticket", state: "ready" },
+  ],
+  relations: [
+    {
+      type: "DEPENDS_ON",
+      sourceWorkName: "reply",
+      targetWorkName: "approval",
+      // Omit only when the target Work Type declares the default "complete".
+      requiredState: "classified",
+    },
+  ],
+});
+const dispatched = await session.advanceToNext();
+const advanced = await session.advanceBy(250);
+const current = session.state();
+const closed = await session.close();
+```
+
+`start()` writes one atomic canonical bootstrap batch in `RUN_REQUEST`,
+`INITIAL_STRUCTURE_REQUEST`, `SESSION_STARTED` order. The started state becomes
+visible only after the sink accepts the complete batch. `state()` and
+`status()` return detached, structured-cloneable snapshots; the kernel does not
+retain playback or event history. An idle session remains open for later Work.
+
+`submit()` accepts one validated scenario Work value, a relationship-free Work
+array, or a `{ works, relations }` batch. `DEPENDS_ON` is the only supported
+emulator relationship; both endpoints must be names from that batch. The
+complete request is validated before its atomic sink write, so an invalid item
+or graph cannot partially create Work. Submissions remain available while
+other Work is active and after the session returns to idle.
+
+Accepted relationship batches emit one canonical `WORK_REQUEST` carrying the
+resolved relations, followed by one `RELATIONSHIP_CHANGE_REQUEST` per relation
+in declared order. The complete event sequence is one sink batch, and state and
+identity counters commit only after that batch succeeds. Use
+`replayFactoryEmulatorSubmissions(events)` to reconstruct detached Work identity,
+initial state, payload, and outbound relationships from canonical submission
+events.
+
+Virtual time advances only when the host calls `advanceBy(durationMs)` or
+`advanceToNext()`. Ready Work starts in one deterministic scheduler batch;
+`advanceToNext()` then jumps to the earliest due instant and completes every
+dispatch due there in stable Work order. `advanceBy()` processes every due
+outcome through its requested instant. Event timestamps are always the scenario
+`startAt` plus committed virtual elapsed time; these commands use no wall-clock
+or browser timers. Receipts, state, status, and validation errors are detached
+structured-cloneable values.
+
+Each scheduler batch considers at most 50 eligible bindings in deterministic
+Work-in-queue order. Multi-input workstations require a stable binding for every
+input, and selected candidates claim all consumable Work and declared top-level
+resource capacity atomically. Independent candidates can start together when
+capacity permits; active dispatches retain their claims until completion, and
+released capacity is available to waiting Work in the following scheduler
+batch. Work with `DEPENDS_ON` relations remains ready but cannot enter a
+scheduler candidate until every target Work currently occupies its normalized
+required state. Dependency eligibility is recalculated after each accepted
+completion batch, so newly unblocked Work can dispatch in the same `advanceBy()`
+command. Worker-only resource metadata does not change mocked execution
+capacity.
+
+When a target enters a failed state, every non-terminal dependent moves to its
+own Work Type's failed state through a deterministic breadth-first closure in
+that same completion tick. Each move emits one canonical `WORK_STATE_CHANGE`
+with source `cascading-failure`; terminal and already-failed Work is unchanged.
+
+The package's frozen runtime-reference corpus includes both a `DEPENDS_ON`
+prerequisite release and a terminal-failure cascade. Conformance compares
+dependency eligibility, dispatch selection, consumed Work, routes, terminal
+states, and submission replay projection at every logical tick.
+
+Accepted, continued, rejected, and failed outcomes preserve Work lineage while
+routing to explicit destinations in declared order. Accepted fan-out supports
+multiple outputs and both `OUTPUT_AS_PAYLOAD` and `PRESERVE_INPUT` propagation.
+Missing routes use the supported Factory defaults: failures enter the input Work
+Type's failed state, STANDARD rejections use the effective failure route, and
+REPEATER rejections return to their inputs.
+
+Supported workerless `LOGICAL_MOVE` workstations do not need scenario rules.
+Their `VISIT_COUNT` guards read the inclusive transition counts carried by the
+first authored input lineage, and an eligible move routes synchronously at the
+current virtual instant without creating active worker-dispatch state. The
+resulting canonical `DISPATCH_RESPONSE` preserves lineage, propagation mode,
+and declared output order; session Work snapshots expose the carried `visits`
+map for deterministic inspection. Zero-duration logical cycles share the
+session's configured cycle and cooperative-yield boundaries.
+
+Canonical identities and event ordering are derived from the Factory identity,
+the complete validated scenario (including its seed), normalized command
+inputs, command order, and virtual elapsed time. Object key insertion order,
+wall-clock time, and host playback speed do not participate. `reset()` restores
+the pre-start counters, rule cursors, identities, initial submissions, and
+virtual-time origin while retaining the caller-owned sink, so the host can
+clear or replace its own recording destination and reproduce the same supported
+history byte for byte.
+
+Every state-changing command retains its complete detached candidate state and
+canonical event batch until the caller-owned sink accepts the batch. While a
+write is pending, other state-changing commands fail with
+`FactoryEmulatorPendingCommandError`; read-only snapshots remain available.
+After rejection, status exposes the structured sink error and pending phase.
+Retry the same command with the same arguments to write the byte-identical
+batch before execution continues, or call `reset()` to explicitly discard the
+rejected transaction and restore the pre-start state.
+
+`close()` writes one canonical `SESSION_COMPLETED` terminal batch, then awaits
+the sink's optional `close()` boundary before exposing the terminal closed
+state. A terminal write or sink-close rejection remains retryable. Sink-close
+retries never duplicate an already accepted terminal event, and successful
+close rejects all later state-changing commands.
+
+## Execution safety and cooperative scheduling
+
+The session enforces deterministic safety budgets before a calculated batch is
+sent to the sink. Defaults allow 1,000 completed dispatches, 10,000 canonical
+events, one virtual hour, 1,000 consecutive zero-duration scheduler batches,
+100 synchronous scheduler batches, and 1,000 Work items in one synchronous
+batch. Overrides must be positive safe integers and cannot exceed the exported
+`FACTORY_EMULATOR_LIMIT_HARD_CAPS`.
+
+Crossing an event, completed-dispatch, or virtual-time budget throws
+`FactoryEmulatorExecutionPausedError` and exposes a detached
+`budget-exceeded` diagnostic through `status().error`. The diagnostic identifies
+the limit, configured and observed values, and virtual-time context. The
+calculated over-limit batch is not written or committed, and the kernel does
+not fabricate failed Work. A consecutive zero-time scheduler chain uses the
+distinct `zero-duration-cycle` diagnostic. Initial and runtime Work sets larger
+than `maxSynchronousWorkItems` fail atomically with
+`bounded-work-exceeded` before partial Work or events become visible.
+After any execution pause, `reset()` clears the structured failure and restores
+the deterministic pre-start state. The caller remains responsible for clearing
+or replacing its owned event history before rerunning the same scenario; that
+rerun emits the same canonical history and stops at the same configured
+boundary.
+
+Hosts can provide `yieldControl` to choose their own cooperative task boundary.
+Long advancement commands await it after every `maxSynchronousBatches`
+accepted scheduler batches and then resume the same serialized deterministic
+command. The kernel itself does not create timers or Web Workers.
+
+## Caller-owned event history
+
+`MemoryFactoryEventSink` retains ordered Factory Events up to a required
+caller-selected bound. Each non-empty batch is atomic: history changes only
+after the asynchronous write resolves, and rejection or capacity overflow
+preserves the prior snapshot. Concurrent calls are serialized in call order.
+
+```ts
+import { MemoryFactoryEventSink } from "@you-agent-factory/factory-emulator";
+
+const sink = new MemoryFactoryEventSink({ maxEvents: 1_000 });
+await sink.write(eventBatch);
+const detachedHistory = sink.snapshot();
+await sink.close();
+```
+
+Input batches and returned snapshots are mutation-isolated. `close()` is
+idempotent, waits for writes accepted before close, and rejects later writes
+with a `FactoryEventSinkError` whose code is `closed`. Empty batches and
+all-or-nothing capacity failures use the `empty_batch` and `capacity_exceeded`
+codes. The optional `beforeWrite` hook provides caller-controlled backpressure
+and failure injection without transferring ownership of retained history.
+
+`RecordingFactoryEventSink` applies the same asynchronous, bounded, atomic
+lifecycle to a canonical UI-client `FactoryRecording`. It rejects duplicate
+event IDs, non-canonical ordering, mixed Factory or session identities, and any
+batch that would make the full recording invalid, without changing the prior
+snapshot.
+
+```ts
+import { RecordingFactoryEventSink } from "@you-agent-factory/factory-emulator";
+
+const recordingSink = new RecordingFactoryEventSink({
+  maxEvents: 1_000,
+  recording: {
+    schemaVersion: "factory-recording/v1",
+    id: "customer-support-example",
+    title: "Customer support example",
+    factory,
+  },
+});
+await recordingSink.write(eventBatch);
+const detachedRecording = recordingSink.snapshot();
+```
+
+## Package verification
+
+The package is built and verified independently from the dashboard. Run
+`bun run verify` from this directory to check the generated schema module,
+types, formatting and lint rules, focused tests, compiled frozen-reference
+conformance and determinism, dependency boundary, packed inventory, and a
+clean installed consumer. The installed consumer reruns every frozen reference
+from the packed artifact, so fixture freshness is proven without a backend or
+fixture generator. `bun run generate` refreshes the committed runtime schema module after editing
+`schema/scenario.schema.json`.
+
+`@you-agent-factory/client` is an explicit peer contract because the emulator
+uses its canonical Factory, Factory Event, and recording APIs without bundling
+or duplicating them. Consumers install both packages at the same version.
+
+## Frozen runtime references
+
+`loadFactoryEmulatorRuntimeReferences()` returns detached package-local
+references for the documented supported subset. The loader validates each
+fixture's public provenance, Factory and scenario, strictly ordered logical
+ticks, and flattened Factory-event kind sequence before a conformance consumer
+can compare emulator semantics. These references remain frontend-only and do
+not invoke a backend, Go, or WASM fixture generator.
+
+The corpus includes resource contention, parallel dispatch, and simultaneous
+completion cases. Their frozen ticks preserve the selected Work, consumed Work,
+completion outcomes, terminal routes, and replay projection so capacity and
+same-deadline behavior remain reproducible between runs.
+
+Each fixture records its specific public documentation provenance. In particular,
+the repeater fixture observes a `CONTINUE` route, the routing fixture observes a
+`REJECTED` route, the propagation fixture compares the routed payload under
+`PRESERVE_INPUT`, and the logical-move fixture first makes its `VISIT_COUNT`
+guard eligible before recording the workerless move's synchronous route.
+
+`compareFactoryEmulatorRuntimeReference(reference)` runs a reference through a
+fresh deterministic session and compares each logical tick independently. It
+compares ordered event kinds plus normalized dispatch choices, consumed Work,
+outcomes, routes (including routed payload), terminal states, and submission replay projection. Event
+identities and virtual timestamps are deliberately excluded; all other compared
+values are semantic evidence. A mismatch returns the fixture ID, first divergent
+logical tick, comparison surface, expected value, and actual value.