@eduardorenani/atlasjs 0.1.0-alpha.0

package/dist/buildActors.d.ts

@@ -0,0 +1,4 @@
+import type { AnyActorLogic } from "xstate";
+import type { Slot } from "./walk.js";
+export declare function buildActors(slots: readonly Slot[], deps: Readonly<Record<string, unknown>>): Record<string, AnyActorLogic>;
+//# sourceMappingURL=buildActors.d.ts.map

package/dist/buildActors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildActors.d.ts","sourceRoot":"","sources":["../src/buildActors.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAG5C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEtC,wBAAgB,WAAW,CACvB,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CA6B/B"}

package/dist/buildActors.js

@@ -0,0 +1,40 @@
+// Build the `actors` map for XState's `setup({ actors })`. Spec:
+// docs/specs/004-tasks.md Phase 5.3 + docs/specs/004-xstate-agent-wrapper.md
+// §Mapping. Spec 005: the wrapper closes over the agent's frozen `deps`
+// reference and threads it into every active leaf's `behavior` callback.
+//
+// One entry per active `Mode` (leaf) slot, keyed by `actorName(path)`. Each
+// entry wraps the user's `behavior` in
+// `fromPromise(async ({ input }) => behavior({ input, deps }))` — the only
+// place the wrapper bridges user code to XState's actor runtime.
+// Passive leaves do not produce an actor; they are atomic states with `on`
+// handlers (handled in slice 5.4).
+import { fromPromise } from "xstate";
+import { actorName } from "./actorName.js";
+export function buildActors(slots, deps) {
+    const actors = {};
+    for (const slot of slots) {
+        if (slot.kind !== "leaf")
+            continue;
+        const config = slot.config;
+        if (!("behavior" in config))
+            continue; // passive leaf — no actor
+        const name = actorName(slot.path);
+        if (name in actors) {
+            // Two leaves sharing an actor name would silently overwrite. Per
+            // DD-008 the name is derived from path, so a collision here means
+            // two slots share a path — which `walk()` already prevents — or
+            // future renames broke the invariant. Fail loudly.
+            throw new Error(`atlas/buildActors: duplicate actor name "${name}" at path "${slot.path}"`);
+        }
+        // The user's `behavior` was typed against its own `TDeps` at the
+        // `defineMode` call site; the internal carrier here erases that
+        // generic to the default `Record<string, never>`. Cast through the
+        // user-facing envelope shape — by-identity threading is the same
+        // frozen reference all callbacks receive.
+        const userBehavior = config.behavior;
+        actors[name] = fromPromise(async ({ input }) => userBehavior({ input, deps }));
+    }
+    return actors;
+}
+//# sourceMappingURL=buildActors.js.map

package/dist/buildActors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildActors.js","sourceRoot":"","sources":["../src/buildActors.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,6EAA6E;AAC7E,wEAAwE;AACxE,yEAAyE;AACzE,EAAE;AACF,4EAA4E;AAC5E,uCAAuC;AACvC,2EAA2E;AAC3E,iEAAiE;AACjE,2EAA2E;AAC3E,mCAAmC;AAEnC,OAAO,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAGrC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAG3C,MAAM,UAAU,WAAW,CACvB,KAAsB,EACtB,IAAuC;IAEvC,MAAM,MAAM,GAAkC,EAAE,CAAC;IACjD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACvB,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM;YAAE,SAAS;QACnC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC3B,IAAI,CAAC,CAAC,UAAU,IAAI,MAAM,CAAC;YAAE,SAAS,CAAC,0BAA0B;QAEjE,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAClC,IAAI,IAAI,IAAI,MAAM,EAAE,CAAC;YACjB,iEAAiE;YACjE,kEAAkE;YAClE,gEAAgE;YAChE,mDAAmD;YACnD,MAAM,IAAI,KAAK,CACX,4CAA4C,IAAI,cAAc,IAAI,CAAC,IAAI,GAAG,CAC7E,CAAC;QACN,CAAC;QACD,iEAAiE;QACjE,gEAAgE;QAChE,mEAAmE;QACnE,iEAAiE;QACjE,0CAA0C;QAC1C,MAAM,YAAY,GAAG,MAAM,CAAC,QAGN,CAAC;QACvB,MAAM,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,YAAY,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IACnF,CAAC;IACD,OAAO,MAAM,CAAC;AAClB,CAAC"}

