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

package/src/contracts.ts

@@ -1,41 +0,0 @@
-import type { FactoryEvent } from "@you-agent-factory/client";
-
-/**
- * One ordered canonical Factory event batch submitted by an emulator logical
- * tick. This value contains data only, so hosts can structured-clone it across
- * process or worker boundaries.
- */
-export interface FactoryEventBatch {
-  readonly events: readonly FactoryEvent[];
-}
-
-/**
- * The only successful result of a batch write. A receipt is returned only when
- * every supplied event was accepted in its supplied order; partial acceptance
- * must reject the write instead of returning this receipt.
- */
-export interface FactoryEventSinkWriteReceipt {
-  readonly status: "accepted";
-}
-
-/**
- * The only successful result of an explicit sink close. Closing does not
- * implicitly accept a pending batch; callers must await its write first.
- */
-export interface FactoryEventSinkCloseReceipt {
-  readonly status: "closed";
-}
-
-/**
- * Caller-owned asynchronous destination for canonical Factory events.
- *
- * `write` is the backpressure boundary: resolution means the entire ordered
- * batch was accepted, while rejection means none of the batch was accepted.
- * `close` is explicit and asynchronous so a host can observe either its
- * successful completion or rejection. The contract deliberately has no
- * subscription, replay, transport, browser, or dashboard dependency.
- */
-export interface FactoryEventSink {
-  write(batch: FactoryEventBatch): Promise<FactoryEventSinkWriteReceipt>;
-  close(): Promise<FactoryEventSinkCloseReceipt>;
-}

package/src/data-error.js

@@ -1,21 +0,0 @@
-export function defineDataError(name, code, fields) {
-  const DataError = function (...args) {
-    return {
-      name,
-      message: fields.message(...args),
-      code,
-      ...fields.details(...args),
-    };
-  };
-  Object.defineProperty(DataError, "name", { value: name });
-  Object.defineProperty(DataError, Symbol.hasInstance, {
-    value(candidate) {
-      return candidate !== null
-        && typeof candidate === "object"
-        && Object.getPrototypeOf(candidate) === Object.prototype
-        && candidate.name === name
-        && candidate.code === code;
-    },
-  });
-  return DataError;
-}

package/src/data-only.js

