@formbar/arbiter 0.2.0

package/dist/index.cjs

@@ -0,0 +1,83 @@
+'use strict';
+
+var core = require('@arbitre/core');
+var kuery = require('kuery');
+
+// src/arbiter-plugin.ts
+
+// src/internal-paths.ts
+function isArbiterInternalPath(path) {
+  return path.startsWith("$") && !path.startsWith("$ui.");
+}
+
+// src/arbiter-plugin.ts
+function createArbiterPlugin(options) {
+  const { rules, session: externalSession } = options;
+  let session;
+  let ownsSession;
+  if (externalSession) {
+    session = externalSession;
+    ownsSession = false;
+  } else if (rules) {
+    session = core.createSession({ rules });
+    ownsSession = true;
+  } else {
+    throw new Error("createArbiterPlugin requires either `rules` or `session`");
+  }
+  return {
+    id: "arbiter",
+    evaluate(ctx) {
+      if (ctx.origin.startsWith("plugin:arbiter")) return;
+      if (!ctx.change.dataChanged && !ctx.change.uiChanged) return;
+      const data = ctx.data;
+      for (const key of Object.keys(data)) {
+        session.assert(key, data[key]);
+      }
+      const uiState = ctx.uiState;
+      for (const key of Object.keys(uiState)) {
+        session.assert(`$ui.${key}`, uiState[key]);
+      }
+      const result = session.fire();
+      const writes = [];
+      for (const change of result.changes) {
+        if (isArbiterInternalPath(change.path)) continue;
+        writes.push({
+          path: change.path,
+          value: change.newValue,
+          mode: "set"
+        });
+      }
+      const fieldMeta = {};
+      const state = session.getState();
+      for (const [path, value] of Object.entries(state)) {
+        if (!path.startsWith("$meta.")) continue;
+        const fieldPath = path.slice("$meta.".length);
+        if (typeof value === "object" && value !== null) {
+          fieldMeta[fieldPath] = value;
+        }
+      }
+      return {
+        writes: writes.length > 0 ? writes : void 0,
+        fieldMeta: Object.keys(fieldMeta).length > 0 ? fieldMeta : void 0
+      };
+    },
+    onDispose() {
+      if (ownsSession) {
+        session.dispose();
+      }
+    }
+  };
+}
+function evaluateExpression(expr, context) {
+  return kuery.evaluate(expr, context);
+}
+
+Object.defineProperty(exports, "assertSafeSegment", {
+  enumerable: true,
+  get: function () { return kuery.assertSafeSegment; }
+});
+exports.createArbiterPlugin = createArbiterPlugin;
+exports.evaluateExpression = evaluateExpression;
+exports.isArbiterInternalPath = isArbiterInternalPath;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internal-paths.ts","../src/arbiter-plugin.ts","../src/expression-utils.ts"],"names":["createSession","evaluate"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * Arbiter-internal paths start with $ and are not user-facing form data.\n * Filter them out of write intents.\n */\nexport function isArbiterInternalPath(path: string): boolean {\n\treturn path.startsWith(\"$\") && !path.startsWith(\"$ui.\");\n}\n","import { createSession } from \"@arbitre/core\";\nimport type { FiringResult, ProductionRule, RuleSession } from \"@arbitre/core\";\nimport type {\n\tFormPlugin,\n\tPluginEvaluateContext,\n\tPluginEvaluateResult,\n\tPluginFieldMeta,\n\tPluginWrite,\n} from \"@formbar/core\";\nimport { isArbiterInternalPath } from \"./internal-paths.js\";\n\nexport interface ArbiterPluginOptions {\n\t/** Provide raw rules — a session will be created internally. */\n\treadonly rules?: readonly ProductionRule[];\n\t/** Provide a pre-configured session instead of raw rules. */\n\treadonly session?: RuleSession;\n}\n\n/**\n * Creates a FormPlugin that bridges @arbitre/core into the formbar pipeline.\n * Syncs form data into the rule session, fires rules, and converts results\n * into PluginWrite[] and PluginFieldMeta records.\n */\nexport function createArbiterPlugin(options: ArbiterPluginOptions): FormPlugin {\n\tconst { rules, session: externalSession } = options;\n\n\tlet session: RuleSession;\n\tlet ownsSession: boolean;\n\n\tif (externalSession) {\n\t\tsession = externalSession;\n\t\townsSession = false;\n\t} else if (rules) {\n\t\tsession = createSession({ rules: rules as ProductionRule[] });\n\t\townsSession = true;\n\t} else {\n\t\tthrow new Error(\"createArbiterPlugin requires either `rules` or `session`\");\n\t}\n\n\treturn {\n\t\tid: \"arbiter\",\n\n\t\tevaluate(ctx: PluginEvaluateContext): PluginEvaluateResult | void {\n\t\t\t// Prevent re-entry from own writes\n\t\t\tif (ctx.origin.startsWith(\"plugin:arbiter\")) return;\n\n\t\t\t// Short-circuit when nothing relevant changed\n\t\t\tif (!ctx.change.dataChanged && !ctx.change.uiChanged) return;\n\n\t\t\t// Sync form data fields into the session\n\t\t\tconst data = ctx.data as Record<string, unknown>;\n\t\t\tfor (const key of Object.keys(data)) {\n\t\t\t\tsession.assert(key, data[key]);\n\t\t\t}\n\n\t\t\t// Sync $ui.* state\n\t\t\tconst uiState = ctx.uiState as Record<string, unknown>;\n\t\t\tfor (const key of Object.keys(uiState)) {\n\t\t\t\tsession.assert(`$ui.${key}`, uiState[key]);\n\t\t\t}\n\n\t\t\t// Fire rules\n\t\t\tconst result: FiringResult = session.fire();\n\n\t\t\t// Convert changes to PluginWrite[], filtering internal paths\n\t\t\tconst writes: PluginWrite[] = [];\n\t\t\tfor (const change of result.changes) {\n\t\t\t\tif (isArbiterInternalPath(change.path)) continue;\n\t\t\t\twrites.push({\n\t\t\t\t\tpath: change.path,\n\t\t\t\t\tvalue: change.newValue,\n\t\t\t\t\tmode: \"set\",\n\t\t\t\t});\n\t\t\t}\n\n\t\t\t// Derive field meta from session state\n\t\t\tconst fieldMeta: Record<string, PluginFieldMeta> = {};\n\t\t\tconst state = session.getState();\n\t\t\tfor (const [path, value] of Object.entries(state)) {\n\t\t\t\tif (!path.startsWith(\"$meta.\")) continue;\n\t\t\t\t// Convention: $meta.<fieldPath> holds { visible, disabled, required, readOnly, label }\n\t\t\t\tconst fieldPath = path.slice(\"$meta.\".length);\n\t\t\t\tif (typeof value === \"object\" && value !== null) {\n\t\t\t\t\tfieldMeta[fieldPath] = value as PluginFieldMeta;\n\t\t\t\t}\n\t\t\t}\n\n\t\t\treturn {\n\t\t\t\twrites: writes.length > 0 ? writes : undefined,\n\t\t\t\tfieldMeta: Object.keys(fieldMeta).length > 0 ? fieldMeta : undefined,\n\t\t\t};\n\t\t},\n\n\t\tonDispose() {\n\t\t\tif (ownsSession) {\n\t\t\t\tsession.dispose();\n\t\t\t}\n\t\t},\n\t};\n}\n","import { assertSafeSegment, evaluate } from \"kuery\";\nimport type { ExprNode } from \"kuery\";\n\n/**\n * Evaluate a kuery expression against a data context.\n * This is a convenience re-export for consumers using expressions with arbiter rules.\n */\nexport function evaluateExpression(expr: ExprNode, context: Record<string, unknown>): unknown {\n\treturn evaluate(expr, context);\n}\n\nexport { assertSafeSegment };\nexport type { ExprNode };\n"]}