package/dist/buildPassiveState.d.ts

@@ -0,0 +1,19 @@
+import { type LiftContext } from "./contextLift.js";
+import type { JsonObject, PassiveModeConfig, RouteTarget } from "./types.js";
+type InternalCtx = JsonObject;
+export type LoweredTransition = {
+    target?: RouteTarget;
+    actions?: string | readonly string[];
+    guard?: (args: {
+        context: unknown;
+        event: unknown;
+    }) => boolean;
+};
+export type LoweredAtomicState = {
+    on: Record<string, LoweredTransition | readonly LoweredTransition[]>;
+};
+export declare function buildPassiveState(config: PassiveModeConfig<InternalCtx, {
+    type: string;
+}>, lift: LiftContext | undefined, deps: Readonly<Record<string, unknown>>): LoweredAtomicState;
+export {};
+//# sourceMappingURL=buildPassiveState.d.ts.map

package/dist/buildPassiveState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildPassiveState.d.ts","sourceRoot":"","sources":["../src/buildPassiveState.ts"],"names":[],"mappings":"AAeA,OAAO,EAAa,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,KAAK,EAER,UAAU,EACV,iBAAiB,EACjB,WAAW,EACd,MAAM,YAAY,CAAC;AAIpB,KAAK,WAAW,GAAG,UAAU,CAAC;AAK9B,MAAM,MAAM,iBAAiB,GAAG;IAC5B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IACrC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC;CACnE,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC7B,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,GAAG,SAAS,iBAAiB,EAAE,CAAC,CAAC;CACxE,CAAC;AAyCF,wBAAgB,iBAAiB,CAC7B,MAAM,EAAE,iBAAiB,CAAC,WAAW,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,EACxD,IAAI,EAAE,WAAW,GAAG,SAAS,EAC7B,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxC,kBAAkB,CASpB"}

package/dist/buildPassiveState.js

@@ -0,0 +1,59 @@
+// Lower a passive `ModeConfig` to an XState atomic-state config.
+// Spec: docs/specs/004-tasks.md Phase 5.4 + docs/specs/004-xstate-agent-wrapper.md §Mapping.
+// Spec 005: `on[*].guard` gains a `deps` parameter; the wrapper captures the
+// agent's frozen `deps` reference in the generated guard's closure.
+//
+// Passive leaves carry only `on` handlers (no `behavior`, no actor). The
+// mapping is structurally identity for `target` / `actions`:
+//   { on: { EVENT: { target, actions, guard } } } → same shape on XState.
+// `actions` strings reference entries in `defineAgent.actions` (registered
+// in `setup({ actions })` — those already close over `deps`).
+//
+// `END` targets stay as the `END` symbol in the output; the compound-level
+// `$end` substate injection + END→`$end` rewrite happens in slice 5.11
+// before the final XState `createMachine` call.
+import { liftGuard } from "./contextLift.js";
+// `Array.isArray` narrows to `any[]`, which fails to subtract
+// `readonly T[]` from a union like `T | readonly T[]`. This typed predicate
+// gives TypeScript the narrowing it needs without leaking `any`.
+function isReadonlyArray(value) {
+    return Array.isArray(value);
+}
+function mapTransition(t, lift, deps) {
+    const out = {};
+    if (t.target !== undefined)
+        out.target = t.target;
+    if (t.actions !== undefined)
+        out.actions = t.actions;
+    if (t.guard !== undefined) {
+        // The user typed `guard` as `({ context, event, deps }) => boolean`
+        // with concrete C/E types. Widening to `unknown` is safe — XState
+        // calls the function with the matching shape at runtime, and the
+        // user code's narrowing is preserved as it was written.
+        //
+        // Under a compound-local context lift, route the call through
+        // `liftGuard` so the user sees the virtual merged view (inherited
+        // + local) — same view the type system promised. `deps` is
+        // forwarded verbatim regardless of lift.
+        const userGuard = t.guard;
+        if (lift !== undefined) {
+            out.guard = liftGuard(userGuard, lift, deps);
+        }
+        else {
+            out.guard = ({ context, event }) => userGuard({ context, event, deps });
+        }
+    }
+    return out;
+}
+export function buildPassiveState(config, lift, deps) {
+    const on = {};
+    for (const [eventType, transitions] of Object.entries(config.on)) {
+        if (transitions === undefined)
+            continue;
+        on[eventType] = isReadonlyArray(transitions)
+            ? transitions.map((t) => mapTransition(t, lift, deps))
+            : mapTransition(transitions, lift, deps);
+    }
+    return { on };
+}
+//# sourceMappingURL=buildPassiveState.js.map