@@ -1,208 +0,0 @@
-const DATA_ONLY_EXPECTATION =
-  "plain objects, dense arrays, null, booleans, strings, or finite numbers";
-
-const MAXIMUM_DATA_ONLY_NODES = 10_000;
-const MAXIMUM_DATA_ONLY_DEPTH = 100;
-
-/** Returns deterministic JSON-Pointer diagnostics for values outside the data-only graph. */
-export function dataOnlyDiagnostics(value, { code, rootPath = "/" }) {
-  const diagnostics = [];
-  const ancestors = new Set();
-  const stack = [{ depth: 0, kind: "visit", path: rootPath, value }];
-  let inspectedNodes = 0;
-
-  while (stack.length > 0) {
-    const frame = stack.pop();
-    if (frame.kind === "leave") {
-      ancestors.delete(frame.value);
-      continue;
-    }
-
-    inspectedNodes += 1;
-    if (inspectedNodes > MAXIMUM_DATA_ONLY_NODES) {
-      diagnostics.push(boundDiagnostic(
-        code,
-        frame.path,
-        `more than ${MAXIMUM_DATA_ONLY_NODES} data nodes`,
-      ));
-      break;
-    }
-    if (frame.depth > MAXIMUM_DATA_ONLY_DEPTH) {
-      diagnostics.push(boundDiagnostic(
-        code,
-        frame.path,
-        `data nested deeper than ${MAXIMUM_DATA_ONLY_DEPTH} levels`,
-      ));
-      break;
-    }
-    if (isPrimitive(frame.value)) {
-      continue;
-    }
-    if (typeof frame.value !== "object") {
-      diagnostics.push(diagnostic(code, frame.path, typeof frame.value));
-      continue;
-    }
-
-    const inspection = inspectObject(frame.value, frame.path, code, ancestors);
-    if (inspection.diagnostic !== undefined) {
-      diagnostics.push(inspection.diagnostic);
-      continue;
-    }
-    if (inspection.children.length > MAXIMUM_DATA_ONLY_NODES - inspectedNodes) {
-      diagnostics.push(boundDiagnostic(
-        code,
-        frame.path,
-        `more than ${MAXIMUM_DATA_ONLY_NODES} data nodes`,
-      ));
-      break;
-    }
-
-    ancestors.add(frame.value);
-    stack.push({ kind: "leave", value: frame.value });
-    for (let index = inspection.children.length - 1; index >= 0; index -= 1) {
-      stack.push({
-        ...inspection.children[index],
-        depth: frame.depth + 1,
-        kind: "visit",
-      });
-    }
-    diagnostics.push(...inspection.propertyDiagnostics);
-  }
-  return diagnostics;
-}
-
-function isPrimitive(value) {
-  return (
-    value === null ||
-    typeof value === "string" ||
-    typeof value === "boolean" ||
-    (typeof value === "number" && Number.isFinite(value))
-  );
-}
-
-function inspectObject(value, path, code, ancestors) {
-  let prototype;
-  let descriptors;
-  try {
-    prototype = Object.getPrototypeOf(value);
-    if (prototype !== Object.prototype && prototype !== Array.prototype) {
-      return { diagnostic: diagnostic(code, path, "an object with an unsupported prototype") };
-    }
-    if (ancestors.has(value)) {
-      return { diagnostic: diagnostic(code, path, "a circular reference") };
-    }
-    if (Array.isArray(value) && value.length > MAXIMUM_DATA_ONLY_NODES) {
-      return {
-        diagnostic: boundDiagnostic(
-          code,
-          path,
-          `an array longer than ${MAXIMUM_DATA_ONLY_NODES} entries`,
-        ),
-      };
-    }
-    if (!Array.isArray(value) && hasTooManyEnumerableProperties(value)) {
-      return {
-        diagnostic: boundDiagnostic(
-          code,
-          path,
-          `an object with more than ${MAXIMUM_DATA_ONLY_NODES} entries`,
-        ),
-      };
-    }
-    descriptors = Object.getOwnPropertyDescriptors(value);
-  } catch {
-    return { diagnostic: diagnostic(code, path, "an uninspectable object") };
-  }
-
-  return Array.isArray(value)
-    ? inspectArray(value, path, code, descriptors)
-    : inspectRecord(path, code, descriptors);
-}
-
-function hasTooManyEnumerableProperties(value) {
-  let count = 0;
-  for (const key in value) {
-    if (!Object.hasOwn(value, key)) {
-      continue;
-    }
-    count += 1;
-    if (count > MAXIMUM_DATA_ONLY_NODES) {
-      return true;
-    }
-  }
-  return false;
-}
-
-function inspectArray(value, path, code, descriptors) {
-  const children = [];
-  const propertyDiagnostics = [];
-  for (let index = 0; index < value.length; index += 1) {
-    const childPath = joinPath(path, String(index));
-    const descriptor = descriptors[index];
-    if (descriptor === undefined) {
-      propertyDiagnostics.push(diagnostic(code, childPath, "a sparse array slot"));
-      continue;
-    }
-    inspectDescriptor(descriptor, childPath, code, children, propertyDiagnostics);
-  }
-  for (const key of Reflect.ownKeys(descriptors)) {
-    if (key === "length" || (typeof key === "string" && isArrayIndex(key, value.length))) {
-      continue;
-    }
-    propertyDiagnostics.push(
-      diagnostic(code, joinPath(path, String(key)), "an array property"),
-    );
-  }
-  return { children, propertyDiagnostics };
-}
-
-function inspectRecord(path, code, descriptors) {
-  const children = [];
-  const propertyDiagnostics = [];
-  for (const key of Reflect.ownKeys(descriptors)) {
-    const childPath = typeof key === "symbol" ? path : joinPath(path, key);
-    if (typeof key === "symbol") {
-      propertyDiagnostics.push(diagnostic(code, childPath, "a symbol-keyed property"));
-      continue;
-    }
-    inspectDescriptor(descriptors[key], childPath, code, children, propertyDiagnostics);
-  }
-  return { children, propertyDiagnostics };
-}
-
-function inspectDescriptor(descriptor, path, code, children, diagnostics) {
-  if (!descriptor.enumerable || !("value" in descriptor)) {
-    diagnostics.push(diagnostic(code, path, "an accessor or non-enumerable property"));
-    return;
-  }
-  children.push({ path, value: descriptor.value });
-}
-
-function isArrayIndex(key, length) {
-  const index = Number(key);
-  return Number.isInteger(index) && index >= 0 && index < length && String(index) === key;
-}
-
-function joinPath(parent, property) {
-  const escaped = property.replaceAll("~", "~0").replaceAll("/", "~1");
-  return parent === "/" ? `/${escaped}` : `${parent}/${escaped}`;
-}
-
-function diagnostic(code, path, received) {
-  return {
-    code,
-    path,
-    message: `${path} must contain data-only values; received ${received}.`,
-    expectation: DATA_ONLY_EXPECTATION,
-  };
-}
-
-function boundDiagnostic(code, path, received) {
-  return {
-    code,
-    path,
-    message: `${path} exceeds the bounded data-only inspection: ${received}.`,
-    expectation:
-      `${DATA_ONLY_EXPECTATION} within ${MAXIMUM_DATA_ONLY_NODES} nodes and ${MAXIMUM_DATA_ONLY_DEPTH} levels`,
-  };
-}