package/dist/index.d.cts

@@ -0,0 +1,31 @@
+import { ProductionRule, RuleSession } from '@arbitre/core';
+import { FormPlugin } from '@formbar/core';
+import { ExprNode } from 'kuery';
+export { ExprNode, assertSafeSegment } from 'kuery';
+
+interface ArbiterPluginOptions {
+    /** Provide raw rules — a session will be created internally. */
+    readonly rules?: readonly ProductionRule[];
+    /** Provide a pre-configured session instead of raw rules. */
+    readonly session?: RuleSession;
+}
+/**
+ * Creates a FormPlugin that bridges @arbitre/core into the formbar pipeline.
+ * Syncs form data into the rule session, fires rules, and converts results
+ * into PluginWrite[] and PluginFieldMeta records.
+ */
+declare function createArbiterPlugin(options: ArbiterPluginOptions): FormPlugin;
+
+/**
+ * Evaluate a kuery expression against a data context.
+ * This is a convenience re-export for consumers using expressions with arbiter rules.
+ */
+declare function evaluateExpression(expr: ExprNode, context: Record<string, unknown>): unknown;
+
+/**
+ * Arbiter-internal paths start with $ and are not user-facing form data.
+ * Filter them out of write intents.
+ */
+declare function isArbiterInternalPath(path: string): boolean;
+
+export { type ArbiterPluginOptions, createArbiterPlugin, evaluateExpression, isArbiterInternalPath };

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+import { ProductionRule, RuleSession } from '@arbitre/core';
+import { FormPlugin } from '@formbar/core';
+import { ExprNode } from 'kuery';
+export { ExprNode, assertSafeSegment } from 'kuery';
+
+interface ArbiterPluginOptions {
+    /** Provide raw rules — a session will be created internally. */
+    readonly rules?: readonly ProductionRule[];
+    /** Provide a pre-configured session instead of raw rules. */
+    readonly session?: RuleSession;
+}
+/**
+ * Creates a FormPlugin that bridges @arbitre/core into the formbar pipeline.
+ * Syncs form data into the rule session, fires rules, and converts results
+ * into PluginWrite[] and PluginFieldMeta records.
+ */
+declare function createArbiterPlugin(options: ArbiterPluginOptions): FormPlugin;
+
+/**
+ * Evaluate a kuery expression against a data context.
+ * This is a convenience re-export for consumers using expressions with arbiter rules.
+ */
+declare function evaluateExpression(expr: ExprNode, context: Record<string, unknown>): unknown;
+
+/**
+ * Arbiter-internal paths start with $ and are not user-facing form data.
+ * Filter them out of write intents.
+ */
+declare function isArbiterInternalPath(path: string): boolean;
+
+export { type ArbiterPluginOptions, createArbiterPlugin, evaluateExpression, isArbiterInternalPath };

