@very-coffee/statespace 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Zach Garrett
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+# @very-coffee/statespace
+
+## Typing / registries
+
+Prefer `StateSpace<T>` at machine definition sites. Use `AnyStateSpace` / `eraseStateSpace` (and the executable parallels) only when putting spaces into a mixed collection. Calling `apply` / `enabled` on an erased space means you are responsible for passing a state that matches the original `T`.
+
+## Effects
+
+Path-focused effects (`set`, numeric, string ops) keep a `path`. Whole-state transforms do not:
+
+```ts
+effect: {
+  operation: "transform",
+  transform: (state, context?) => ({ success: true, state: next }),
+}
+```
+
+**Breaking:** the previous `{ path, operation: "transform", value: (path, state, context) => … }` shape is removed. Explorer edge metadata `path` is optional and omitted for transforms.
+
+## Morphisms (optional)
+
+Import from `@very-coffee/statespace/morphisms` (not the package root).
+
+Semantic **objects** are named regions (`contains` predicates). **Arrows** are Kleisli morphisms: total functions into `Result` that carry certified `ObjectValue` witnesses. Availability and validation failures are typed `MorphismError`s. Category operations are total: compatible arrows always compose; identity laws hold via Result chaining.
+
+```ts
+import {
+  classify,
+  composeArrows,
+  createMorphismSpace,
+  defineMorphisms,
+  defineObjects,
+  identityArrow,
+  instantiate,
+  ok,
+} from "@very-coffee/statespace/morphisms";
+import type { Schema } from "@very-coffee/statespace";
+
+type Tip = { tip: "idle" | "ready"; value: number };
+
+const shape = {
+  type: "object",
+  properties: {
+    tip: { type: "string", enum: ["idle", "ready"] },
+    value: { type: "number" },
+  },
+  required: ["tip", "value"],
+  additionalProperties: false,
+} as unknown as Schema<Tip>;
+
+const objects = defineObjects<Tip>()([
+  { key: "idle", contains: (s) => s.tip === "idle" },
+  { key: "ready", contains: (s) => s.tip === "ready" },
+]);
+
+const armDef = {
+  name: "arm",
+  source: "idle" as const,
+  target: "ready" as const,
+  run: (v: { state: Tip }) => ok({ ...v.state, tip: "ready" as const }),
+};
+
+const arm = instantiate(armDef, undefined, objects);
+const space = createMorphismSpace({
+  shape,
+  objects,
+  morphisms: [arm],
+});
+```
+
+- `instantiate(def, params, objects, instanceName?)` closes parameters into a concrete arrow (use `instanceName` when params distinguish transitions).
+- `composeArrows([...])` returns a composition certificate plus a single arrow; left-to-right.
+- `createMorphismSpace` compiles arrows to pathless `transform` transitions — no `effectPath`.
+- Lifecycle/UI metadata (phase, labels, interpret) stays in consumer packages.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@very-coffee/statespace",
+  "version": "0.1.0",
+  "description": "Configurable framework for generating and analyzing state graphs.",
+  "license": "MIT",
+  "type": "module",
+  "module": "./src/index.ts",
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/coffee-fueled-dev/statespace.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/coffee-fueled-dev/statespace#readme",
+  "bugs": "https://github.com/coffee-fueled-dev/statespace/issues",
+  "keywords": [
+    "state-space",
+    "state-graph",
+    "exploration",
+    "pathfinding",
+    "bun"
+  ],
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    },
+    "./morphisms": {
+      "import": "./src/morphisms/index.ts",
+      "types": "./src/morphisms/index.ts"
+    }
+  },
+  "dependencies": {
+    "@datastructures-js/priority-queue": "^6.3.4",
+    "ajv": "^8.17.1",
+    "immer": "^10.1.3",
+    "queue": "^7.0.0"
+  },
+  "peerDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/codex/adapters.ts

@@ -0,0 +1,8 @@
+import type { Codex } from "./entity";
+
+// TODO: stronger codecs later (canonical JSON, content-hash + state store) if Map key size/CPU matters.
+export const jsonCodex = <T>(): Codex<T> => ({
+  key: "JSON",
+  encode: async (systemState) => JSON.stringify(systemState) ?? "null",
+  decode: async (key) => JSON.parse(key),
+});

package/src/codex/entity.ts

@@ -0,0 +1,7 @@
+export type Hash = string;
+
+export type Codex<T = unknown> = {
+  key: string;
+  encode: (systemState: T) => Promise<string>;
+  decode: (key: Hash) => Promise<T>;
+};

package/src/codex/index.ts

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

package/src/constraint/adapters.ts

