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

package/dist/session-contracts.d.ts

@@ -0,0 +1,262 @@
+import type { FactoryDefinition, FactoryEvent } from "@you-agent-factory/client";
+import type { FactoryEventSink } from "./event-sink.js";
+import type { FactoryEmulatorInitialSubmission, FactoryEmulatorScenario, FactoryEmulatorScenarioIssue, FactoryEmulatorSubmissionBatch } from "./scenario-contracts.js";
+export declare const DEFAULT_FACTORY_EMULATOR_LIMITS: Readonly<{
+    maxCompletedDispatches: 1000;
+    maxEvents: 10000;
+    maxVirtualElapsedMs: 3600000;
+    maxZeroDurationBatches: 1000;
+    maxSynchronousBatches: 100;
+    maxSynchronousWorkItems: 1000;
+}>;
+export declare const FACTORY_EMULATOR_LIMIT_HARD_CAPS: Readonly<{
+    maxCompletedDispatches: 100000;
+    maxEvents: 1000000;
+    maxVirtualElapsedMs: 86400000;
+    maxZeroDurationBatches: 10000;
+    maxSynchronousBatches: 10000;
+    maxSynchronousWorkItems: 100000;
+}>;
+export interface FactoryEmulatorLimits {
+    readonly maxCompletedDispatches?: number;
+    readonly maxEvents?: number;
+    readonly maxVirtualElapsedMs?: number;
+    readonly maxZeroDurationBatches?: number;
+    readonly maxSynchronousBatches?: number;
+    readonly maxSynchronousWorkItems?: number;
+}
+export type ResolvedFactoryEmulatorLimits = Readonly<Required<FactoryEmulatorLimits>>;
+export type FactoryEmulatorConfigurationDiagnostic = {
+    readonly code: "incompatible_factory" | "invalid_factory" | "invalid_limit" | "invalid_sink" | "invalid_yield_control";
+    readonly path: readonly (string | number)[];
+    readonly message: string;
+} | FactoryEmulatorScenarioIssue;
+export declare class FactoryEmulatorConfigurationError extends Error {
+    readonly code: "invalid_configuration";
+    readonly diagnostics: readonly FactoryEmulatorConfigurationDiagnostic[];
+    constructor(diagnostics: readonly FactoryEmulatorConfigurationDiagnostic[]);
+}
+export type FactoryEmulatorCommand = "start" | "submit" | "advanceBy" | "advanceToNext" | "close" | "reset";
+export declare class FactoryEmulatorLifecycleError extends Error {
+    readonly code: "invalid_lifecycle";
+    readonly command: FactoryEmulatorCommand;
+    readonly lifecycle: FactoryEmulatorSessionState["lifecycle"];
+    constructor(command: FactoryEmulatorCommand, lifecycle: FactoryEmulatorSessionState["lifecycle"]);
+}
+export declare class FactoryEmulatorPendingCommandError extends Error {
+    readonly code: "pending_transaction";
+    readonly attemptedCommand: FactoryEmulatorCommand;
+    readonly pendingCommand: FactoryEmulatorCommand;
+    constructor(attemptedCommand: FactoryEmulatorCommand, pendingCommand: FactoryEmulatorCommand);
+}
+export declare class FactoryEmulatorDurationError extends Error {
+    readonly code: "invalid_duration";
+    readonly durationMs: number;
+    constructor(durationMs: number);
+}
+export declare class FactoryEmulatorSubmissionError extends Error {
+    readonly code: "invalid_submission";
+    readonly diagnostics: readonly FactoryEmulatorScenarioIssue[];
+    constructor(diagnostics: readonly FactoryEmulatorScenarioIssue[]);
+}
+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: "bounded-work-exceeded";
+    readonly limit: "synchronousWorkItems";
+    readonly configured: number;
+    readonly observed: number;
+    readonly virtualTime: string;
+    readonly virtualElapsedMs: number;
+};
+export declare class FactoryEmulatorExecutionPausedError extends Error {
+    readonly code: "execution_paused";
+    readonly diagnostic: FactoryEmulatorExecutionDiagnostic;
+    constructor(diagnostic: FactoryEmulatorExecutionDiagnostic);
+}
+export interface FactoryEmulatorSessionOptions {
+    readonly factory: FactoryDefinition;
+    readonly scenario: FactoryEmulatorScenario;
+    readonly sink: FactoryEventSink;
+    readonly limits?: FactoryEmulatorLimits;
+    /** Host-owned cooperative boundary. The kernel never schedules browser timers. */
+    readonly yieldControl?: () => void | PromiseLike<void>;
+}
+export interface FactoryEmulatorSessionCounters {
+    readonly commands: number;
+    readonly events: number;
+    readonly completedDispatches: number;
+}
+export interface FactoryEmulatorNormalizedRelation {
+    readonly type: "DEPENDS_ON";
+    readonly sourceWorkName: string;
+    readonly targetWorkName: string;
+    readonly targetWorkId: string;
+    readonly requiredState: string;
+}
+export interface FactoryEmulatorSessionWork {
+    readonly submissionId: string;
+    readonly requestId: string;
+    readonly traceId: string;
+    /** Consumable token identity; routed fan-out tokens may share one Work ID. */
+    readonly tokenId: string;
+    readonly workId: string;
+    /** Stable root identity used by lineage-scoped scenario cursors. */
+    readonly rootWorkId: string;
+    /** Deterministic transition visit counts carried by this Work lineage. */
+    readonly visits: Readonly<Record<string, number>>;
+    readonly workType: string;
+    readonly state: string;
+    readonly input?: string;
+    readonly parent?: string;
+    /** Canonical outbound execution relationships for which this Work is blocked. */
+    readonly relations?: readonly FactoryEmulatorNormalizedRelation[];
+    /** Virtual instant when this Work entered its current queue. */
+    readonly queuedElapsedMs: number;
+    /** Earliest completed dispatch for this Work lineage, when initialized. */
+    readonly lastDispatchElapsedMs?: number;
+    readonly phase: "ready" | "waiting" | "active" | "completed";
+    readonly dispatch?: {
+        readonly dispatchId: string;
+        readonly completionId: string;
+        readonly transitionId: string;
+        readonly workstation: string;
+        readonly worker: string;
+        readonly startedElapsedMs: number;
+        readonly dueElapsedMs: number;
+        /** Stable declared-input order for every token consumed by this dispatch. */
+        readonly inputTokenIds: readonly string[];
+        /** Factory-scoped capacity held until this dispatch reaches an outcome. */
+        readonly resources: readonly {
+            readonly name: string;
+            readonly capacity: number;
+        }[];
+        readonly outcome: import("./scenario-contracts.js").FactoryEmulatorOutcome;
+    };
+}
+export type FactoryEmulatorSessionState = {
+    readonly lifecycle: "pre-start";
+    readonly virtualElapsedMs: 0;
+    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 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 interface FactoryEmulatorPendingTransactionStatus {
+    readonly command: FactoryEmulatorCommand;
+    readonly phase: "sink-write" | "sink-close";
+    readonly eventCount: number;
+}
+export type FactoryEmulatorSessionError = {
+    readonly code: "sink_write_rejected";
+    readonly operation: "write";
+    readonly command: FactoryEmulatorCommand;
+    readonly message: string;
+} | {
+    readonly code: "sink_close_rejected";
+    readonly operation: "close";
+    readonly command: FactoryEmulatorCommand;
+    readonly message: string;
+} | {
+    readonly code: "execution_paused";
+    readonly operation: "execute";
+    readonly command: FactoryEmulatorCommand;
+    readonly message: string;
+    readonly diagnostic: FactoryEmulatorExecutionDiagnostic;
+};
+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;
+}
+export interface FactoryEmulatorStartReceipt {
+    readonly status: "started";
+    readonly batches: readonly (readonly FactoryEvent[])[];
+    readonly state: Extract<FactoryEmulatorSessionState, {
+        lifecycle: "started";
+    }>;
+}
+export interface FactoryEmulatorSubmitReceipt {
+    readonly status: "submitted";
+    readonly batch: readonly FactoryEvent[];
+    readonly state: Extract<FactoryEmulatorSessionState, {
+        lifecycle: "started";
+    }>;
+}
+export interface FactoryEmulatorAdvanceReceipt {
+    readonly status: "advanced" | "idle";
+    readonly command: "advanceBy" | "advanceToNext";
+    readonly fromVirtualTime: string;
+    readonly virtualTime: string;
+    readonly virtualElapsedMs: number;
+    readonly batches: readonly (readonly FactoryEvent[])[];
+    readonly state: Extract<FactoryEmulatorSessionState, {
+        lifecycle: "started";
+    }>;
+}
+export interface FactoryEmulatorCloseReceipt {
+    readonly status: "closed";
+    readonly batch: readonly FactoryEvent[];
+    readonly state: Extract<FactoryEmulatorSessionState, {
+        lifecycle: "closed";
+    }>;
+}
+export interface FactoryEmulatorResetReceipt {
+    readonly status: "reset";
+    readonly state: Extract<FactoryEmulatorSessionState, {
+        lifecycle: "pre-start";
+    }>;
+}
+export interface FactoryEmulatorSession {
+    start(): Promise<FactoryEmulatorStartReceipt>;
+    submit(submissionOrBatch: FactoryEmulatorInitialSubmission | readonly FactoryEmulatorInitialSubmission[] | FactoryEmulatorSubmissionBatch): Promise<FactoryEmulatorSubmitReceipt>;
+    advanceBy(durationMs: number): Promise<FactoryEmulatorAdvanceReceipt>;
+    advanceToNext(): Promise<FactoryEmulatorAdvanceReceipt>;
+    close(): Promise<FactoryEmulatorCloseReceipt>;
+    reset(): FactoryEmulatorResetReceipt;
+    state(): FactoryEmulatorSessionState;
+    status(): FactoryEmulatorSessionStatus;
+}