package/dist/index.js

@@ -0,0 +1,76 @@
+import { createSession } from '@arbitre/core';
+import { evaluate } from 'kuery';
+export { assertSafeSegment } from 'kuery';
+
+// src/arbiter-plugin.ts
+
+// src/internal-paths.ts
+function isArbiterInternalPath(path) {
+  return path.startsWith("$") && !path.startsWith("$ui.");
+}
+
+// src/arbiter-plugin.ts
+function createArbiterPlugin(options) {
+  const { rules, session: externalSession } = options;
+  let session;
+  let ownsSession;
+  if (externalSession) {
+    session = externalSession;
+    ownsSession = false;
+  } else if (rules) {
+    session = createSession({ rules });
+    ownsSession = true;
+  } else {
+    throw new Error("createArbiterPlugin requires either `rules` or `session`");
+  }
+  return {
+    id: "arbiter",
+    evaluate(ctx) {
+      if (ctx.origin.startsWith("plugin:arbiter")) return;
+      if (!ctx.change.dataChanged && !ctx.change.uiChanged) return;
+      const data = ctx.data;
+      for (const key of Object.keys(data)) {
+        session.assert(key, data[key]);
+      }
+      const uiState = ctx.uiState;
+      for (const key of Object.keys(uiState)) {
+        session.assert(`$ui.${key}`, uiState[key]);
+      }
+      const result = session.fire();
+      const writes = [];
+      for (const change of result.changes) {
+        if (isArbiterInternalPath(change.path)) continue;
+        writes.push({
+          path: change.path,
+          value: change.newValue,
+          mode: "set"
+        });
+      }
+      const fieldMeta = {};
+      const state = session.getState();
+      for (const [path, value] of Object.entries(state)) {
+        if (!path.startsWith("$meta.")) continue;
+        const fieldPath = path.slice("$meta.".length);
+        if (typeof value === "object" && value !== null) {
+          fieldMeta[fieldPath] = value;
+        }
+      }
+      return {
+        writes: writes.length > 0 ? writes : void 0,
+        fieldMeta: Object.keys(fieldMeta).length > 0 ? fieldMeta : void 0
+      };
+    },
+    onDispose() {
+      if (ownsSession) {
+        session.dispose();
+      }
+    }
+  };
+}
+function evaluateExpression(expr, context) {
+  return evaluate(expr, context);
+}
+
+export { createArbiterPlugin, evaluateExpression, isArbiterInternalPath };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internal-paths.ts","../src/arbiter-plugin.ts","../src/expression-utils.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Arbiter-internal paths start with $ and are not user-facing form data.\n * Filter them out of write intents.\n */\nexport function isArbiterInternalPath(path: string): boolean {\n\treturn path.startsWith(\"$\") && !path.startsWith(\"$ui.\");\n}\n","import { createSession } from \"@arbitre/core\";\nimport type { FiringResult, ProductionRule, RuleSession } from \"@arbitre/core\";\nimport type {\n\tFormPlugin,\n\tPluginEvaluateContext,\n\tPluginEvaluateResult,\n\tPluginFieldMeta,\n\tPluginWrite,\n} from \"@formbar/core\";\nimport { isArbiterInternalPath } from \"./internal-paths.js\";\n\nexport interface ArbiterPluginOptions {\n\t/** Provide raw rules — a session will be created internally. */\n\treadonly rules?: readonly ProductionRule[];\n\t/** Provide a pre-configured session instead of raw rules. */\n\treadonly session?: RuleSession;\n}\n\n/**\n * Creates a FormPlugin that bridges @arbitre/core into the formbar pipeline.\n * Syncs form data into the rule session, fires rules, and converts results\n * into PluginWrite[] and PluginFieldMeta records.\n */\nexport function createArbiterPlugin(options: ArbiterPluginOptions): FormPlugin {\n\tconst { rules, session: externalSession } = options;\n\n\tlet session: RuleSession;\n\tlet ownsSession: boolean;\n\n\tif (externalSession) {\n\t\tsession = externalSession;\n\t\townsSession = false;\n\t} else if (rules) {\n\t\tsession = createSession({ rules: rules as ProductionRule[] });\n\t\townsSession = true;\n\t} else {\n\t\tthrow new Error(\"createArbiterPlugin requires either `rules` or `session`\");\n\t}\n\n\treturn {\n\t\tid: \"arbiter\",\n\n\t\tevaluate(ctx: PluginEvaluateContext): PluginEvaluateResult | void {\n\t\t\t// Prevent re-entry from own writes\n\t\t\tif (ctx.origin.startsWith(\"plugin:arbiter\")) return;\n\n\t\t\t// Short-circuit when nothing relevant changed\n\t\t\tif (!ctx.change.dataChanged && !ctx.change.uiChanged) return;\n\n\t\t\t// Sync form data fields into the session\n\t\t\tconst data = ctx.data as Record<string, unknown>;\n\t\t\tfor (const key of Object.keys(data)) {\n\t\t\t\tsession.assert(key, data[key]);\n\t\t\t}\n\n\t\t\t// Sync $ui.* state\n\t\t\tconst uiState = ctx.uiState as Record<string, unknown>;\n\t\t\tfor (const key of Object.keys(uiState)) {\n\t\t\t\tsession.assert(`$ui.${key}`, uiState[key]);\n\t\t\t}\n\n\t\t\t// Fire rules\n\t\t\tconst result: FiringResult = session.fire();\n\n\t\t\t// Convert changes to PluginWrite[], filtering internal paths\n\t\t\tconst writes: PluginWrite[] = [];\n\t\t\tfor (const change of result.changes) {\n\t\t\t\tif (isArbiterInternalPath(change.path)) continue;\n\t\t\t\twrites.push({\n\t\t\t\t\tpath: change.path,\n\t\t\t\t\tvalue: change.newValue,\n\t\t\t\t\tmode: \"set\",\n\t\t\t\t});\n\t\t\t}\n\n\t\t\t// Derive field meta from session state\n\t\t\tconst fieldMeta: Record<string, PluginFieldMeta> = {};\n\t\t\tconst state = session.getState();\n\t\t\tfor (const [path, value] of Object.entries(state)) {\n\t\t\t\tif (!path.startsWith(\"$meta.\")) continue;\n\t\t\t\t// Convention: $meta.<fieldPath> holds { visible, disabled, required, readOnly, label }\n\t\t\t\tconst fieldPath = path.slice(\"$meta.\".length);\n\t\t\t\tif (typeof value === \"object\" && value !== null) {\n\t\t\t\t\tfieldMeta[fieldPath] = value as PluginFieldMeta;\n\t\t\t\t}\n\t\t\t}\n\n\t\t\treturn {\n\t\t\t\twrites: writes.length > 0 ? writes : undefined,\n\t\t\t\tfieldMeta: Object.keys(fieldMeta).length > 0 ? fieldMeta : undefined,\n\t\t\t};\n\t\t},\n\n\t\tonDispose() {\n\t\t\tif (ownsSession) {\n\t\t\t\tsession.dispose();\n\t\t\t}\n\t\t},\n\t};\n}\n","import { assertSafeSegment, evaluate } from \"kuery\";\nimport type { ExprNode } from \"kuery\";\n\n/**\n * Evaluate a kuery expression against a data context.\n * This is a convenience re-export for consumers using expressions with arbiter rules.\n */\nexport function evaluateExpression(expr: ExprNode, context: Record<string, unknown>): unknown {\n\treturn evaluate(expr, context);\n}\n\nexport { assertSafeSegment };\nexport type { ExprNode };\n"]}