package/dist/buildPassiveState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildPassiveState.js","sourceRoot":"","sources":["../src/buildPassiveState.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,6FAA6F;AAC7F,6EAA6E;AAC7E,oEAAoE;AACpE,EAAE;AACF,yEAAyE;AACzE,6DAA6D;AAC7D,0EAA0E;AAC1E,2EAA2E;AAC3E,8DAA8D;AAC9D,EAAE;AACF,2EAA2E;AAC3E,uEAAuE;AACvE,gDAAgD;AAEhD,OAAO,EAAE,SAAS,EAAoB,MAAM,kBAAkB,CAAC;AAyB/D,8DAA8D;AAC9D,4EAA4E;AAC5E,iEAAiE;AACjE,SAAS,eAAe,CAAI,KAAuB;IAC/C,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAChC,CAAC;AAED,SAAS,aAAa,CAClB,CAAiD,EACjD,IAA6B,EAC7B,IAAuC;IAEvC,MAAM,GAAG,GAAsB,EAAE,CAAC;IAClC,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS;QAAE,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC;IAClD,IAAI,CAAC,CAAC,OAAO,KAAK,SAAS;QAAE,GAAG,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC;IACrD,IAAI,CAAC,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,oEAAoE;QACpE,kEAAkE;QAClE,iEAAiE;QACjE,wDAAwD;QACxD,EAAE;QACF,8DAA8D;QAC9D,kEAAkE;QAClE,2DAA2D;QAC3D,yCAAyC;QACzC,MAAM,SAAS,GAAG,CAAC,CAAC,KAIP,CAAC;QACd,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACrB,GAAG,CAAC,KAAK,GAAG,SAAS,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;QACjD,CAAC;aAAM,CAAC;YACJ,GAAG,CAAC,KAAK,GAAG,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5E,CAAC;IACL,CAAC;IACD,OAAO,GAAG,CAAC;AACf,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC7B,MAAwD,EACxD,IAA6B,EAC7B,IAAuC;IAEvC,MAAM,EAAE,GAA6B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,SAAS,EAAE,WAAW,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC;QAC/D,IAAI,WAAW,KAAK,SAAS;YAAE,SAAS;QACxC,EAAE,CAAC,SAAS,CAAC,GAAG,eAAe,CAAC,WAAW,CAAC;YACxC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;YACtD,CAAC,CAAC,aAAa,CAAC,WAAW,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,CAAC;AAClB,CAAC"}

package/dist/compile.d.ts

@@ -0,0 +1,6 @@
+import { type AnyStateMachine } from "xstate";
+import type { AgentConfig, ModesMap } from "./types.js";
+export declare function compile<TContext, TEvents extends {
+    type: string;
+}, TModes extends ModesMap<TContext, TEvents, TDeps>, TDeps extends Record<string, unknown> = Record<string, never>>(config: AgentConfig<TContext, TEvents, TModes, TDeps>, frozenDeps: Readonly<TDeps>): AnyStateMachine;
+//# sourceMappingURL=compile.d.ts.map

package/dist/compile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../src/compile.ts"],"names":[],"mappings":"AAoBA,OAAO,EAA6B,KAAK,eAAe,EAA0B,MAAM,QAAQ,CAAC;AAmBjG,OAAO,KAAK,EACR,WAAW,EAGX,QAAQ,EAGX,MAAM,YAAY,CAAC;AAkLpB,wBAAgB,OAAO,CACnB,QAAQ,EACR,OAAO,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EAChC,MAAM,SAAS,QAAQ,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,CAAC,EACjD,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAE7D,MAAM,EAAE,WAAW,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EACrD,UAAU,EAAE,QAAQ,CAAC,KAAK,CAAC,GAC5B,eAAe,CA6CjB"}