package/dist/session-contracts.js

@@ -0,0 +1,74 @@
+export const DEFAULT_FACTORY_EMULATOR_LIMITS = Object.freeze({
+    maxCompletedDispatches: 1_000,
+    maxEvents: 10_000,
+    maxVirtualElapsedMs: 3_600_000,
+    maxZeroDurationBatches: 1_000,
+    maxSynchronousBatches: 100,
+    maxSynchronousWorkItems: 1_000,
+});
+export const FACTORY_EMULATOR_LIMIT_HARD_CAPS = Object.freeze({
+    maxCompletedDispatches: 100_000,
+    maxEvents: 1_000_000,
+    maxVirtualElapsedMs: 86_400_000,
+    maxZeroDurationBatches: 10_000,
+    maxSynchronousBatches: 10_000,
+    maxSynchronousWorkItems: 100_000,
+});
+export class FactoryEmulatorConfigurationError extends Error {
+    code = "invalid_configuration";
+    diagnostics;
+    constructor(diagnostics) {
+        super("Factory emulator session configuration is invalid.");
+        this.name = "FactoryEmulatorConfigurationError";
+        this.diagnostics = JSON.parse(JSON.stringify(diagnostics));
+    }
+}
+export class FactoryEmulatorLifecycleError extends Error {
+    code = "invalid_lifecycle";
+    command;
+    lifecycle;
+    constructor(command, lifecycle) {
+        super(`Cannot ${command} an emulator session in ${lifecycle} lifecycle.`);
+        this.name = "FactoryEmulatorLifecycleError";
+        this.command = command;
+        this.lifecycle = lifecycle;
+    }
+}
+export class FactoryEmulatorPendingCommandError extends Error {
+    code = "pending_transaction";
+    attemptedCommand;
+    pendingCommand;
+    constructor(attemptedCommand, pendingCommand) {
+        super(`Cannot ${attemptedCommand} while ${pendingCommand} is awaiting the event sink.`);
+        this.name = "FactoryEmulatorPendingCommandError";
+        this.attemptedCommand = attemptedCommand;
+        this.pendingCommand = pendingCommand;
+    }
+}
+export class FactoryEmulatorDurationError extends Error {
+    code = "invalid_duration";
+    durationMs;
+    constructor(durationMs) {
+        super("durationMs must be a non-negative safe integer.");
+        this.name = "FactoryEmulatorDurationError";
+        this.durationMs = durationMs;
+    }
+}
+export class FactoryEmulatorSubmissionError extends Error {
+    code = "invalid_submission";
+    diagnostics;
+    constructor(diagnostics) {
+        super("Factory emulator Work submission is invalid.");
+        this.name = "FactoryEmulatorSubmissionError";
+        this.diagnostics = JSON.parse(JSON.stringify(diagnostics));
+    }
+}
+export class FactoryEmulatorExecutionPausedError extends Error {
+    code = "execution_paused";
+    diagnostic;
+    constructor(diagnostic) {
+        super(`Factory emulator execution paused: ${diagnostic.kind}.`);
+        this.name = "FactoryEmulatorExecutionPausedError";
+        this.diagnostic = JSON.parse(JSON.stringify(diagnostic));
+    }
+}

package/dist/session.d.ts

@@ -0,0 +1,4 @@
+import { type FactoryEmulatorSession, type FactoryEmulatorSessionOptions } from "./session-contracts.js";
+export * from "./session-contracts.js";
+/** Creates one validated, caller-owned deterministic Factory emulator session. */
+export declare function createFactoryEmulatorSession(options: FactoryEmulatorSessionOptions): FactoryEmulatorSession;