@you-agent-factory/factory-emulator 0.0.0

package/src/generated/factory-schema.js

@@ -0,0 +1,5 @@
+// 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

@@ -0,0 +1,4 @@
+// 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

@@ -0,0 +1,6 @@
+// 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;

package/src/generated/scenario.ts

@@ -0,0 +1,103 @@
+// Code generated by scripts/generate-emulator.mjs; DO NOT EDIT.
+
+export type EmulatorScenarioVersion = "you-agent-factory.emulator.scenario.v1";
+
+export interface EmulatorInitialSubmission {
+  /** Minimum length: 1. Maximum length: 128. */
+  id: string;
+  /** Minimum length: 1. Maximum length: 128. */
+  workType: string;
+  input?: Record<string, unknown>;
+}
+
+export interface EmulatorRule {
+  /** Minimum length: 1. Maximum length: 128. */
+  id: string;
+  match: EmulatorMatcher;
+  /** Minimum items: 1. */
+  outcomes: readonly EmulatorOutcome[];
+  exhaustionBehavior: EmulatorExhaustionBehavior;
+}
+
+export type EmulatorMatcher =
+  | {
+      kind: "all";
+    }
+  | {
+      kind: "workType";
+      /** Minimum length: 1. Maximum length: 128. */
+      workType: string;
+    }
+  | {
+      kind: "submissionId";
+      /** Minimum length: 1. Maximum length: 128. */
+      submissionId: string;
+    };
+
+export type EmulatorOutcome =
+  | {
+      kind: "complete";
+      /** Deterministic virtual execution duration in milliseconds. Defaults to zero. Minimum: 0. */
+      durationMs?: number;
+      output?: Record<string, unknown>;
+      lineageCursor?: EmulatorLineageCursor;
+    }
+  | {
+      kind: "reject";
+      /** Deterministic virtual execution duration in milliseconds. Defaults to zero. Minimum: 0. */
+      durationMs?: number;
+      /** Minimum length: 1. Maximum length: 512. */
+      reason: string;
+    };
+
+export type EmulatorLineageCursor =
+  | {
+      kind: "initialSubmission";
+      /** Minimum length: 1. Maximum length: 128. */
+      submissionId: string;
+    }
+  | {
+      kind: "scriptedOutcome";
+      /** Minimum length: 1. Maximum length: 128. */
+      ruleId: string;
+      /** Minimum: 0. */
+      outcomeIndex: number;
+    };
+
+export type EmulatorExhaustionBehavior =
+  | {
+      kind: "repeatLast";
+    }
+  | {
+      kind: "useUnmatchedBehavior";
+    }
+  | {
+      kind: "reject";
+      /** Minimum length: 1. Maximum length: 512. */
+      reason: string;
+    };
+
+export type EmulatorUnmatchedBehavior =
+  | {
+      kind: "ignore";
+    }
+  | {
+      kind: "reject";
+      /** Minimum length: 1. Maximum length: 512. */
+      reason: string;
+    };
+
+export interface EmulatorScenario {
+  version: EmulatorScenarioVersion;
+  /** Minimum length: 1. Maximum length: 128. */
+  id: string;
+  /** Minimum length: 1. Maximum length: 256. */
+  seed: 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]+)?Z$. */
+  startAt: string;
+  initialSubmissions?: readonly EmulatorInitialSubmission[];
+  rules: readonly EmulatorRule[];
+  unmatchedBehavior: EmulatorUnmatchedBehavior;
+  /** Bounded transient emulator activity metadata. It is never a canonical Factory event field. Minimum length: 1. Maximum length: 120. */
+  activityLabel?: string;
+}

package/src/identity.js

