@very-coffee/statespace 0.1.0

package/src/explorer/adapters.ts

@@ -0,0 +1,155 @@
+import Queue from "queue";
+import type { Codex } from "../codex/entity";
+import type { ExecutableStateSpace, Schema } from "../statespace/domain";
+import type { HashedTransition, IExplorer, MarkovChain, MarkovGraph, StudyConfig } from "./domain";
+
+export class Explorer<T extends object> implements IExplorer<T> {
+  private _graph: MarkovGraph = new Map();
+  private _uniqueStates: number = 0;
+  private _totalOperations: number = 0;
+
+  constructor(
+    private readonly stateSpace: ExecutableStateSpace<T>,
+    private readonly codex: Codex<T>,
+  ) {}
+
+  private async _processTransition(
+    name: string,
+    initialState: T,
+    transitionMap: Map<string, MarkovChain[2]>,
+    context?: unknown,
+  ): Promise<HashedTransition<T> | null> {
+    this._totalOperations++;
+    const result = this.stateSpace.apply(initialState, name, context);
+
+    if (result.success) {
+      const resultStateHash = await this.encode(result.state);
+
+      const transitionEntry = transitionMap.get(resultStateHash);
+      if (!transitionEntry) {
+        this._uniqueStates++;
+        transitionMap.set(resultStateHash, [
+          {
+            name: result.name,
+            ...("path" in result.effect ? { path: result.effect.path } : {}),
+            cost: result.effect.cost,
+            meta: result.effect.meta,
+          },
+          1,
+        ]);
+      } else {
+        transitionEntry[1]++;
+      }
+
+      return { result, hash: resultStateHash };
+    }
+
+    return null;
+  }
+
+  async neighbors(initialState: T, context?: unknown): Promise<HashedTransition<T>[]> {
+    const neighbors: HashedTransition<T>[] = [];
+    for await (const neighbor of this.neighborIterator(initialState, context)) {
+      neighbors.push(neighbor);
+    }
+
+    return neighbors;
+  }
+
+  async *neighborIterator(initialState: T, context?: unknown): AsyncGenerator<HashedTransition<T>> {
+    const initialStateHash = await this.encode(initialState);
+    let transitionMap = this._graph.get(initialStateHash);
+    if (!transitionMap) {
+      this._uniqueStates++;
+      transitionMap = new Map();
+      this._graph.set(initialStateHash, transitionMap);
+    }
+
+    // Use queue package for better async processing with streaming results
+    const results: HashedTransition<T>[] = [];
+    let processedCount = 0;
+
+    const q = new Queue({
+      concurrency: Infinity, // Process all transitions in parallel
+      autostart: true,
+      results: [],
+    });
+
+    // Add each transition as a job to the queue
+    for (const transition of this.stateSpace.transitions) {
+      q.push(async () => {
+        const hashedTransition = await this._processTransition(
+          transition.name,
+          initialState,
+          transitionMap,
+          context,
+        );
+        if (hashedTransition) {
+          results.push(hashedTransition);
+        }
+        processedCount++;
+      });
+    }
+
+    // Stream results as they become available
+    while (processedCount < this.stateSpace.transitions.length || results.length > 0) {
+      const next = results.shift();
+      if (next) {
+        yield next;
+      } else {
+        // Small delay to prevent busy waiting
+        await new Promise((resolve) => setTimeout(resolve, 1));
+      }
+    }
+  }
+
+  async encode(state: T): Promise<string> {
+    return this.codex.encode(state);
+  }
+
+  async decode(key: string): Promise<T> {
+    return this.codex.decode(key);
+  }
+
+  /**
+   * Runs a study with this explorer instance, providing a unified interface
+   * for executing different types of algorithms and studies.
+   */
+  async study<TResult>(
+    study: (config: StudyConfig<T>) => Promise<TResult>,
+    config: Omit<StudyConfig<T>, "explorer">,
+  ): Promise<TResult> {
+    // Reset internal state for clean study execution
+    this.resetState();
+
+    return await study({
+      explorer: this,
+      ...config,
+    });
+  }
+
+  /**
+   * Resets the internal state tracking for a fresh study execution
+   */
+  resetState(): void {
+    this._graph.clear();
+    this._uniqueStates = 0;
+    this._totalOperations = 0;
+  }
+
+  get graph(): MarkovGraph {
+    return this._graph;
+  }
+
+  get uniqueStates(): number {
+    return this._uniqueStates;
+  }
+
+  get totalOperations(): number {
+    return this._totalOperations;
+  }
+
+  get shape(): Schema<T> {
+    return this.stateSpace.shape;
+  }
+}

