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

package/dist/scenario.js

@@ -0,0 +1,333 @@
+import Ajv2020, {} from "ajv/dist/2020.js";
+import addFormats from "ajv-formats";
+import { generatedScenarioSchema } from "./generated/scenario-schema.js";
+import { FactoryEmulatorScenarioValidationError, } from "./scenario-contracts.js";
+import { validateDependencyRelationships } from "./submission-validation.js";
+export * from "./scenario-contracts.js";
+export const scenarioSchema = generatedScenarioSchema;
+const ajv = new Ajv2020({
+    allErrors: true,
+    coerceTypes: false,
+    removeAdditional: false,
+    strict: false,
+    useDefaults: false,
+});
+addFormats(ajv);
+const validateScenarioShape = ajv.compile(generatedScenarioSchema);
+function pointerSegments(pointer) {
+    if (pointer.length === 0)
+        return [];
+    return pointer
+        .slice(1)
+        .split("/")
+        .map((segment) => segment.replaceAll("~1", "/").replaceAll("~0", "~"))
+        .map((segment) => /^(0|[1-9]\d*)$/.test(segment) ? Number(segment) : segment);
+}
+function errorPath(error) {
+    const path = pointerSegments(error.instancePath);
+    if (error.keyword === "required") {
+        return [...path, error.params.missingProperty];
+    }
+    if (error.keyword === "additionalProperties") {
+        return [...path, error.params.additionalProperty];
+    }
+    return path;
+}
+function structuralIssueCode(error, path) {
+    if (error.keyword === "required")
+        return "missing_required_field";
+    if (error.keyword === "additionalProperties")
+        return "unsupported_field";
+    if (error.keyword === "type")
+        return "invalid_type";
+    if (path.join(".") === "schemaVersion")
+        return "unsupported_schema_version";
+    if (path.join(".") === "startAt")
+        return "invalid_start_at";
+    if (error.keyword === "pattern" &&
+        ["id", "name"].includes(String(path.at(-1)))) {
+        return "unstable_identity";
+    }
+    if (path.includes("cursor"))
+        return "invalid_cursor";
+    if (path.at(-1) === "exhaustion")
+        return "invalid_exhaustion";
+    if (path.includes("unmatched"))
+        return "invalid_unmatched";
+    if (path.includes("outcomes") || path.at(-1) === "outcome") {
+        return "invalid_outcome";
+    }
+    return "invalid_value";
+}
+function structuralIssues(errors) {
+    const results = [];
+    const seen = new Set();
+    for (const error of errors ?? []) {
+        if (error.keyword === "oneOf")
+            continue;
+        const path = errorPath(error);
+        const code = structuralIssueCode(error, path);
+        const field = path.at(-1);
+        const message = error.keyword === "required"
+            ? `Expected required field ${String(field)}.`
+            : error.keyword === "additionalProperties"
+                ? `Unsupported field ${String(field)}.`
+                : `Expected ${path.join(".") || "scenario"} to satisfy the scenario contract: ${error.message ?? error.keyword}.`;
+        const key = `${code}:${path.join(".")}:${message}`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            results.push({ category: "structure", code, path, message });
+        }
+    }
+    return results;
+}
+function addDuplicateIssues(values, pathForIndex, label, issues) {
+    const indexesByValue = new Map();
+    for (const [index, value] of values.entries()) {
+        const indexes = indexesByValue.get(value) ?? [];
+        indexes.push(index);
+        indexesByValue.set(value, indexes);
+    }
+    for (const [value, indexes] of indexesByValue) {
+        if (indexes.length < 2)
+            continue;
+        for (const index of indexes) {
+            issues.push({
+                category: "semantic",
+                code: "duplicate_identity",
+                path: pathForIndex(index),
+                message: `${label} identity ${value} is duplicated at indexes ${indexes.join(", ")}.`,
+            });
+        }
+    }
+}
+function isNormalizedUtcTimestamp(value) {
+    const timestamp = Date.parse(value);
+    return (Number.isFinite(timestamp) && new Date(timestamp).toISOString() === value);
+}
+function selectorCovers(earlier, later) {
+    const earlierValues = [
+        earlier.workstation,
+        earlier.worker,
+        earlier.input?.workType,
+        earlier.input?.state,
+        earlier.input?.name,
+    ];
+    const laterValues = [
+        later.workstation,
+        later.worker,
+        later.input?.workType,
+        later.input?.state,
+        later.input?.name,
+    ];
+    return earlierValues.every((value, index) => value === undefined || value === laterValues[index]);
+}
+function validateOutcome(outcome, path, issues) {
+    if (!Number.isFinite(outcome.durationMs) || outcome.durationMs < 0) {
+        issues.push({
+            category: "semantic",
+            code: "invalid_outcome",
+            path: [...path, "durationMs"],
+            message: "Outcome durationMs must be a non-negative finite number.",
+        });
+    }
+    const hasError = outcome.error !== undefined;
+    if (outcome.result === "failed" ? !hasError : hasError) {
+        issues.push({
+            category: "semantic",
+            code: "invalid_outcome",
+            path: [...path, "error"],
+            message: outcome.result === "failed"
+                ? "A failed outcome requires an error."
+                : `An ${outcome.result} outcome must not declare an error.`,
+        });
+    }
+}
+function validateSelectorReferences(scenario, factory, issues) {
+    const workstationByName = new Map((factory.workstations ?? []).map((workstation) => [
+        workstation.name,
+        workstation,
+    ]));
+    const workerNames = new Set((factory.workers ?? []).map((worker) => worker.name));
+    const workTypes = new Map((factory.workTypes ?? []).map((workType) => [
+        workType.name,
+        new Set(workType.states.map((state) => state.name)),
+    ]));
+    for (const [index, rule] of scenario.rules.entries()) {
+        const path = ["rules", index, "selector"];
+        const workstation = rule.selector.workstation;
+        const worker = rule.selector.worker;
+        const workType = rule.selector.input?.workType;
+        const state = rule.selector.input?.state;
+        if (workstation !== undefined && !workstationByName.has(workstation)) {
+            issues.push(referenceIssue([...path, "workstation"], "workstation", workstation));
+        }
+        if (worker !== undefined && !workerNames.has(worker)) {
+            issues.push(referenceIssue([...path, "worker"], "worker", worker));
+        }
+        if (workstation !== undefined &&
+            worker !== undefined &&
+            workstationByName.get(workstation)?.worker !== worker) {
+            issues.push({
+                category: "semantic",
+                code: "invalid_selector_reference",
+                path: [...path, "worker"],
+                message: `Worker ${worker} is not assigned to workstation ${workstation}.`,
+            });
+        }
+        if (workType !== undefined && !workTypes.has(workType)) {
+            issues.push(referenceIssue([...path, "input", "workType"], "Work type", workType));
+        }
+        if (state !== undefined && workType === undefined) {
+            issues.push({
+                category: "semantic",
+                code: "invalid_selector_reference",
+                path: [...path, "input", "state"],
+                message: "A selector state requires an input Work type.",
+            });
+        }
+        else if (state !== undefined &&
+            !workTypes.get(workType ?? "")?.has(state)) {
+            issues.push(referenceIssue([...path, "input", "state"], "Work state", state));
+        }
+    }
+    const submissions = submissionWorks(scenario.initialSubmissions);
+    const workPathPrefix = scenario.initialSubmissions !== undefined &&
+        isSubmissionArray(scenario.initialSubmissions)
+        ? ["initialSubmissions"]
+        : ["initialSubmissions", "works"];
+    for (const [index, submission] of submissions.entries()) {
+        const path = [...workPathPrefix, index];
+        if (!workTypes.has(submission.workType)) {
+            issues.push(referenceIssue([...path, "workType"], "Work type", submission.workType));
+        }
+        else if (!workTypes.get(submission.workType)?.has(submission.state)) {
+            issues.push(referenceIssue([...path, "state"], "Work state", submission.state));
+        }
+    }
+}
+function submissionWorks(value) {
+    if (value === undefined)
+        return [];
+    return isSubmissionArray(value) ? value : value.works;
+}
+function isSubmissionArray(value) {
+    return Array.isArray(value);
+}
+function referenceIssue(path, label, value) {
+    return {
+        category: "semantic",
+        code: "invalid_selector_reference",
+        path,
+        message: `${label} ${value} is not declared by the Factory.`,
+    };
+}
+function validateSubmissionRelationships(submissions, pathPrefix, issues) {
+    const names = new Set(submissions.map((submission) => submission.name));
+    const parentByName = new Map(submissions
+        .filter((submission) => submission.parent !== undefined)
+        .map((submission) => [submission.name, submission.parent]));
+    for (const [index, submission] of submissions.entries()) {
+        if (submission.parent === undefined)
+            continue;
+        if (!names.has(submission.parent)) {
+            issues.push(relationshipIssue(pathPrefix, index, `Parent ${submission.parent} is not in this submission batch.`));
+            continue;
+        }
+        const visited = new Set([submission.name]);
+        let parent = submission.parent;
+        while (parent !== undefined) {
+            if (visited.has(parent)) {
+                issues.push(relationshipIssue(pathPrefix, index, "Initial submission parent relationships must be acyclic."));
+                break;
+            }
+            visited.add(parent);
+            parent = parentByName.get(parent);
+        }
+    }
+}
+function relationshipIssue(pathPrefix, index, message) {
+    return {
+        category: "semantic",
+        code: "invalid_initial_submission_relationship",
+        path: [...pathPrefix, index, "parent"],
+        message,
+    };
+}
+function semanticIssues(scenario, factory) {
+    const issues = [];
+    if (scenario.factory.name !== factory.name) {
+        issues.push({
+            category: "semantic",
+            code: "invalid_factory_identity",
+            path: ["factory", "name"],
+            message: `Scenario Factory ${scenario.factory.name} does not match ${factory.name}.`,
+        });
+    }
+    if (!isNormalizedUtcTimestamp(scenario.startAt)) {
+        issues.push({
+            category: "semantic",
+            code: "invalid_start_at",
+            path: ["startAt"],
+            message: "startAt must be a normalized UTC RFC 3339 timestamp with millisecond precision.",
+        });
+    }
+    addDuplicateIssues(scenario.rules.map((rule) => rule.id), (index) => ["rules", index, "id"], "Rule", issues);
+    const submissions = submissionWorks(scenario.initialSubmissions);
+    const submissionPathPrefix = scenario.initialSubmissions !== undefined &&
+        isSubmissionArray(scenario.initialSubmissions)
+        ? ["initialSubmissions"]
+        : ["initialSubmissions", "works"];
+    addDuplicateIssues(submissions.map((submission) => submission.name), (index) => [...submissionPathPrefix, index, "name"], "Initial submission", issues);
+    for (const [index, rule] of scenario.rules.entries()) {
+        const shadowingIndex = scenario.rules
+            .slice(0, index)
+            .findIndex((earlier) => selectorCovers(earlier.selector, rule.selector));
+        if (shadowingIndex >= 0) {
+            issues.push({
+                category: "semantic",
+                code: "fully_shadowed_rule",
+                path: ["rules", index, "selector"],
+                message: `Rule ${rule.id} is fully shadowed by earlier first-match rule ${scenario.rules[shadowingIndex]?.id}.`,
+            });
+        }
+        rule.outcomes.forEach((outcome, outcomeIndex) => {
+            validateOutcome(outcome, ["rules", index, "outcomes", outcomeIndex], issues);
+        });
+    }
+    if (scenario.unmatched.behavior === "outcome") {
+        validateOutcome(scenario.unmatched.outcome, ["unmatched", "outcome"], issues);
+    }
+    validateSelectorReferences(scenario, factory, issues);
+    validateSubmissionRelationships(submissions, submissionPathPrefix, issues);
+    if (scenario.initialSubmissions !== undefined &&
+        !isSubmissionArray(scenario.initialSubmissions)) {
+        validateDependencyRelationships(scenario.initialSubmissions, factory, issues);
+    }
+    return issues;
+}
+/** Validate an authored scenario without mutating it or the Factory context. */
+export function safeParseFactoryEmulatorScenario(input, factory) {
+    if (!validateScenarioShape(input)) {
+        return {
+            success: false,
+            issues: structuralIssues(validateScenarioShape.errors),
+        };
+    }
+    const scenario = input;
+    const issues = semanticIssues(scenario, factory);
+    if (issues.length > 0)
+        return { success: false, issues };
+    return {
+        success: true,
+        data: JSON.parse(JSON.stringify(scenario)),
+    };
+}
+/** Parse a complete scenario or throw one error containing every diagnostic. */
+export function parseFactoryEmulatorScenario(input, factory) {
+    const result = safeParseFactoryEmulatorScenario(input, factory);
+    if (!result.success) {
+        throw new FactoryEmulatorScenarioValidationError(result.issues);
+    }
+    return result.data;
+}

