@eduardorenani/atlasjs 0.1.0-alpha.0

package/dist/validateRoutes.js

@@ -0,0 +1,107 @@
+// Phase 5.15: route shape runtime validator — belt-and-suspenders for the
+// `RouteList<E>` constraint.
+//
+// Spec: docs/specs/004-tasks.md Phase 5.15,
+// docs/specs/004-xstate-agent-wrapper.md verification line 821.
+//
+// The type system already enforces `RouteList<E>` at every call site:
+//   - `achieved` / `abandoned` / `error` reject the empty array `[]`
+//   - non-last array entries must carry `when` (otherwise they shadow later
+//     entries — first-match-wins at runtime would skip everything after)
+//   - the last array entry must NOT carry `when` (it is the unguarded
+//     default; without it no fallback fires).
+//
+// A user can bypass these checks with `as Routes<...>`. This validator
+// re-checks the same invariants at machine-creation time and throws a
+// structured error naming the leaf path, the slot (`achieved` / `retry` /
+// `abandoned` / `error`), and the offending index — spec verification
+// line 821.
+//
+// Scope is intentionally narrow:
+//   - shape only (array vs. scalar, length, presence of `when`)
+//   - target resolution stays in `validateTargets` (5.14)
+//   - field-level shape (`target` missing on an ExitEntry, `assign` not a
+//     function, etc.) is out of scope for this slice; the type system
+//     remains the primary guard for those.
+//
+// Like 5.14, this slice ships the validator standalone. Slice 5.16 wires
+// it into `defineAgent(...)` so the throw fires on machine creation.
+function joinPath(parent, name) {
+    return parent === "" ? name : `${parent}.${name}`;
+}
+function asCarrier(value, path) {
+    if (typeof value !== "object" || value === null || !("__kind" in value)) {
+        throw new Error(`atlas/validateRoutes: state at "${path}" is not a Mode or CompoundMode. ` +
+            `Pass values constructed via defineMode() or defineCompoundMode().`);
+    }
+    const kind = value.__kind;
+    if (kind !== "leaf" && kind !== "compound") {
+        throw new Error(`atlas/validateRoutes: state at "${path}" has unknown kind ${String(kind)}`);
+    }
+    return value;
+}
+function fail(leafPath, slot, index, reason) {
+    const where = index === null ? `routes.${slot}` : `routes.${slot}[${index}]`;
+    throw new Error(`atlas/validateRoutes: ${where} at "${leafPath}": ${reason}`);
+}
+function validateRouteListShape(slot, value, leafPath) {
+    if (value === undefined) {
+        if (slot === "error")
+            return; // optional
+        fail(leafPath, slot, null, `required outcome is missing (declare an entry with \`target\` or, for retry, supply \`[]\`)`);
+    }
+    if (!Array.isArray(value)) {
+        // Scalar form — single-default. Field-level shape (target, when,
+        // assign) is the type system's responsibility; we only verify it
+        // is at least an object.
+        if (typeof value !== "object" || value === null) {
+            fail(leafPath, slot, null, `must be an object or array (got ${typeof value})`);
+        }
+        return;
+    }
+    const arr = value;
+    if (arr.length === 0) {
+        if (slot === "retry")
+            return; // explicit empty retry = no-op default
+        fail(leafPath, slot, null, `must not be the empty array []. Provide a single default entry, or guarded entries followed by a default.`);
+    }
+    // Non-last entries MUST carry `when` — without it they shadow every
+    // entry after them at first-match-wins runtime.
+    for (let i = 0; i < arr.length - 1; i += 1) {
+        if (arr[i].when === undefined) {
+            fail(leafPath, slot, i, `non-last entry is missing \`when\` — it would shadow later entries at runtime (first-match-wins)`);
+        }
+    }
+    // Last entry MUST NOT carry `when` — the last entry is the unguarded
+    // default; otherwise no fallback exists when every preceding `when`
+    // returns false.
+    const lastIndex = arr.length - 1;
+    const last = arr[lastIndex];
+    if (last !== undefined && last.when !== undefined) {
+        fail(leafPath, slot, lastIndex, `last entry carries \`when\` — the last entry must be the unguarded default`);
+    }
+}
+function validateActiveLeafRoutes(config, leafPath) {
+    const routes = (config.routes ?? {});
+    validateRouteListShape("achieved", routes.achieved, leafPath);
+    validateRouteListShape("retry", routes.retry, leafPath);
+    validateRouteListShape("abandoned", routes.abandoned, leafPath);
+    validateRouteListShape("error", routes.error, leafPath);
+}
+// Public entry point. Recursively validates `routes` shape on every active
+// leaf in the tree. Passive leaves are skipped (no `routes` field).
+export function validateRoutes(modes, parentPath = "") {
+    for (const [name, value] of Object.entries(modes)) {
+        const path = joinPath(parentPath, name);
+        const carrier = asCarrier(value, path);
+        if (carrier.__kind === "leaf") {
+            if ("behavior" in carrier.config && carrier.config.behavior !== undefined) {
+                validateActiveLeafRoutes(carrier.config, path);
+            }
+        }
+        else {
+            validateRoutes(carrier.config.modes, path);
+        }
+    }
+}
+//# sourceMappingURL=validateRoutes.js.map