package/src/explorer/domain.ts

@@ -0,0 +1,57 @@
+import type { Hash } from "../codex/entity";
+import type { Metadata } from "../effect/domain";
+import type { Schema } from "../statespace/domain";
+import type { TransitionResult, TransitionSuccess } from "../transition/domain";
+
+export interface IExplorer<T extends object> {
+  readonly graph: MarkovGraph;
+  readonly uniqueStates: number;
+  readonly totalOperations: number;
+  readonly shape: Schema<T>;
+
+  neighbors(initialState: T, context?: unknown): Promise<HashedTransition<T>[]>;
+  neighborIterator(initialState: T, context?: unknown): AsyncGenerator<HashedTransition<T>>;
+  encode(state: T): Promise<string>;
+  decode(key: string): Promise<T>;
+  study<TResult>(
+    study: (config: StudyConfig<T>) => Promise<TResult>,
+    config: Omit<StudyConfig<T>, "explorer">,
+  ): Promise<TResult>;
+  resetState(): void;
+}
+
+export type StudyResult<T extends object> = {
+  lastTransition: TransitionResult<T> | null;
+  exitReason: string;
+};
+
+export interface StudyConfig<T extends object> {
+  explorer: IExplorer<T>;
+  initialState: T;
+  context?: unknown;
+  exitConditions: ((
+    explorer: IExplorer<T>,
+  ) => StudyResult<T> | null | Promise<StudyResult<T> | null>)[];
+}
+
+export type MarkovChain = [
+  Hash,
+  Hash,
+  [
+    {
+      name: string;
+      /** Present for path-focused effects; omitted for whole-state transforms. */
+      path?: string;
+      meta?: Metadata;
+      cost?: number | null | undefined;
+    },
+    number, // number of times this transition has been taken
+  ],
+];
+
+export type MarkovGraph = Map<MarkovChain[0], Map<MarkovChain[1], MarkovChain[2]>>;
+
+export type HashedTransition<T extends object> = {
+  result: TransitionSuccess<T>;
+  hash: Hash;
+};

package/src/explorer/index.ts

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

package/src/index.ts

@@ -0,0 +1,9 @@
+export * from "./codex";
+export * from "./constraint";
+export * from "./effect";
+export * from "./explorer";
+export * from "./path";
+export * from "./statespace";
+export * from "./studies/bfs";
+export * from "./studies/dfs";
+export * from "./transition";

package/src/morphisms/category.ts