package/dist/compile.js

@@ -0,0 +1,164 @@
+// `compile` — lowers an `AgentConfig` tree into an XState machine.
+//
+// Spec: docs/specs/004-xstate-agent-wrapper.md §"Wrapper internals (compile.ts)"
+// + §Mapping. Tasks: docs/specs/004-tasks.md Phase 5.16 (final emit).
+// Spec 005: closes over a frozen `deps` reference and threads it to every
+//           build* helper. `deps` is NOT placed in XState context — it lives
+//           in callback closures, so `JSON.stringify(actor.getSnapshot().context)`
+//           returns only TContext (+ synthetic compound-local slots).
+//
+// This is the only file in `atlas` that calls `setup().createMachine`. It
+// composes the toolkit slices built in 5.1–5.15:
+//   - validateTargets, validateRoutes   (fail-fast at machine creation)
+//   - walk + actorName + buildActors    (active-leaf actor map)
+//   - buildActions                      (named-actions map)
+//   - buildActiveState / buildPassiveState (per-leaf lowering, lift-aware)
+//   - contextLift (LiftContext + entry/exit on compounds that declare context)
+//   - injectEnd (per-level `$end` substate + END → name rewrite)
+//
+// `defineAgent` returns this value verbatim.
+import { setup } from "xstate";
+import { buildActions } from "./buildActions.js";
+import { buildActiveState } from "./buildActiveState.js";
+import { buildActors } from "./buildActors.js";
+import { buildPassiveState } from "./buildPassiveState.js";
+import { compoundLocalKey, makeCompoundEntry, makeCompoundExit, } from "./contextLift.js";
+import { END_SUBSTATE, hasEndReference, pickEndName, rewriteEndTargets, } from "./injectEnd.js";
+import { END } from "./types.js";
+import { validateRoutes } from "./validateRoutes.js";
+import { validateTargets } from "./validateTargets.js";
+import { walk } from "./walk.js";
+function asCarrier(value) {
+    return value;
+}
+// ── END detection / rewriting at a level ─────────────────────────────
+function isCompound(node) {
+    return "initial" in node && "states" in node;
+}
+function isFinal(node) {
+    return "type" in node && node.type === "final";
+}
+function nodeExitsViaEnd(node) {
+    if (isFinal(node))
+        return false;
+    if (isCompound(node)) {
+        return node.onDone !== undefined && node.onDone.target === END;
+    }
+    return hasEndReference(node);
+}
+function rewriteNodeEnd(node, endName) {
+    if (isFinal(node))
+        return node;
+    if (isCompound(node)) {
+        if (node.onDone !== undefined && node.onDone.target === END) {
+            return { ...node, onDone: { target: endName } };
+        }
+        return node;
+    }
+    return rewriteEndTargets(node, endName);
+}
+function injectEndAtLevel(states) {
+    let anyEnd = false;
+    for (const node of Object.values(states)) {
+        if (nodeExitsViaEnd(node)) {
+            anyEnd = true;
+            break;
+        }
+    }
+    if (!anyEnd)
+        return states;
+    const endName = pickEndName(Object.keys(states));
+    const rewritten = {};
+    for (const [name, node] of Object.entries(states)) {
+        rewritten[name] = rewriteNodeEnd(node, endName);
+    }
+    rewritten[endName] = END_SUBSTATE;
+    return rewritten;
+}
+// ── Recursive mode-map lowering ──────────────────────────────────────
+function joinPath(parent, name) {
+    return parent === "" ? name : `${parent}.${name}`;
+}
+function buildStatesMap(modes, parentLift, parentPath, deps) {
+    const out = {};
+    for (const [name, value] of Object.entries(modes)) {
+        const path = joinPath(parentPath, name);
+        const carrier = asCarrier(value);
+        if (carrier.__kind === "leaf") {
+            const config = carrier.config;
+            if ("behavior" in config && config.behavior !== undefined) {
+                const slot = { kind: "leaf", path, config };
+                out[name] = buildActiveState(slot, parentLift, deps);
+            }
+            else {
+                out[name] = buildPassiveState(config, parentLift, deps);
+            }
+            continue;
+        }
+        // Compound.
+        const cfg = carrier.config;
+        let childLift = parentLift;
+        let ownEntry;
+        let ownExit;
+        if (cfg.context !== undefined) {
+            const ctx = cfg.context;
+            const newLift = {
+                key: compoundLocalKey(path),
+                inherit: ctx.inherit,
+                initialLocal: ctx.local,
+                parent: parentLift,
+            };
+            childLift = newLift;
+            ownEntry = makeCompoundEntry(newLift);
+            ownExit = makeCompoundExit(newLift);
+        }
+        const childStatesRaw = buildStatesMap(cfg.modes, childLift, path, deps);
+        const childStates = injectEndAtLevel(childStatesRaw);
+        const compound = {
+            initial: cfg.initial,
+            states: childStates,
+            onDone: { target: cfg.onDone },
+        };
+        if (ownEntry !== undefined)
+            compound.entry = ownEntry;
+        if (ownExit !== undefined)
+            compound.exit = ownExit;
+        out[name] = compound;
+    }
+    return out;
+}
+// ── Public entry ─────────────────────────────────────────────────────
+export function compile(config, frozenDeps) {
+    const rawModes = config.modes;
+    // Erase TDeps for the loose internal contract — every build* helper takes
+    // `Readonly<Record<string, unknown>>` and the user's concrete type has
+    // already been enforced at the call site.
+    const deps = frozenDeps;
+    // Fail-fast at machine creation — spec verification lines 821 + 824.
+    validateTargets(rawModes);
+    validateRoutes(rawModes);
+    const slots = walk(rawModes);
+    const actors = buildActors(slots, deps);
+    const actions = buildActions(config.actions, deps);
+    const lowered = buildStatesMap(rawModes, undefined, "", deps);
+    const finalStates = injectEndAtLevel(lowered);
+    // The wrapper's type contract was discharged at the user's call site
+    // (defineMode / defineCompoundMode / defineAgent). At this internal layer
+    // every shape is `unknown`-typed by construction. XState's `setup` types
+    // are too strict to satisfy generically — its `MachineContext` constraint
+    // collides with `TContext` being arbitrary — so we hand it the already-
+    // shaped values through `unknown`. The output is `AnyStateMachine`, which
+    // is what `defineAgent` returns.
+    const looseSetup = setup;
+    const machine = looseSetup({
+        actors,
+        actions,
+    }).createMachine({
+        id: config.id,
+        initial: config.initial,
+        context: config.context,
+        states: finalStates,
+    });
+    return machine;
+}
+//# sourceMappingURL=compile.js.map