package/package.json

@@ -0,0 +1,38 @@
+{
+	"name": "@formbar/arbiter",
+	"version": "0.2.0",
+	"type": "module",
+	"description": "Arbiter rule engine bridge for @formbar/core — declarative UI governance via production rules",
+	"license": "MIT",
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"require": "./dist/index.cjs"
+		}
+	},
+	"files": [
+		"dist",
+		"src"
+	],
+	"sideEffects": false,
+	"scripts": {
+		"build": "tsc --noEmit",
+		"build:dist": "tsup",
+		"test": "vitest run"
+	},
+	"dependencies": {
+		"@formbar/core": "workspace:*"
+	},
+	"peerDependencies": {
+		"@arbitre/core": ">=0.1.0",
+		"kuery": ">=2.0.0"
+	},
+	"devDependencies": {
+		"@arbitre/core": "link:@arbitre/core",
+		"kuery": "^2.0.0"
+	}
+}

package/src/__tests__/arbiter-demo18-repro.test.ts

@@ -0,0 +1,162 @@
+import type { ProductionRule } from "@arbitre/core";
+import { createForm } from "@formbar/core";
+import { describe, expect, test } from "vitest";
+import { createArbiterPlugin } from "../arbiter-plugin.js";
+
+/**
+ * Reproduction test for demo 18 (arbiter visibility).
+ * Uses the exact same rules and initial state as the demo component
+ * to verify core logic works end-to-end through createForm + arbiter plugin.
+ */
+
+interface FormData {
+	readonly country: string;
+	readonly state: string;
+	readonly province: string;
+	readonly region: string;
+}
+
+interface UiState {
+	readonly showState: boolean;
+	readonly showProvince: boolean;
+}
+
+const arbiterRules: readonly ProductionRule[] = [
+	{
+		name: "showUSState",
+		when: { country: "US" },
+		then: [{ $set: { "$ui.showState": true, "$ui.showProvince": false } }],
+	},
+	{
+		name: "showCAProvince",
+		when: { country: "CA" },
+		then: [{ $set: { "$ui.showState": false, "$ui.showProvince": true } }],
+	},
+	{
+		name: "hideRegional",
+		when: { country: { $nin: ["US", "CA"] } },
+		then: [{ $set: { "$ui.showState": false, "$ui.showProvince": false } }],
+	},
+];
+
+function makeForm() {
+	return createForm<FormData, UiState>({
+		initialData: { country: "", state: "", province: "", region: "" },
+		initialUiState: { showState: false, showProvince: false },
+		plugins: [createArbiterPlugin({ rules: arbiterRules })],
+	});
+}
+
+describe("demo 18 arbiter visibility — direct state", () => {
+	test("initial state: both hidden", () => {
+		const form = makeForm();
+		const { uiState } = form.getState();
+		expect(uiState.showState).toBe(false);
+		expect(uiState.showProvince).toBe(false);
+		form.dispose();
+	});
+
+	test("select US: showState=true, showProvince=false", () => {
+		const form = makeForm();
+		form.setValue("country", "US");
+		const { uiState } = form.getState();
+		expect(uiState.showState).toBe(true);
+		expect(uiState.showProvince).toBe(false);
+		form.dispose();
+	});
+
+	test("switch US → CA: showState=false, showProvince=true", () => {
+		const form = makeForm();
+		form.setValue("country", "US");
+		form.setValue("country", "CA");
+		const { uiState } = form.getState();
+		expect(uiState.showState).toBe(false);
+		expect(uiState.showProvince).toBe(true);
+		form.dispose();
+	});
+
+	test("switch CA → UK: both hidden", () => {
+		const form = makeForm();
+		form.setValue("country", "US");
+		form.setValue("country", "CA");
+		form.setValue("country", "UK");
+		const { uiState } = form.getState();
+		expect(uiState.showState).toBe(false);
+		expect(uiState.showProvince).toBe(false);
+		form.dispose();
+	});
+
+	test("switch UK → US: showState=true again", () => {
+		const form = makeForm();
+		form.setValue("country", "US");
+		form.setValue("country", "CA");
+		form.setValue("country", "UK");
+		form.setValue("country", "US");
+		const { uiState } = form.getState();
+		expect(uiState.showState).toBe(true);
+		expect(uiState.showProvince).toBe(false);
+		form.dispose();
+	});
+
+	test("select empty string: both hidden", () => {
+		const form = makeForm();
+		form.setValue("country", "US");
+		form.setValue("country", "");
+		const { uiState } = form.getState();
+		expect(uiState.showState).toBe(false);
+		expect(uiState.showProvince).toBe(false);
+		form.dispose();
+	});
+});
+
+describe("demo 18 arbiter visibility — subscription", () => {
+	test("subscriber sees correct uiState after each setValue", () => {
+		const form = makeForm();
+		const snapshots: UiState[] = [];
+		form.subscribe(() => {
+			snapshots.push({ ...form.getState().uiState });
+		});
+
+		form.setValue("country", "US");
+		const afterUS = snapshots[snapshots.length - 1];
+		expect(afterUS.showState).toBe(true);
+		expect(afterUS.showProvince).toBe(false);
+
+		form.setValue("country", "CA");
+		const afterCA = snapshots[snapshots.length - 1];
+		expect(afterCA.showState).toBe(false);
+		expect(afterCA.showProvince).toBe(true);
+
+		form.setValue("country", "UK");
+		const afterUK = snapshots[snapshots.length - 1];
+		expect(afterUK.showState).toBe(false);
+		expect(afterUK.showProvince).toBe(false);
+
+		form.setValue("country", "US");
+		const afterUS2 = snapshots[snapshots.length - 1];
+		expect(afterUS2.showState).toBe(true);
+		expect(afterUS2.showProvince).toBe(false);
+
+		form.setValue("country", "");
+		const afterEmpty = snapshots[snapshots.length - 1];
+		expect(afterEmpty.showState).toBe(false);
+		expect(afterEmpty.showProvince).toBe(false);
+
+		form.dispose();
+	});
+
+	test("subscriber receives notifications for every transition", () => {
+		const form = makeForm();
+		let callCount = 0;
+		form.subscribe(() => {
+			callCount++;
+		});
+
+		form.setValue("country", "US");
+		form.setValue("country", "CA");
+		form.setValue("country", "UK");
+
+		expect(callCount).toBeGreaterThanOrEqual(3);
+		form.dispose();
+	});
+});

