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

package/src/session.ts

@@ -1,324 +0,0 @@
-import type { FactoryEventBatch, FactoryEventSink } from "./contracts.js";
-import type {
-  EmulatorInitialSubmission,
-  EmulatorOutcome,
-  EmulatorScenario,
-} from "./generated/scenario.js";
-import type {
-  EmulatorFactoryDefinition,
-  EmulatorScenarioDiagnostic,
-} from "./parser.js";
-
-export type FactoryEmulatorConfigurationDiagnostic =
-  | EmulatorScenarioDiagnostic
-  | {
-      readonly code: "INVALID_LIMIT_CONFIGURATION";
-      readonly path: string;
-      readonly message: string;
-      readonly expectation: string;
-    }
-  | {
-      readonly code: "SYNCHRONOUS_WORK_LIMIT_EXCEEDED";
-      readonly path: "/initialSubmissions";
-      readonly message: string;
-      readonly expectation: string;
-    };
-
-export interface FactoryEmulatorDataError {
-  readonly name: string;
-  readonly message: string;
-  readonly code: string;
-}
-
-export interface FactoryEmulatorConfigurationError extends FactoryEmulatorDataError {
-  readonly name: "FactoryEmulatorConfigurationError";
-  readonly code: "INVALID_CONFIGURATION";
-  readonly diagnostics: readonly FactoryEmulatorConfigurationDiagnostic[];
-}
-export declare const FactoryEmulatorConfigurationError: {
-  new (diagnostics: readonly FactoryEmulatorConfigurationDiagnostic[]): FactoryEmulatorConfigurationError;
-};
-
-export interface FactoryEmulatorLifecycleError extends FactoryEmulatorDataError {
-  readonly name: "FactoryEmulatorLifecycleError";
-  readonly code: "INVALID_LIFECYCLE";
-  readonly command: "start" | "submit" | "advanceBy" | "advanceToNext" | "close" | "reset";
-  readonly phase:
-    | FactoryEmulatorSessionState["lifecycle"]
-    | "starting"
-    | "submitting"
-    | "advancing"
-    | "closing";
-}
-export declare const FactoryEmulatorLifecycleError: {
-  new (
-    command: FactoryEmulatorLifecycleError["command"],
-    phase: FactoryEmulatorLifecycleError["phase"],
-  ): FactoryEmulatorLifecycleError;
-};
-
-export interface FactoryEmulatorDurationError extends FactoryEmulatorDataError {
-  readonly name: "FactoryEmulatorDurationError";
-  readonly code: "INVALID_DURATION";
-  readonly durationMs: number;
-}
-export declare const FactoryEmulatorDurationError: {
-  new (durationMs: number): FactoryEmulatorDurationError;
-};
-
-export interface FactoryEmulatorSubmissionError extends FactoryEmulatorDataError {
-  readonly name: "FactoryEmulatorSubmissionError";
-  readonly code: "INVALID_SUBMISSION";
-  readonly diagnostics: readonly EmulatorScenarioDiagnostic[];
-}
-export declare const FactoryEmulatorSubmissionError: {
-  new (diagnostics: readonly EmulatorScenarioDiagnostic[]): FactoryEmulatorSubmissionError;
-};
-
-export type FactoryEmulatorExecutionDiagnostic =
-  | {
-      readonly kind: "budget-exceeded";
-      readonly limit: "completedDispatches" | "events" | "virtualElapsedMs";
-      readonly configured: number;
-      readonly observed: number;
-      readonly virtualTime: string;
-      readonly virtualElapsedMs: number;
-    }
-  | {
-      readonly kind: "zero-duration-cycle";
-      readonly limit: "zeroDurationBatches";
-      readonly configured: number;
-      readonly observed: number;
-      readonly virtualTime: string;
-      readonly virtualElapsedMs: number;
-    }
-  | {
-      readonly kind: "synchronous-work-limit";
-      readonly limit: "schedulerWorkItems";
-      readonly configured: number;
-      readonly observed: number;
-      readonly virtualTime: string;
-      readonly virtualElapsedMs: number;
-    };
-
-export interface FactoryEmulatorExecutionPausedError extends FactoryEmulatorDataError {
-  readonly name: "FactoryEmulatorExecutionPausedError";
-  readonly code: "EXECUTION_PAUSED";
-  readonly diagnostic: FactoryEmulatorExecutionDiagnostic;
-}
-export declare const FactoryEmulatorExecutionPausedError: {
-  new (diagnostic: FactoryEmulatorExecutionDiagnostic): FactoryEmulatorExecutionPausedError;
-};
-
-export interface FactoryEmulatorLimits {
-  readonly maxCompletedDispatches?: number;
-  readonly maxEvents?: number;
-  readonly maxVirtualElapsedMs?: number;
-  readonly maxZeroDurationBatches?: number;
-  readonly maxSynchronousBatches?: number;
-  readonly maxSynchronousWorkItems?: number;
-}
-
-export declare const DEFAULT_FACTORY_EMULATOR_LIMITS: Readonly<Required<FactoryEmulatorLimits>>;
-export declare const FACTORY_EMULATOR_LIMIT_HARD_CAPS: Readonly<Required<FactoryEmulatorLimits>>;
-
-export interface FactoryEmulatorPendingCommandError extends FactoryEmulatorDataError {
-  readonly name: "FactoryEmulatorPendingCommandError";
-  readonly code: "PENDING_TRANSACTION";
-  readonly attemptedCommand:
-    | "start"
-    | "submit"
-    | "advanceBy"
-    | "advanceToNext"
-    | "close";
-  readonly pendingCommand:
-    | "start"
-    | "submit"
-    | "advanceBy"
-    | "advanceToNext"
-    | "close";
-}
-export declare const FactoryEmulatorPendingCommandError: {
-  new (
-    attemptedCommand: FactoryEmulatorPendingCommandError["attemptedCommand"],
-    pendingCommand: FactoryEmulatorPendingCommandError["pendingCommand"],
-  ): FactoryEmulatorPendingCommandError;
-};
-
-export type FactoryEmulatorCommandError =
-  | FactoryEmulatorConfigurationError
-  | FactoryEmulatorDurationError
-  | FactoryEmulatorExecutionPausedError
-  | FactoryEmulatorLifecycleError
-  | FactoryEmulatorPendingCommandError
-  | FactoryEmulatorSubmissionError;
-
-export interface FactoryEmulatorSessionOptions {
-  readonly factory: EmulatorFactoryDefinition;
-  readonly scenario: EmulatorScenario;
-  readonly sink: FactoryEventSink;
-  readonly limits?: FactoryEmulatorLimits;
-  /** Host-owned task boundary used after the configured synchronous cadence. */
-  readonly yieldControl?: () => void | PromiseLike<void>;
-}
-
-export interface FactoryEmulatorSessionWork {
-  readonly submissionId: string;
-  readonly requestId: string;
-  readonly traceId: string;
-  readonly workId: string;
-  readonly tokenId: string;
-  readonly workType: string;
-  readonly phase: "active" | "ready" | "waiting" | "completed";
-  readonly input?: Readonly<Record<string, unknown>>;
-  readonly output?: Readonly<Record<string, unknown>>;
-  readonly rejectionReason?: string;
-  readonly dispatch?: {
-    readonly dispatchId: string;
-    readonly completionId: string;
-    readonly lineageTokenId: string;
-    readonly outputTokenId: string;
-    readonly transitionId: string;
-    readonly startedElapsedMs: number;
-    readonly dueElapsedMs: number;
-    readonly outcome: EmulatorOutcome;
-  };
-}
-
-export interface FactoryEmulatorSessionCounters {
-  readonly commands: number;
-  readonly events: number;
-  readonly requests: number;
-  readonly works: number;
-  readonly dispatches: number;
-  readonly completions: number;
-}
-
-export type FactoryEmulatorSessionState =
-  | {
-      readonly lifecycle: "pre-start";
-      readonly virtualElapsedMs: 0;
-      readonly works: readonly [];
-      readonly ruleCursors: Readonly<Record<string, number>>;
-      readonly counters: FactoryEmulatorSessionCounters;
-    }
-  | {
-      readonly lifecycle: "started";
-      readonly sessionId: string;
-      readonly virtualTime: string;
-      readonly virtualElapsedMs: number;
-      readonly works: readonly FactoryEmulatorSessionWork[];
-      readonly ruleCursors: Readonly<Record<string, number>>;
-      readonly counters: FactoryEmulatorSessionCounters;
-    }
-  | {
-      readonly lifecycle: "closed";
-      readonly sessionId: string;
-      readonly virtualTime: string;
-      readonly virtualElapsedMs: number;
-      readonly works: readonly FactoryEmulatorSessionWork[];
-      readonly ruleCursors: Readonly<Record<string, number>>;
-      readonly counters: FactoryEmulatorSessionCounters;
-    };
-
-export interface FactoryEmulatorStartReceipt {
-  readonly status: "started";
-  readonly batches: readonly FactoryEventBatch[];
-  readonly state: Extract<FactoryEmulatorSessionState, { lifecycle: "started" }>;
-}
-
-export interface FactoryEmulatorResetReceipt {
-  readonly status: "reset";
-  readonly state: Extract<FactoryEmulatorSessionState, { lifecycle: "pre-start" }>;
-}
-
-export interface FactoryEmulatorSubmitReceipt {
-  readonly status: "submitted";
-  readonly batch: FactoryEventBatch;
-  readonly state: Extract<FactoryEmulatorSessionState, { lifecycle: "started" }>;
-}
-
-export interface FactoryEmulatorSessionAdvanceReceipt {
-  readonly status: "advanced" | "idle";
-  readonly command: "advanceBy" | "advanceToNext";
-  readonly fromVirtualTime: string;
-  readonly virtualTime: string;
-  readonly virtualElapsedMs: number;
-  readonly batches: readonly FactoryEventBatch[];
-  readonly state: Extract<FactoryEmulatorSessionState, { lifecycle: "started" }>;
-}
-
-export interface FactoryEmulatorSessionCloseReceipt {
-  readonly status: "closed";
-  readonly batch: FactoryEventBatch;
-  readonly state: Extract<FactoryEmulatorSessionState, { lifecycle: "closed" }>;
-}
-
-export interface FactoryEmulatorBudgetUsage {
-  readonly completedDispatches: {
-    readonly used: number;
-    readonly limit: number;
-  };
-  readonly events: {
-    readonly used: number;
-    readonly limit: number;
-  };
-  readonly virtualElapsedMs: {
-    readonly used: number;
-    readonly limit: number;
-  };
-}
-
-export type FactoryEmulatorSessionError =
-  | {
-      readonly code: "EXECUTION_PAUSED";
-      readonly diagnostic: FactoryEmulatorExecutionDiagnostic;
-    }
-  | {
-      readonly code: "SINK_WRITE_REJECTED" | "SINK_CLOSE_REJECTED";
-      readonly operation: "write" | "close";
-      readonly command: "start" | "submit" | "advanceBy" | "advanceToNext" | "close";
-      readonly message: string;
-    };
-
-export interface FactoryEmulatorPendingTransactionStatus {
-  readonly command: "start" | "submit" | "advanceBy" | "advanceToNext" | "close";
-  readonly phase: "sink-write" | "sink-close";
-  readonly eventCount: number;
-}
-
-export interface FactoryEmulatorSessionStatus {
-  readonly phase:
-    | "error"
-    | "closed"
-    | "active"
-    | "ready"
-    | "waiting"
-    | "idle";
-  readonly reason: string;
-  readonly virtualTime?: string;
-  readonly virtualElapsedMs: number;
-  readonly budgetUsage: FactoryEmulatorBudgetUsage;
-  readonly pendingTransaction?: FactoryEmulatorPendingTransactionStatus;
-  readonly error?: FactoryEmulatorSessionError;
-  readonly diagnostic?: FactoryEmulatorExecutionDiagnostic;
-}
-
-export interface FactoryEmulatorSession {
-  start(): Promise<FactoryEmulatorStartReceipt>;
-  submit(
-    submissionOrBatch: EmulatorInitialSubmission | readonly EmulatorInitialSubmission[],
-  ): Promise<FactoryEmulatorSubmitReceipt>;
-  advanceBy(durationMs: number): Promise<FactoryEmulatorSessionAdvanceReceipt>;
-  advanceToNext(): Promise<FactoryEmulatorSessionAdvanceReceipt>;
-  close(): Promise<FactoryEmulatorSessionCloseReceipt>;
-  reset(): FactoryEmulatorResetReceipt;
-  pending(): FactoryEventBatch | undefined;
-  state(): FactoryEmulatorSessionState;
-  status(): FactoryEmulatorSessionStatus;
-}
-
-/** Creates one validated, caller-owned deterministic Factory emulator session. */
-export declare function createFactoryEmulatorSession(
-  options: FactoryEmulatorSessionOptions,
-): FactoryEmulatorSession;