package/dist/compile.js.map

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

package/dist/contextLift.d.ts

@@ -0,0 +1,35 @@
+import { assign } from "xstate";
+export type LiftContext = {
+    readonly key: string;
+    readonly inherit: readonly string[];
+    readonly initialLocal: Readonly<Record<string, unknown>>;
+    readonly parent?: LiftContext;
+};
+export declare function compoundLocalKey(path: string): string;
+export declare function liftInput(userInput: (args: {
+    context: unknown;
+    deps: Readonly<Record<string, unknown>>;
+}) => unknown, lift: LiftContext, deps: Readonly<Record<string, unknown>>): (args: {
+    context: unknown;
+}) => unknown;
+export declare function liftExitAssign(userAssign: (args: {
+    context: unknown;
+    payload: unknown;
+    deps: Readonly<Record<string, unknown>>;
+}) => object, lift: LiftContext, deps: Readonly<Record<string, unknown>>): ReturnType<typeof assign>;
+export declare function liftErrorAssign(userAssign: (args: {
+    context: unknown;
+    error: unknown;
+    deps: Readonly<Record<string, unknown>>;
+}) => object, lift: LiftContext, deps: Readonly<Record<string, unknown>>): ReturnType<typeof assign>;
+export declare function liftGuard(userGuard: (args: {
+    context: unknown;
+    event: unknown;
+    deps: Readonly<Record<string, unknown>>;
+}) => boolean, lift: LiftContext, deps: Readonly<Record<string, unknown>>): (args: {
+    context: unknown;
+    event: unknown;
+}) => boolean;
+export declare function makeCompoundEntry(lift: LiftContext): ReturnType<typeof assign>;
+export declare function makeCompoundExit(lift: LiftContext): ReturnType<typeof assign>;
+//# sourceMappingURL=contextLift.d.ts.map