@@ -0,0 +1,231 @@
+import type {
+  Arrow,
+  CompositionCertificate,
+  MorphismDef,
+  MorphismError,
+  ObjectValue,
+  SemanticObject,
+} from "./domain";
+import { classify, classifyAs, objectByKey } from "./objects";
+import { err, flatMap, ok, type Result } from "./result";
+
+/** Preserve literal morphism name unions from a const definition list. */
+export function defineMorphisms<TState extends object, TContext = unknown>() {
+  return <
+    const TDefs extends readonly MorphismDef<
+      TState,
+      TContext,
+      string,
+      string,
+      // biome-ignore lint/suspicious/noExplicitAny: open params slot for parameterized defs
+      any
+    >[],
+  >(
+    definitions: TDefs,
+  ): TDefs => definitions;
+}
+
+/**
+ * Seal a morphism definition with fixed params into a certified Arrow.
+ * Source membership and target closure are enforced on every run.
+ */
+export function instantiate<TState extends object, TContext, S extends string, T extends string, P>(
+  def: MorphismDef<TState, TContext, S, T, P>,
+  params: P,
+  objects: readonly SemanticObject<TState>[],
+  /** Override transition name when params distinguish instances. */
+  instanceName?: string,
+): Arrow<TState, S, T, P> {
+  if (!objectByKey(objects, def.source)) {
+    throw new Error(`Unknown source object: ${def.source}`);
+  }
+  if (!objectByKey(objects, def.target)) {
+    throw new Error(`Unknown target object: ${def.target}`);
+  }
+
+  const name = instanceName ?? def.name;
+
+  return {
+    name,
+    source: def.source,
+    target: def.target,
+    params,
+    run: (value, context) => {
+      if (value.object !== def.source) {
+        return err({
+          type: "wrong-source",
+          expected: def.source,
+          actual: value.object,
+        });
+      }
+      // Re-check live containment in case the witness is stale.
+      const sourceCheck = classifyAs(value.state, objects, def.source);
+      if (!sourceCheck.ok) return sourceCheck;
+
+      let nextState: TState;
+      try {
+        const effectResult = def.run(sourceCheck.value, context as TContext, params);
+        if (!effectResult.ok) return effectResult;
+        nextState = effectResult.value;
+      } catch (cause) {
+        return err({
+          type: "effect-failed",
+          cause: cause instanceof Error ? cause.message : String(cause),
+        });
+      }
+
+      const targetCheck = classify(nextState, objects);
+      if (!targetCheck.ok) {
+        return err({
+          type: "invalid-target",
+          expected: def.target,
+        });
+      }
+      if (targetCheck.value.object !== def.target) {
+        return err({
+          type: "invalid-target",
+          expected: def.target,
+          actual: targetCheck.value.object,
+        });
+      }
+      return ok({ object: def.target, state: nextState });
+    },
+  };
+}
+
+/** Identity endomorphism for an object key. */
+export function identityArrow<TState extends object, K extends string>(
+  objectKey: K,
+): Arrow<TState, K, K> {
+  return {
+    name: `id_${objectKey}`,
+    source: objectKey,
+    target: objectKey,
+    run: (value) => {
+      if (value.object !== objectKey) {
+        return err({
+          type: "wrong-source",
+          expected: objectKey,
+          actual: value.object,
+        });
+      }
+      return ok({ object: objectKey, state: value.state });
+    },
+  };
+}
+
+/**
+ * Compose arrows left-to-right (f then g). Compatible pairs always compose;
+ * connectivity failures yield a failed certificate and a failing apply.
+ */
+export function composeArrows<TState extends object>(
+  arrows: readonly Arrow<TState>[],
+): {
+  certificate: CompositionCertificate;
+  arrow: Arrow<TState>;
+} {
+  if (arrows.length === 0) {
+    const error = "Empty composition.";
+    return {
+      certificate: { ok: false, intermediates: [], steps: [], error },
+      arrow: {
+        name: "(empty)",
+        source: "",
+        target: "",
+        run: () => err({ type: "compose", reason: error }),
+      },
+    };
+  }
+
+  for (let i = 0; i < arrows.length - 1; i++) {
+    const left = arrows[i];
+    const right = arrows[i + 1];
+    if (!left || !right) continue;
+    if (left.target !== right.source) {
+      const reason = `Cannot compose ${left.name} → ${right.name}: ${left.target} ≠ ${right.source}`;
+      return {
+        certificate: {
+          ok: false,
+          source: arrows[0]?.source,
+          intermediates: [],
+          steps: arrows.map((a) => a.name),
+          error: reason,
+        },
+        arrow: {
+          name: `(invalid:${left.name}∘${right.name})`,
+          source: arrows[0]?.source ?? "",
+          target: arrows[arrows.length - 1]?.target ?? "",
+          run: () => err({ type: "compose", reason }),
+        },
+      };
+    }
+  }
+
+  const first = arrows[0];
+  const last = arrows[arrows.length - 1];
+  if (!first || !last) {
+    const error = "Empty composition.";
+    return {
+      certificate: { ok: false, intermediates: [], steps: [], error },
+      arrow: {
+        name: "(empty)",
+        source: "",
+        target: "",
+        run: () => err({ type: "compose", reason: error }),
+      },
+    };
+  }
+
+  const intermediates = arrows.slice(0, -1).map((a) => a.target);
+  const certificate: CompositionCertificate = {
+    ok: true,
+    source: first.source,
+    target: last.target,
+    intermediates,
+    steps: arrows.map((a) => a.name),
+  };
+
+  const arrow: Arrow<TState> = {
+    name: arrows.map((a) => a.name).join("∘"),
+    source: first.source,
+    target: last.target,
+    run: (value, context) => {
+      let current: Result<ObjectValue<TState, string>, MorphismError> = ok(value);
+      for (const step of arrows) {
+        current = flatMap(current, (v) => step.run(v, context));
+        if (!current.ok) return current;
+      }
+      return current;
+    },
+  };
+
+  return { certificate, arrow };
+}
+
+/** Binary compose: f then g (requires f.target === g.source). */
+export function compose<
+  TState extends object,
+  A extends string,
+  B extends string,
+  C extends string,
+>(f: Arrow<TState, A, B>, g: Arrow<TState, B, C>): Arrow<TState, A, C> {
+  const { certificate, arrow } = composeArrows([f, g]);
+  if (!certificate.ok) {
+    return {
+      name: `${f.name}∘${g.name}`,
+      source: f.source,
+      target: g.target,
+      run: () =>
+        err({
+          type: "compose",
+          reason: certificate.error ?? "Cannot compose",
+        }),
+    };
+  }
+  return {
+    name: arrow.name,
+    source: f.source,
+    target: g.target,
+    run: arrow.run,
+  };
+}