@@ -0,0 +1,66 @@
+import Ajv from "ajv";
+import { PathRepository } from "../path/adapters";
+import type { IConstraintRepository } from "./domain";
+
+const ajv = new Ajv({
+  strict: false,
+  validateSchema: false,
+});
+
+export const ConstraintRepository: IConstraintRepository = {
+  apply: (constraint, state, path, phase) =>
+    ConstraintRepository.makeExecutable(constraint)(path, state, phase),
+
+  createImperative: (fn) => (path, state, phase) => {
+    const value = PathRepository.valueFromPath(path, state);
+    const result = fn(value, state);
+
+    return ConstraintRepository.formatResult({
+      isValid: result.success,
+      state,
+      phase,
+      path,
+      message: result.message,
+    });
+  },
+
+  formatResult: ({ isValid, state, phase, path, message }) => {
+    if (isValid) {
+      return {
+        success: true,
+        state,
+        phase,
+        path,
+      };
+    } else {
+      return {
+        success: false,
+        state,
+        phase,
+        path,
+        message: message || "Constraint validation failed",
+      };
+    }
+  },
+
+  makeExecutable: (constraint) => (path, state, phase) => {
+    if (typeof constraint.validation === "function") {
+      return constraint.validation(path, state, phase);
+    }
+    const value = PathRepository.valueFromPath(path, state);
+    const validator = ajv.compile(constraint.validation);
+    const isValid = validator(value);
+
+    const errorMessage =
+      validator.errors?.map((err) => `${err.instancePath} ${err.message}`).join(", ") ||
+      "Validation failed";
+
+    return ConstraintRepository.formatResult({
+      isValid,
+      state,
+      phase,
+      path,
+      message: errorMessage,
+    });
+  },
+} as const;

package/src/constraint/domain.ts

@@ -0,0 +1,61 @@
+import type { Path, Value } from "../path/domain";
+import type { Schema } from "../statespace/domain";
+
+export type ConstraintSuccess<TState extends object, TPath extends Path<TState> = Path<TState>> = {
+  success: true;
+  state: TState;
+  phase: "before_transition" | "after_transition";
+  path: TPath;
+};
+
+export type ConstraintFailure<TState extends object, TPath extends Path<TState> = Path<TState>> = {
+  success: false;
+  state: TState;
+  phase: "before_transition" | "after_transition";
+  path: TPath;
+  message?: string;
+};
+
+export type ConstraintResult<TState extends object, TPath extends Path<TState> = Path<TState>> =
+  | ConstraintSuccess<TState, TPath>
+  | ConstraintFailure<TState, TPath>;
+
+export type ConstraintFn<TState extends object, TPath extends Path<TState> = Path<TState>> = (
+  path: TPath,
+  state: TState,
+  phase: "before_transition" | "after_transition",
+) => ConstraintResult<TState, TPath>;
+
+export type Constraint<TState extends object> = {
+  [P in Path<TState>]: {
+    phase: "before_transition" | "after_transition";
+    path: P;
+    validation: Schema<Value<TState, P>> | ConstraintFn<TState, P>;
+    message?: string;
+  };
+}[Path<TState>];
+
+export interface IConstraintRepository {
+  readonly apply: <TState extends object>(
+    constraint: Constraint<TState>,
+    state: TState,
+    path: Path<TState>,
+    phase: "before_transition" | "after_transition",
+  ) => ConstraintResult<TState>;
+
+  readonly createImperative: <TState extends object, TPath extends Path<TState> = Path<TState>>(
+    fn: (value: Value<TState, TPath>, state: TState) => { success: boolean; message?: string },
+  ) => ConstraintFn<TState, TPath>;
+
+  readonly formatResult: <TState extends object, TPath extends Path<TState> = Path<TState>>(args: {
+    isValid: boolean;
+    state: TState;
+    phase: "before_transition" | "after_transition";
+    path: TPath;
+    message?: string;
+  }) => ConstraintResult<TState, TPath>;
+
+  readonly makeExecutable: <TState extends object>(
+    constraint: Constraint<TState>,
+  ) => ConstraintFn<TState>;
+}

package/src/constraint/index.ts

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

package/src/effect/adapters.ts