package/dist/contextLift.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextLift.d.ts","sourceRoot":"","sources":["../src/contextLift.ts"],"names":[],"mappings":"AA2BA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,MAAM,MAAM,WAAW,GAAG;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACzD,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CACjC,CAAC;AAOF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMrD;AAmGD,wBAAgB,SAAS,CACrB,SAAS,EAAE,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CAAE,KAAK,OAAO,EAC3F,IAAI,EAAE,WAAW,EACjB,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxC,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,KAAK,OAAO,CAKzC;AAKD,wBAAgB,cAAc,CAC1B,UAAU,EAAE,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CAAE,KAAK,MAAM,EAC7G,IAAI,EAAE,WAAW,EACjB,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxC,UAAU,CAAC,OAAO,MAAM,CAAC,CAQ3B;AAGD,wBAAgB,eAAe,CAC3B,UAAU,EAAE,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CAAE,KAAK,MAAM,EAC3G,IAAI,EAAE,WAAW,EACjB,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxC,UAAU,CAAC,OAAO,MAAM,CAAC,CAQ3B;AAGD,wBAAgB,SAAS,CACrB,SAAS,EAAE,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CAAE,KAAK,OAAO,EAC3G,IAAI,EAAE,WAAW,EACjB,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxC,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,KAAK,OAAO,CAKzD;AAOD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU,CAAC,OAAO,MAAM,CAAC,CAI9E;AAKD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU,CAAC,OAAO,MAAM,CAAC,CAI7E"}

package/dist/contextLift.js