package/dist/validateRoutes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateRoutes.js","sourceRoot":"","sources":["../src/validateRoutes.ts"],"names":[],"mappings":"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"}

package/dist/validateTargets.d.ts

@@ -0,0 +1,2 @@
+export declare function validateTargets(modes: Record<string, unknown>, parentPath?: string): void;
+//# sourceMappingURL=validateTargets.d.ts.map

package/dist/validateTargets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateTargets.d.ts","sourceRoot":"","sources":["../src/validateTargets.ts"],"names":[],"mappings":"AAkLA,wBAAgB,eAAe,CAC3B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,UAAU,GAAE,MAAW,GACxB,IAAI,CAiBN"}

package/dist/validateTargets.js

@@ -0,0 +1,132 @@
+// Phase 5.14: target resolution validator (sibling-name only).
+//
+// Spec: docs/specs/004-tasks.md Phase 5.14,
+// docs/specs/004-xstate-agent-wrapper.md §Target resolution (lines 824-829).
+//
+// Every `target` declared by the user — `routes.achieved[i].target`,
+// `routes.abandoned[i].target`, `routes.error[i].target`, passive
+// `on[event][i].target`, and a compound's `onDone` — must name a key in
+// the **immediate enclosing** `modes` map. The token symbols `END`
+// (achieved/abandoned/error/onDone/passive-on) and `RE_THROW`
+// (error only) pass through verbatim — they are resolved by slices 5.10
+// (RE_THROW) and 5.11 ($end injection).
+//
+// String targets are additionally rejected when they:
+//   - contain `.` (dotted paths like "socratic.teaching")
+//   - start with `#` (XState absolute paths like "#agent.root")
+//   - start with `.` (descendant paths — caught implicitly by the dot rule)
+//
+// On failure the validator throws a structured `Error` whose message names
+// the offending leaf (or compound) path, the slot descriptor
+// (`routes.achieved[0]`, `on.CLICK[1]`, `onDone`), and the literal bad
+// target string — spec verification line 824.
+//
+// 5.14 ships the validator as a standalone toolkit. Wiring it into
+// `defineAgent(...)` (so the throw fires on machine creation) is part of
+// the final assembly slice (5.16) — same composition pattern as 5.11 and
+// 5.13.
+import { END, RE_THROW } from "./types.js";
+function joinPath(parent, name) {
+    return parent === "" ? name : `${parent}.${name}`;
+}
+function asCarrier(value, path) {
+    if (typeof value !== "object" || value === null || !("__kind" in value)) {
+        throw new Error(`atlas/validateTargets: state at "${path}" is not a Mode or CompoundMode. ` +
+            `Pass values constructed via defineMode() or defineCompoundMode().`);
+    }
+    const kind = value.__kind;
+    if (kind !== "leaf" && kind !== "compound") {
+        throw new Error(`atlas/validateTargets: state at "${path}" has unknown kind ${String(kind)}`);
+    }
+    return value;
+}
+// Normalize a `T | readonly T[] | undefined` slot to a flat `readonly T[]`
+// for uniform iteration.
+function normalize(value) {
+    if (value === undefined)
+        return [];
+    if (Array.isArray(value))
+        return value;
+    return [value];
+}
+// Format error consistently — spec verification line 824 requires the path,
+// slot descriptor, and literal target.
+function fail(target, leafPath, slotDesc, reason) {
+    const literal = typeof target === "string" ? JSON.stringify(target) : String(target);
+    throw new Error(`atlas/validateTargets: target ${literal} at "${leafPath}" in ${slotDesc}: ${reason}`);
+}
+function checkTarget(target, siblings, leafPath, slotDesc) {
+    if (target === END || target === RE_THROW)
+        return;
+    if (typeof target !== "string") {
+        fail(target, leafPath, slotDesc, `target must be a sibling name (string), END, or RE_THROW`);
+    }
+    if (target.includes(".")) {
+        fail(target, leafPath, slotDesc, `dotted paths are not accepted — END is the only way to exit a compound`);
+    }
+    if (target.startsWith("#")) {
+        fail(target, leafPath, slotDesc, `XState absolute paths (#-prefixed) are not accepted`);
+    }
+    if (!siblings.includes(target)) {
+        fail(target, leafPath, slotDesc, `no such sibling. Available siblings: ${JSON.stringify(siblings)}`);
+    }
+}
+function validateActiveLeaf(config, leafPath, siblings) {
+    const routes = (config.routes ?? {});
+    const groups = [
+        { key: "achieved", allowReThrow: false },
+        { key: "abandoned", allowReThrow: false },
+        { key: "error", allowReThrow: true },
+    ];
+    for (const { key } of groups) {
+        if (routes[key] === undefined)
+            continue;
+        const entries = normalize(routes[key]);
+        for (let i = 0; i < entries.length; i += 1) {
+            const target = entries[i].target;
+            checkTarget(target, siblings, leafPath, `routes.${key}[${i}]`);
+        }
+    }
+    // `routes.retry` has no `target` field at the type level — skipped.
+}
+function validatePassiveLeaf(config, leafPath, siblings) {
+    const on = (config.on ?? {});
+    for (const [event, transitions] of Object.entries(on)) {
+        const list = normalize(transitions);
+        for (let i = 0; i < list.length; i += 1) {
+            const target = list[i].target;
+            // `on[event].target` is optional — a transition with only
+            // `actions` is an internal/no-target action and is valid.
+            if (target === undefined)
+                continue;
+            checkTarget(target, siblings, leafPath, `on.${event}[${i}]`);
+        }
+    }
+}
+function validateCompound(carrier, compoundPath, siblings) {
+    checkTarget(carrier.config.onDone, siblings, compoundPath, "onDone");
+}
+// Public entry point. Recursively validates every `target` in the tree.
+// Throws on the first violation — fail-fast surfaces the user's mistake at
+// `defineAgent(...)` call time with full context.
+export function validateTargets(modes, parentPath = "") {
+    const siblings = Object.keys(modes);
+    for (const [name, value] of Object.entries(modes)) {
+        const path = joinPath(parentPath, name);
+        const carrier = asCarrier(value, path);
+        if (carrier.__kind === "leaf") {
+            if ("behavior" in carrier.config && carrier.config.behavior !== undefined) {
+                validateActiveLeaf(carrier.config, path, siblings);
+            }
+            else {
+                validatePassiveLeaf(carrier.config, path, siblings);
+            }
+        }
+        else {
+            validateCompound(carrier, path, siblings);
+            // Inner siblings = keys of THIS compound's `modes` map.
+            validateTargets(carrier.config.modes, path);
+        }
+    }
+}
+//# sourceMappingURL=validateTargets.js.map