@@ -0,0 +1,55 @@
+const IDENTITY_KINDS = new Set([
+  "completion",
+  "dispatch",
+  "event",
+  "request",
+  "session",
+  "token",
+  "trace",
+  "work",
+]);
+
+/** Derives one domain-separated identity from stable semantic coordinates. */
+export function deriveFactoryEmulatorIdentity(kind, coordinates) {
+  if (!IDENTITY_KINDS.has(kind)) {
+    throw new TypeError(`unsupported Factory emulator identity kind: ${kind}`);
+  }
+  const source = `${kind}\u0000${canonicalStringify(coordinates)}`;
+  return `emulator-${kind}-${hash64(source, 0xcbf29ce484222325n)}${hash64(
+    source,
+    0x84222325cbf29cen,
+  )}`;
+}
+
+/** Produces a key-order-independent representation for deterministic inputs. */
+export function canonicalStringify(value) {
+  if (value === null || typeof value === "boolean" || typeof value === "string") {
+    return JSON.stringify(value);
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new TypeError("deterministic identity inputs must contain finite numbers");
+    }
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((entry) => canonicalStringify(entry ?? null)).join(",")}]`;
+  }
+  if (value && typeof value === "object") {
+    const entries = Object.keys(value)
+      .filter((key) => value[key] !== undefined)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${canonicalStringify(value[key])}`);
+    return `{${entries.join(",")}}`;
+  }
+  throw new TypeError("deterministic identity inputs must contain data values only");
+}
+
+function hash64(value, offset) {
+  let hash = offset;
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= BigInt(value.charCodeAt(index));
+    hash = BigInt.asUintN(64, hash * 0x100000001b3n);
+  }
+  return hash.toString(16).padStart(16, "0");
+}

package/src/index.js

@@ -0,0 +1,34 @@
+export {
+  FactoryEventSinkCapacityError,
+  FactoryEventSinkClosedError,
+  createFactoryRecordingSink,
+  createMemoryFactoryEventSink,
+} from "./sinks.js";
+export {
+  FactoryEmulatorAdvanceInProgressError,
+  FactoryEmulatorClosedError,
+  FactoryEmulatorPendingTransactionError,
+  createFactoryEmulator,
+} from "./emulator.js";
+export {
+  FactoryEmulatorConfigurationError,
+  FactoryEmulatorDurationError,
+  FactoryEmulatorExecutionPausedError,
+  FactoryEmulatorLifecycleError,
+  FactoryEmulatorPendingCommandError,
+  FactoryEmulatorSubmissionError,
+  DEFAULT_FACTORY_EMULATOR_LIMITS,
+  FACTORY_EMULATOR_LIMIT_HARD_CAPS,
+  createFactoryEmulatorSession,
+} from "./session.js";
+export {
+  scenarioSchema,
+  SUPPORTED_SCENARIO_VERSION,
+} from "./generated/scenario-schema.js";
+export { parseEmulatorScenario } from "./parser.js";
+export { emulatorScenarioExamples } from "./examples.js";
+export { inspectEmulatorSupport } from "./support.js";
+export {
+  resolveEmulatorScenarioResult,
+  selectEmulatorRule,
+} from "./semantics.js";

package/src/index.ts

