@formbar/arbiter 0.8.0 → 0.9.0

package/src/__tests__/nested-policy-sync.test.ts

@@ -0,0 +1,303 @@
+import { ArbiterError, ArbiterErrorCode, createSession } from "@arbitre/core";
+import type { ProductionRule, RuleSession } from "@arbitre/core";
+import { createForm } from "@formbar/core";
+import { describe, expect, test } from "vitest";
+import { createArbiterPlugin } from "../arbiter-plugin.js";
+import { readFieldPolicyOutput } from "../field-policy-output.js";
+
+const output = (path: string, policy: Record<string, unknown>) => ({ path, ...policy });
+
+function policyRule(name: string, when: ProductionRule["when"], entries: Record<string, unknown>): ProductionRule {
+	return { name, when, then: [{ $set: entries }] };
+}
+
+function paths(form: ReturnType<typeof createForm>): readonly (readonly (string | number)[])[] {
+	return form.getState().fieldPolicy.map((item) => item.path.segments);
+}
+
+function tick(form: ReturnType<typeof createForm>, value: number) {
+	return form.setValue("tick", value);
+}
+
+describe("Arbiter field policy output decoding", () => {
+	test("retains every property, false, empty label, producer, and lexical output order", () => {
+		const rules = [
+			policyRule(
+				"policy",
+				{ enabled: true },
+				{
+					"$formbar.fieldPolicy.z-last": output("/z", { required: true }),
+					"$formbar.fieldPolicy.a-first": output("/profile/name", {
+						visible: false,
+						disabled: false,
+						readOnly: false,
+						required: false,
+						label: "",
+					}),
+				},
+			),
+		];
+		const form = createForm({ initialData: { enabled: false, tick: 0 }, plugins: [createArbiterPlugin({ rules })] });
+
+		form.setValue("enabled", true);
+		expect(form.getState().fieldPolicy).toEqual([
+			{
+				path: { namespace: "data", segments: ["profile", "name"] },
+				producerId: "arbiter",
+				visible: false,
+				disabled: false,
+				readOnly: false,
+				required: false,
+				label: "",
+			},
+			{ path: { namespace: "data", segments: ["z"] }, producerId: "arbiter", required: true },
+		]);
+		const previous = form.getState().fieldPolicy;
+		tick(form, 1);
+		expect(form.getState().fieldPolicy).toBe(previous);
+		form.dispose();
+	});
+
+	test("normalizes nested, literal dotted, concrete array, leading-zero, and literal $ui data targets", () => {
+		const rules = [
+			policyRule(
+				"paths",
+				{ "profile.country": "US" },
+				{
+					"$formbar.fieldPolicy.array": output("/items/0/code", { disabled: true }),
+					"$formbar.fieldPolicy.dot": output("/profile.name", { readOnly: true }),
+					"$formbar.fieldPolicy.leading": output("/items/01/code", { required: true }),
+					"$formbar.fieldPolicy.nested": output("/profile/contact/email", { visible: false }),
+					"$formbar.fieldPolicy.ui-data": output("/$ui/name", { label: "Data $ui" }),
+				},
+			),
+		];
+		const form = createForm({
+			initialData: { profile: { country: "", contact: { email: "" } }, items: [{ enabled: false }], tick: 0 },
+			plugins: [createArbiterPlugin({ rules })],
+		});
+		form.setValue("profile.country", "US");
+
+		expect(paths(form)).toEqual([
+			["items", 0, "code"],
+			["profile.name"],
+			["items", "01", "code"],
+			["profile", "contact", "email"],
+			["$ui", "name"],
+		]);
+		form.setValue("profile.country", "CA");
+		expect(form.getState().fieldPolicy).toEqual([]);
+		form.dispose();
+	});
+
+	test.each([
+		["wildcard", { path: "/items/*/name", visible: true }],
+		["scope", { path: "$row.name", visible: true }],
+		["ui namespace", { path: "$ui.name", visible: true }],
+		["bad escape", { path: "/bad~2path", visible: true }],
+		["unsafe segment", { path: "/__proto__/name", visible: true }],
+	])("rejects unsupported %s target with Arbiter path diagnostics", (_name, record) => {
+		expect(() => readFieldPolicyOutput({ getPath: () => ({ target: record }) })).toThrowError(
+			expect.objectContaining<Partial<ArbiterError>>({ code: ArbiterErrorCode.INVALID_PATH }),
+		);
+	});
+
+	test("includes output ID and path in target diagnostics", () => {
+		try {
+			readFieldPolicyOutput({ getPath: () => ({ repeated: output("/items/*/name", { visible: true }) }) });
+			throw new Error("expected path rejection");
+		} catch (error) {
+			expect(error).toBeInstanceOf(ArbiterError);
+			expect((error as ArbiterError).details).toEqual({
+				root: "$formbar.fieldPolicy",
+				outputId: "repeated",
+				path: "/items/*/name",
+			});
+		}
+	});
+
+	test.each([
+		["root", []],
+		["ID", { "bad.id": output("/name", { visible: true }) }],
+		["record", { bad: null }],
+		["unknown key", { bad: output("/name", { hidden: true }) }],
+		["missing policy", { bad: { path: "/name" } }],
+		["boolean type", { bad: output("/name", { visible: 1 }) }],
+		["label type", { bad: output("/name", { label: false }) }],
+	])("rejects malformed %s with Arbiter compilation diagnostics", (_name, root) => {
+		expect(() => readFieldPolicyOutput({ getPath: () => root })).toThrowError(
+			expect.objectContaining<Partial<ArbiterError>>({ code: ArbiterErrorCode.RULE_COMPILATION_FAILED }),
+		);
+	});
+
+	test("rejects duplicate normalized targets atomically", () => {
+		const session = createSession();
+		const form = createForm({ initialData: { tick: 0 }, plugins: [createArbiterPlugin({ session })] });
+		session.assert("$formbar.fieldPolicy.good", output("/items/0/code", { visible: false }));
+		expect(tick(form, 1).ok).toBe(true);
+		session.assert("$formbar.fieldPolicy.duplicate", output("/items/00/code", { required: true }));
+		expect(tick(form, 2)).toMatchObject({ ok: true });
+		const previous = form.getState().fieldPolicy;
+		session.assert("$formbar.fieldPolicy.duplicate", output("/items/0/code", { required: true }));
+		const failed = tick(form, 3);
+		expect(failed.ok).toBe(false);
+		expect(failed.error).toContain("target the same path");
+		expect(form.getState().fieldPolicy).toBe(previous);
+		expect((form.getState().data as { tick: number }).tick).toBe(2);
+		form.dispose();
+	});
+
+	test("rejects a malformed replacement without changing the committed snapshot", () => {
+		const session = createSession();
+		const form = createForm({ initialData: { tick: 0 }, plugins: [createArbiterPlugin({ session })] });
+		session.assert("$formbar.fieldPolicy.target", output("/name", { visible: false }));
+		tick(form, 1);
+		const previous = form.getState().fieldPolicy;
+		session.assert("$formbar.fieldPolicy.target", output("/name", { visible: "no" }));
+		expect(tick(form, 2)).toMatchObject({ ok: false });
+		expect(form.getState().fieldPolicy).toBe(previous);
+		form.dispose();
+	});
+});
+
+describe("Arbiter policy snapshot synchronization", () => {
+	test("replaces moved output and clears deactivated and explicitly unset output", () => {
+		const rules: readonly ProductionRule[] = [
+			{
+				name: "move",
+				when: { active: true },
+				then: [{ $set: { "$formbar.fieldPolicy.target": output("/old", { visible: false }) } }],
+			},
+			{
+				name: "clear",
+				when: { clear: true },
+				then: [{ $unset: { "$formbar.fieldPolicy.target": true } }],
+			},
+		];
+		const session = createSession({ rules });
+		const form = createForm({
+			initialData: { active: false, clear: false, tick: 0 },
+			plugins: [createArbiterPlugin({ session })],
+		});
+		form.setValue("active", true);
+		expect(paths(form)).toEqual([["old"]]);
+		session.assert("$formbar.fieldPolicy.target", output("/new", { visible: false }));
+		tick(form, 1);
+		expect(paths(form)).toEqual([["new"]]);
+		form.setValue("clear", true);
+		expect(form.getState().fieldPolicy).toEqual([]);
+		form.dispose();
+	});
+
+	test("observes borrowed rule removal and output cessation on the next relevant tick", () => {
+		const session = createSession({
+			rules: [
+				policyRule(
+					"borrowed",
+					{ active: true },
+					{ "$formbar.fieldPolicy.borrowed": output("/name", { required: true }) },
+				),
+			],
+		});
+		const form = createForm({ initialData: { active: false, tick: 0 }, plugins: [createArbiterPlugin({ session })] });
+		form.setValue("active", true);
+		expect(form.getState().fieldPolicy).toHaveLength(1);
+		session.removeRule("borrowed");
+		tick(form, 1);
+		expect(form.getState().fieldPolicy).toEqual([]);
+		session.assert("$formbar.fieldPolicy.host", output("/host", { disabled: true }));
+		tick(form, 2);
+		expect(paths(form)).toEqual([["host"]]);
+		session.retract("$formbar.fieldPolicy.host");
+		tick(form, 3);
+		expect(form.getState().fieldPolicy).toEqual([]);
+		form.dispose();
+		expect(() => session.assert("hostOwned", true)).not.toThrow();
+		session.dispose();
+	});
+
+	test("retracts synchronized roots that disappear and resynchronizes after reset", () => {
+		const session = createSession({
+			rules: [
+				policyRule(
+					"dynamic",
+					{ dynamic: true },
+					{ "$formbar.fieldPolicy.dynamic": output("/dynamic", { visible: false }) },
+				),
+			],
+		});
+		const form = createForm({
+			initialData: { tick: 0 },
+			initialUiState: {},
+			plugins: [createArbiterPlugin({ session })],
+		});
+		form.setValue("dynamic", true);
+		form.setValue("$ui.transient", true);
+		expect(form.getState().fieldPolicy).toHaveLength(1);
+		expect(session.getPath("$ui.transient")).toBe(true);
+		form.reset();
+		expect(form.getState().fieldPolicy).toEqual([]);
+		tick(form, 1);
+		expect(session.getPath("dynamic")).toBeUndefined();
+		expect(session.getPath("$ui.transient")).toBeUndefined();
+		expect(form.getState().fieldPolicy).toEqual([]);
+		form.dispose();
+	});
+
+	test("keeps policy on skipped evaluation and disposes only owned sessions", () => {
+		const ownedPlugin = createArbiterPlugin({
+			rules: [
+				policyRule("owned", { active: true }, { "$formbar.fieldPolicy.owned": output("/name", { visible: false }) }),
+			],
+		});
+		const form = createForm({ initialData: { active: false }, plugins: [ownedPlugin] });
+		form.setValue("active", true);
+		const previous = form.getState().fieldPolicy;
+		const context = {
+			action: { type: "init" },
+			data: form.getState().data,
+			uiState: form.getState().uiState,
+			prevData: form.getState().data,
+			prevUiState: form.getState().uiState,
+			change: { type: "init", path: undefined, dataChanged: false, uiChanged: false },
+			issues: [],
+			origin: "init",
+			getValueAtPath: () => undefined,
+		} as const;
+		const skipped = ownedPlugin.evaluate?.(context);
+		expect(skipped).toBeUndefined();
+		expect(form.getState().fieldPolicy).toBe(previous);
+		form.dispose();
+		expect(() =>
+			ownedPlugin.evaluate?.({
+				...context,
+				change: { ...context.change, dataChanged: true },
+			}),
+		).toThrowError(expect.objectContaining<Partial<ArbiterError>>({ code: ArbiterErrorCode.SESSION_DISPOSED }));
+	});
+
+	test("models demo-21-style section fields with concrete policy targets", () => {
+		const rules = [
+			policyRule(
+				"employment",
+				{ "profile.employed": true },
+				{
+					"$formbar.fieldPolicy.company": output("/profile/employment/company", { visible: true, required: true }),
+					"$formbar.fieldPolicy.role": output("/profile/employment/role", { visible: true }),
+				},
+			),
+		];
+		const form = createForm({
+			initialData: { profile: { employed: false, employment: { company: "", role: "" } } },
+			plugins: [createArbiterPlugin({ rules })],
+		});
+		form.setValue("profile.employed", true);
+		expect(paths(form)).toEqual([
+			["profile", "employment", "company"],
+			["profile", "employment", "role"],
+		]);
+		form.setValue("profile.employed", false);
+		expect(form.getState().fieldPolicy).toEqual([]);
+		form.dispose();
+	});
+});