package/src/__tests__/arbiter-integration.test.ts

@@ -0,0 +1,205 @@
+import type { ProductionRule } from "@arbitre/core";
+import { createSession } from "@arbitre/core";
+import { createForm } from "@formbar/core";
+import { describe, expect, test } from "vitest";
+import { createArbiterPlugin } from "../arbiter-plugin.js";
+
+describe("createArbiterPlugin", () => {
+	test("creates plugin from rules", () => {
+		const rules: readonly ProductionRule[] = [
+			{
+				name: "setTotal",
+				when: { qty: { $gt: 0 } },
+				then: [{ $set: { "$ui.showTotal": true } }],
+			},
+		];
+		const plugin = createArbiterPlugin({ rules });
+		expect(plugin.id).toBe("arbiter");
+		expect(plugin.evaluate).toBeInstanceOf(Function);
+	});
+
+	test("plugin writes when rules fire via form", () => {
+		const rules: readonly ProductionRule[] = [
+			{
+				name: "showDiscount",
+				when: { qty: { $gte: 10 } },
+				then: [{ $set: { "$ui.showDiscount": true } }],
+			},
+		];
+		const form = createForm({
+			initialData: { qty: 0 },
+			plugins: [createArbiterPlugin({ rules })],
+		});
+		form.setValue("qty", 15);
+		expect((form.getState().uiState as Record<string, unknown>).showDiscount).toBe(true);
+		form.dispose();
+	});
+
+	test("no writes when rules do not fire", () => {
+		const rules: readonly ProductionRule[] = [
+			{
+				name: "showDiscount",
+				when: { qty: { $gte: 10 } },
+				then: [{ $set: { "$ui.showDiscount": true } }],
+			},
+		];
+		const form = createForm({
+			initialData: { qty: 3 },
+			plugins: [createArbiterPlugin({ rules })],
+		});
+		form.setValue("qty", 5);
+		expect((form.getState().uiState as Record<string, unknown>).showDiscount).toBeUndefined();
+		form.dispose();
+	});
+});
+
+describe("createArbiterPlugin with pre-configured session", () => {
+	test("wraps a pre-configured session", () => {
+		const session = createSession({
+			rules: [{ name: "r1", when: { x: 1 }, then: [{ $set: { "$ui.y": 2 } }] }],
+		});
+		const plugin = createArbiterPlugin({ session });
+		expect(plugin.id).toBe("arbiter");
+	});
+
+	test("filters out arbiter-internal namespace changes", () => {
+		const rules: readonly ProductionRule[] = [
+			{
+				name: "internalWrite",
+				when: {},
+				then: [
+					{ $set: { "$state.counter": 1 } },
+					{ $set: { "$ui.visible": true } },
+					{ $set: { "$meta.timestamp": 999 } },
+					{ $set: { "$contributions.source": "test" } },
+					{ $set: { name: "kept" } },
+				],
+			},
+		];
+		const form = createForm({
+			initialData: { trigger: true, name: "" },
+			plugins: [createArbiterPlugin({ rules })],
+		});
+		form.setValue("trigger", false);
+		const state = form.getState();
+		// $ui writes should pass through
+		expect((state.uiState as Record<string, unknown>).visible).toBe(true);
+		// data writes should pass through
+		expect((state.data as Record<string, unknown>).name).toBe("kept");
+		form.dispose();
+	});
+});
+
+describe("createForm with arbiter plugin", () => {
+	test("form with arbiter plugin evaluates on setValue", () => {
+		const rules: readonly ProductionRule[] = [
+			{
+				name: "calcTotal",
+				when: {},
+				then: [{ $set: { "$ui.evaluated": true } }],
+			},
+		];
+		const form = createForm({
+			initialData: { qty: 0 },
+			plugins: [createArbiterPlugin({ rules })],
+		});
+		form.setValue("qty", 5);
+		const state = form.getState();
+		expect((state.uiState as Record<string, unknown>).evaluated).toBe(true);
+		form.dispose();
+	});
+
+	test("form without plugins skips expression step", () => {
+		const form = createForm({ initialData: { x: 1 } });
+		const result = form.setValue("x", 2);
+		expect(result.ok).toBe(true);
+		expect(form.getState().data).toEqual({ x: 2 });
+		form.dispose();
+	});
+
+	test("arbiter plugin can write to data namespace", () => {
+		const rules: readonly ProductionRule[] = [
+			{
+				name: "setLabel",
+				when: {},
+				then: [{ $set: { label: "computed" } }],
+			},
+		];
+		const form = createForm({
+			initialData: { name: "test", label: "" },
+			plugins: [createArbiterPlugin({ rules })],
+		});
+		form.setValue("name", "hello");
+		expect((form.getState().data as Record<string, unknown>).label).toBe("computed");
+		form.dispose();
+	});
+
+	test("form with arbiterPlugin from session", () => {
+		const session = createSession({
+			rules: [{ name: "r1", when: {}, then: [{ $set: { "$ui.ready": true } }] }],
+		});
+		const form = createForm({
+			initialData: { x: 0 },
+			plugins: [createArbiterPlugin({ session })],
+		});
+		form.setValue("x", 1);
+		expect((form.getState().uiState as Record<string, unknown>).ready).toBe(true);
+		form.dispose();
+	});
+
+	test("data writes apply to all fields including user-edited field", () => {
+		const rules: readonly ProductionRule[] = [
+			{
+				name: "resetQty",
+				when: {},
+				then: [{ $set: { qty: 0 } }],
+			},
+		];
+		const form = createForm({
+			initialData: { qty: 0, label: "" },
+			plugins: [createArbiterPlugin({ rules })],
+		});
+		form.setValue("qty", 5);
+		// Plugin writes apply unconditionally — filtering is plugin responsibility
+		expect((form.getState().data as Record<string, unknown>).qty).toBe(0);
+		form.dispose();
+	});
+
+	test("arbiter writes to OTHER fields still apply when user edits a field", () => {
+		const rules: readonly ProductionRule[] = [
+			{
+				name: "computeLabel",
+				when: {},
+				then: [{ $set: { label: "computed" } }],
+			},
+		];
+		const form = createForm({
+			initialData: { qty: 0, label: "" },
+			plugins: [createArbiterPlugin({ rules })],
+		});
+		form.setValue("qty", 5);
+		expect((form.getState().data as Record<string, unknown>).label).toBe("computed");
+		form.dispose();
+	});
+
+	test("uiState retracts when rule condition becomes false", () => {
+		const rules: readonly ProductionRule[] = [
+			{
+				name: "showDiscount",
+				when: { qty: { $gte: 10 } },
+				then: [{ $set: { "$ui.showDiscount": true } }],
+			},
+		];
+		const form = createForm({
+			initialData: { qty: 15 },
+			plugins: [createArbiterPlugin({ rules })],
+		});
+
+		form.setValue("qty", 15);
+		expect((form.getState().uiState as Record<string, unknown>).showDiscount).toBe(true);
+
+		form.setValue("qty", 3);
+		expect((form.getState().uiState as Record<string, unknown>).showDiscount).toBeUndefined();
+		form.dispose();
+	});
+});

