@very-coffee/statespace 0.1.0

package/src/morphisms/objects.ts

@@ -0,0 +1,64 @@
+import type { MorphismError, ObjectValue, SemanticObject } from "./domain";
+import { err, ok, type Result } from "./result";
+
+/** Preserve literal object key unions from a const definition list. */
+export function defineObjects<TState extends object>() {
+  return <const TObjs extends readonly SemanticObject<TState, string>[]>(objects: TObjs): TObjs =>
+    objects;
+}
+
+export function objectByKey<TState extends object>(
+  objects: readonly SemanticObject<TState>[],
+  key: string,
+): SemanticObject<TState> | undefined {
+  return objects.find((object) => object.key === key);
+}
+
+/**
+ * Classify a state into exactly one object. Returns unclassified or ambiguous
+ * errors when zero or multiple predicates match.
+ */
+export function classify<TState extends object>(
+  state: TState,
+  objects: readonly SemanticObject<TState>[],
+): Result<ObjectValue<TState, string>, MorphismError> {
+  const matches: SemanticObject<TState>[] = [];
+  for (const object of objects) {
+    if (object.contains(state)) matches.push(object);
+  }
+  if (matches.length === 0) {
+    return err({ type: "unclassified", reason: "State is unclassified." });
+  }
+  if (matches.length > 1) {
+    return err({ type: "ambiguous", keys: matches.map((m) => m.key) });
+  }
+  const match = matches[0];
+  if (!match) {
+    return err({ type: "unclassified", reason: "State is unclassified." });
+  }
+  return ok({ object: match.key, state });
+}
+
+/**
+ * Classify and require a specific source key (wrong-source when classified
+ * elsewhere).
+ */
+export function classifyAs<TState extends object, K extends string>(
+  state: TState,
+  objects: readonly SemanticObject<TState>[],
+  expected: K,
+): Result<ObjectValue<TState, K>, MorphismError> {
+  if (!objectByKey(objects, expected)) {
+    return err({ type: "unknown-object", key: expected });
+  }
+  const classified = classify(state, objects);
+  if (!classified.ok) return classified;
+  if (classified.value.object !== expected) {
+    return err({
+      type: "wrong-source",
+      expected,
+      actual: classified.value.object,
+    });
+  }
+  return ok({ object: expected, state: classified.value.state });
+}

package/src/morphisms/result.ts

@@ -0,0 +1,22 @@
+export type Result<T, E> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly error: E };
+
+export function ok<T>(value: T): Result<T, never> {
+  return { ok: true, value };
+}
+
+export function err<E>(error: E): Result<never, E> {
+  return { ok: false, error };
+}
+
+export function flatMap<T, U, E>(
+  result: Result<T, E>,
+  fn: (value: T) => Result<U, E>,
+): Result<U, E> {
+  return result.ok ? fn(result.value) : result;
+}
+
+export function mapError<T, E, F>(result: Result<T, E>, fn: (error: E) => F): Result<T, F> {
+  return result.ok ? result : err(fn(result.error));
+}

package/src/path/adapters.ts