@@ -0,0 +1,102 @@
+export type {
+  FactoryEventBatch,
+  FactoryEventSink,
+  FactoryEventSinkCloseReceipt,
+  FactoryEventSinkWriteReceipt,
+} from "./contracts.js";
+export {
+  FactoryEventSinkCapacityError,
+  FactoryEventSinkClosedError,
+  createFactoryRecordingSink,
+  createMemoryFactoryEventSink,
+} from "./sinks.js";
+export type {
+  FactoryRecordingSink,
+  FactoryRecordingSinkOptions,
+  MemoryFactoryEventSink,
+  MemoryFactoryEventSinkOptions,
+} from "./sinks.js";
+export {
+  FactoryEmulatorAdvanceInProgressError,
+  FactoryEmulatorClosedError,
+  FactoryEmulatorPendingTransactionError,
+  createFactoryEmulator,
+} from "./emulator.js";
+export {
+  FactoryEmulatorConfigurationError,
+  FactoryEmulatorDurationError,
+  FactoryEmulatorExecutionPausedError,
+  FactoryEmulatorLifecycleError,
+  FactoryEmulatorPendingCommandError,
+  FactoryEmulatorSubmissionError,
+  DEFAULT_FACTORY_EMULATOR_LIMITS,
+  FACTORY_EMULATOR_LIMIT_HARD_CAPS,
+  createFactoryEmulatorSession,
+} from "./session.js";
+export type {
+  FactoryEmulatorCommandError,
+  FactoryEmulatorSessionAdvanceReceipt,
+  FactoryEmulatorBudgetUsage,
+  FactoryEmulatorSessionCloseReceipt,
+  FactoryEmulatorResetReceipt,
+  FactoryEmulatorSession,
+  FactoryEmulatorSessionCounters,
+  FactoryEmulatorConfigurationDiagnostic,
+  FactoryEmulatorDataError,
+  FactoryEmulatorExecutionDiagnostic,
+  FactoryEmulatorLimits,
+  FactoryEmulatorSessionOptions,
+  FactoryEmulatorPendingTransactionStatus,
+  FactoryEmulatorSessionError,
+  FactoryEmulatorSessionState,
+  FactoryEmulatorSessionStatus,
+  FactoryEmulatorSessionWork,
+  FactoryEmulatorStartReceipt,
+  FactoryEmulatorSubmitReceipt,
+} from "./session.js";
+export type {
+  FactoryEmulator,
+  FactoryEmulatorAdvanceReceipt,
+  FactoryEmulatorCloseCalculator,
+  FactoryEmulatorCloseReceipt,
+  FactoryEmulatorOptions,
+  FactoryEmulatorStatus,
+  FactoryEmulatorTick,
+  FactoryEmulatorTickCalculator,
+} from "./emulator.js";
+export type {
+  EmulatorExhaustionBehavior,
+  EmulatorInitialSubmission,
+  EmulatorLineageCursor,
+  EmulatorMatcher,
+  EmulatorOutcome,
+  EmulatorRule,
+  EmulatorScenario,
+  EmulatorScenarioVersion,
+  EmulatorUnmatchedBehavior,
+} from "./generated/scenario.js";
+export {
+  scenarioSchema,
+  SUPPORTED_SCENARIO_VERSION,
+} from "./generated/scenario-schema.js";
+export {
+  parseEmulatorScenario,
+  type EmulatorFactoryDefinition,
+  type EmulatorScenarioDiagnostic,
+  type EmulatorScenarioDiagnosticCode,
+  type EmulatorScenarioParseResult,
+} from "./parser.js";
+export {
+  emulatorScenarioExamples,
+  type EmulatorScenarioExample,
+} from "./examples.js";
+export {
+  inspectEmulatorSupport,
+  type EmulatorSupportInspection,
+} from "./support.js";
+export {
+  resolveEmulatorScenarioResult,
+  selectEmulatorRule,
+  type EmulatorScenarioResolution,
+  type EmulatorSubmission,
+} from "./semantics.js";

package/src/limits.js