package/src/emulator.js

@@ -1,195 +0,0 @@
-const committedReceipt = Object.freeze({ status: "committed" });
-
-export class FactoryEmulatorAdvanceInProgressError extends Error {
-  constructor() {
-    super("Factory emulator is waiting for the current logical tick to be accepted");
-    this.name = "FactoryEmulatorAdvanceInProgressError";
-  }
-}
-
-export class FactoryEmulatorPendingTransactionError extends Error {
-  constructor() {
-    super("Factory emulator has a rejected logical tick that must be retried or reset");
-    this.name = "FactoryEmulatorPendingTransactionError";
-  }
-}
-
-export class FactoryEmulatorClosedError extends Error {
-  constructor() {
-    super("Factory emulator is closed");
-    this.name = "FactoryEmulatorClosedError";
-  }
-}
-
-/**
- * Creates a transport-neutral logical-tick emulator.
- *
- * State and calculated tick values are copied at the emulator boundary. This
- * keeps the sink write and the eventual commit paired to one immutable
- * calculation, even when the host retains or mutates its original values.
- */
-export function createFactoryEmulator({ calculateClose, calculateTick, initialState, sink }) {
-  if (typeof calculateTick !== "function") {
-    throw new TypeError("calculateTick must be a function");
-  }
-  if (!sink || typeof sink.write !== "function") {
-    throw new TypeError("sink must provide a write function");
-  }
-
-  let committedState = copy(initialState);
-  let advanceInProgress = false;
-  let closed = false;
-  let pendingTick;
-  let pendingCloseBatch;
-  let pendingCloseBatchAccepted = false;
-  let lastError;
-
-  return Object.freeze({
-    async advance() {
-      if (advanceInProgress) {
-        throw new FactoryEmulatorAdvanceInProgressError();
-      }
-      assertOpen(closed);
-      if (pendingCloseBatch) {
-        throw new FactoryEmulatorPendingTransactionError();
-      }
-
-      const calculation = pendingTick ?? calculateCalculation(calculateTick, committedState);
-      return writeAndCommitTick(calculation);
-    },
-    async close() {
-      if (advanceInProgress) {
-        throw new FactoryEmulatorAdvanceInProgressError();
-      }
-      if (closed) {
-        throw new FactoryEmulatorClosedError();
-      }
-      if (pendingTick) {
-        throw new FactoryEmulatorPendingTransactionError();
-      }
-
-      if (!pendingCloseBatch) {
-        if (typeof calculateClose !== "function") {
-          throw new TypeError("calculateClose must be a function before closing the emulator");
-        }
-        pendingCloseBatch = calculateCloseBatch(calculateClose, committedState);
-      }
-      if (!pendingCloseBatchAccepted) {
-        advanceInProgress = true;
-        try {
-          await sink.write(copy(pendingCloseBatch));
-          pendingCloseBatchAccepted = true;
-          lastError = undefined;
-        } catch (error) {
-          lastError = errorStatus("write", error);
-          throw error;
-        } finally {
-          advanceInProgress = false;
-        }
-      }
-
-      advanceInProgress = true;
-      try {
-        await sink.close();
-        closed = true;
-        lastError = undefined;
-        return copy({ status: "closed", batch: pendingCloseBatch });
-      } catch (error) {
-        lastError = errorStatus("close", error);
-        throw error;
-      } finally {
-        advanceInProgress = false;
-      }
-    },
-    reset() {
-      if (advanceInProgress) {
-        throw new FactoryEmulatorAdvanceInProgressError();
-      }
-      if (closed) {
-        throw new FactoryEmulatorClosedError();
-      }
-      if (pendingCloseBatch) {
-        if (pendingCloseBatchAccepted) {
-          throw new FactoryEmulatorPendingTransactionError();
-        }
-        pendingCloseBatch = undefined;
-        lastError = undefined;
-        return;
-      }
-      pendingTick = undefined;
-      lastError = undefined;
-    },
-    pending() {
-      return pendingTick ? copy(pendingTick.batch) : undefined;
-    },
-    status() {
-      return copy({
-        phase: closed ? "closed" : pendingCloseBatch ? "closing" : pendingTick ? "pending" : "open",
-        lastError,
-      });
-    },
-    state() {
-      return copy(committedState);
-    },
-  });
-
-  async function writeAndCommitTick(calculation) {
-    advanceInProgress = true;
-    try {
-      await sink.write(copy(calculation.batch));
-      committedState = calculation.state;
-      pendingTick = undefined;
-      lastError = undefined;
-      return copy({ ...committedReceipt, batch: calculation.batch });
-    } catch (error) {
-      pendingTick = calculation;
-      lastError = errorStatus("write", error);
-      throw error;
-    } finally {
-      advanceInProgress = false;
-    }
-  }
-}
-
-function calculateCalculation(calculateTick, committedState) {
-  const calculation = copy(calculateTick(copy(committedState)));
-  assertCalculation(calculation);
-  return calculation;
-}
-
-function calculateCloseBatch(calculateClose, committedState) {
-  const batch = copy(calculateClose(copy(committedState)));
-  if (!batch || !Array.isArray(batch.events)) {
-    throw new TypeError("calculateClose must return a terminal lifecycle event batch");
-  }
-  return batch;
-}
-
-function assertCalculation(calculation) {
-  if (!calculation || typeof calculation !== "object") {
-    throw new TypeError("calculateTick must return a logical tick calculation");
-  }
-  if (!calculation.batch || !Array.isArray(calculation.batch.events)) {
-    throw new TypeError("logical tick calculation batch must contain an events array");
-  }
-  if (!("state" in calculation)) {
-    throw new TypeError("logical tick calculation must contain the calculated state");
-  }
-}
-
-function assertOpen(closed) {
-  if (closed) {
-    throw new FactoryEmulatorClosedError();
-  }
-}
-
-function errorStatus(operation, error) {
-  return {
-    operation,
-    message: error instanceof Error ? error.message : String(error),
-  };
-}
-
-function copy(value) {
-  return structuredClone(value);
-}