package/dist/scheduler.d.ts

@@ -0,0 +1,24 @@
+export declare const FACTORY_EMULATOR_SCHEDULER_CANDIDATE_LIMIT = 50;
+export interface FactorySchedulerToken {
+    readonly tokenId: string;
+    readonly customerWork: boolean;
+    readonly processing: boolean;
+    readonly queuedElapsedMs: number;
+    readonly lastDispatchElapsedMs?: number;
+}
+export interface FactorySchedulerResourceClaim {
+    readonly name: string;
+    readonly capacity: number;
+}
+export interface FactorySchedulerCandidate<Value = unknown> {
+    readonly transitionId: string;
+    readonly workerId: string;
+    readonly workstationKind: "logical" | "normal";
+    readonly tokens: readonly FactorySchedulerToken[];
+    readonly resources: readonly FactorySchedulerResourceClaim[];
+    readonly value: Value;
+}
+/** Go-compatible Work-in-queue ordering for the emulator's supported subset. */
+export declare function compareFactorySchedulerCandidates(left: FactorySchedulerCandidate, right: FactorySchedulerCandidate): number;
+/** Selects one deterministic batch while preventing double token consumption. */
+export declare function selectFactorySchedulerCandidates<Value>(candidates: readonly FactorySchedulerCandidate<Value>[], limit?: number, availableResources?: Readonly<Record<string, number>>): readonly FactorySchedulerCandidate<Value>[];