@@ -0,0 +1,172 @@
+// Phase 5.13 helpers: compound-local context lift.
+//
+// Spec: docs/specs/004-tasks.md Phase 5.13,
+// docs/specs/004-xstate-agent-wrapper.md §"Lexical scoping of context"
+// (lines 104-111) and §Mapping line 626.
+//
+// A `CompoundMode` with `context: { inherit, local }` exposes a narrowed view
+// to its children: `Pick<TParent, inherit[number]> & typeof local`. At runtime the
+// wrapper materializes this view by:
+//   - allocating a slot under a generated root-context key (`__<path>_local`)
+//     initialized to `local` on every entry, cleared on every exit
+//   - wrapping each child callback (`input`, `assign`, passive `guard`) so
+//     the `context` they see is the virtual merged view, and any `Partial`
+//     they return is split back to the correct destination
+//
+// Inherit keys are read live from the parent (no copy on entry, no
+// project-back on exit) — writes propagate through to the owning slot in
+// the same step. Local keys live in this compound's own slot and reset
+// automatically on re-entry. Nested compounds chain: a nested `LiftContext`
+// carries a `parent` reference that the helpers walk to resolve inherit
+// reads/writes.
+//
+// The actual emission of `entry`/`exit` actions onto a lowered compound
+// shape, plus the threading of `LiftContext` through the walk, lands in
+// slice 5.16; 5.13 ships the toolkit and integrates it with
+// `buildActiveState` / `buildPassiveState` via an optional `lift` argument.
+import { assign } from "xstate";
+// Slot-name generator. Path is the compound's dotted slot
+// (e.g. `socratic.evaluating` → `__socratic_evaluating_local`). The `__`
+// prefix + `_local` suffix make collisions with user-declared agent-context
+// keys vanishingly rare; dots are replaced with `_` so the key is a valid
+// JS identifier.
+export function compoundLocalKey(path) {
+    if (path === "") {
+        throw new Error("atlas/contextLift: compoundLocalKey called with empty path");
+    }
+    const safe = path.replace(/\./g, "_");
+    return `__${safe}_local`;
+}
+function localKeys(lift) {
+    return Object.keys(lift.initialLocal);
+}
+// Build the parent's effective view from the root context. For a top-level
+// compound (no parent), the parent view IS the root context. For a nested
+// compound, recurse into the enclosing lift to materialize ITS subContext.
+function buildParentView(rootContext, parent) {
+    if (parent === undefined)
+        return rootContext;
+    return buildSubContext(rootContext, parent);
+}
+// Build the virtual subContext a child callback sees: inherit keys read
+// from the parent view (live), local keys read from this compound's slot.
+function buildSubContext(rootContext, lift) {
+    const parentView = buildParentView(rootContext, lift.parent);
+    const sub = {};
+    for (const k of lift.inherit) {
+        sub[k] = parentView[k];
+    }
+    const slot = rootContext[lift.key];
+    if (slot !== undefined && typeof slot === "object" && slot !== null) {
+        const slotRec = slot;
+        for (const k of localKeys(lift)) {
+            sub[k] = slotRec[k];
+        }
+    }
+    return sub;
+}
+// Walk up the parent chain to find which ancestor declared `key` as a
+// local. If no ancestor owns it, the key lives in the agent's root context.
+function findInheritOwner(key, parent) {
+    if (parent === undefined)
+        return { kind: "root" };
+    if (localKeys(parent).includes(key))
+        return { kind: "slot", slotKey: parent.key };
+    return findInheritOwner(key, parent.parent);
+}
+// Split the user's `Partial<combined>` return into a root-context patch
+// XState's `assign` can apply. Local writes update this compound's slot;
+// inherit writes update either the agent root or an ancestor's slot,
+// depending on where the key was declared as local.
+function splitUserUpdate(update, rootContext, lift) {
+    const ownLocals = localKeys(lift);
+    const rootPatch = {};
+    const slotPatches = {};
+    function touchSlot(slotKey, k, v) {
+        const existing = slotPatches[slotKey] ?? {};
+        existing[k] = v;
+        slotPatches[slotKey] = existing;
+    }
+    for (const [k, v] of Object.entries(update)) {
+        if (ownLocals.includes(k)) {
+            touchSlot(lift.key, k, v);
+            continue;
+        }
+        if (lift.inherit.includes(k)) {
+            const owner = findInheritOwner(k, lift.parent);
+            if (owner.kind === "root") {
+                rootPatch[k] = v;
+            }
+            else {
+                touchSlot(owner.slotKey, k, v);
+            }
+            continue;
+        }
+        // Out-of-scope key: the type system already rejected it. A bypass
+        // via `as` reaches here — drop silently rather than leak into root.
+    }
+    // XState `assign` is shallow at the root level — we must hand it the
+    // full new slot object, not a delta.
+    for (const [slotKey, patch] of Object.entries(slotPatches)) {
+        const current = (rootContext[slotKey] ?? {});
+        rootPatch[slotKey] = { ...current, ...patch };
+    }
+    return rootPatch;
+}
+// Wrap a user `input({ context, deps })` callback so it sees the virtual
+// view. `deps` is captured verbatim from the closure that `compile.ts`
+// threaded down — the lift only transforms `context`.
+export function liftInput(userInput, lift, deps) {
+    return ({ context }) => {
+        const sub = buildSubContext(context, lift);
+        return userInput({ context: sub, deps });
+    };
+}
+// Wrap a user `assign({ context, payload, deps }) => Partial<combined>`
+// callback, returning an XState `assign(...)` action that applies the split
+// update. `deps` is forwarded by identity from the wrapper's closure.
+export function liftExitAssign(userAssign, lift, deps) {
+    return assign(({ context, event }) => {
+        const root = context;
+        const sub = buildSubContext(root, lift);
+        const payload = event.output.payload;
+        const update = userAssign({ context: sub, payload, deps });
+        return splitUserUpdate(update, root, lift);
+    });
+}
+// Wrap a user `assign({ context, error, deps })` callback (error routes).
+export function liftErrorAssign(userAssign, lift, deps) {
+    return assign(({ context, event }) => {
+        const root = context;
+        const sub = buildSubContext(root, lift);
+        const error = event.error;
+        const update = userAssign({ context: sub, error, deps });
+        return splitUserUpdate(update, root, lift);
+    });
+}
+// Wrap a user `guard({ context, event, deps })` (passive `on` transitions).
+export function liftGuard(userGuard, lift, deps) {
+    return ({ context, event }) => {
+        const sub = buildSubContext(context, lift);
+        return userGuard({ context: sub, event, deps });
+    };
+}
+// XState `entry` action: initialize this compound's local slot. A fresh
+// shallow copy of `initialLocal` per entry so subsequent mutations stay
+// scoped to this activation. Deep cloning is not promised — the spec's
+// canonical local is primitive-valued (`{ attempts: 0 }`); nested object
+// values are shared by reference.
+export function makeCompoundEntry(lift) {
+    return assign({
+        [lift.key]: () => ({ ...lift.initialLocal }),
+    });
+}
+// XState `exit` action: clear this compound's local slot. The next entry
+// (if any) re-initializes via `makeCompoundEntry`, satisfying the
+// reset-on-re-entry invariant from spec line 109.
+export function makeCompoundExit(lift) {
+    return assign({
+        [lift.key]: () => undefined,
+    });
+}
+//# sourceMappingURL=contextLift.js.map