package/src/emulator.ts

@@ -1,86 +0,0 @@
-import type { FactoryEventBatch, FactoryEventSink } from "./contracts.js";
-
-/** Raised when an advancing command arrives before the prior tick is accepted. */
-export declare class FactoryEmulatorAdvanceInProgressError extends Error {}
-
-/** Raised when a rejected tick must be retried or explicitly reset first. */
-export declare class FactoryEmulatorPendingTransactionError extends Error {}
-
-/** Raised when a command is issued after the emulator has closed. */
-export declare class FactoryEmulatorClosedError extends Error {}
-
-/**
- * The complete result of calculating one logical scheduler step. The emulator
- * writes `batch` before it makes `state` visible as its next committed state.
- */
-export interface FactoryEmulatorTick<State> {
-  readonly batch: FactoryEventBatch;
-  readonly state: State;
-}
-
-/** Computes one complete logical tick from a detached committed-state snapshot. */
-export type FactoryEmulatorTickCalculator<State> = (
-  state: State,
-) => FactoryEmulatorTick<State>;
-
-/** Builds the terminal lifecycle event batch written before the sink closes. */
-export type FactoryEmulatorCloseCalculator<State> = (
-  state: State,
-) => FactoryEventBatch;
-
-/** Dependencies and initial state for one caller-owned emulator session. */
-export interface FactoryEmulatorOptions<State> {
-  /** Required when callers use `close`; returns the terminal lifecycle batch. */
-  readonly calculateClose?: FactoryEmulatorCloseCalculator<State>;
-  readonly calculateTick: FactoryEmulatorTickCalculator<State>;
-  readonly initialState: State;
-  readonly sink: FactoryEventSink;
-}
-
-/** Returned only after the matching sink write accepts the entire batch. */
-export interface FactoryEmulatorAdvanceReceipt {
-  readonly status: "committed";
-  readonly batch: FactoryEventBatch;
-}
-
-/** The result returned after a terminal batch and sink close both succeed. */
-export interface FactoryEmulatorCloseReceipt {
-  readonly status: "closed";
-  readonly batch: FactoryEventBatch;
-}
-
-/** Observable retry and lifecycle status for one emulator session. */
-export interface FactoryEmulatorStatus {
-  readonly phase: "open" | "pending" | "closing" | "closed";
-  readonly lastError?: {
-    readonly operation: "write" | "close";
-    readonly message: string;
-  };
-}
-
-/**
- * A caller-owned logical-tick runtime.
- *
- * `advance` computes one full batch, awaits the asynchronous sink write, and
- * commits the calculated state only after that write resolves. A second
- * advancing command while the write is unresolved rejects explicitly, so it
- * cannot calculate or commit a later tick ahead of the pending batch.
- * A rejected write retains the calculated batch unchanged; the next `advance`
- * retries it before new work is calculated, while `reset` explicitly discards
- * it. `close` retries its caller-calculated terminal lifecycle batch unchanged
- * after rejection, then closes the sink. It cannot bypass a rejected tick.
- * `state` returns a detached snapshot of the latest committed state.
- */
-export interface FactoryEmulator<State> {
-  advance(): Promise<FactoryEmulatorAdvanceReceipt>;
-  close(): Promise<FactoryEmulatorCloseReceipt>;
-  reset(): void;
-  pending(): FactoryEventBatch | undefined;
-  status(): FactoryEmulatorStatus;
-  state(): State;
-}
-
-/** Creates an emulator with explicit state, scheduling, and sink ownership. */
-export declare function createFactoryEmulator<State>(
-  options: FactoryEmulatorOptions<State>,
-): FactoryEmulator<State>;