package/src/morphisms/compile.ts

@@ -0,0 +1,93 @@
+import type { EffectResult } from "../effect/domain";
+import { StateSpaceRepository } from "../statespace/adapters";
+import type { Schema, StateSpace } from "../statespace/domain";
+import type { Transition } from "../transition/domain";
+import type { Arrow, MorphismSpace, SemanticObject } from "./domain";
+import { formatMorphismError } from "./domain";
+import { classify } from "./objects";
+
+function toTransition<TState extends object>(
+  arrow: Arrow<TState>,
+  objects: readonly SemanticObject<TState>[],
+): Transition<TState> {
+  return {
+    name: arrow.name,
+    constraints: [],
+    effect: {
+      operation: "transform",
+      transform: (state, context) => {
+        const classified = classify(state, objects);
+        if (!classified.ok) {
+          return {
+            success: false,
+            error: formatMorphismError(classified.error),
+          } satisfies EffectResult<TState>;
+        }
+        const result = arrow.run(classified.value, context);
+        if (!result.ok) {
+          return {
+            success: false,
+            error: formatMorphismError(result.error),
+          } satisfies EffectResult<TState>;
+        }
+        return { success: true, state: result.value.state };
+      },
+    },
+  };
+}
+
+/**
+ * Compile a finite set of instantiated arrows into a StateSpace plus morphism
+ * helpers. No effectPath — transitions are whole-state transforms.
+ */
+export function createMorphismSpace<
+  TState extends object,
+  const TArrows extends readonly Arrow<TState>[],
+>(options: {
+  shape: Schema<TState>;
+  objects: readonly SemanticObject<TState>[];
+  /** Instantiated arrows; context type is whatever each arrow accepts. */
+  morphisms: TArrows;
+}): MorphismSpace<TState, TArrows> {
+  const { shape, objects, morphisms } = options;
+
+  const objectKeys = new Set(objects.map((o) => o.key));
+  if (objectKeys.size !== objects.length) {
+    throw new Error("Duplicate semantic object key.");
+  }
+
+  const seen = new Set<string>();
+  for (const arrow of morphisms) {
+    if (seen.has(arrow.name)) {
+      throw new Error(`Duplicate morphism name: ${arrow.name}`);
+    }
+    seen.add(arrow.name);
+    if (!objectKeys.has(arrow.source)) {
+      throw new Error(`Unknown source object: ${arrow.source}`);
+    }
+    if (!objectKeys.has(arrow.target)) {
+      throw new Error(`Unknown target object: ${arrow.target}`);
+    }
+  }
+
+  const byName = new Map<string, TArrows[number]>(morphisms.map((a) => [a.name, a]));
+
+  const stateSpace: StateSpace<TState> = {
+    shape,
+    transitions: morphisms.map((arrow) => toTransition(arrow, objects)),
+  };
+
+  let executable: ReturnType<typeof StateSpaceRepository.makeExecutable<TState>> | undefined;
+
+  return {
+    objects,
+    morphisms,
+    stateSpace,
+    shape,
+    arrowOf: (name) => byName.get(name),
+    makeExecutable: () => {
+      if (!executable) executable = StateSpaceRepository.makeExecutable(stateSpace);
+      return executable;
+    },
+  };
+}

package/src/morphisms/domain.ts

