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

package/dist/compatibility.d.ts

@@ -0,0 +1,19 @@
+import type { FactoryDefinition, FactoryEvent } from "@you-agent-factory/client";
+import type { FactoryEventSink } from "./event-sink.js";
+export type FactoryEmulatorCompatibilityIssueCode = "invalid_logical_move" | "invalid_route_reference" | "invalid_worker_reference" | "provider_global_resource" | "unresolved_resource_requirement" | "unsupported_classifier" | "unsupported_execution" | "unsupported_guard" | "unsupported_orchestrator" | "unsupported_relationship_behavior" | "unsupported_workstation_behavior";
+export interface FactoryEmulatorCompatibilityIssue {
+    readonly code: FactoryEmulatorCompatibilityIssueCode;
+    readonly path: readonly (string | number)[];
+    readonly message: string;
+}
+export type FactoryEmulatorCompatibilityResult = {
+    readonly supported: true;
+    readonly diagnostics: readonly [];
+} | {
+    readonly supported: false;
+    readonly diagnostics: readonly FactoryEmulatorCompatibilityIssue[];
+};
+/** Inspect the executable subset without mutating or retaining the Factory. */
+export declare function inspectFactoryEmulatorCompatibility(factory: FactoryDefinition): FactoryEmulatorCompatibilityResult;
+/** Write only after the complete compatibility preflight succeeds. */
+export declare function writeFactoryEventsIfCompatible(factory: FactoryDefinition, events: readonly FactoryEvent[], sink: FactoryEventSink): Promise<FactoryEmulatorCompatibilityResult>;

package/dist/compatibility.js