@@ -0,0 +1,126 @@
+import type { IPathRepository, Path, Value } from "./domain";
+
+export const PathRepository: IPathRepository = {
+  paths: (object, prefix = "") => {
+    type TState = typeof object;
+    type TPath = Path<TState>;
+
+    const _paths: TPath[] = [];
+
+    for (const key in object) {
+      if (Object.hasOwn(object, key)) {
+        const currentPath = prefix ? `${prefix}.${key}` : key;
+        _paths.push(currentPath as TPath);
+
+        const value = object[key];
+        if (value && typeof value === "object") {
+          if (Array.isArray(value)) {
+            // Add array indexing paths
+            for (let i = 0; i < value.length; i++) {
+              const indexPath = `${currentPath}[${i}]`;
+              _paths.push(indexPath as TPath);
+
+              // If array element is an object, recursively add its paths
+              if (value[i] && typeof value[i] === "object" && !Array.isArray(value[i])) {
+                _paths.push(...PathRepository.paths(value[i] as object, indexPath));
+              }
+            }
+          } else {
+            // Regular object traversal
+            _paths.push(...PathRepository.paths(value as object, currentPath));
+          }
+        }
+      }
+    }
+
+    return _paths;
+  },
+
+  isPath: (path, object) => {
+    if (path === ".") {
+      return false;
+    }
+    return (PathRepository.paths(object) as string[]).includes(path);
+  },
+
+  isPathRef: (maybeRef, state) =>
+    typeof maybeRef === "string" &&
+    maybeRef.startsWith("$") &&
+    PathRepository.isPath(maybeRef.slice(1), state),
+
+  valueFromPath: (path, state) => {
+    type TState = typeof state;
+    type TPath = typeof path;
+    type TValue = Value<TState, TPath>;
+
+    // Parse path segments that can include array indexing
+    const segments = PathRepository.parsePathSegments(path);
+
+    let current: unknown = state;
+    for (const segment of segments) {
+      if (segment.type === "property") {
+        if (current && typeof current === "object" && segment.key in current) {
+          current = (current as Record<string, unknown>)[segment.key];
+        } else {
+          throw new Error(`Invalid path: ${path}`);
+        }
+      } else if (segment.type === "index") {
+        if (Array.isArray(current) && segment.index >= 0 && segment.index < current.length) {
+          current = current[segment.index];
+        } else {
+          throw new Error(`Invalid path: ${path}`);
+        }
+      }
+    }
+
+    return current as TValue;
+  },
+
+  // Helper method to parse path segments
+  parsePathSegments: (path: string) => {
+    const segments: Array<{ type: "property"; key: string } | { type: "index"; index: number }> =
+      [];
+    let i = 0;
+
+    while (i < path.length) {
+      if (path[i] === "[") {
+        // Parse array index
+        const start = i + 1;
+        const end = path.indexOf("]", start);
+        if (end === -1) {
+          throw new Error(`Invalid path: unclosed bracket in ${path}`);
+        }
+        const indexStr = path.slice(start, end);
+        const index = parseInt(indexStr, 10);
+        if (Number.isNaN(index)) {
+          throw new Error(`Invalid path: non-numeric array index in ${path}`);
+        }
+        segments.push({ type: "index", index });
+        i = end + 1;
+
+        // Skip dot after bracket if present
+        if (i < path.length && path[i] === ".") {
+          i++;
+        }
+      } else {
+        // Parse property name
+        let end = i;
+        while (end < path.length && path[end] !== "." && path[end] !== "[") {
+          end++;
+        }
+        const key = path.slice(i, end);
+        if (key) {
+          segments.push({ type: "property", key });
+        }
+        i = end;
+
+        // Skip dot
+        if (i < path.length && path[i] === ".") {
+          i++;
+        }
+      }
+    }
+
+    return segments;
+  },
+};

package/src/path/domain.ts

@@ -0,0 +1,54 @@
+export type Path<TState> = TState extends object
+  ? {
+      [K in keyof TState]-?: K extends string
+        ? TState[K] extends object
+          ? TState[K] extends (infer U)[]
+            ? K | `${K}[${number}]` | `${K}[${number}].${Path<U>}`
+            : K | `${K}.${Path<TState[K]>}`
+          : K
+        : never;
+    }[keyof TState]
+  : never;
+
+export type Value<TState, TPath extends string> = TPath extends `${infer K}[${string}].${infer R}`
+  ? K extends keyof TState
+    ? TState[K] extends (infer U)[]
+      ? Value<U, R>
+      : never
+    : never
+  : TPath extends `${infer K}[${string}]`
+    ? K extends keyof TState
+      ? TState[K] extends (infer U)[]
+        ? U
+        : never
+      : never
+    : TPath extends `${infer K}.${infer R}`
+      ? K extends keyof TState
+        ? Value<TState[K], R>
+        : never
+      : TPath extends keyof TState
+        ? TState[TPath]
+        : never;
+
+export type PathReference<TState extends object, TPath extends Path<TState>> = `$${TPath}`;
+
+export interface IPathRepository {
+  readonly paths: <TState extends object>(state: TState, prefix?: string) => Path<TState>[];
+
+  readonly isPath: <TState extends object, TPath extends string>(
+    path: TPath,
+    state: TState,
+  ) => boolean;
+
+  // TODO: return errors
+  readonly isPathRef: <TState extends object>(maybeRef: unknown, state: TState) => boolean;
+
+  readonly valueFromPath: <TState extends object, TPath extends Path<TState> = Path<TState>>(
+    path: TPath,
+    state: TState,
+  ) => Value<TState, TPath>;
+
+  readonly parsePathSegments: (
+    path: string,
+  ) => Array<{ type: "property"; key: string } | { type: "index"; index: number }>;
+}