package/dist/validateTargets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateTargets.js","sourceRoot":"","sources":["../src/validateTargets.ts"],"names":[],"mappings":"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"}

package/dist/walk.d.ts

@@ -0,0 +1,20 @@
+import type { JsonObject, ModeConfig } from "./types.js";
+type InternalCtx = JsonObject;
+export type LeafSlot = {
+    readonly kind: "leaf";
+    readonly path: string;
+    readonly config: ModeConfig<InternalCtx, {
+        type: string;
+    }, unknown>;
+};
+export type CompoundSlot = {
+    readonly kind: "compound";
+    readonly path: string;
+    readonly config: {
+        readonly modes: Record<string, unknown>;
+    };
+};
+export type Slot = LeafSlot | CompoundSlot;
+export declare function walk(modes: Record<string, unknown>, parentPath?: string): Slot[];
+export {};
+//# sourceMappingURL=walk.d.ts.map

package/dist/walk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk.d.ts","sourceRoot":"","sources":["../src/walk.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAKzD,KAAK,WAAW,GAAG,UAAU,CAAC;AAe9B,MAAM,MAAM,QAAQ,GAAG;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,OAAO,CAAC,CAAC;CACvE,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACvB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;CAChE,CAAC;AAEF,MAAM,MAAM,IAAI,GAAG,QAAQ,GAAG,YAAY,CAAC;AAgB3C,wBAAgB,IAAI,CAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,UAAU,SAAK,GAChB,IAAI,EAAE,CAaR"}

package/dist/walk.js

