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

package/dist/runtime-reference.js

@@ -0,0 +1,143 @@
+import { inspectFactoryEmulatorCompatibility } from "./compatibility.js";
+import { runtimeReferenceFixtures } from "./runtime-reference-fixtures.js";
+import { safeParseFactoryEmulatorScenario, } from "./scenario.js";
+export const FACTORY_EMULATOR_RUNTIME_REFERENCE_SCHEMA_VERSION = "factory-emulator-runtime-reference/v1";
+const factoryEventKinds = new Set([
+    "RUN_REQUEST",
+    "INITIAL_STRUCTURE_REQUEST",
+    "SESSION_STARTED",
+    "WORK_REQUEST",
+    "RELATIONSHIP_CHANGE_REQUEST",
+    "DISPATCH_REQUEST",
+    "DISPATCH_RESPONSE",
+    "WORK_STATE_CHANGE",
+    "SESSION_COMPLETED",
+]);
+function issue(issues, code, path, message) {
+    issues.push({ code, path, message });
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requiredString(value, path, issues) {
+    if (typeof value === "string" && value.trim().length > 0)
+        return true;
+    issue(issues, "missing_required_data", path, `Expected ${path.join(".")} to be a non-empty string.`);
+    return false;
+}
+/** Validates frozen, package-local evidence before a conformance comparison starts. */
+// biome-ignore lint/complexity/noExcessiveLinesPerFunction: The ordered validation passes deliberately retain every fixture diagnostic in one stable result.
+export function safeParseFactoryEmulatorRuntimeReference(input) {
+    const issues = [];
+    if (!isRecord(input)) {
+        issue(issues, "invalid_value", [], "Expected a runtime reference object.");
+        return { success: false, issues };
+    }
+    if (input.schemaVersion !== FACTORY_EMULATOR_RUNTIME_REFERENCE_SCHEMA_VERSION) {
+        issue(issues, "invalid_schema_version", ["schemaVersion"], "Unsupported runtime reference schema version.");
+    }
+    requiredString(input.id, ["id"], issues);
+    requiredString(input.title, ["title"], issues);
+    if (!isRecord(input.provenance)) {
+        issue(issues, "missing_required_data", ["provenance"], "Expected runtime-reference provenance.");
+    }
+    else {
+        requiredString(input.provenance.source, ["provenance", "source"], issues);
+        if (!["public-behavior", "public-documentation", "public-recording"].includes(input.provenance.kind)) {
+            issue(issues, "invalid_provenance", ["provenance", "kind"], "Expected public behavior, documentation, or recording provenance.");
+        }
+    }
+    if (!isRecord(input.factory) ||
+        !requiredString(input.factory.name, ["factory", "name"], issues)) {
+        issue(issues, "invalid_factory", ["factory"], "Expected a Factory definition with a name.");
+    }
+    if (!isRecord(input.scenario)) {
+        issue(issues, "missing_required_data", ["scenario"], "Expected a complete emulator scenario.");
+    }
+    else if (isRecord(input.factory)) {
+        const parsed = safeParseFactoryEmulatorScenario(input.scenario, input.factory);
+        if (!parsed.success) {
+            issue(issues, "invalid_value", ["scenario"], `Scenario is invalid: ${parsed.issues[0]?.message ?? "unknown error"}`);
+        }
+    }
+    const ticks = Array.isArray(input.ticks) ? input.ticks : [];
+    if (ticks.length === 0) {
+        issue(issues, "missing_required_data", ["ticks"], "Expected at least one logical-tick reference.");
+    }
+    const eventKinds = [];
+    for (const [index, tick] of ticks.entries()) {
+        const logicalTick = isRecord(tick) ? tick.logicalTick : undefined;
+        if (typeof logicalTick !== "number" ||
+            !Number.isSafeInteger(logicalTick) ||
+            logicalTick < 0) {
+            issue(issues, "invalid_tick_order", ["ticks", index, "logicalTick"], "Expected a non-negative integer logical tick.");
+        }
+        else if (logicalTick !== index) {
+            issue(issues, "invalid_tick_order", ["ticks", index, "logicalTick"], "Logical ticks must be contiguous and begin at zero.");
+        }
+        if (!isRecord(tick) || !Array.isArray(tick.eventKinds)) {
+            issue(issues, "missing_required_data", ["ticks", index, "eventKinds"], "Expected the ordered event kinds for this tick.");
+            continue;
+        }
+        if (!isRecord(tick.semantics)) {
+            issue(issues, "missing_semantics", ["ticks", index, "semantics"], "Expected normalized semantic evidence for this logical tick.");
+        }
+        else {
+            for (const surface of [
+                "dispatchChoices",
+                "consumedWork",
+                "outcomes",
+                "routes",
+                "terminalStates",
+                "replayProjection",
+            ]) {
+                if (!Array.isArray(tick.semantics[surface])) {
+                    issue(issues, "missing_semantics", ["ticks", index, "semantics", surface], `Expected ${surface} semantic evidence.`);
+                }
+            }
+        }
+        for (const [eventIndex, eventKind] of tick.eventKinds.entries()) {
+            if (!factoryEventKinds.has(eventKind)) {
+                issue(issues, "unexpected_event_kind", ["ticks", index, "eventKinds", eventIndex], `Unexpected Factory event kind ${String(eventKind)}.`);
+            }
+            else
+                eventKinds.push(eventKind);
+        }
+    }
+    if (!Array.isArray(input.orderedEventKinds)) {
+        issue(issues, "missing_required_data", ["orderedEventKinds"], "Expected the complete ordered event-kind sequence.");
+    }
+    else if (JSON.stringify(input.orderedEventKinds) !== JSON.stringify(eventKinds)) {
+        issue(issues, "invalid_value", ["orderedEventKinds"], "Ordered event kinds must exactly concatenate the logical-tick event kinds.");
+    }
+    if (issues.length > 0)
+        return { success: false, issues };
+    const reference = input;
+    const compatibility = inspectFactoryEmulatorCompatibility(reference.factory);
+    if (!compatibility.supported) {
+        return {
+            success: false,
+            issues: [
+                {
+                    code: "invalid_factory",
+                    path: ["factory"],
+                    message: compatibility.diagnostics[0]?.message ??
+                        "Factory is not supported by the emulator.",
+                },
+            ],
+        };
+    }
+    return {
+        success: true,
+        data: JSON.parse(JSON.stringify(reference)),
+    };
+}
+/** Returns detached validated fixtures in their frozen package declaration order. */
+export function loadFactoryEmulatorRuntimeReferences() {
+    return runtimeReferenceFixtures.map((fixture) => {
+        const parsed = safeParseFactoryEmulatorRuntimeReference(fixture);
+        if (!parsed.success)
+            throw new Error(`Invalid runtime reference ${String(fixture.id)}: ${parsed.issues.map(({ message }) => message).join(" ")}`);
+        return parsed.data;
+    });
+}

package/dist/scenario-contracts.d.ts

@@ -0,0 +1,81 @@
+export declare const FACTORY_EMULATOR_SCENARIO_SCHEMA_VERSION: "factory-emulator-scenario/v1";
+export interface FactoryEmulatorRuleSelector {
+    readonly workstation?: string;
+    readonly worker?: string;
+    readonly input?: {
+        readonly workType?: string;
+        readonly state?: string;
+        readonly name?: string;
+    };
+}
+export interface FactoryEmulatorOutcome {
+    readonly result: "accepted" | "continued" | "rejected" | "failed";
+    readonly durationMs: number;
+    readonly output?: string;
+    readonly feedback?: string;
+    readonly activityLabel?: string;
+    readonly error?: string;
+}
+export interface FactoryEmulatorRule {
+    readonly id: string;
+    readonly selector: FactoryEmulatorRuleSelector;
+    readonly cursor: {
+        readonly scope: "lineage";
+        readonly input: "rootWorkId";
+    };
+    readonly outcomes: readonly FactoryEmulatorOutcome[];
+    readonly exhaustion: "repeat-last" | "fail";
+}
+export interface FactoryEmulatorInitialSubmission {
+    readonly name: string;
+    readonly workType: string;
+    readonly state: string;
+    readonly input?: string;
+    readonly parent?: string;
+}
+export interface FactoryEmulatorSubmissionRelation {
+    readonly type: "DEPENDS_ON" | "PARENT_CHILD" | "SPAWNED_BY";
+    readonly sourceWorkName: string;
+    readonly targetWorkName: string;
+    readonly requiredState?: string;
+}
+export interface FactoryEmulatorSubmissionBatch {
+    readonly works: readonly FactoryEmulatorInitialSubmission[];
+    readonly relations?: readonly FactoryEmulatorSubmissionRelation[];
+}
+export type FactoryEmulatorInitialSubmissions = readonly FactoryEmulatorInitialSubmission[] | FactoryEmulatorSubmissionBatch;
+export interface FactoryEmulatorScenario {
+    readonly schemaVersion: typeof FACTORY_EMULATOR_SCENARIO_SCHEMA_VERSION;
+    readonly id: string;
+    readonly factory: {
+        readonly name: string;
+    };
+    readonly seed: string;
+    readonly startAt: string;
+    readonly rules: readonly FactoryEmulatorRule[];
+    readonly unmatched: {
+        readonly behavior: "error";
+    } | {
+        readonly behavior: "outcome";
+        readonly outcome: FactoryEmulatorOutcome;
+    };
+    readonly initialSubmissions?: FactoryEmulatorInitialSubmissions;
+}
+export type FactoryEmulatorScenarioIssueCode = "duplicate_identity" | "fully_shadowed_rule" | "invalid_cursor" | "invalid_exhaustion" | "invalid_factory_identity" | "invalid_initial_submission_relationship" | "invalid_outcome" | "invalid_selector_reference" | "invalid_start_at" | "invalid_type" | "invalid_unmatched" | "invalid_value" | "missing_required_field" | "unsupported_field" | "unsupported_schema_version" | "unstable_identity";
+export interface FactoryEmulatorScenarioIssue {
+    readonly category: "structure" | "semantic";
+    readonly code: FactoryEmulatorScenarioIssueCode;
+    readonly path: readonly (string | number)[];
+    readonly message: string;
+}
+export type SafeParseFactoryEmulatorScenarioResult = {
+    readonly success: true;
+    readonly data: FactoryEmulatorScenario;
+} | {
+    readonly success: false;
+    readonly issues: readonly FactoryEmulatorScenarioIssue[];
+};
+export declare class FactoryEmulatorScenarioValidationError extends Error {
+    readonly issues: readonly FactoryEmulatorScenarioIssue[];
+    constructor(issues: readonly FactoryEmulatorScenarioIssue[]);
+}

package/dist/scenario-contracts.js

@@ -0,0 +1,11 @@
+export const FACTORY_EMULATOR_SCENARIO_SCHEMA_VERSION = "factory-emulator-scenario/v1";
+export class FactoryEmulatorScenarioValidationError extends Error {
+    issues;
+    constructor(issues) {
+        super(issues.length === 1
+            ? `Factory emulator scenario validation failed: ${issues[0]?.message}`
+            : `Factory emulator scenario validation failed with ${issues.length} issues`);
+        this.name = "FactoryEmulatorScenarioValidationError";
+        this.issues = issues;
+    }
+}

package/dist/scenario.d.ts

@@ -0,0 +1,271 @@
+import type { FactoryDefinition } from "@you-agent-factory/client";
+import { type FactoryEmulatorScenario, type SafeParseFactoryEmulatorScenarioResult } from "./scenario-contracts.js";
+export * from "./scenario-contracts.js";
+export declare const scenarioSchema: {
+    $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;
+                    };
+                };
+            };
+        };
+    };
+};
+/** Validate an authored scenario without mutating it or the Factory context. */
+export declare function safeParseFactoryEmulatorScenario(input: unknown, factory: FactoryDefinition): SafeParseFactoryEmulatorScenarioResult;
+/** Parse a complete scenario or throw one error containing every diagnostic. */
+export declare function parseFactoryEmulatorScenario(input: unknown, factory: FactoryDefinition): FactoryEmulatorScenario;