package/dist/scheduler.js

@@ -0,0 +1,104 @@
+export const FACTORY_EMULATOR_SCHEDULER_CANDIDATE_LIMIT = 50;
+function uniqueTokens(candidate) {
+    const seen = new Set();
+    return candidate.tokens.filter(({ tokenId }) => {
+        if (seen.has(tokenId))
+            return false;
+        seen.add(tokenId);
+        return true;
+    });
+}
+function earliest(values) {
+    const present = values.filter((value) => value !== undefined);
+    return present.length === 0 ? undefined : Math.min(...present);
+}
+function compareOptionalAge(left, right) {
+    if (left === undefined)
+        return right === undefined ? 0 : 1;
+    if (right === undefined)
+        return -1;
+    return left - right;
+}
+function compareText(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function compareTokenIds(left, right) {
+    if (left.length !== right.length)
+        return left.length - right.length;
+    for (const [index, token] of left.entries()) {
+        const comparison = compareText(token.tokenId, right[index]?.tokenId ?? "");
+        if (comparison !== 0)
+            return comparison;
+    }
+    return 0;
+}
+/** Go-compatible Work-in-queue ordering for the emulator's supported subset. */
+export function compareFactorySchedulerCandidates(left, right) {
+    const leftTokens = uniqueTokens(left);
+    const rightTokens = uniqueTokens(right);
+    const processing = rightTokens.filter(({ processing: value }) => value).length -
+        leftTokens.filter(({ processing: value }) => value).length;
+    if (processing !== 0)
+        return processing;
+    const customer = Number(rightTokens.some(({ customerWork }) => customerWork)) -
+        Number(leftTokens.some(({ customerWork }) => customerWork));
+    if (customer !== 0)
+        return customer;
+    const workstation = Number(left.workstationKind === "normal") -
+        Number(right.workstationKind === "normal");
+    if (workstation !== 0)
+        return workstation;
+    const leftDispatchAge = earliest(leftTokens.map(({ lastDispatchElapsedMs }) => lastDispatchElapsedMs));
+    const rightDispatchAge = earliest(rightTokens.map(({ lastDispatchElapsedMs }) => lastDispatchElapsedMs));
+    const initialized = Number(rightDispatchAge !== undefined) -
+        Number(leftDispatchAge !== undefined);
+    if (initialized !== 0)
+        return initialized;
+    if (leftDispatchAge !== undefined && rightDispatchAge !== undefined) {
+        const dispatchAge = compareOptionalAge(leftDispatchAge, rightDispatchAge);
+        if (dispatchAge !== 0)
+            return dispatchAge;
+    }
+    const queueAge = compareOptionalAge(earliest(leftTokens.map(({ queuedElapsedMs }) => queuedElapsedMs)), earliest(rightTokens.map(({ queuedElapsedMs }) => queuedElapsedMs)));
+    if (queueAge !== 0)
+        return queueAge;
+    const transition = compareText(left.transitionId, right.transitionId);
+    if (transition !== 0)
+        return transition;
+    const worker = compareText(left.workerId, right.workerId);
+    if (worker !== 0)
+        return worker;
+    return compareTokenIds(leftTokens, rightTokens);
+}
+/** Selects one deterministic batch while preventing double token consumption. */
+export function selectFactorySchedulerCandidates(candidates, limit = FACTORY_EMULATOR_SCHEDULER_CANDIDATE_LIMIT, availableResources = {}) {
+    const selected = [];
+    const claimed = new Set();
+    const claimedResources = {};
+    const boundedLimit = Math.max(0, Math.min(limit, FACTORY_EMULATOR_SCHEDULER_CANDIDATE_LIMIT));
+    for (const candidate of [...candidates].sort(compareFactorySchedulerCandidates)) {
+        if (selected.length >= boundedLimit)
+            break;
+        const tokenIds = uniqueTokens(candidate).map(({ tokenId }) => tokenId);
+        if (tokenIds.length === 0 ||
+            tokenIds.some((tokenId) => claimed.has(tokenId))) {
+            continue;
+        }
+        const resourceClaims = candidate.resources.reduce((claims, resource) => {
+            claims[resource.name] =
+                (claims[resource.name] ?? 0) + resource.capacity;
+            return claims;
+        }, {});
+        if (Object.entries(resourceClaims).some(([name, capacity]) => capacity + (claimedResources[name] ?? 0) >
+            (availableResources[name] ?? 0))) {
+            continue;
+        }
+        for (const tokenId of tokenIds)
+            claimed.add(tokenId);
+        for (const [name, capacity] of Object.entries(resourceClaims)) {
+            claimedResources[name] = (claimedResources[name] ?? 0) + capacity;
+        }
+        selected.push(candidate);
+    }
+    return selected;
+}