@@ -0,0 +1,156 @@
+function addIssue(diagnostics, code, path, message) {
+    diagnostics.push({ code, path, message });
+}
+function inspectRoutes(factory, workstationIndex, diagnostics) {
+    const workstation = factory.workstations?.[workstationIndex];
+    if (workstation === undefined)
+        return;
+    const workStates = new Map((factory.workTypes ?? []).map((workType) => [
+        workType.name,
+        new Set(workType.states.map((state) => state.name)),
+    ]));
+    const routeGroups = [
+        ["inputs", workstation.inputs],
+        ["outputs", workstation.outputs ?? []],
+        ["onContinue", workstation.onContinue ?? []],
+        ["onRejection", workstation.onRejection ?? []],
+        ["onFailure", workstation.onFailure ?? []],
+    ];
+    for (const [routeName, routes] of routeGroups) {
+        for (const [routeIndex, route] of routes.entries()) {
+            const path = [
+                "workstations",
+                workstationIndex,
+                routeName,
+                routeIndex,
+            ];
+            const states = workStates.get(route.workType);
+            if (states === undefined) {
+                addIssue(diagnostics, "invalid_route_reference", [...path, "workType"], `Work type ${route.workType} is not declared by the Factory.`);
+            }
+            else if (!states.has(route.state)) {
+                addIssue(diagnostics, "invalid_route_reference", [...path, "state"], `State ${route.state} is not declared by Work type ${route.workType}.`);
+            }
+            for (const [guardIndex, guard] of (route.guards ?? []).entries()) {
+                const guardPath = [...path, "guards", guardIndex];
+                const relationshipAware = guard.parentInput !== undefined ||
+                    guard.matchInput !== undefined ||
+                    guard.spawnedBy !== undefined ||
+                    guard.type !== "VISIT_COUNT";
+                addIssue(diagnostics, relationshipAware
+                    ? "unsupported_relationship_behavior"
+                    : "unsupported_guard", guardPath, relationshipAware
+                    ? "Parent-aware, peer-aware, and runtime-spawn-aware input behavior is not supported by emulator v1."
+                    : "Input guards are not supported by emulator v1.");
+            }
+        }
+    }
+}
+function inspectWorkstation(factory, workstationIndex, diagnostics) {
+    const workstation = factory.workstations?.[workstationIndex];
+    if (workstation === undefined)
+        return;
+    const path = ["workstations", workstationIndex];
+    const behavior = workstation.behavior ?? "STANDARD";
+    const type = workstation.type;
+    if (behavior !== "STANDARD" && behavior !== "REPEATER") {
+        addIssue(diagnostics, "unsupported_workstation_behavior", [...path, "behavior"], `Workstation behavior ${behavior} is not supported by emulator v1.`);
+    }
+    if (type === "CLASSIFIER_WORKSTATION" ||
+        workstation.classificationRoutes !== undefined ||
+        workstation.outcomeFormat !== undefined) {
+        addIssue(diagnostics, "unsupported_classifier", [
+            ...path,
+            type === "CLASSIFIER_WORKSTATION"
+                ? "type"
+                : workstation.classificationRoutes !== undefined
+                    ? "classificationRoutes"
+                    : "outcomeFormat",
+        ], "Classifier routing and classifier output contracts are not supported by emulator v1.");
+    }
+    else if (type !== "AGENT_RUN" && type !== "LOGICAL_MOVE") {
+        addIssue(diagnostics, "unsupported_execution", [...path, "type"], `Workstation execution ${type ?? "omitted"} is not supported by emulator v1.`);
+    }
+    const workerNames = new Set((factory.workers ?? []).map((worker) => worker.name));
+    if (type === "LOGICAL_MOVE") {
+        if (workstation.worker !== "") {
+            addIssue(diagnostics, "invalid_logical_move", [...path, "worker"], "A LOGICAL_MOVE must be workerless.");
+        }
+        const guards = workstation.guards ?? [];
+        if (guards.length === 0) {
+            addIssue(diagnostics, "invalid_logical_move", [...path, "guards"], "A LOGICAL_MOVE requires at least one VISIT_COUNT guard.");
+        }
+        for (const [guardIndex, guard] of guards.entries()) {
+            const guardPath = [...path, "guards", guardIndex];
+            if (guard.type !== "VISIT_COUNT" ||
+                guard.parentInput !== undefined ||
+                guard.matchInput !== undefined ||
+                guard.spawnedBy !== undefined) {
+                addIssue(diagnostics, "unsupported_guard", guardPath, "LOGICAL_MOVE supports only VISIT_COUNT guards in emulator v1.");
+            }
+            else if (guard.workstation === undefined ||
+                !new Set(factory.workstations?.map((item) => item.name)).has(guard.workstation) ||
+                guard.maxVisits === undefined ||
+                !Number.isInteger(guard.maxVisits) ||
+                guard.maxVisits < 1) {
+                addIssue(diagnostics, "invalid_logical_move", guardPath, "VISIT_COUNT requires a declared workstation and a positive integer maxVisits.");
+            }
+        }
+    }
+    else if (type === "AGENT_RUN") {
+        if (workstation.worker === "" || !workerNames.has(workstation.worker)) {
+            addIssue(diagnostics, "invalid_worker_reference", [...path, "worker"], `Worker ${workstation.worker || "<empty>"} is not declared by the Factory.`);
+        }
+        else {
+            const worker = factory.workers?.find((candidate) => candidate.name === workstation.worker);
+            if (worker?.type !== undefined && worker.type !== "AGENT_WORKER") {
+                addIssue(diagnostics, "unsupported_execution", ["workers", factory.workers?.indexOf(worker) ?? -1, "type"], `Worker execution ${worker.type} is not supported for AGENT_RUN emulator workstations.`);
+            }
+        }
+        for (const [guardIndex] of (workstation.guards ?? []).entries()) {
+            addIssue(diagnostics, "unsupported_guard", [...path, "guards", guardIndex], "AGENT_RUN workstation guards are not supported by emulator v1.");
+        }
+    }
+    else {
+        for (const [guardIndex] of (workstation.guards ?? []).entries()) {
+            addIssue(diagnostics, "unsupported_guard", [...path, "guards", guardIndex], "Workstation guards on unsupported execution types are not supported by emulator v1.");
+        }
+    }
+    const declaredResources = new Set((factory.resources ?? []).map((resource) => resource.name));
+    for (const [resourceIndex, requirement] of (workstation.resources ?? []).entries()) {
+        if (!declaredResources.has(requirement.name)) {
+            addIssue(diagnostics, "unresolved_resource_requirement", [...path, "resources", resourceIndex, "name"], `Resource ${requirement.name} is not declared at Factory scope.`);
+        }
+    }
+    inspectRoutes(factory, workstationIndex, diagnostics);
+}
+/** Inspect the executable subset without mutating or retaining the Factory. */
+export function inspectFactoryEmulatorCompatibility(factory) {
+    const diagnostics = [];
+    if (factory.orchestrator !== undefined &&
+        factory.orchestrator.kind !== "PETRI") {
+        addIssue(diagnostics, "unsupported_orchestrator", ["orchestrator", "kind"], `Orchestrator ${factory.orchestrator.kind} is not supported by emulator v1.`);
+    }
+    for (const [guardIndex] of (factory.guards ?? []).entries()) {
+        addIssue(diagnostics, "unsupported_guard", ["guards", guardIndex], "Factory-level guards are not supported by emulator v1.");
+    }
+    for (const [resourceIndex, resource] of (factory.resources ?? []).entries()) {
+        if (resource.type === "PROVIDER_QUOTA" || resource.provider !== undefined) {
+            addIssue(diagnostics, "provider_global_resource", ["resources", resourceIndex], `Resource ${resource.name} depends on provider-global capacity.`);
+        }
+    }
+    for (const workstationIndex of (factory.workstations ?? []).keys()) {
+        inspectWorkstation(factory, workstationIndex, diagnostics);
+    }
+    return diagnostics.length === 0
+        ? { supported: true, diagnostics: [] }
+        : { supported: false, diagnostics };
+}
+/** Write only after the complete compatibility preflight succeeds. */
+export async function writeFactoryEventsIfCompatible(factory, events, sink) {
+    const result = inspectFactoryEmulatorCompatibility(factory);
+    if (!result.supported)
+        return result;
+    await sink.write(events);
+    return result;
+}