@@ -0,0 +1,131 @@
+import { PathRepository } from "../path/adapters";
+import type { Path, PathReference, Value } from "../path/domain";
+import type {
+  Effect,
+  EffectFailure,
+  EffectSuccess,
+  IEffectRepository,
+  PathEffect,
+  TransformEffect,
+} from "./domain";
+import { isPathEffect, isTransformEffect } from "./domain";
+import { mergeValue, validateMutation } from "./libs";
+
+export const EffectRepository: IEffectRepository = {
+  apply: (state, transition, validator, context) => {
+    try {
+      const result = EffectRepository.makeExecutable(transition.effect)(state, context);
+
+      if (!result.success) {
+        return result;
+      }
+
+      // TODO: return validation error messages if any
+      if (!validator(result.state)) {
+        return {
+          success: false,
+          error: "Malformed state after effect",
+        } satisfies EffectFailure;
+      }
+
+      return result;
+    } catch (error) {
+      let errorMessage = "Failed to apply effect";
+      if (error instanceof Error) {
+        errorMessage += `:\n${error.message}`;
+      }
+      return {
+        success: false,
+        error: errorMessage,
+      } satisfies EffectFailure;
+    }
+  },
+
+  resolveValue: (effect, state) => {
+    type TState = typeof state;
+    type TPath = Path<TState>;
+    type TValue = Value<TState, TPath>;
+
+    const maybeRef = effect.value as unknown;
+
+    if (PathRepository.isPathRef(maybeRef, state)) {
+      const pathRef = effect.value as PathReference<TState, TPath>;
+      const path = pathRef.slice(1) as TPath;
+
+      return PathRepository.valueFromPath(path, state) as TValue;
+    } else {
+      return effect.value as TValue;
+    }
+  },
+
+  makeExecutable: (effect) => (state, context) => {
+    type TState = typeof state;
+
+    if (isTransformEffect(effect as Effect<TState>)) {
+      const transformEffect = effect as TransformEffect<TState>;
+      const transformResult = transformEffect.transform(state, context);
+      if (transformResult.success) {
+        return {
+          success: true,
+          state: transformResult.state,
+        };
+      }
+      return {
+        success: false,
+        error: transformResult.error,
+      } satisfies EffectFailure;
+    }
+
+    if (!isPathEffect(effect as Effect<TState>)) {
+      throw new Error(`Invalid effect operation: ${(effect as { operation: string }).operation}`);
+    }
+
+    const pathEffect = effect as PathEffect<TState>;
+    const path = pathEffect.path as Path<TState>;
+    type TPath = typeof path;
+
+    const currentValue = PathRepository.valueFromPath(path, state);
+
+    function mergeAndValidate<TValue>(nextValue: TValue): EffectSuccess<TState> {
+      const validatedValue = validateMutation(path, state, nextValue as Value<TState, TPath>);
+      const nextState = mergeValue(state, path, validatedValue);
+
+      return {
+        success: true,
+        state: nextState,
+      };
+    }
+
+    const effectValue = EffectRepository.resolveValue(pathEffect, state);
+    switch (pathEffect.operation) {
+      case "set":
+        return mergeAndValidate(effectValue);
+
+      case "add":
+        return mergeAndValidate(Number(currentValue) + Number(effectValue));
+
+      case "subtract":
+        return mergeAndValidate(Number(currentValue) - Number(effectValue));
+
+      case "multiply":
+        return mergeAndValidate(Number(currentValue) * Number(effectValue));
+
+      case "divide":
+        return mergeAndValidate(Number(currentValue) / Number(effectValue));
+
+      case "append":
+        return mergeAndValidate(String(currentValue) + String(effectValue));
+
+      case "prepend":
+        return mergeAndValidate(String(effectValue) + String(currentValue));
+
+      case "cut":
+        return mergeAndValidate(String(currentValue).replace(String(effectValue), ""));
+
+      default:
+        throw new Error(
+          `Invalid effect operation: ${(pathEffect as { operation: string }).operation}`,
+        );
+    }
+  },
+} as const;

package/src/effect/domain.ts