@@ -0,0 +1,125 @@
+export const DEFAULT_FACTORY_EMULATOR_LIMITS = Object.freeze({
+  maxCompletedDispatches: 1_000,
+  maxEvents: 10_000,
+  maxVirtualElapsedMs: 60 * 60 * 1_000,
+  maxZeroDurationBatches: 1_000,
+  maxSynchronousBatches: 100,
+  maxSynchronousWorkItems: 100,
+});
+
+export const FACTORY_EMULATOR_LIMIT_HARD_CAPS = Object.freeze({
+  maxCompletedDispatches: 100_000,
+  maxEvents: 1_000_000,
+  maxVirtualElapsedMs: 365 * 24 * 60 * 60 * 1_000,
+  maxZeroDurationBatches: 100_000,
+  maxSynchronousBatches: 10_000,
+  maxSynchronousWorkItems: 10_000,
+});
+
+const limitNames = Object.freeze(Object.keys(DEFAULT_FACTORY_EMULATOR_LIMITS));
+const minimumLimitValues = Object.freeze({
+  maxCompletedDispatches: 1,
+  // start always publishes INITIAL_STRUCTURE_REQUEST and RUN_REQUEST atomically.
+  maxEvents: 2,
+  maxVirtualElapsedMs: 1,
+  maxZeroDurationBatches: 1,
+  maxSynchronousBatches: 1,
+  maxSynchronousWorkItems: 1,
+});
+
+/** Normalizes caller policy without reading environment or process-global state. */
+export function normalizeFactoryEmulatorLimits(limits) {
+  if (limits === undefined) {
+    return { success: true, limits: { ...DEFAULT_FACTORY_EMULATOR_LIMITS } };
+  }
+  if (limits === null || typeof limits !== "object" || Array.isArray(limits)) {
+    return invalid("/limits", "must be an object containing positive integer limits");
+  }
+  const unknown = Object.keys(limits).find((name) => !limitNames.includes(name));
+  if (unknown !== undefined) {
+    return invalid(`/limits/${unknown}`, "is not a supported emulator limit");
+  }
+
+  const normalized = { ...DEFAULT_FACTORY_EMULATOR_LIMITS };
+  for (const name of limitNames) {
+    const value = limits[name];
+    if (value === undefined) {
+      continue;
+    }
+    if (!Number.isSafeInteger(value) || value < minimumLimitValues[name]) {
+      return invalid(
+        `/limits/${name}`,
+        `must be a safe integer no less than ${minimumLimitValues[name]}`,
+      );
+    }
+    if (value > FACTORY_EMULATOR_LIMIT_HARD_CAPS[name]) {
+      return invalid(
+        `/limits/${name}`,
+        `must not exceed the library hard cap ${FACTORY_EMULATOR_LIMIT_HARD_CAPS[name]}`,
+      );
+    }
+    normalized[name] = value;
+  }
+  return { success: true, limits: normalized };
+}
+
+export function budgetExceededDiagnostic({
+  configured,
+  limit,
+  observed,
+  virtualTime,
+  virtualElapsedMs,
+}) {
+  return {
+    kind: "budget-exceeded",
+    limit,
+    configured,
+    observed,
+    virtualTime,
+    virtualElapsedMs,
+  };
+}
+
+export function zeroDurationCycleDiagnostic({
+  configured,
+  observed,
+  virtualTime,
+  virtualElapsedMs,
+}) {
+  return {
+    kind: "zero-duration-cycle",
+    limit: "zeroDurationBatches",
+    configured,
+    observed,
+    virtualTime,
+    virtualElapsedMs,
+  };
+}
+
+export function synchronousWorkLimitDiagnostic({
+  configured,
+  observed,
+  virtualTime,
+  virtualElapsedMs,
+}) {
+  return {
+    kind: "synchronous-work-limit",
+    limit: "schedulerWorkItems",
+    configured,
+    observed,
+    virtualTime,
+    virtualElapsedMs,
+  };
+}
+
+function invalid(path, message) {
+  return {
+    success: false,
+    diagnostics: [{
+      code: "INVALID_LIMIT_CONFIGURATION",
+      path,
+      message,
+      expectation: "a supported safe integer within its documented minimum and hard cap",
+    }],
+  };
+}

package/src/parser.js

@@ -0,0 +1,113 @@
+import Ajv2020 from "ajv/dist/2020.js";
+import addFormats from "ajv-formats";
+import { scenarioSchema } from "./generated/scenario-schema.js";
+import { factorySchema } from "./generated/factory-schema.js";
+import { scenarioSemanticDiagnostics } from "./semantics.js";
+import { factorySupportDiagnostics } from "./support.js";
+import { dataOnlyDiagnostics } from "./data-only.js";
+
+const ajv = new Ajv2020({
+  allErrors: true,
+  coerceTypes: false,
+  removeAdditional: false,
+  strict: false,
+  useDefaults: false,
+});
+addFormats(ajv);
+ajv.addFormat("int32", true);
+ajv.addFormat("int64", true);
+const validateScenarioShape = ajv.compile(scenarioSchema);
+const validateFactoryShape = ajv.compile(factorySchema);
+
+/**
+ * Parses only data. It neither creates Factory events nor starts emulator
+ * activity, so callers can reject unsupported input before any runtime work.
+ */
+export function parseEmulatorScenario(scenario, factory) {
+  const scenarioDataDiagnostics = dataOnlyDiagnostics(scenario, {
+    code: "INVALID_SCENARIO_SHAPE",
+  });
+  if (scenarioDataDiagnostics.length > 0) {
+    return failure(scenarioDataDiagnostics);
+  }
+  if (!validateScenarioShape(scenario)) {
+    return failure(shapeDiagnostics(validateScenarioShape.errors ?? []));
+  }
+
+  const factoryDiagnostics = dataOnlyDiagnostics(factory, {
+    code: "INVALID_FACTORY_DEFINITION",
+  });
+  if (factoryDiagnostics.length === 0 && !validateFactoryShape(factory)) {
+    factoryDiagnostics.push(
+      ...shapeDiagnostics(
+        validateFactoryShape.errors ?? [],
+        "INVALID_FACTORY_DEFINITION",
+      ),
+    );
+  }
+  if (factoryDiagnostics.length === 0) {
+    factoryDiagnostics.push(...factorySupportDiagnostics(factory));
+  }
+  const diagnostics =
+    factoryDiagnostics.length === 0
+      ? scenarioSemanticDiagnostics(scenario, factory)
+      : factoryDiagnostics;
+  return diagnostics.length === 0
+    ? { success: true, scenario, factory }
+    : failure(diagnostics);
+}
+
+function failure(diagnostics) {
+  return { success: false, diagnostics: Object.freeze(diagnostics) };
+}
+
+function shapeDiagnostics(errors, defaultCode = "INVALID_SCENARIO_SHAPE") {
+  return errors
+    .map((error) => {
+      const path = errorPath(error);
+      return {
+        code:
+          error.keyword === "const" && path === "/version"
+            ? "UNSUPPORTED_SCENARIO_VERSION"
+            : defaultCode,
+        path,
+        message: `${path} ${error.message ?? "does not match the Emulator Scenario schema"}.`,
+        expectation: shapeExpectation(error),
+      };
+    })
+    .sort(compareDiagnostics);
+}
+
+function errorPath(error) {
+  const property =
+    error.keyword === "required"
+      ? error.params.missingProperty
+      : error.keyword === "additionalProperties"
+        ? error.params.additionalProperty
+        : undefined;
+  return typeof property === "string"
+    ? `${error.instancePath}/${escapeJsonPointer(property)}`
+    : error.instancePath || "/";
+}
+
+function shapeExpectation(error) {
+  if (error.keyword === "required") {
+    return `required property ${JSON.stringify(error.params.missingProperty)}`;
+  }
+  if (error.keyword === "additionalProperties") {
+    return `no additional property ${JSON.stringify(error.params.additionalProperty)}`;
+  }
+  return error.message ?? error.keyword;
+}
+
+function compareDiagnostics(left, right) {
+  return (
+    left.path.localeCompare(right.path) ||
+    left.code.localeCompare(right.code) ||
+    left.expectation.localeCompare(right.expectation)
+  );
+}
+
+function escapeJsonPointer(value) {
+  return value.replaceAll("~", "~0").replaceAll("/", "~1");
+}