package/dist/event-sink.d.ts

@@ -0,0 +1,29 @@
+import type { FactoryEvent } from "@you-agent-factory/client";
+export type FactoryEventSinkErrorCode = "capacity_exceeded" | "closed" | "duplicate_event_id" | "empty_batch" | "invalid_capacity" | "invalid_event_order" | "invalid_recording" | "mixed_factory_identity" | "mixed_session_identity";
+export declare class FactoryEventSinkError extends Error {
+    readonly code: FactoryEventSinkErrorCode;
+    constructor(code: FactoryEventSinkErrorCode, message: string);
+}
+/** Caller-owned destination for one ordered, atomic Factory Event batch. */
+export interface FactoryEventSink {
+    write(events: readonly FactoryEvent[]): Promise<void>;
+    /** Optional lifecycle boundary used when an emulator session closes. */
+    close?(): Promise<void>;
+}
+export interface MemoryFactoryEventSinkOptions {
+    /** Maximum number of events retained. A batch that crosses this bound fails whole. */
+    readonly maxEvents: number;
+    /** Optional asynchronous boundary for backpressure or caller-controlled failure injection. */
+    readonly beforeWrite?: (events: readonly FactoryEvent[]) => Promise<void>;
+}
+/**
+ * Bounded, caller-owned event history. Concurrent writes are processed in call
+ * order, and one rejected write does not prevent a later write or retry.
+ */
+export declare class MemoryFactoryEventSink implements FactoryEventSink {
+    #private;
+    constructor(options: MemoryFactoryEventSinkOptions);
+    write(events: readonly FactoryEvent[]): Promise<void>;
+    snapshot(): readonly FactoryEvent[];
+    close(): Promise<void>;
+}

package/dist/event-sink.js

