@arcane-engine/runtime 0.1.0

package/src/state/transaction.ts

@@ -0,0 +1,280 @@
+import type { ArcaneError } from "./error.ts";
+import { createError } from "./error.ts";
+
+/** A mutation: a named, describable, applicable state change */
+export type Mutation<S> = Readonly<{
+  type: string;
+  path: string;
+  description: string;
+  apply: (state: S) => S;
+}>;
+
+// --- Core mutation primitives ---
+
+/** Set a value at a path */
+export function set<S>(path: string, value: unknown): Mutation<S> {
+  return {
+    type: "set",
+    path,
+    description: `Set ${path} to ${JSON.stringify(value)}`,
+    apply: (state: S) => setAtPath(state, path, value) as S,
+  };
+}
+
+/** Update a value at a path with a function */
+export function update<S>(
+  path: string,
+  fn: (current: unknown) => unknown,
+): Mutation<S> {
+  return {
+    type: "update",
+    path,
+    description: `Update ${path}`,
+    apply: (state: S) => {
+      const current = getAtPath(state, path);
+      return setAtPath(state, path, fn(current)) as S;
+    },
+  };
+}
+
+/** Push an item onto an array at a path */
+export function push<S>(path: string, item: unknown): Mutation<S> {
+  return {
+    type: "push",
+    path,
+    description: `Push item onto ${path}`,
+    apply: (state: S) => {
+      const arr = getAtPath(state, path);
+      if (!Array.isArray(arr)) {
+        throw new Error(`Expected array at path "${path}", got ${typeof arr}`);
+      }
+      return setAtPath(state, path, [...arr, item]) as S;
+    },
+  };
+}
+
+/** Remove items from an array at a path matching a predicate */
+export function removeWhere<S>(
+  path: string,
+  predicate: (item: unknown) => boolean,
+): Mutation<S> {
+  return {
+    type: "remove",
+    path,
+    description: `Remove matching items from ${path}`,
+    apply: (state: S) => {
+      const arr = getAtPath(state, path);
+      if (!Array.isArray(arr)) {
+        throw new Error(`Expected array at path "${path}", got ${typeof arr}`);
+      }
+      return setAtPath(
+        state,
+        path,
+        arr.filter((item) => !predicate(item)),
+      ) as S;
+    },
+  };
+}
+
+/** Remove a key from an object at a path */
+export function removeKey<S>(path: string): Mutation<S> {
+  const segments = path.split(".");
+  const key = segments.pop()!;
+  const parentPath = segments.join(".");
+
+  return {
+    type: "remove",
+    path,
+    description: `Remove key "${key}" from ${parentPath || "root"}`,
+    apply: (state: S) => {
+      const parent = parentPath ? getAtPath(state, parentPath) : state;
+      if (typeof parent !== "object" || parent === null) {
+        throw new Error(
+          `Expected object at path "${parentPath}", got ${typeof parent}`,
+        );
+      }
+      const { [key]: _, ...rest } = parent as Record<string, unknown>;
+      return (parentPath ? setAtPath(state, parentPath, rest) : rest) as S;
+    },
+  };
+}
+
+// --- Diff ---
+
+/** A single change entry */
+export type DiffEntry = Readonly<{
+  path: string;
+  from: unknown;
+  to: unknown;
+}>;
+
+/** All changes from a transaction */
+export type Diff = Readonly<{
+  entries: readonly DiffEntry[];
+}>;
+
+// --- Transaction result ---
+
+/** An effect triggered by a state change (for observer/event routing) */
+export type Effect = Readonly<{
+  type: string;
+  source: string;
+  data: Readonly<Record<string, unknown>>;
+}>;
+
+/** Result of executing a transaction */
+export type TransactionResult<S> = Readonly<{
+  state: S;
+  diff: Diff;
+  effects: readonly Effect[];
+  valid: boolean;
+  error?: ArcaneError;
+}>;
+
+/** Apply mutations atomically. All succeed or all roll back. */
+export function transaction<S>(
+  state: S,
+  mutations: readonly Mutation<S>[],
+): TransactionResult<S> {
+  try {
+    let current = state;
+    for (const mutation of mutations) {
+      current = mutation.apply(current);
+    }
+
+    const diff = computeDiff(state, current);
+
+    return {
+      state: current,
+      diff,
+      effects: [],
+      valid: true,
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      state,
+      diff: { entries: [] },
+      effects: [],
+      valid: false,
+      error: createError("TRANSACTION_FAILED", `Transaction failed: ${message}`, {
+        action: mutations.map((m) => m.description).join("; "),
+        reason: message,
+        suggestion: "Check that all paths exist and values are of expected types",
+      }),
+    };
+  }
+}
+
+/** Compute the diff between two state trees */
+export function computeDiff<S>(before: S, after: S): Diff {
+  const entries: DiffEntry[] = [];
+  diffRecursive(before, after, "", entries);
+  return { entries };
+}
+
+// --- Internal helpers ---
+
+function diffRecursive(
+  before: unknown,
+  after: unknown,
+  path: string,
+  entries: DiffEntry[],
+): void {
+  if (before === after) return;
+
+  if (
+    typeof before !== "object" ||
+    typeof after !== "object" ||
+    before === null ||
+    after === null ||
+    Array.isArray(before) !== Array.isArray(after)
+  ) {
+    entries.push({ path: path || "root", from: before, to: after });
+    return;
+  }
+
+  if (Array.isArray(before) && Array.isArray(after)) {
+    const maxLen = Math.max(before.length, after.length);
+    for (let i = 0; i < maxLen; i++) {
+      const childPath = path ? `${path}.${i}` : `${i}`;
+      if (i >= before.length) {
+        entries.push({ path: childPath, from: undefined, to: after[i] });
+      } else if (i >= after.length) {
+        entries.push({ path: childPath, from: before[i], to: undefined });
+      } else {
+        diffRecursive(before[i], after[i], childPath, entries);
+      }
+    }
+    if (before.length !== after.length) {
+      const lengthPath = path ? `${path}.length` : "length";
+      entries.push({ path: lengthPath, from: before.length, to: after.length });
+    }
+    return;
+  }
+
+  const beforeObj = before as Record<string, unknown>;
+  const afterObj = after as Record<string, unknown>;
+  const allKeys = new Set([
+    ...Object.keys(beforeObj),
+    ...Object.keys(afterObj),
+  ]);
+
+  for (const key of allKeys) {
+    const childPath = path ? `${path}.${key}` : key;
+    if (!(key in beforeObj)) {
+      entries.push({ path: childPath, from: undefined, to: afterObj[key] });
+    } else if (!(key in afterObj)) {
+      entries.push({ path: childPath, from: beforeObj[key], to: undefined });
+    } else {
+      diffRecursive(beforeObj[key], afterObj[key], childPath, entries);
+    }
+  }
+}
+
+function getAtPath(obj: unknown, path: string): unknown {
+  const segments = path.split(".");
+  let current: unknown = obj;
+
+  for (const segment of segments) {
+    if (current === null || current === undefined) return undefined;
+    if (typeof current !== "object") return undefined;
+    current = (current as Record<string, unknown>)[segment];
+  }
+
+  return current;
+}
+
+function setAtPath(obj: unknown, path: string, value: unknown): unknown {
+  const segments = path.split(".");
+
+  if (segments.length === 1) {
+    if (typeof obj !== "object" || obj === null) {
+      throw new Error(`Cannot set property "${path}" on ${typeof obj}`);
+    }
+    if (Array.isArray(obj)) {
+      const index = parseInt(segments[0], 10);
+      const result = [...obj];
+      result[index] = value;
+      return result;
+    }
+    return { ...(obj as Record<string, unknown>), [segments[0]]: value };
+  }
+
+  const [head, ...rest] = segments;
+  const restPath = rest.join(".");
+
+  if (typeof obj !== "object" || obj === null) {
+    throw new Error(`Cannot traverse into ${typeof obj} at "${head}"`);
+  }
+
+  if (Array.isArray(obj)) {
+    const index = parseInt(head, 10);
+    const result = [...obj];
+    result[index] = setAtPath(result[index], restPath, value);
+    return result;
+  }
+
+  const record = obj as Record<string, unknown>;
+  return { ...record, [head]: setAtPath(record[head], restPath, value) };
+}