@@ -0,0 +1,97 @@
+import type { Path, Value } from "../path/domain";
+import type { Transition } from "../transition/domain";
+
+export type Scalar = number | string | boolean | undefined | null;
+export type Metadata = Record<string, Scalar>;
+
+export type EffectSuccess<TState extends object> = {
+  success: true;
+  state: TState;
+  meta?: Metadata;
+};
+
+export type EffectFailure = {
+  success: false;
+  error: string;
+};
+
+export type EffectResult<TState extends object> = EffectSuccess<TState> | EffectFailure;
+
+/** Whole-state transform; receives and may replace the entire state. */
+export type TransformFn<TState extends object> = (
+  state: TState,
+  context?: unknown,
+) => EffectResult<TState>;
+
+type NumericEffect<TState extends object, P extends Path<TState>> = {
+  path: P;
+  operation: "add" | "subtract" | "multiply" | "divide";
+  value: number;
+  meta?: Metadata;
+  cost?: number;
+};
+
+type StringEffect<TState extends object, P extends Path<TState>> = {
+  path: P;
+  operation: "prepend" | "append" | "cut";
+  value: string;
+  meta?: Metadata;
+  cost?: number;
+};
+
+type SetEffect<TState extends object, P extends Path<TState>> = {
+  path: P;
+  operation: "set";
+  value: Value<TState, P> | `$${Path<TState>}`;
+  meta?: Metadata;
+  cost?: number;
+};
+
+/** Path-focused ops for a single path (no transform). */
+type EffectForPath<TState extends object, P extends Path<TState>> =
+  | SetEffect<TState, P>
+  | (Value<TState, P> extends number ? NumericEffect<TState, P> : never)
+  | (Value<TState, P> extends string ? StringEffect<TState, P> : never);
+
+export type PathEffect<TState extends object> = {
+  [P in Path<TState>]: EffectForPath<TState, P>;
+}[Path<TState>];
+
+export type TransformEffect<TState extends object> = {
+  operation: "transform";
+  transform: TransformFn<TState>;
+  meta?: Metadata;
+  cost?: number;
+};
+
+export type Effect<TState extends object> = PathEffect<TState> | TransformEffect<TState>;
+
+export function isPathEffect<TState extends object>(
+  effect: Effect<TState>,
+): effect is PathEffect<TState> {
+  return "path" in effect;
+}
+
+export function isTransformEffect<TState extends object>(
+  effect: Effect<TState>,
+): effect is TransformEffect<TState> {
+  return effect.operation === "transform";
+}
+
+export interface IEffectRepository {
+  readonly makeExecutable: <TState extends object>(
+    effect: Effect<TState>,
+  ) => (state: TState, context?: unknown) => EffectResult<TState>;
+
+  readonly apply: <TState extends object>(
+    state: TState,
+    transition: Transition<TState>,
+    validator: (state: TState) => boolean,
+    context?: unknown,
+  ) => EffectResult<TState>;
+
+  readonly resolveValue: <TState extends object>(
+    effect: PathEffect<TState>,
+    state: TState,
+  ) => Value<TState, Path<TState>>;
+}

package/src/effect/index.ts

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

package/src/effect/libs.ts

@@ -0,0 +1,97 @@
+import { produce } from "immer";
+import { PathRepository } from "../path/adapters";
+import type { Path, Value } from "../path/domain";
+
+export const mergeValue = <T extends object, P extends Path<T>>(
+  state: T,
+  path: P,
+  nextValue: Value<T, P>,
+): T => {
+  return produce(state, (draft) => {
+    const segments = PathRepository.parsePathSegments(path);
+    let current: object = draft;
+
+    const childAt = (
+      parent: object,
+      segment: { type: "property"; key: string } | { type: "index"; index: number },
+    ): object => {
+      const next =
+        segment.type === "property"
+          ? (parent as Record<string, unknown>)[segment.key]
+          : (parent as unknown[])[segment.index];
+      if (typeof next !== "object" || next === null) {
+        throw new Error(`Invalid path: ${String(path)}`);
+      }
+      return next;
+    };
+
+    for (let i = 0; i < segments.length - 1; i++) {
+      const segment = segments[i];
+      if (!segment) throw new Error(`Invalid path: ${String(path)}`);
+      current = childAt(current, segment);
+    }
+
+    const lastSegment = segments[segments.length - 1];
+    if (!lastSegment) throw new Error(`Invalid path: ${String(path)}`);
+    if (lastSegment.type === "property") {
+      (current as Record<string, unknown>)[lastSegment.key] = nextValue;
+    } else {
+      (current as unknown[])[lastSegment.index] = nextValue;
+    }
+  });
+};
+
+export const validateMutation = <T extends object, P extends Path<T>>(
+  path: P,
+  state: T,
+  nextValue: Value<T, P>,
+): Value<T, P> => {
+  if (!operationMaintainsType(nextValue, path, state)) {
+    const currentValue = PathRepository.valueFromPath(path, state);
+    throw new Error(
+      `Mutation of path '${String(
+        path,
+      )}' resulted in incompatible type. Expected ${typeof currentValue}, got ${typeof nextValue}`,
+    );
+  }
+  return nextValue;
+};
+
+const operationMaintainsType = <T extends object, P extends Path<T>>(
+  value: unknown,
+  path: P,
+  object: T,
+): value is Value<T, P> => {
+  if (!PathRepository.isPath(path, object)) {
+    return false;
+  }
+
+  // Get the current value at the path path to infer the expected type
+  const currentValue = PathRepository.valueFromPath(path, object);
+
+  // Basic runtime type checking
+  if (typeof currentValue === "number") {
+    return typeof value === "number";
+  }
+  if (typeof currentValue === "string") {
+    return typeof value === "string";
+  }
+  if (typeof currentValue === "boolean") {
+    return typeof value === "boolean";
+  }
+  if (currentValue === null) {
+    return value === null;
+  }
+  if (currentValue === undefined) {
+    return value === undefined;
+  }
+  if (typeof currentValue === "object") {
+    return typeof value === "object" && value !== null;
+  }
+  if (Array.isArray(currentValue)) {
+    return Array.isArray(value);
+  }
+
+  // For other types, just check they're the same type
+  return typeof value === typeof currentValue;
+};