package/src/sinks.js

@@ -1,118 +0,0 @@
-const acceptedReceipt = Object.freeze({ status: "accepted" });
-const closedReceipt = Object.freeze({ status: "closed" });
-
-export class FactoryEventSinkClosedError extends Error {
-  constructor() {
-    super("Factory event sink is closed");
-    this.name = "FactoryEventSinkClosedError";
-  }
-}
-
-export class FactoryEventSinkCapacityError extends Error {
-  constructor(limit, attempted) {
-    super(
-      `Factory event sink capacity ${limit} cannot accept ${attempted} more event${attempted === 1 ? "" : "s"}`,
-    );
-    this.name = "FactoryEventSinkCapacityError";
-  }
-}
-
-export function createMemoryFactoryEventSink({ maxEvents }) {
-  assertPositiveInteger(maxEvents, "maxEvents");
-  const retainedBatches = [];
-  let retainedEventCount = 0;
-  let isClosed = false;
-
-  return Object.freeze({
-    maxEvents,
-    async write(batch) {
-      assertOpen(isClosed);
-      const copiedBatch = copyBatch(batch);
-      if (copiedBatch.events.length === 0) {
-        return acceptedReceipt;
-      }
-      if (copiedBatch.events.length > maxEvents) {
-        throw new FactoryEventSinkCapacityError(maxEvents, copiedBatch.events.length);
-      }
-      while (
-        retainedBatches.length > 0 &&
-        retainedEventCount + copiedBatch.events.length > maxEvents
-      ) {
-        retainedEventCount -= retainedBatches.shift().events.length;
-      }
-      retainedBatches.push(copiedBatch);
-      retainedEventCount += copiedBatch.events.length;
-      return acceptedReceipt;
-    },
-    async close() {
-      isClosed = true;
-      return closedReceipt;
-    },
-    batches() {
-      return copyBatches(retainedBatches);
-    },
-  });
-}
-
-export function createFactoryRecordingSink({ sessionId, maxEvents }) {
-  if (typeof sessionId !== "string" || sessionId.length === 0) {
-    throw new TypeError("sessionId must be a non-empty string");
-  }
-  assertPositiveInteger(maxEvents, "maxEvents");
-
-  const retainedEvents = [];
-  let isClosed = false;
-
-  return Object.freeze({
-    sessionId,
-    maxEvents,
-    async write(batch) {
-      assertOpen(isClosed);
-      const copiedBatch = copyBatch(batch);
-      assertRecordingSession(copiedBatch.events, sessionId);
-      const attemptedCount = retainedEvents.length + copiedBatch.events.length;
-      if (attemptedCount > maxEvents) {
-        throw new FactoryEventSinkCapacityError(maxEvents, copiedBatch.events.length);
-      }
-      retainedEvents.push(...copiedBatch.events);
-      return acceptedReceipt;
-    },
-    async close() {
-      isClosed = true;
-      return closedReceipt;
-    },
-    recording() {
-      return structuredClone({
-        schemaVersion: "agent-factory.recording.v1",
-        sessionId,
-        events: retainedEvents,
-      });
-    },
-  });
-}
-
-function assertPositiveInteger(value, name) {
-  if (!Number.isSafeInteger(value) || value < 1) {
-    throw new RangeError(`${name} must be a positive safe integer`);
-  }
-}
-
-function assertOpen(isClosed) {
-  if (isClosed) {
-    throw new FactoryEventSinkClosedError();
-  }
-}
-
-function assertRecordingSession(events, sessionId) {
-  if (events.some((event) => event.context.sessionId !== sessionId)) {
-    throw new TypeError("recording sink batch has an event for another session");
-  }
-}
-
-function copyBatch(batch) {
-  return structuredClone(batch);
-}
-
-function copyBatches(batches) {
-  return structuredClone(batches);
-}