package/src/arbiter-plugin.ts

@@ -0,0 +1,100 @@
+import { createSession } from "@arbitre/core";
+import type { FiringResult, ProductionRule, RuleSession } from "@arbitre/core";
+import type {
+	FormPlugin,
+	PluginEvaluateContext,
+	PluginEvaluateResult,
+	PluginFieldMeta,
+	PluginWrite,
+} from "@formbar/core";
+import { isArbiterInternalPath } from "./internal-paths.js";
+
+export interface ArbiterPluginOptions {
+	/** Provide raw rules — a session will be created internally. */
+	readonly rules?: readonly ProductionRule[];
+	/** Provide a pre-configured session instead of raw rules. */
+	readonly session?: RuleSession;
+}
+
+/**
+ * Creates a FormPlugin that bridges @arbitre/core into the formbar pipeline.
+ * Syncs form data into the rule session, fires rules, and converts results
+ * into PluginWrite[] and PluginFieldMeta records.
+ */
+export function createArbiterPlugin(options: ArbiterPluginOptions): FormPlugin {
+	const { rules, session: externalSession } = options;
+
+	let session: RuleSession;
+	let ownsSession: boolean;
+
+	if (externalSession) {
+		session = externalSession;
+		ownsSession = false;
+	} else if (rules) {
+		session = createSession({ rules: rules as ProductionRule[] });
+		ownsSession = true;
+	} else {
+		throw new Error("createArbiterPlugin requires either `rules` or `session`");
+	}
+
+	return {
+		id: "arbiter",
+
+		evaluate(ctx: PluginEvaluateContext): PluginEvaluateResult | void {
+			// Prevent re-entry from own writes
+			if (ctx.origin.startsWith("plugin:arbiter")) return;
+
+			// Short-circuit when nothing relevant changed
+			if (!ctx.change.dataChanged && !ctx.change.uiChanged) return;
+
+			// Sync form data fields into the session
+			const data = ctx.data as Record<string, unknown>;
+			for (const key of Object.keys(data)) {
+				session.assert(key, data[key]);
+			}
+
+			// Sync $ui.* state
+			const uiState = ctx.uiState as Record<string, unknown>;
+			for (const key of Object.keys(uiState)) {
+				session.assert(`$ui.${key}`, uiState[key]);
+			}
+
+			// Fire rules
+			const result: FiringResult = session.fire();
+
+			// Convert changes to PluginWrite[], filtering internal paths
+			const writes: PluginWrite[] = [];
+			for (const change of result.changes) {
+				if (isArbiterInternalPath(change.path)) continue;
+				writes.push({
+					path: change.path,
+					value: change.newValue,
+					mode: "set",
+				});
+			}
+
+			// Derive field meta from session state
+			const fieldMeta: Record<string, PluginFieldMeta> = {};
+			const state = session.getState();
+			for (const [path, value] of Object.entries(state)) {
+				if (!path.startsWith("$meta.")) continue;
+				// Convention: $meta.<fieldPath> holds { visible, disabled, required, readOnly, label }
+				const fieldPath = path.slice("$meta.".length);
+				if (typeof value === "object" && value !== null) {
+					fieldMeta[fieldPath] = value as PluginFieldMeta;
+				}
+			}
+
+			return {
+				writes: writes.length > 0 ? writes : undefined,
+				fieldMeta: Object.keys(fieldMeta).length > 0 ? fieldMeta : undefined,
+			};
+		},
+
+		onDispose() {
+			if (ownsSession) {
+				session.dispose();
+			}
+		},
+	};
+}

package/src/expression-utils.ts

@@ -0,0 +1,13 @@
+import { assertSafeSegment, evaluate } from "kuery";
+import type { ExprNode } from "kuery";
+
+/**
+ * Evaluate a kuery expression against a data context.
+ * This is a convenience re-export for consumers using expressions with arbiter rules.
+ */
+export function evaluateExpression(expr: ExprNode, context: Record<string, unknown>): unknown {
+	return evaluate(expr, context);
+}
+
+export { assertSafeSegment };
+export type { ExprNode };

package/src/index.ts

@@ -0,0 +1,5 @@
+export { createArbiterPlugin } from "./arbiter-plugin.js";
+export type { ArbiterPluginOptions } from "./arbiter-plugin.js";
+export { evaluateExpression, assertSafeSegment } from "./expression-utils.js";
+export type { ExprNode } from "./expression-utils.js";
+export { isArbiterInternalPath } from "./internal-paths.js";

package/src/internal-paths.ts

@@ -0,0 +1,7 @@
+/**
+ * Arbiter-internal paths start with $ and are not user-facing form data.
+ * Filter them out of write intents.
+ */
+export function isArbiterInternalPath(path: string): boolean {
+	return path.startsWith("$") && !path.startsWith("$ui.");
+}