package/src/examples.js

@@ -1,86 +0,0 @@
-import { SUPPORTED_SCENARIO_VERSION } from "./generated/scenario-schema.js";
-
-/** Published, parser-validated documents for consumers starting an emulator host. */
-export const emulatorScenarioExamples = Object.freeze([
-  {
-    name: "minimal",
-    factory: {
-      name: "minimal-emulator-factory",
-      workTypes: [{ name: "checkout", states: [] }],
-      workstations: [{
-        name: "complete",
-        worker: "emulator",
-        inputs: [],
-        behavior: "STANDARD",
-      }],
-    },
-    scenario: {
-      version: SUPPORTED_SCENARIO_VERSION,
-      id: "minimal-checkout",
-      seed: "minimal-checkout-seed",
-      startAt: "2026-07-18T08:00:00Z",
-      rules: [{
-        id: "complete-checkout",
-        match: { kind: "workType", workType: "checkout" },
-        outcomes: [{ kind: "complete" }],
-        exhaustionBehavior: { kind: "repeatLast" },
-      }],
-      unmatchedBehavior: { kind: "ignore" },
-    },
-  },
-  {
-    name: "multi-rule-lineage",
-    factory: {
-      name: "multi-rule-emulator-factory",
-      workTypes: [
-        { name: "checkout", states: [] },
-        { name: "fulfillment", states: [] },
-        { name: "other", states: [] },
-      ],
-      workstations: [{
-        name: "complete",
-        worker: "emulator",
-        inputs: [],
-        behavior: "STANDARD",
-      }],
-    },
-    scenario: {
-      version: SUPPORTED_SCENARIO_VERSION,
-      id: "checkout-and-fulfillment",
-      seed: "checkout-and-fulfillment-seed",
-      startAt: "2026-07-18T08:30:00Z",
-      activityLabel: "Emulating deterministic checkout",
-      initialSubmissions: [
-        { id: "checkout-1", workType: "checkout" },
-        { id: "fulfillment-1", workType: "fulfillment" },
-      ],
-      rules: [
-        {
-          id: "priority-checkout",
-          match: { kind: "submissionId", submissionId: "checkout-1" },
-          outcomes: [{
-            kind: "complete",
-            lineageCursor: { kind: "initialSubmission", submissionId: "checkout-1" },
-          }],
-          exhaustionBehavior: { kind: "useUnmatchedBehavior" },
-        },
-        {
-          id: "remaining-checkout",
-          match: { kind: "workType", workType: "checkout" },
-          outcomes: [{ kind: "complete" }],
-          exhaustionBehavior: { kind: "repeatLast" },
-        },
-        {
-          id: "fulfillment-from-checkout",
-          match: { kind: "workType", workType: "fulfillment" },
-          outcomes: [{
-            kind: "complete",
-            lineageCursor: { kind: "scriptedOutcome", ruleId: "priority-checkout", outcomeIndex: 0 },
-          }],
-          exhaustionBehavior: { kind: "useUnmatchedBehavior" },
-        },
-      ],
-      unmatchedBehavior: { kind: "reject", reason: "no scripted match" },
-    },
-  },
-]);