package/src/sinks.ts

@@ -1,56 +0,0 @@
-import type { FactoryRecording } from "@you-agent-factory/client";
-
-import type {
-  FactoryEventBatch,
-  FactoryEventSink,
-} from "./contracts.js";
-
-/** Raised when a caller writes to a helper after it has closed. */
-export declare class FactoryEventSinkClosedError extends Error {}
-
-/** Raised when a batch cannot fit without exceeding a helper's declared bound. */
-export declare class FactoryEventSinkCapacityError extends Error {}
-
-/**
- * The maximum number of events a memory sink retains. Batches remain atomic:
- * an oversized batch is rejected and older complete batches are discarded
- * before a later accepted batch is retained.
- */
-export interface MemoryFactoryEventSinkOptions {
-  readonly maxEvents: number;
-}
-
-/**
- * A bounded in-memory sink. `batches` returns a detached snapshot, not the
- * values retained by the sink.
- */
-export interface MemoryFactoryEventSink extends FactoryEventSink {
-  readonly maxEvents: number;
-  batches(): readonly FactoryEventBatch[];
-}
-
-/** Creates a bounded, detached in-memory event sink. */
-export declare function createMemoryFactoryEventSink(
-  options: MemoryFactoryEventSinkOptions,
-): MemoryFactoryEventSink;
-
-/** The fixed metadata and capacity of one finite Factory recording. */
-export interface FactoryRecordingSinkOptions {
-  readonly sessionId: string;
-  readonly maxEvents: number;
-}
-
-/**
- * A bounded sink that produces one finite recording. `recording` returns a
- * detached snapshot and remains readable after close.
- */
-export interface FactoryRecordingSink extends FactoryEventSink {
-  readonly sessionId: string;
-  readonly maxEvents: number;
-  recording(): FactoryRecording;
-}
-
-/** Creates a bounded sink for one caller-owned Factory recording. */
-export declare function createFactoryRecordingSink(
-  options: FactoryRecordingSinkOptions,
-): FactoryRecordingSink;