package/src/state/types.test.ts

@@ -0,0 +1,33 @@
+import { describe, it, assert } from "../testing/harness.ts";
+import { entityId, generateId } from "./types.ts";
+
+describe("entityId", () => {
+  it("creates an EntityId from a string", () => {
+    const id = entityId("goblin_1");
+    assert.equal(id, "goblin_1");
+    assert.equal(typeof id, "string");
+  });
+
+  it("preserves the original string value", () => {
+    const id = entityId("player");
+    assert.equal(`${id}`, "player");
+    assert.equal(JSON.stringify(id), '"player"');
+  });
+});
+
+describe("generateId", () => {
+  it("returns a string", () => {
+    const id = generateId();
+    assert.equal(typeof id, "string");
+  });
+
+  it("generates unique ids", () => {
+    const ids = new Set(Array.from({ length: 100 }, () => generateId()));
+    assert.equal(ids.size, 100);
+  });
+
+  it("generates UUID-format strings", () => {
+    const id = generateId();
+    assert.match(id, /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
+  });
+});

package/src/state/types.ts

@@ -0,0 +1,30 @@
+/** Branded string type for entity identification */
+export type EntityId = string & { readonly __entityId: true };
+
+/** Create an EntityId from a string */
+export function entityId(id: string): EntityId {
+  return id as EntityId;
+}
+
+/** Generate a unique EntityId (uses crypto.randomUUID or counter in tests) */
+export function generateId(): EntityId {
+  return crypto.randomUUID() as EntityId;
+}
+
+/** 2D position vector (immutable) */
+export type Vec2 = Readonly<{ x: number; y: number }>;
+
+type Primitive = string | number | boolean | null | undefined;
+
+/** Deep recursive readonly — enforces immutability at the type level */
+export type DeepReadonly<T> = T extends Primitive
+  ? T
+  : T extends (infer U)[]
+    ? ReadonlyArray<DeepReadonly<U>>
+    : T extends Map<infer K, infer V>
+      ? ReadonlyMap<DeepReadonly<K>, DeepReadonly<V>>
+      : T extends Set<infer U>
+        ? ReadonlySet<DeepReadonly<U>>
+        : T extends object
+          ? { readonly [K in keyof T]: DeepReadonly<T[K]> }
+          : T;

package/src/systems/index.ts

@@ -0,0 +1,2 @@
+export type { Condition, Action, Rule, SystemDef, RuleResult, ExtendOptions } from "./types.ts";
+export { system, rule, applyRule, getApplicableRules, extend } from "./system.ts";

package/src/systems/system.test.ts

@@ -0,0 +1,217 @@
+import { describe, it, assert } from "../testing/harness.ts";
+import { system, rule, applyRule, getApplicableRules, extend } from "./system.ts";
+import type { SystemDef, Rule } from "./types.ts";
+
+type Counter = { count: number; label: string };
+
+describe("system()", () => {
+  it("creates a named system with rules", () => {
+    const r = rule<Counter>("inc").then((s) => ({ ...s, count: s.count + 1 }));
+    const sys = system("counter", [r]);
+    assert.equal(sys.name, "counter");
+    assert.equal(sys.rules.length, 1);
+    assert.equal(sys.rules[0].name, "inc");
+  });
+
+  it("creates an empty system", () => {
+    const sys = system<Counter>("empty", []);
+    assert.equal(sys.rules.length, 0);
+  });
+});
+
+describe("rule()", () => {
+  it("creates a rule with no conditions", () => {
+    const r = rule<Counter>("inc").then((s) => ({ ...s, count: s.count + 1 }));
+    assert.equal(r.name, "inc");
+    assert.equal(r.conditions.length, 0);
+    assert.equal(r.actions.length, 1);
+  });
+
+  it("creates a rule with conditions and actions", () => {
+    const r = rule<Counter>("inc-if-low")
+      .when((s) => s.count < 10)
+      .then((s) => ({ ...s, count: s.count + 1 }));
+    assert.equal(r.conditions.length, 1);
+    assert.equal(r.actions.length, 1);
+  });
+
+  it("chains multiple actions", () => {
+    const r = rule<Counter>("double-inc")
+      .then(
+        (s) => ({ ...s, count: s.count + 1 }),
+        (s) => ({ ...s, count: s.count * 2 }),
+      );
+    assert.equal(r.actions.length, 2);
+  });
+
+  it("chains multiple conditions", () => {
+    const r = rule<Counter>("guarded")
+      .when(
+        (s) => s.count > 0,
+        (s) => s.count < 100,
+      )
+      .then((s) => s);
+    assert.equal(r.conditions.length, 2);
+  });
+
+  it("creates a replacement rule", () => {
+    const r = rule<Counter>("new-inc")
+      .replaces("inc")
+      .then((s) => ({ ...s, count: s.count + 10 }));
+    assert.equal(r.replaces, "inc");
+    assert.equal(r.name, "new-inc");
+  });
+
+  it("replaces with conditions", () => {
+    const r = rule<Counter>("guarded-inc")
+      .replaces("inc")
+      .when((s) => s.count < 5)
+      .then((s) => ({ ...s, count: s.count + 1 }));
+    assert.equal(r.replaces, "inc");
+    assert.equal(r.conditions.length, 1);
+  });
+});
+
+describe("applyRule()", () => {
+  const inc = rule<Counter>("inc").then((s) => ({ ...s, count: s.count + 1 }));
+  const guarded = rule<Counter>("guarded")
+    .when((s) => s.count < 3)
+    .then((s) => ({ ...s, count: s.count + 1 }));
+  const sys = system("counter", [inc, guarded]);
+
+  it("applies an unconditional rule", () => {
+    const result = applyRule(sys, "inc", { count: 0, label: "x" });
+    assert.ok(result.ok);
+    assert.equal(result.state.count, 1);
+    assert.equal(result.ruleName, "inc");
+  });
+
+  it("applies a conditional rule when met", () => {
+    const result = applyRule(sys, "guarded", { count: 1, label: "x" });
+    assert.ok(result.ok);
+    assert.equal(result.state.count, 2);
+  });
+
+  it("rejects when condition not met", () => {
+    const result = applyRule(sys, "guarded", { count: 3, label: "x" });
+    assert.equal(result.ok, false);
+    assert.equal(result.state.count, 3);
+    assert.ok(result.error);
+    assert.equal(result.error!.code, "CONDITION_FAILED");
+  });
+
+  it("returns error for unknown rule", () => {
+    const result = applyRule(sys, "nope", { count: 0, label: "x" });
+    assert.equal(result.ok, false);
+    assert.equal(result.error!.code, "UNKNOWN_RULE");
+  });
+
+  it("chains multiple actions in order", () => {
+    const r = rule<Counter>("add-then-double")
+      .then(
+        (s) => ({ ...s, count: s.count + 3 }),
+        (s) => ({ ...s, count: s.count * 2 }),
+      );
+    const s = system("math", [r]);
+    const result = applyRule(s, "add-then-double", { count: 1, label: "x" });
+    assert.ok(result.ok);
+    assert.equal(result.state.count, 8); // (1+3)*2 = 8
+  });
+
+  it("passes args to conditions and actions", () => {
+    const r = rule<Counter>("add-n")
+      .when((_s, args) => (args.n as number) > 0)
+      .then((s, args) => ({ ...s, count: s.count + (args.n as number) }));
+    const s = system("args-test", [r]);
+    const result = applyRule(s, "add-n", { count: 5, label: "x" }, { n: 3 });
+    assert.ok(result.ok);
+    assert.equal(result.state.count, 8);
+  });
+
+  it("preserves original state on failure", () => {
+    const original = { count: 5, label: "x" };
+    const result = applyRule(sys, "guarded", original);
+    assert.equal(result.state, original);
+  });
+});
+
+describe("getApplicableRules()", () => {
+  const always = rule<Counter>("always").then((s) => s);
+  const lowOnly = rule<Counter>("low-only")
+    .when((s) => s.count < 3)
+    .then((s) => s);
+  const highOnly = rule<Counter>("high-only")
+    .when((s) => s.count >= 3)
+    .then((s) => s);
+  const sys = system("multi", [always, lowOnly, highOnly]);
+
+  it("returns all applicable rules for low count", () => {
+    const names = getApplicableRules(sys, { count: 1, label: "x" });
+    assert.deepEqual(names, ["always", "low-only"]);
+  });
+
+  it("returns all applicable rules for high count", () => {
+    const names = getApplicableRules(sys, { count: 5, label: "x" });
+    assert.deepEqual(names, ["always", "high-only"]);
+  });
+
+  it("passes args to conditions", () => {
+    const argRule = rule<Counter>("needs-flag")
+      .when((_s, args) => args.enabled === true)
+      .then((s) => s);
+    const s = system("arg-sys", [argRule]);
+    assert.deepEqual(getApplicableRules(s, { count: 0, label: "x" }, { enabled: true }), ["needs-flag"]);
+    assert.deepEqual(getApplicableRules(s, { count: 0, label: "x" }, { enabled: false }), []);
+  });
+});
+
+describe("extend()", () => {
+  const inc = rule<Counter>("inc").then((s) => ({ ...s, count: s.count + 1 }));
+  const dec = rule<Counter>("dec").then((s) => ({ ...s, count: s.count - 1 }));
+  const base = system("counter", [inc, dec]);
+
+  it("adds new rules", () => {
+    const doubleRule = rule<Counter>("double").then((s) => ({ ...s, count: s.count * 2 }));
+    const ext = extend(base, { rules: [doubleRule] });
+    assert.equal(ext.rules.length, 3);
+    assert.equal(ext.rules[2].name, "double");
+  });
+
+  it("replaces rules by name", () => {
+    const bigInc = rule<Counter>("big-inc")
+      .replaces("inc")
+      .then((s) => ({ ...s, count: s.count + 10 }));
+    const ext = extend(base, { rules: [bigInc] });
+    assert.equal(ext.rules.length, 2);
+    // First rule is replaced
+    const result = applyRule(ext, "big-inc", { count: 0, label: "x" });
+    assert.ok(result.ok);
+    assert.equal(result.state.count, 10);
+  });
+
+  it("removes rules by name", () => {
+    const ext = extend(base, { remove: ["dec"] });
+    assert.equal(ext.rules.length, 1);
+    assert.equal(ext.rules[0].name, "inc");
+  });
+
+  it("combines add, replace, and remove", () => {
+    const bigInc = rule<Counter>("big-inc")
+      .replaces("inc")
+      .then((s) => ({ ...s, count: s.count + 10 }));
+    const reset = rule<Counter>("reset").then((s) => ({ ...s, count: 0 }));
+    const ext = extend(base, {
+      rules: [bigInc, reset],
+      remove: ["dec"],
+    });
+    // inc replaced by big-inc, dec removed, reset added
+    assert.equal(ext.rules.length, 2);
+    assert.equal(ext.rules[0].name, "big-inc");
+    assert.equal(ext.rules[1].name, "reset");
+  });
+
+  it("preserves system name", () => {
+    const ext = extend(base, { rules: [] });
+    assert.equal(ext.name, "counter");
+  });
+});