package/src/path/index.ts

@@ -0,0 +1,2 @@
+export * from "./adapters";
+export * from "./domain";

package/src/statespace/adapters.ts

@@ -0,0 +1,54 @@
+import Ajv from "ajv";
+import { TransitionRepository } from "../transition/adapters";
+import type { TransitionFn, TransitionSuccess } from "../transition/domain";
+import type { ExecutableStateSpace, IStateSpaceRepository, StateSpace } from "./domain";
+
+const ajv = new Ajv({
+  strict: false,
+  validateSchema: false,
+});
+
+export const StateSpaceRepository: IStateSpaceRepository = {
+  makeExecutable: <TState extends object>(
+    stateSpace: StateSpace<TState>,
+  ): ExecutableStateSpace<TState> => {
+    const validator = ajv.compile(stateSpace.shape);
+    const byName = new Map<string, TransitionFn<TState>>();
+
+    for (const transition of stateSpace.transitions) {
+      if (byName.has(transition.name)) {
+        throw new Error(`Duplicate transition name: ${transition.name}`);
+      }
+      byName.set(transition.name, TransitionRepository.makeExecutable(transition, validator));
+    }
+
+    const apply: ExecutableStateSpace<TState>["apply"] = (state, name, context) => {
+      const fn = byName.get(name);
+      if (!fn) {
+        return {
+          success: false,
+          name,
+          state,
+          error: `Unknown transition: ${name}`,
+        };
+      }
+      return fn(state, context);
+    };
+
+    return {
+      shape: stateSpace.shape,
+      transitions: stateSpace.transitions,
+      apply,
+      enabled: (state, context) => {
+        const neighbors: TransitionSuccess<TState>[] = [];
+        for (const transition of stateSpace.transitions) {
+          const result = apply(state, transition.name, context);
+          if (result.success) {
+            neighbors.push(result);
+          }
+        }
+        return neighbors;
+      },
+    };
+  },
+};

package/src/statespace/domain.ts

@@ -0,0 +1,61 @@
+import type { JSONSchemaType } from "ajv";
+import type { Transition, TransitionResult, TransitionSuccess } from "../transition/domain";
+
+export type Schema<T> = JSONSchemaType<T>;
+
+export type StateSpace<TState extends object> = {
+  shape: Schema<TState>;
+  transitions: Transition<TState>[];
+};
+
+export interface ExecutableStateSpace<TState extends object> {
+  shape: Schema<TState>;
+  transitions: Transition<TState>[];
+  apply(state: TState, name: string, context?: unknown): TransitionResult<TState>;
+  enabled(state: TState, context?: unknown): TransitionSuccess<TState>[];
+}
+
+/**
+ * State space with the state parameter erased.
+ * Use for heterogeneous registries (catalogs, kernels) where many
+ * StateSpace<T_i> share one Map. Not a covariant subtype of StateSpace<object>.
+ *
+ * Prefer `StateSpace<T>` at machine definition sites. Use `AnyStateSpace` /
+ * `eraseStateSpace` only when putting spaces into a mixed collection.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: intentional erase for heterogeneous registries
+export type AnyStateSpace = StateSpace<any>;
+
+/**
+ * Erase T for registry storage. Prefer this over casting to StateSpace<object>.
+ * Accepts a structural shape so unions of StateSpace<T_i> type-check
+ * (AJV JSONSchemaType blocks StateSpace<T> assigning to StateSpace<any> otherwise).
+ */
+export function eraseStateSpace(space: {
+  readonly shape: unknown;
+  readonly transitions: readonly unknown[];
+}): AnyStateSpace {
+  return space as AnyStateSpace;
+}
+
+/**
+ * Executable state space with the state parameter erased.
+ * Same registry use case as AnyStateSpace. Calling apply/enabled on an erased
+ * space means you are responsible for passing a state that matches the original T.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: intentional erase for heterogeneous registries
+export type AnyExecutableStateSpace = ExecutableStateSpace<any>;
+
+/** Erase T for registry storage. Prefer this over casting to ExecutableStateSpace<object>. */
+export function eraseExecutableStateSpace<TState extends object>(
+  space: ExecutableStateSpace<TState>,
+): AnyExecutableStateSpace {
+  // AJV JSONSchemaType keeps Schema<T> from assigning to Schema<any>; erase here.
+  return space as AnyExecutableStateSpace;
+}
+
+export interface IStateSpaceRepository {
+  readonly makeExecutable: <TState extends object>(
+    stateSpace: StateSpace<TState>,
+  ) => ExecutableStateSpace<TState>;
+}