package/dist/contextLift.js.map

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

package/dist/defineAgent.d.ts

@@ -0,0 +1,60 @@
+import type { AnyStateMachine } from "xstate";
+import type { AgentConfig, ModesMap } from "./types.js";
+/**
+ * Construct the **root agent** — compiles the declarative `AgentConfig` into
+ * a runnable XState machine. This is the single boundary where the wrapper
+ * touches `xstate`: the return type is `AnyStateMachine`, so callers feed it
+ * straight into `createActor`, the inspector, and existing tests.
+ *
+ * The agent's `modes` map can mix `Mode`s (leaves) and nested `CompoundMode`s
+ * freely. The compile step lowers them, validates sibling-target references,
+ * injects the `END` synthetic state per-compound when referenced, and wires
+ * the payload-driven `routes` into XState transitions.
+ *
+ * @template TContext  The agent's root context shape. Constrained to
+ *                     `JsonCompatible<TContext>` so the snapshot round-trips
+ *                     through arbitrary storage without custom encoding.
+ * @template TEvents   The agent's full event union. Each variant must have a
+ *                     `type: string` discriminant. Pass `{} as Ev` to the
+ *                     `events` field — only its type matters; it's a phantom.
+ * @template TModes    The root `modes` map. `initial` is keyed against this
+ *                     type so a typo is a compile error.
+ * @template TDeps     Frozen container of external resources. Defaults to
+ *                     `Record<string, never>` when `deps` is omitted —
+ *                     callbacks still receive `deps`, typed as the empty
+ *                     object, so the envelope shape stays uniform.
+ *
+ * @param config  `{ id, initial, context, events, deps?, actions?, modes }`.
+ *                `actions` registers reusable, deps-aware callbacks (each
+ *                returning `Partial<TContext>`) referenced by name from
+ *                passive `on[event].actions`. The wrapper wraps them in
+ *                `assign(...)` at compile time, so user code never imports
+ *                from `xstate`.
+ *
+ * @returns An `AnyStateMachine` ready to pass to `createActor`.
+ *
+ * @example
+ * ```ts
+ * const agent = defineAgent<Ctx, Ev, Modes, { db: Driver; logger: Logger }>({
+ *     id: "zoe",
+ *     initial: "listening",
+ *     context: { messages: [], attempts: 0 },
+ *     events: {} as Ev,
+ *     deps: { db: realDb, logger: pino() },
+ *     actions: {
+ *         appendUserMsg: ({ context, event, deps }) =>
+ *             event.type === "USER_MSG"
+ *                 ? { messages: [...context.messages, { role: "user", content: event.text }] }
+ *                 : {},
+ *     },
+ *     modes: { listening, classifying, greetings, socratic },
+ * });
+ *
+ * const actor = createActor(agent).start();
+ * actor.send({ type: "USER_MSG", text: "hi" });
+ * ```
+ */
+export declare function defineAgent<TContext, TEvents extends {
+    type: string;
+}, TModes extends ModesMap<TContext, TEvents, TDeps>, TDeps extends Record<string, unknown> = Record<string, never>>(config: AgentConfig<TContext, TEvents, TModes, TDeps>): AnyStateMachine;
+//# sourceMappingURL=defineAgent.d.ts.map

package/dist/defineAgent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineAgent.d.ts","sourceRoot":"","sources":["../src/defineAgent.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAG9C,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,wBAAgB,WAAW,CACvB,QAAQ,EACR,OAAO,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EAChC,MAAM,SAAS,QAAQ,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,CAAC,EACjD,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAC/D,MAAM,EAAE,WAAW,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,GAAG,eAAe,CAOxE"}