@@ -0,0 +1,35 @@
+// Tree walk over an agent's `modes` map.
+//
+// Spec: docs/specs/004-tasks.md Phase 5.1.
+//
+// Enumerates every `Mode` (leaf) and `CompoundMode` slot, recording a
+// root-relative dotted path. The path is used only inside `compile.ts` (for
+// actor naming, for target resolution, for error messages); it is never
+// exposed to users.
+function asCarrier(value, path) {
+    if (typeof value !== "object" || value === null || !("__kind" in value)) {
+        throw new Error(`atlas/walk: state at "${path}" is not a Mode or CompoundMode. ` +
+            `Pass values constructed via defineMode() or defineCompoundMode().`);
+    }
+    const kind = value.__kind;
+    if (kind !== "leaf" && kind !== "compound") {
+        throw new Error(`atlas/walk: state at "${path}" has unknown kind ${String(kind)}`);
+    }
+    return value;
+}
+export function walk(modes, parentPath = "") {
+    const slots = [];
+    for (const [key, value] of Object.entries(modes)) {
+        const path = parentPath === "" ? key : `${parentPath}.${key}`;
+        const carrier = asCarrier(value, path);
+        if (carrier.__kind === "leaf") {
+            slots.push({ kind: "leaf", path, config: carrier.config });
+        }
+        else {
+            slots.push({ kind: "compound", path, config: carrier.config });
+            slots.push(...walk(carrier.config.modes, path));
+        }
+    }
+    return slots;
+}
+//# sourceMappingURL=walk.js.map

package/dist/walk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk.js","sourceRoot":"","sources":["../src/walk.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,2CAA2C;AAC3C,EAAE;AACF,sEAAsE;AACtE,4EAA4E;AAC5E,wEAAwE;AACxE,oBAAoB;AAoCpB,SAAS,SAAS,CAAC,KAAc,EAAE,IAAY;IAC3C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,CAAC,QAAQ,IAAI,KAAK,CAAC,EAAE,CAAC;QACtE,MAAM,IAAI,KAAK,CACX,yBAAyB,IAAI,mCAAmC;YAC5D,mEAAmE,CAC1E,CAAC;IACN,CAAC;IACD,MAAM,IAAI,GAAI,KAA6B,CAAC,MAAM,CAAC;IACnD,IAAI,IAAI,KAAK,MAAM,IAAI,IAAI,KAAK,UAAU,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CAAC,yBAAyB,IAAI,sBAAsB,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACvF,CAAC;IACD,OAAO,KAAsC,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,IAAI,CAChB,KAA8B,EAC9B,UAAU,GAAG,EAAE;IAEf,MAAM,KAAK,GAAW,EAAE,CAAC;IACzB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/C,MAAM,IAAI,GAAG,UAAU,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,UAAU,IAAI,GAAG,EAAE,CAAC;QAC9D,MAAM,OAAO,GAAG,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QACvC,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;YAC5B,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;QAC/D,CAAC;aAAM,CAAC;YACJ,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;YAC/D,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;QACpD,CAAC;IACL,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC"}

package/package.json

@@ -0,0 +1,63 @@
+{
+    "name": "@eduardorenani/atlasjs",
+    "version": "0.1.0-alpha.0",
+    "description": "Mode-based agent orchestration on top of XState v5. Typed modes, four-outcome contract, goal-bound exits.",
+    "type": "module",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist",
+        "README.md",
+        "LICENSE"
+    ],
+    "sideEffects": false,
+    "scripts": {
+        "build": "tsc -p tsconfig.build.json && node scripts/fix-dts-extensions.mjs",
+        "clean": "rm -rf dist",
+        "test": "vitest run --passWithNoTests && vitest --typecheck --run --passWithNoTests",
+        "test:types": "vitest --typecheck --run --passWithNoTests",
+        "prepublishOnly": "npm run clean && npm run build"
+    },
+    "peerDependencies": {
+        "xstate": "^5"
+    },
+    "devDependencies": {
+        "typescript": "^5.7",
+        "vitest": "^3",
+        "xstate": "^5"
+    },
+    "keywords": [
+        "xstate",
+        "state-machine",
+        "agent",
+        "ai-agent",
+        "orchestration",
+        "llm",
+        "typescript",
+        "modes"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/EduardoRenani/atlas.git",
+        "directory": "packages/atlas"
+    },
+    "homepage": "https://github.com/EduardoRenani/atlas#readme",
+    "bugs": {
+        "url": "https://github.com/EduardoRenani/atlas/issues"
+    },
+    "license": "Apache-2.0",
+    "author": "Eduardo Renani",
+    "publishConfig": {
+        "access": "public",
+        "provenance": true
+    },
+    "engines": {
+        "node": ">=20"
+    }
+}