package/src/statespace/index.ts

@@ -0,0 +1,2 @@
+export * from "./adapters";
+export * from "./domain";

package/src/studies/bfs.ts

@@ -0,0 +1,96 @@
+import { type ICompare, PriorityQueue } from "@datastructures-js/priority-queue";
+import type { StudyConfig, StudyResult } from "../explorer";
+import type { TransitionResult, TransitionSuccess } from "../transition/domain";
+
+export interface BFSConfig<T extends object> extends StudyConfig<T> {
+  comparator?: ICompare<TransitionResult<T>>;
+}
+
+export interface BFSResult<T extends object> extends StudyResult<T> {
+  reconstructPath?: (goalStateHash: string) => Promise<TransitionSuccess<T>[]>;
+}
+
+export async function bfs<T extends object>({
+  explorer,
+  initialState,
+  exitConditions,
+  context,
+  comparator = (a, b) => (a.effect?.cost ?? 0) - (b.effect?.cost ?? 0),
+}: BFSConfig<T>): Promise<BFSResult<T>> {
+  explorer.resetState();
+
+  const queue = new PriorityQueue<TransitionSuccess<T>>(comparator);
+  const visited = new Set<string>();
+  const parents = new Map<string, { parentHash: string; transition: TransitionSuccess<T> }>();
+
+  const initialHash = await explorer.encode(initialState);
+  visited.add(initialHash);
+
+  const initialNeighbors = await explorer.neighbors(initialState, context);
+  for (const neighbor of initialNeighbors) {
+    if (neighbor.result.success) {
+      queue.enqueue(neighbor.result);
+      parents.set(neighbor.hash, {
+        parentHash: initialHash,
+        transition: neighbor.result,
+      });
+    }
+  }
+
+  const reconstructPath = async (goalStateHash: string): Promise<TransitionSuccess<T>[]> => {
+    const path: TransitionSuccess<T>[] = [];
+    let currentHash = goalStateHash;
+
+    while (parents.has(currentHash)) {
+      const parent = parents.get(currentHash);
+      if (!parent) break;
+      path.unshift(parent.transition);
+      currentHash = parent.parentHash;
+    }
+
+    return path;
+  };
+
+  let lastTransition: TransitionResult<T> | null = null;
+
+  while (!queue.isEmpty()) {
+    const current = queue.dequeue();
+    if (!current) break;
+    lastTransition = current;
+
+    // Check async or sync exit conditions
+    for (const exitCondition of exitConditions) {
+      const maybeExit = exitCondition(explorer) as
+        | StudyResult<T>
+        | null
+        | Promise<StudyResult<T> | null>;
+
+      const exitResult = await Promise.resolve(maybeExit);
+      if (exitResult) {
+        return {
+          ...exitResult,
+          reconstructPath,
+        };
+      }
+    }
+
+    const currentHash = await explorer.encode(current.state);
+    if (visited.has(currentHash)) continue;
+    visited.add(currentHash);
+
+    const neighbors = await explorer.neighbors(current.state, context);
+    for (const neighbor of neighbors) {
+      const { result, hash } = neighbor;
+      if (result.success && !visited.has(hash)) {
+        queue.enqueue(result);
+        parents.set(hash, { parentHash: currentHash, transition: result });
+      }
+    }
+  }
+
+  return {
+    lastTransition: lastTransition,
+    exitReason: "Search exhausted without meeting exit conditions",
+    reconstructPath,
+  };
+}

package/src/studies/dfs.ts