package/src/parser.ts

@@ -0,0 +1,56 @@
+import type { EmulatorScenario } from "./generated/scenario.js";
+
+export type EmulatorScenarioDiagnosticCode =
+  | "INVALID_SCENARIO_SHAPE"
+  | "UNSUPPORTED_SCENARIO_VERSION"
+  | "INVALID_FACTORY_DEFINITION"
+  | "UNSUPPORTED_FACTORY_CAPABILITY"
+  | "DUPLICATE_SCENARIO_IDENTIFIER"
+  | "UNKNOWN_FACTORY_WORK_TYPE"
+  | "UNKNOWN_INITIAL_SUBMISSION"
+  | "MISSING_LINEAGE_CURSOR_TARGET"
+  | "FORWARD_LINEAGE_CURSOR"
+  | "CYCLIC_LINEAGE_CURSOR"
+  | "INCOMPATIBLE_LINEAGE_CURSOR"
+  | "SHADOWED_RULE";
+
+export interface EmulatorScenarioDiagnostic {
+  code: EmulatorScenarioDiagnosticCode;
+  path: string;
+  message: string;
+  expectation: string;
+}
+
+/** The executable Factory subset accepted by the v1 browser emulator. */
+export interface EmulatorFactoryDefinition {
+  [property: string]: unknown;
+  orchestrator?: { kind?: string; [property: string]: unknown };
+  resources?: unknown[];
+  guards?: unknown[];
+  workTypes?: Array<{ name?: string; [property: string]: unknown }>;
+  workstations?: Array<{
+    [property: string]: unknown;
+    behavior?: string;
+    cron?: unknown;
+    resources?: unknown[];
+    guards?: unknown[];
+    inputs?: Array<{ guards?: unknown[]; [property: string]: unknown }>;
+  }>;
+}
+
+export type EmulatorScenarioParseResult =
+  | {
+      success: true;
+      scenario: EmulatorScenario;
+      factory: EmulatorFactoryDefinition;
+    }
+  | { success: false; diagnostics: readonly EmulatorScenarioDiagnostic[] };
+
+/**
+ * Validates scenario structure and Factory execution support without creating
+ * Factory events or starting emulator activity.
+ */
+export declare function parseEmulatorScenario(
+  scenario: unknown,
+  factory: unknown,
+): EmulatorScenarioParseResult;