package/src/examples.ts

@@ -1,11 +0,0 @@
-import type { EmulatorScenario } from "./generated/scenario.js";
-import type { EmulatorFactoryDefinition } from "./parser.js";
-
-export interface EmulatorScenarioExample {
-  readonly name: "minimal" | "multi-rule-lineage";
-  readonly factory: EmulatorFactoryDefinition;
-  readonly scenario: EmulatorScenario;
-}
-
-/** Published, parser-validated documents for consumers starting an emulator host. */
-export declare const emulatorScenarioExamples: readonly EmulatorScenarioExample[];

package/src/generated/factory-schema.d.ts

@@ -1,3 +0,0 @@
-// Code generated by scripts/generate-emulator.mjs; DO NOT EDIT.
-
-export declare const factorySchema: Readonly<Record<string, unknown>>;

package/src/generated/factory-schema.js

@@ -1,5 +0,0 @@
-// Code generated by scripts/generate-emulator.mjs; DO NOT EDIT.
-
-import schema from "../../generated/factory.schema.json" with { type: "json" };
-
-export const factorySchema = schema;

package/src/generated/scenario-schema.d.ts

@@ -1,4 +0,0 @@
-// Code generated by scripts/generate-emulator.mjs; DO NOT EDIT.
-
-export declare const SUPPORTED_SCENARIO_VERSION: "you-agent-factory.emulator.scenario.v1";
-export declare const scenarioSchema: Readonly<Record<string, unknown>>;

package/src/generated/scenario-schema.js

@@ -1,6 +0,0 @@
-// Code generated by scripts/generate-emulator.mjs; DO NOT EDIT.
-
-import schema from "../../generated/factory-emulator-scenario.schema.json" with { type: "json" };
-
-export const SUPPORTED_SCENARIO_VERSION = "you-agent-factory.emulator.scenario.v1";
-export const scenarioSchema = schema;