@@ -0,0 +1,58 @@
+export class FactoryEventSinkError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "FactoryEventSinkError";
+        this.code = code;
+    }
+}
+function cloneEvents(events) {
+    return JSON.parse(JSON.stringify(events));
+}
+/**
+ * Bounded, caller-owned event history. Concurrent writes are processed in call
+ * order, and one rejected write does not prevent a later write or retry.
+ */
+export class MemoryFactoryEventSink {
+    #maxEvents;
+    #beforeWrite;
+    #events = [];
+    #acceptingWrites = true;
+    #tail = Promise.resolve();
+    #closePromise;
+    constructor(options) {
+        if (!Number.isSafeInteger(options.maxEvents) || options.maxEvents < 1) {
+            throw new FactoryEventSinkError("invalid_capacity", "Memory sink maxEvents must be a positive safe integer.");
+        }
+        this.#maxEvents = options.maxEvents;
+        this.#beforeWrite = options.beforeWrite;
+    }
+    write(events) {
+        if (!this.#acceptingWrites) {
+            return Promise.reject(new FactoryEventSinkError("closed", "The event sink is closed."));
+        }
+        if (events.length === 0) {
+            return Promise.reject(new FactoryEventSinkError("empty_batch", "Factory Event batches must be non-empty."));
+        }
+        const proposedBatch = cloneEvents(events);
+        const write = this.#tail.then(async () => {
+            await this.#beforeWrite?.(cloneEvents(proposedBatch));
+            if (this.#events.length + proposedBatch.length > this.#maxEvents) {
+                throw new FactoryEventSinkError("capacity_exceeded", `The batch would exceed the configured ${this.#maxEvents}-event capacity.`);
+            }
+            this.#events = [...this.#events, ...proposedBatch];
+        });
+        this.#tail = write.catch(() => undefined);
+        return write;
+    }
+    snapshot() {
+        return cloneEvents(this.#events);
+    }
+    close() {
+        if (this.#closePromise !== undefined)
+            return this.#closePromise;
+        this.#acceptingWrites = false;
+        this.#closePromise = this.#tail;
+        return this.#closePromise;
+    }
+}

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

@@ -0,0 +1,268 @@
+/**
+ * Generated by scripts/generate-scenario-schema.mjs from
+ * schema/scenario.schema.json. Do not edit this file directly.
+ */
+export declare const generatedScenarioSchema: {
+    $schema: string;
+    $id: string;
+    title: string;
+    type: string;
+    additionalProperties: boolean;
+    required: string[];
+    properties: {
+        schemaVersion: {
+            const: string;
+        };
+        id: {
+            $ref: string;
+        };
+        factory: {
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                name: {
+                    $ref: string;
+                };
+            };
+        };
+        seed: {
+            type: string;
+            minLength: number;
+            maxLength: number;
+        };
+        startAt: {
+            type: string;
+            format: string;
+            pattern: string;
+        };
+        rules: {
+            type: string;
+            items: {
+                $ref: string;
+            };
+        };
+        unmatched: {
+            $ref: string;
+        };
+        initialSubmissions: {
+            oneOf: ({
+                type: string;
+                items: {
+                    $ref: string;
+                };
+                $ref?: undefined;
+            } | {
+                $ref: string;
+                type?: undefined;
+                items?: undefined;
+            })[];
+        };
+    };
+    $defs: {
+        stableIdentity: {
+            type: string;
+            minLength: number;
+            maxLength: number;
+            pattern: string;
+        };
+        nonEmptyText128: {
+            type: string;
+            minLength: number;
+            maxLength: number;
+        };
+        plainText: {
+            type: string;
+            maxLength: number;
+        };
+        feedbackText: {
+            type: string;
+            maxLength: number;
+        };
+        activityLabel: {
+            type: string;
+            minLength: number;
+            maxLength: number;
+        };
+        inputSelector: {
+            type: string;
+            additionalProperties: boolean;
+            properties: {
+                workType: {
+                    $ref: string;
+                };
+                state: {
+                    $ref: string;
+                };
+                name: {
+                    $ref: string;
+                };
+            };
+        };
+        selector: {
+            type: string;
+            additionalProperties: boolean;
+            properties: {
+                workstation: {
+                    $ref: string;
+                };
+                worker: {
+                    $ref: string;
+                };
+                input: {
+                    $ref: string;
+                };
+            };
+        };
+        cursor: {
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                scope: {
+                    const: string;
+                };
+                input: {
+                    const: string;
+                };
+            };
+        };
+        outcome: {
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                result: {
+                    enum: string[];
+                };
+                durationMs: {
+                    type: string;
+                    minimum: number;
+                };
+                output: {
+                    $ref: string;
+                };
+                feedback: {
+                    $ref: string;
+                };
+                activityLabel: {
+                    $ref: string;
+                };
+                error: {
+                    $ref: string;
+                };
+            };
+        };
+        rule: {
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                id: {
+                    $ref: string;
+                };
+                selector: {
+                    $ref: string;
+                };
+                cursor: {
+                    $ref: string;
+                };
+                outcomes: {
+                    type: string;
+                    minItems: number;
+                    items: {
+                        $ref: string;
+                    };
+                };
+                exhaustion: {
+                    enum: string[];
+                };
+            };
+        };
+        unmatched: {
+            oneOf: ({
+                type: string;
+                additionalProperties: boolean;
+                required: string[];
+                properties: {
+                    behavior: {
+                        const: string;
+                    };
+                    outcome?: undefined;
+                };
+            } | {
+                type: string;
+                additionalProperties: boolean;
+                required: string[];
+                properties: {
+                    behavior: {
+                        const: string;
+                    };
+                    outcome: {
+                        $ref: string;
+                    };
+                };
+            })[];
+        };
+        initialSubmission: {
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                name: {
+                    $ref: string;
+                };
+                workType: {
+                    $ref: string;
+                };
+                state: {
+                    $ref: string;
+                };
+                input: {
+                    $ref: string;
+                };
+                parent: {
+                    $ref: string;
+                };
+            };
+        };
+        submissionRelation: {
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                type: {
+                    enum: string[];
+                };
+                sourceWorkName: {
+                    $ref: string;
+                };
+                targetWorkName: {
+                    $ref: string;
+                };
+                requiredState: {
+                    $ref: string;
+                };
+            };
+        };
+        submissionBatch: {
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                works: {
+                    type: string;
+                    items: {
+                        $ref: string;
+                    };
+                };
+                relations: {
+                    type: string;
+                    items: {
+                        $ref: string;
+                    };
+                };
+            };
+        };
+    };
+};