@@ -0,0 +1,111 @@
+import type { ExecutableStateSpace, Schema, StateSpace } from "../statespace/domain";
+import type { Result } from "./result";
+
+export type MorphismError =
+  | { type: "unavailable"; reason: string }
+  | { type: "unclassified"; reason: string }
+  | { type: "ambiguous"; keys: readonly string[] }
+  | { type: "wrong-source"; expected: string; actual: string }
+  | { type: "invalid-target"; expected: string; actual?: string }
+  | { type: "unknown-object"; key: string }
+  | { type: "effect-failed"; cause: string }
+  | { type: "compose"; reason: string };
+
+/** Certified membership of `state` in semantic object `object`. */
+export type ObjectValue<TState extends object, K extends string> = {
+  readonly object: K;
+  readonly state: TState;
+};
+
+export type SemanticObject<TState extends object, K extends string = string> = {
+  readonly key: K;
+  readonly contains: (state: TState) => boolean;
+};
+
+/**
+ * Declarative morphism. `run` returns the next raw state; the category seals
+ * source membership and target closure around it. Witness keys are `string` so
+ * heterogeneous definition lists remain assignable (source checked at seal time).
+ */
+export type MorphismDef<
+  TState extends object,
+  TContext = unknown,
+  S extends string = string,
+  T extends string = string,
+  TParams = undefined,
+> = {
+  readonly name: string;
+  readonly source: S;
+  readonly target: T;
+  readonly run: (
+    value: ObjectValue<TState, string>,
+    context: TContext,
+    params: TParams,
+  ) => Result<TState, MorphismError>;
+};
+
+/**
+ * Instantiated arrow: params closed; run is total into Result.
+ * Context stays `unknown` (same as StateSpace.apply) so arrows compose in
+ * heterogeneous lists; typed context is enforced by the sealed definition.
+ */
+export type Arrow<
+  TState extends object,
+  S extends string = string,
+  T extends string = string,
+  TParams = unknown,
+> = {
+  readonly name: string;
+  readonly source: S;
+  readonly target: T;
+  readonly params?: TParams;
+  readonly run: (
+    value: ObjectValue<TState, string>,
+    context?: unknown,
+  ) => Result<ObjectValue<TState, string>, MorphismError>;
+};
+
+export type CompositionCertificate = {
+  readonly ok: boolean;
+  readonly source?: string;
+  readonly target?: string;
+  readonly intermediates: readonly string[];
+  readonly steps: readonly string[];
+  readonly error?: string;
+};
+
+export type MorphismSpace<
+  TState extends object,
+  TArrows extends readonly Arrow<TState>[] = readonly Arrow<TState>[],
+> = {
+  readonly objects: readonly SemanticObject<TState>[];
+  readonly morphisms: TArrows;
+  readonly stateSpace: StateSpace<TState>;
+  readonly shape: Schema<TState>;
+  readonly arrowOf: (name: TArrows[number]["name"]) => TArrows[number] | undefined;
+  readonly makeExecutable: () => ExecutableStateSpace<TState>;
+};
+
+/** Format a typed morphism error for TransitionResult.error. */
+export function formatMorphismError(error: MorphismError): string {
+  switch (error.type) {
+    case "unavailable":
+      return error.reason;
+    case "unclassified":
+      return error.reason;
+    case "ambiguous":
+      return `Ambiguous region: ${error.keys.join(", ")}`;
+    case "wrong-source":
+      return `Expected region ${error.expected}, got ${error.actual}`;
+    case "invalid-target":
+      return error.actual
+        ? `Effect left region ${error.actual}; expected ${error.expected}`
+        : `Effect left unclassified region; expected ${error.expected}`;
+    case "unknown-object":
+      return `Unknown object: ${error.key}`;
+    case "effect-failed":
+      return error.cause;
+    case "compose":
+      return error.reason;
+  }
+}

package/src/morphisms/index.ts

@@ -0,0 +1,21 @@
+export {
+  compose,
+  composeArrows,
+  defineMorphisms,
+  identityArrow,
+  instantiate,
+} from "./category";
+export { createMorphismSpace } from "./compile";
+export type {
+  Arrow,
+  CompositionCertificate,
+  MorphismDef,
+  MorphismError,
+  MorphismSpace,
+  ObjectValue,
+  SemanticObject,
+} from "./domain";
+export { formatMorphismError } from "./domain";
+export { classify, classifyAs, defineObjects, objectByKey } from "./objects";
+export type { Result } from "./result";
+export { err, flatMap, mapError, ok } from "./result";