package/src/arbiter-plugin.ts

@@ -1,8 +1,11 @@
-import { createSession } from "@arbitre/core";
+import { ArbiterError, ArbiterErrorCode, createSession } from "@arbitre/core";
 import type { FiringResult, ProductionRule, RuleSession } from "@arbitre/core";
 import type { FormPlugin, PluginEvaluateContext, PluginEvaluateResult, PluginWrite } from "@formbar/core";
+import { readFieldPolicyOutput } from "./field-policy-output.js";
 import { isArbiterInternalPath } from "./internal-paths.js";
 
+const RESERVED_DATA_ROOT = "$formbar";
+
 export interface ArbiterPluginOptions {
 	/** Provide raw rules — a session will be created internally. */
 	readonly rules?: readonly ProductionRule[];
@@ -16,11 +19,48 @@ function resolveSession(options: ArbiterPluginOptions): { session: RuleSession;
 	throw new Error("createArbiterPlugin requires either `rules` or `session`");
 }
 
-function syncSession(session: RuleSession, ctx: PluginEvaluateContext): void {
-	const data = ctx.data as Record<string, unknown>;
-	for (const key of Object.keys(data)) session.assert(key, data[key]);
-	const uiState = ctx.uiState as Record<string, unknown>;
-	for (const key of Object.keys(uiState)) session.assert(`$ui.${key}`, uiState[key]);
+interface SynchronizedRoots {
+	data: Set<string>;
+	ui: Set<string>;
+}
+
+function syncRoots(
+	session: RuleSession,
+	values: Record<string, unknown>,
+	previous: Set<string>,
+	prefix: string,
+	include: (key: string) => boolean = () => true,
+): Set<string> {
+	const current = new Set(Object.keys(values).filter(include));
+	for (const key of previous) {
+		if (!current.has(key)) session.retract(`${prefix}${key}`);
+	}
+	for (const key of current) session.assert(`${prefix}${key}`, values[key]);
+	return current;
+}
+
+function isFormDataRoot(key: string): boolean {
+	return key !== RESERVED_DATA_ROOT && !key.startsWith(`${RESERVED_DATA_ROOT}.`);
+}
+
+function syncSession(session: RuleSession, ctx: PluginEvaluateContext, roots: SynchronizedRoots): void {
+	roots.data = syncRoots(session, ctx.data as Record<string, unknown>, roots.data, "", isFormDataRoot);
+	roots.ui = syncRoots(session, ctx.uiState as Record<string, unknown>, roots.ui, "$ui.");
+}
+
+function fireSession(session: RuleSession): FiringResult {
+	try {
+		return session.fire();
+	} catch (error) {
+		if (error instanceof ArbiterError) throw error;
+		throw new ArbiterError(
+			ArbiterErrorCode.RULE_COMPILATION_FAILED,
+			"Arbiter session state could not be evaluated safely",
+			error instanceof Error
+				? { details: { root: "$formbar.fieldPolicy" }, cause: error }
+				: { details: { root: "$formbar.fieldPolicy" } },
+		);
+	}
 }
 
 function toWrites(result: FiringResult): readonly PluginWrite[] {
@@ -29,12 +69,16 @@ function toWrites(result: FiringResult): readonly PluginWrite[] {
 		.map((change) => ({ path: change.path, value: change.newValue, mode: "set" as const }));
 }
 
-function evaluateSession(session: RuleSession, ctx: PluginEvaluateContext): PluginEvaluateResult | undefined {
+function evaluateSession(
+	session: RuleSession,
+	ctx: PluginEvaluateContext,
+	roots: SynchronizedRoots,
+): PluginEvaluateResult | undefined {
 	if (ctx.origin.startsWith("plugin:arbiter")) return;
 	if (!ctx.change.dataChanged && !ctx.change.uiChanged) return;
-	syncSession(session, ctx);
-	const writes = toWrites(session.fire());
-	return { writes: writes.length > 0 ? writes : undefined };
+	syncSession(session, ctx, roots);
+	const writes = toWrites(fireSession(session));
+	return { writes: writes.length > 0 ? writes : undefined, fieldPolicy: readFieldPolicyOutput(session) };
 }
 
 /**
@@ -44,9 +88,10 @@ function evaluateSession(session: RuleSession, ctx: PluginEvaluateContext): Plug
  */
 export function createArbiterPlugin(options: ArbiterPluginOptions): FormPlugin {
 	const { session, owned } = resolveSession(options);
+	const roots: SynchronizedRoots = { data: new Set(), ui: new Set() };
 	return {
 		id: "arbiter",
-		evaluate: (ctx) => evaluateSession(session, ctx),
+		evaluate: (ctx) => evaluateSession(session, ctx, roots),
 		onDispose() {
 			if (owned) session.dispose();
 		},

package/src/field-policy-output.ts

@@ -0,0 +1,139 @@
+import { ArbiterError, ArbiterErrorCode } from "@arbitre/core";
+import { type FieldPolicyInput, parsePath } from "@formbar/core";
+
+const OUTPUT_ROOT = "$formbar.fieldPolicy";
+const OUTPUT_ID = /^[A-Za-z][A-Za-z0-9_-]*$/;
+const POLICY_KEYS = new Set<PropertyKey>(["path", "visible", "disabled", "readOnly", "required", "label"]);
+const BOOLEAN_KEYS = ["visible", "disabled", "readOnly", "required"] as const;
+const UNSAFE_SEGMENTS = new Set(["__proto__", "prototype", "constructor"]);
+const INTEGER_SEGMENT = /^(?:0|[1-9]\d*)$/;
+
+interface CapturedRecord {
+	readonly keys: readonly string[];
+	readonly values: ReadonlyMap<string, unknown>;
+}
+
+function outputError(message: string, outputId?: string): never {
+	throw new ArbiterError(ArbiterErrorCode.RULE_COMPILATION_FAILED, message, {
+		details: outputId === undefined ? { root: OUTPUT_ROOT } : { root: OUTPUT_ROOT, outputId },
+	});
+}
+
+function pathError(message: string, outputId: string, path: unknown): never {
+	throw new ArbiterError(ArbiterErrorCode.INVALID_PATH, message, {
+		details: { root: OUTPUT_ROOT, outputId, path },
+	});
+}
+
+function captureRecord(value: unknown, outputId?: string): CapturedRecord {
+	if (value === null || typeof value !== "object") {
+		return outputError("Arbiter field policy output must be a plain data record", outputId);
+	}
+	let array: boolean;
+	let prototype: object | null;
+	let keys: readonly PropertyKey[];
+	const descriptors = new Map<PropertyKey, PropertyDescriptor | undefined>();
+	try {
+		array = Array.isArray(value);
+		prototype = Reflect.getPrototypeOf(value);
+		keys = Reflect.ownKeys(value);
+		for (const key of keys) descriptors.set(key, Reflect.getOwnPropertyDescriptor(value, key));
+	} catch {
+		return outputError("Arbiter field policy output must be inspectable", outputId);
+	}
+	if (array) return outputError("Arbiter field policy output must be a plain data record", outputId);
+	if (prototype !== Object.prototype && prototype !== null) {
+		return outputError("Arbiter field policy output must use a plain prototype", outputId);
+	}
+	const values = new Map<string, unknown>();
+	for (const key of keys) {
+		const descriptor = descriptors.get(key);
+		if (typeof key !== "string" || !descriptor?.enumerable || !("value" in descriptor)) {
+			return outputError("Arbiter field policy output requires enumerable data properties", outputId);
+		}
+		values.set(key, descriptor.value);
+	}
+	return { keys: [...values.keys()], values };
+}
+
+function normalizedPathKey(path: unknown, outputId: string): string {
+	if (typeof path !== "string" || !path.startsWith("/") || path === "/") {
+		return pathError(`Field policy output "${outputId}" path must be a non-empty RFC-6901 pointer`, outputId, path);
+	}
+	let segments: readonly (string | number)[];
+	try {
+		segments = parsePath(path).segments;
+	} catch {
+		return pathError(`Field policy output "${outputId}" has an invalid RFC-6901 pointer`, outputId, path);
+	}
+	if (segments.some((segment) => segment === "" || segment === "*" || UNSAFE_SEGMENTS.has(String(segment)))) {
+		return pathError(`Field policy output "${outputId}" has an unsupported target path`, outputId, path);
+	}
+	const normalized = segments.map((segment) => (INTEGER_SEGMENT.test(String(segment)) ? Number(segment) : segment));
+	if (normalized.some((segment) => typeof segment === "number" && !Number.isSafeInteger(segment))) {
+		return pathError(`Field policy output "${outputId}" has an unsafe array index`, outputId, path);
+	}
+	return JSON.stringify(normalized);
+}
+
+function decodeRecord(
+	value: unknown,
+	outputId: string,
+): { readonly input: FieldPolicyInput; readonly pathKey: string } {
+	const { keys, values } = captureRecord(value, outputId);
+	for (const key of keys) {
+		if (!POLICY_KEYS.has(key)) outputError(`Field policy output "${outputId}" has unknown property "${key}"`, outputId);
+	}
+	if (!keys.includes("path")) outputError(`Field policy output "${outputId}" requires "path"`, outputId);
+	if (!keys.some((key) => key !== "path")) {
+		outputError(`Field policy output "${outputId}" requires at least one policy property`, outputId);
+	}
+	for (const key of BOOLEAN_KEYS) {
+		if (values.has(key) && typeof values.get(key) !== "boolean") {
+			outputError(`Field policy output "${outputId}" property "${key}" must be boolean`, outputId);
+		}
+	}
+	if (values.has("label") && typeof values.get("label") !== "string") {
+		outputError(`Field policy output "${outputId}" property "label" must be a string`, outputId);
+	}
+	const path = values.get("path");
+	const pathKey = normalizedPathKey(path, outputId);
+	const input: FieldPolicyInput = Object.freeze({
+		path: path as string,
+		...(values.has("visible") ? { visible: values.get("visible") as boolean } : {}),
+		...(values.has("disabled") ? { disabled: values.get("disabled") as boolean } : {}),
+		...(values.has("readOnly") ? { readOnly: values.get("readOnly") as boolean } : {}),
+		...(values.has("required") ? { required: values.get("required") as boolean } : {}),
+		...(values.has("label") ? { label: values.get("label") as string } : {}),
+	});
+	return { input, pathKey };
+}
+
+export function readFieldPolicyOutput(session: { getPath(path: string): unknown }): readonly FieldPolicyInput[] {
+	let root: unknown;
+	try {
+		root = session.getPath(OUTPUT_ROOT);
+	} catch (error) {
+		if (error instanceof ArbiterError) throw error;
+		return outputError("Arbiter field policy output root could not be read");
+	}
+	if (root === undefined) return Object.freeze([]);
+	const captured = captureRecord(root);
+	const outputIds = [...captured.keys].sort();
+	const seen = new Map<string, string>();
+	const inputs = outputIds.map((outputId) => {
+		if (!OUTPUT_ID.test(outputId)) outputError(`Invalid field policy output ID "${outputId}"`, outputId);
+		const decoded = decodeRecord(captured.values.get(outputId), outputId);
+		const duplicate = seen.get(decoded.pathKey);
+		if (duplicate) {
+			pathError(
+				`Field policy outputs "${duplicate}" and "${outputId}" target the same path`,
+				outputId,
+				decoded.input.path,
+			);
+		}
+		seen.set(decoded.pathKey, outputId);
+		return decoded.input;
+	});
+	return Object.freeze(inputs);
+}