@@ -0,0 +1,10 @@
+import type { StudyConfig, StudyResult } from "../explorer";
+
+export interface DFSConfig<T extends object> extends StudyConfig<T> {}
+
+/**
+ * DFS implementation that follows one path deeply before backtracking.
+ */
+export async function dfs<T extends object>(_config: DFSConfig<T>): Promise<StudyResult<T>> {
+  throw new Error("DFS is not implemented");
+}

package/src/transition/adapters.ts

@@ -0,0 +1,78 @@
+import { ConstraintRepository } from "../constraint/adapters";
+import { EffectRepository } from "../effect/adapters";
+import type { ITransitionRepository, TransitionFailure, TransitionSuccess } from "./domain";
+
+export const TransitionRepository: ITransitionRepository = {
+  apply: (state, transition, validator, context) =>
+    TransitionRepository.makeExecutable(transition, validator)(state, context),
+
+  validateConstraints: (phase, constraints, state) => {
+    const constrainstOfPhase = constraints.filter((constraint) => constraint.phase === phase);
+    try {
+      return constrainstOfPhase.every((constraint) => {
+        const result = ConstraintRepository.apply(constraint, state, constraint.path, phase);
+        return result.success;
+      });
+    } catch (_error) {
+      return false;
+    }
+  },
+
+  makeExecutable: (transition, validator) => (state, context) => {
+    const { effect, constraints } = transition;
+
+    type TState = typeof state;
+
+    const isValidBefore = TransitionRepository.validateConstraints(
+      "before_transition",
+      constraints,
+      state,
+    );
+
+    if (!isValidBefore) {
+      return {
+        success: false,
+        name: transition.name,
+        state,
+        error: "Constraints failed before transition",
+        effect: effect,
+      } satisfies TransitionFailure<TState>;
+    }
+
+    const result = EffectRepository.apply(state, transition, validator, context);
+
+    if (!result.success) {
+      return {
+        success: false,
+        name: transition.name,
+        state,
+        error: result.error,
+        effect: effect,
+      } satisfies TransitionFailure<TState>;
+    }
+
+    // Check after constraints
+    const isValidAfter = TransitionRepository.validateConstraints(
+      "after_transition",
+      constraints,
+      result.state,
+    );
+
+    if (!isValidAfter) {
+      return {
+        success: false,
+        name: transition.name,
+        state,
+        error: "Constraints failed after transition",
+        effect: effect,
+      } satisfies TransitionFailure<TState>;
+    }
+
+    return {
+      success: true,
+      name: transition.name,
+      state: result.state,
+      effect: effect,
+    } satisfies TransitionSuccess<TState>;
+  },
+} as const;

package/src/transition/domain.ts

@@ -0,0 +1,51 @@
+import type { Constraint } from "../constraint/domain";
+import type { Effect } from "../effect/domain";
+
+export interface Transition<TState extends object> {
+  name: string;
+  effect: Effect<TState>;
+  constraints: Constraint<TState>[]; // Constraints could point to any path of state, not exclusively TPath
+}
+
+export type TransitionFn<TState extends object> = (
+  state: TState,
+  context?: unknown,
+) => TransitionResult<TState>;
+
+export type TransitionSuccess<TState extends object> = {
+  success: true;
+  name: string;
+  state: TState;
+  effect: Effect<TState>;
+};
+export type TransitionFailure<TState extends object> = {
+  success: false;
+  name: string;
+  state: TState;
+  error: string;
+  effect?: Effect<TState>;
+};
+
+export type TransitionResult<TState extends object> =
+  | TransitionSuccess<TState>
+  | TransitionFailure<TState>;
+
+export interface ITransitionRepository {
+  readonly apply: <TState extends object>(
+    state: TState,
+    transition: Transition<TState>,
+    validator: (state: TState) => boolean,
+    context?: unknown,
+  ) => TransitionResult<TState>;
+
+  readonly makeExecutable: <TState extends object>(
+    transition: Transition<TState>,
+    validator: (state: TState) => boolean,
+  ) => TransitionFn<TState>;
+
+  readonly validateConstraints: <TState extends object>(
+    phase: "before_transition" | "after_transition",
+    constraints: Constraint<TState>[],
+    state: TState,
+  ) => boolean;
+}

package/src/transition/index.ts

@@ -0,0 +1,2 @@
+export * from "./adapters";
+export * from "./domain";