al-sem 0.0.1

package/src/policy/predicate-evaluator.ts

@@ -0,0 +1,267 @@
+import type { CapabilityFact } from "../model/capability.ts";
+import type { Routine } from "../model/entities.ts";
+import type { SemanticModel } from "../model/model.ts";
+import type { Predicate, PredicateOperator, PredicateTrace, Tristate } from "./policy-types.ts";
+import type { FieldEvalContext, FieldIndexes, FieldValue } from "./predicate-fields.ts";
+import { getFieldDef } from "./predicate-fields.ts";
+
+export type { Tristate } from "./policy-types.ts";
+
+// ---- Kleene combinators ----
+export function kleeneAnd(a: Tristate, b: Tristate): Tristate {
+	if (a === "false" || b === "false") return "false";
+	if (a === "unknown" || b === "unknown") return "unknown";
+	return "true";
+}
+export function kleeneOr(a: Tristate, b: Tristate): Tristate {
+	if (a === "true" || b === "true") return "true";
+	if (a === "unknown" || b === "unknown") return "unknown";
+	return "false";
+}
+export function kleeneNot(a: Tristate): Tristate {
+	if (a === "true") return "false";
+	if (a === "false") return "true";
+	return "unknown";
+}
+
+// ---- Predicate evaluation ----
+export interface EvalResult {
+	result: Tristate;
+	trace: PredicateTrace;
+}
+
+export function evaluatePredicate(p: Predicate, ctx: FieldEvalContext): EvalResult {
+	switch (p.kind) {
+		case "field":
+			return evaluateField(p, ctx);
+		case "all":
+			return evaluateAll(p.children, ctx);
+		case "any":
+			return evaluateAny(p.children, ctx);
+		case "not": {
+			const inner = evaluatePredicate(p.child, ctx);
+			const result = kleeneNot(inner.result);
+			return { result, trace: { node: "not", result, children: [inner.trace] } };
+		}
+	}
+}
+
+function evaluateAll(children: readonly Predicate[], ctx: FieldEvalContext): EvalResult {
+	if (children.length === 0) {
+		// Empty conjunction is true by convention.
+		return { result: "true", trace: { node: "all", result: "true", children: [] } };
+	}
+	let acc: Tristate = "true";
+	const traces: PredicateTrace[] = [];
+	for (const c of children) {
+		const r = evaluatePredicate(c, ctx);
+		traces.push(r.trace);
+		acc = kleeneAnd(acc, r.result);
+		if (acc === "false") break; // short-circuit; remaining children may not eval.
+	}
+	return { result: acc, trace: { node: "all", result: acc, children: traces } };
+}
+
+function evaluateAny(children: readonly Predicate[], ctx: FieldEvalContext): EvalResult {
+	if (children.length === 0) {
+		// Empty disjunction is false by convention.
+		return { result: "false", trace: { node: "any", result: "false", children: [] } };
+	}
+	let acc: Tristate = "false";
+	const traces: PredicateTrace[] = [];
+	for (const c of children) {
+		const r = evaluatePredicate(c, ctx);
+		traces.push(r.trace);
+		acc = kleeneOr(acc, r.result);
+		if (acc === "true") break;
+	}
+	return { result: acc, trace: { node: "any", result: acc, children: traces } };
+}
+
+function evaluateField(
+	p: Extract<Predicate, { kind: "field" }>,
+	ctx: FieldEvalContext,
+): EvalResult {
+	const def = getFieldDef(p.field);
+	if (def === undefined) {
+		return {
+			result: "unknown",
+			trace: { node: "field", result: "unknown", field: p.field, unknownReason: "evaluator-error" },
+		};
+	}
+	let value: FieldValue;
+	try {
+		value = def.evaluate(ctx);
+	} catch {
+		return {
+			result: "unknown",
+			trace: { node: "field", result: "unknown", field: p.field, unknownReason: "evaluator-error" },
+		};
+	}
+	if (value.kind === "unknown") {
+		return {
+			result: "unknown",
+			trace: {
+				node: "field",
+				result: "unknown",
+				field: p.field,
+				expected: p.value,
+				unknownReason: value.reason,
+			},
+		};
+	}
+	const matched = matchOperator(p.operator, value.value, p.value);
+	const result: Tristate = matched ? "true" : "false";
+	return {
+		result,
+		trace: { node: "field", result, field: p.field, expected: p.value, actual: value.value },
+	};
+}
+
+function matchOperator(op: PredicateOperator, actual: unknown, expected: unknown): boolean {
+	switch (op) {
+		case "==":
+			return actual === expected;
+		case "in":
+			return (
+				Array.isArray(expected) &&
+				(Array.isArray(actual)
+					? actual.some((a) => expected.includes(a))
+					: expected.includes(actual))
+			);
+		case "glob":
+			return typeof expected === "string" && globMatch(expected, actualToString(actual));
+		case "glob-in":
+			return (
+				Array.isArray(expected) &&
+				expected.some(
+					(g) =>
+						typeof g === "string" &&
+						(Array.isArray(actual)
+							? actual.some((a) => globMatch(g, actualToString(a)))
+							: globMatch(g, actualToString(actual))),
+				)
+			);
+	}
+}
+
+function actualToString(v: unknown): string {
+	if (typeof v === "string") return v;
+	if (Array.isArray(v)) return v.join(",");
+	return String(v);
+}
+
+// Case-insensitive glob; * matches any chars, ? matches single char. Anchored.
+export function globMatch(pattern: string, value: string): boolean {
+	const compiled = compileGlob(pattern);
+	return compiled.test(value);
+}
+
+const globCache = new Map<string, RegExp>();
+function compileGlob(pattern: string): RegExp {
+	const cached = globCache.get(pattern);
+	if (cached !== undefined) return cached;
+	// Escape regex metachars except * and ?
+	const escaped = pattern
+		.replace(/[.+^${}()|[\]\\]/g, "\\$&")
+		.replace(/\*/g, ".*")
+		.replace(/\?/g, ".");
+	const re = new RegExp(`^${escaped}$`, "i");
+	globCache.set(pattern, re);
+	return re;
+}
+
+// ---- No-trace evaluation (hot path) ----
+//
+// `evaluatePredicate` (above) always allocates a PredicateTrace tree. The engine
+// only needs the tristate result for applicability pre-checks and the per-fact
+// when/except loop, so these variants skip trace allocation entirely. The traced
+// version is retained for `explain`.
+
+type EvalMode = "full" | "applicability";
+
+/** A frozen placeholder used only in applicability mode. CONTRACT: fact-scoped
+ *  fields short-circuit to "unknown" BEFORE def.evaluate runs, and no
+ *  routine/model-scoped evaluator reads ctx.fact — so these values are never
+ *  observed. `subject` is undefined-as-never so any accidental future read of a
+ *  fact field from a non-fact evaluator surfaces as undefined (⇒ unknown), not a
+ *  plausible value. */
+const PLACEHOLDER_FACT: CapabilityFact = Object.freeze({
+	subject: undefined as never,
+	op: "read",
+	resourceKind: "transaction",
+	confidence: "static",
+	provenance: "direct",
+	via: "self",
+});
+
+/** Routine/model context for applicability — no fact required. */
+export interface ApplicabilityContext {
+	routine: Routine;
+	model: SemanticModel;
+	indexes?: FieldIndexes;
+}
+
+function fieldTristate(
+	p: Extract<Predicate, { kind: "field" }>,
+	ctx: FieldEvalContext,
+	mode: EvalMode,
+): Tristate {
+	const def = getFieldDef(p.field);
+	if (def === undefined) return "unknown";
+	// Applicability: a fact-scoped field cannot be decided without a fact, so it is
+	// "unknown" (never read; no fact is required). Routine/model fields evaluate normally.
+	if (mode === "applicability" && def.scope === "fact") return "unknown";
+	let value: FieldValue;
+	try {
+		value = def.evaluate(ctx);
+	} catch {
+		return "unknown";
+	}
+	if (value.kind === "unknown") return "unknown";
+	return matchOperator(p.operator, value.value, p.value) ? "true" : "false";
+}
+
+function evalTristate(p: Predicate, ctx: FieldEvalContext, mode: EvalMode): Tristate {
+	switch (p.kind) {
+		case "field":
+			return fieldTristate(p, ctx, mode);
+		case "all": {
+			if (p.children.length === 0) return "true";
+			let acc: Tristate = "true";
+			for (const c of p.children) {
+				acc = kleeneAnd(acc, evalTristate(c, ctx, mode));
+				if (acc === "false") return "false";
+			}
+			return acc;
+		}
+		case "any": {
+			if (p.children.length === 0) return "false";
+			let acc: Tristate = "false";
+			for (const c of p.children) {
+				acc = kleeneOr(acc, evalTristate(c, ctx, mode));
+				if (acc === "true") return "true";
+			}
+			return acc;
+		}
+		case "not":
+			return kleeneNot(evalTristate(p.child, ctx, mode));
+	}
+}
+
+/** Full evaluation, tristate only (no trace). Used per-fact in the engine. */
+export function evaluateResult(p: Predicate, ctx: FieldEvalContext): Tristate {
+	return evalTristate(p, ctx, "full");
+}
+
+/** Partial evaluation over routine/model fields only (fact fields ⇒ unknown).
+ *  `false` ⇒ no fact can satisfy P for this routine ⇒ rule not applicable. */
+export function evaluateApplicability(p: Predicate, ctx: ApplicabilityContext): Tristate {
+	const full: FieldEvalContext = {
+		routine: ctx.routine,
+		fact: PLACEHOLDER_FACT,
+		model: ctx.model,
+		indexes: ctx.indexes,
+	};
+	return evalTristate(p, full, "applicability");
+}

package/src/policy/predicate-fields.ts

@@ -0,0 +1,439 @@
+import type { CapabilityFact, CapabilityResourceKind } from "../model/capability.ts";
+import type { ObjectDecl, Routine, Table } from "../model/entities.ts";
+import type { EventSymbol } from "../model/graph.ts";
+import type { EventId, ObjectId, RoutineId, TableId } from "../model/ids.ts";
+import type { SemanticModel } from "../model/model.ts";
+
+export type FieldValueShape =
+	| "enum"
+	| "enum-list"
+	| "glob"
+	| "glob-list"
+	| "string-exact"
+	| "string-list"
+	| "numeric"
+	| "tri-state";
+
+export type FieldScope = "routine" | "fact" | "model";
+
+export type FieldValue =
+	| { kind: "known"; value: string | readonly string[] | number | boolean | undefined }
+	| {
+			kind: "unknown";
+			reason:
+				| "field-not-applicable"
+				| "resource-id-unresolved"
+				| "no-root-classification"
+				| "evaluator-error";
+	  };
+
+export interface FieldIndexes {
+	objectsById: Map<ObjectId, ObjectDecl>;
+	rootKindsByRoutineId: Map<RoutineId, readonly string[]>;
+	tablesById: Map<TableId, Table>;
+	eventsById: Map<EventId, EventSymbol>;
+}
+
+export interface FieldEvalContext {
+	routine: Routine;
+	fact: CapabilityFact;
+	model: SemanticModel;
+	indexes?: FieldIndexes;
+}
+
+/** Build the per-run lookup bundle once; the engine threads it through every
+ *  field evaluation so 108k-routine runs do Map.get instead of Array.find. */
+export function buildFieldIndexes(model: SemanticModel): FieldIndexes {
+	const objectsById = new Map<ObjectId, ObjectDecl>();
+	for (const o of model.objects) objectsById.set(o.id, o);
+	const rootKindsByRoutineId = new Map<RoutineId, readonly string[]>();
+	for (const rc of model.rootClassifications) rootKindsByRoutineId.set(rc.routineId, rc.kinds);
+	const tablesById = new Map<TableId, Table>();
+	for (const t of model.tables) tablesById.set(t.id, t);
+	const eventsById = new Map<EventId, EventSymbol>();
+	for (const e of model.eventGraph.events) eventsById.set(e.id, e);
+	return { objectsById, rootKindsByRoutineId, tablesById, eventsById };
+}
+
+export interface PredicateFieldDef {
+	name: string;
+	scope: FieldScope;
+	valueShape: FieldValueShape;
+	enumValues?: readonly string[];
+	description: string;
+	evaluate(ctx: FieldEvalContext): FieldValue;
+	jsonSchemaFragment: unknown;
+}
+
+// ---- helpers ----
+function known(value: string | readonly string[] | number | boolean | undefined): FieldValue {
+	return { kind: "known", value };
+}
+
+function unknown(
+	reason:
+		| "field-not-applicable"
+		| "resource-id-unresolved"
+		| "no-root-classification"
+		| "evaluator-error",
+): FieldValue {
+	return { kind: "unknown", reason };
+}
+
+// Resource-kind enum values mirror src/model/capability.ts CapabilityResourceKind.
+const RESOURCE_KINDS: readonly CapabilityResourceKind[] = [
+	"table",
+	"event",
+	"codeunit",
+	"page",
+	"report",
+	"http",
+	"telemetry",
+	"isolated-storage",
+	"file",
+	"transaction",
+	"ui",
+	"background",
+];
+
+const CAPABILITY_OPS = [
+	"read",
+	"insert",
+	"modify",
+	"delete",
+	"execute",
+	"publish",
+	"subscribe",
+	"send",
+	"log",
+	"store-read",
+	"store-write",
+	"store-delete",
+	"commit",
+	"open",
+	"write-blob",
+	"start",
+	"ui-confirm",
+	"ui-message",
+	"ui-error",
+] as const;
+
+const CONFIDENCE_VALUES = [
+	"static",
+	"boundedDynamic",
+	"configDynamic",
+	"userDynamic",
+	"unresolved",
+] as const;
+
+const VIA_VALUES = [
+	"self",
+	"call",
+	"object-run",
+	"event-dispatch",
+	"implicit-trigger",
+	"dependency",
+] as const;
+
+const PROVENANCE_VALUES = ["direct", "inherited"] as const;
+
+// Get the containing object for a routine, when present.
+function objectOf(ctx: FieldEvalContext): ObjectDecl | undefined {
+	// When indexes are present they are authoritative (built from the same model);
+	// a miss is genuinely absent — never fall back to a linear scan.
+	if (ctx.indexes !== undefined) return ctx.indexes.objectsById.get(ctx.routine.objectId);
+	return ctx.model.objects.find((o) => o.id === ctx.routine.objectId);
+}
+
+// ---- registry entries ----
+export const PREDICATE_FIELDS: readonly PredicateFieldDef[] = [
+	// ---- Routine-scope fields ----
+	{
+		name: "root.kinds",
+		scope: "routine",
+		valueShape: "enum-list",
+		description: "Root classification kinds for the routine (api-page, event-subscriber, etc.).",
+		evaluate(ctx) {
+			// Decision 2: classification is exhaustive — a routine with no classification is a
+			// non-root, so its root-kind set is empty (NOT unknown). This makes positive
+			// root.kinds constraints correctly `false` for non-roots, enabling the
+			// applicability skip. When indexes are present they are AUTHORITATIVE: a miss is
+			// `[]` at O(1) — never fall back to the linear rootClassifications scan (that
+			// fallback on the ~100k non-root routines is a multi-minute regression).
+			if (ctx.indexes !== undefined) {
+				return known(ctx.indexes.rootKindsByRoutineId.get(ctx.routine.id) ?? []);
+			}
+			const rc = ctx.model.rootClassifications.find((x) => x.routineId === ctx.routine.id);
+			return known(rc?.kinds ?? []);
+		},
+		jsonSchemaFragment: {
+			oneOf: [{ type: "string" }, { type: "array", items: { type: "string" } }],
+		},
+	},
+	{
+		name: "routine.name",
+		scope: "routine",
+		valueShape: "glob",
+		description: "Routine name (case-insensitive glob match).",
+		evaluate(ctx) {
+			return known(ctx.routine.name);
+		},
+		jsonSchemaFragment: {
+			oneOf: [{ type: "string" }, { type: "array", items: { type: "string" } }],
+		},
+	},
+	{
+		name: "routine.kind",
+		scope: "routine",
+		valueShape: "enum",
+		enumValues: ["procedure", "trigger", "event-publisher", "event-subscriber"],
+		description: "Routine kind.",
+		evaluate(ctx) {
+			return known(ctx.routine.kind);
+		},
+		jsonSchemaFragment: {
+			type: "string",
+			enum: ["procedure", "trigger", "event-publisher", "event-subscriber"],
+		},
+	},
+	{
+		name: "routine.accessModifier",
+		scope: "routine",
+		valueShape: "enum-list",
+		enumValues: ["public", "internal", "local", "protected"],
+		description: "Routine access modifier.",
+		// accessModifier is ProcedureAccessModifier ("local"|"internal"|"protected") | undefined.
+		// Absent/undefined means AL default ("public").
+		evaluate(ctx) {
+			return known(ctx.routine.accessModifier ?? "public");
+		},
+		jsonSchemaFragment: {
+			oneOf: [{ type: "string" }, { type: "array", items: { type: "string" } }],
+		},
+	},
+	{
+		name: "object.name",
+		scope: "routine",
+		valueShape: "glob",
+		description: "Containing object name (case-insensitive glob).",
+		evaluate(ctx) {
+			const obj = objectOf(ctx);
+			if (obj === undefined) return unknown("field-not-applicable");
+			return known(obj.name);
+		},
+		jsonSchemaFragment: {
+			oneOf: [{ type: "string" }, { type: "array", items: { type: "string" } }],
+		},
+	},
+	{
+		name: "object.kind",
+		scope: "routine",
+		valueShape: "enum-list",
+		enumValues: [
+			"codeunit",
+			"table",
+			"page",
+			"report",
+			"xmlport",
+			"query",
+			"enum",
+			"interface",
+			"permissionset",
+		],
+		description: "Containing object kind.",
+		// objectType is verbatim from AL source (e.g. "Codeunit", "Table") — lowercase for matching.
+		evaluate(ctx) {
+			const obj = objectOf(ctx);
+			if (obj === undefined) return unknown("field-not-applicable");
+			return known(obj.objectType.toLowerCase());
+		},
+		jsonSchemaFragment: {
+			oneOf: [{ type: "string" }, { type: "array", items: { type: "string" } }],
+		},
+	},
+	{
+		name: "object.appGuid",
+		scope: "routine",
+		valueShape: "string-exact",
+		description: "Containing object's app GUID (advanced; cross-app rules).",
+		evaluate(ctx) {
+			const obj = objectOf(ctx);
+			if (obj === undefined) return unknown("field-not-applicable");
+			return known(obj.appGuid);
+		},
+		jsonSchemaFragment: { type: "string" },
+	},
+
+	// ---- Fact-scope fields ----
+	{
+		name: "capability.op",
+		scope: "fact",
+		valueShape: "enum-list",
+		enumValues: CAPABILITY_OPS,
+		description: "Capability op (insert, commit, send, ui-confirm, etc.).",
+		evaluate(ctx) {
+			return known(ctx.fact.op);
+		},
+		jsonSchemaFragment: {
+			oneOf: [
+				{ type: "string", enum: CAPABILITY_OPS },
+				{ type: "array", items: { type: "string", enum: CAPABILITY_OPS } },
+			],
+		},
+	},
+	{
+		name: "capability.resourceKind",
+		scope: "fact",
+		valueShape: "enum-list",
+		enumValues: RESOURCE_KINDS,
+		description: "Capability resource kind.",
+		evaluate(ctx) {
+			return known(ctx.fact.resourceKind);
+		},
+		jsonSchemaFragment: {
+			oneOf: [
+				{ type: "string", enum: RESOURCE_KINDS },
+				{ type: "array", items: { type: "string", enum: RESOURCE_KINDS } },
+			],
+		},
+	},
+	{
+		name: "capability.resource.table.name",
+		scope: "fact",
+		valueShape: "glob",
+		description: "Target table name when resourceKind is 'table' (case-insensitive glob).",
+		evaluate(ctx) {
+			if (ctx.fact.resourceKind !== "table") return unknown("field-not-applicable");
+			if (typeof ctx.fact.resourceId !== "string") return unknown("resource-id-unresolved");
+			const tableId = ctx.fact.resourceId;
+			const table =
+				ctx.indexes !== undefined
+					? ctx.indexes.tablesById.get(tableId)
+					: ctx.model.tables.find((t) => t.id === tableId);
+			if (table === undefined) return unknown("resource-id-unresolved");
+			return known(table.name);
+		},
+		jsonSchemaFragment: {
+			oneOf: [{ type: "string" }, { type: "array", items: { type: "string" } }],
+		},
+	},
+	{
+		name: "capability.resource.event.name",
+		scope: "fact",
+		valueShape: "glob",
+		description: "Target event name when resourceKind is 'event'.",
+		evaluate(ctx) {
+			if (ctx.fact.resourceKind !== "event") return unknown("field-not-applicable");
+			if (typeof ctx.fact.resourceId !== "string") return unknown("resource-id-unresolved");
+			const eventId = ctx.fact.resourceId;
+			const ev =
+				ctx.indexes !== undefined
+					? ctx.indexes.eventsById.get(eventId)
+					: ctx.model.eventGraph.events.find((e) => e.id === eventId);
+			if (ev === undefined) return unknown("resource-id-unresolved");
+			return known(ev.eventName);
+		},
+		jsonSchemaFragment: {
+			oneOf: [{ type: "string" }, { type: "array", items: { type: "string" } }],
+		},
+	},
+	{
+		name: "capability.resource.http.method",
+		scope: "fact",
+		valueShape: "enum-list",
+		enumValues: ["Send", "Get", "Post", "Put", "Delete", "Patch"],
+		description: "HTTP method when resourceKind is 'http'.",
+		evaluate(ctx) {
+			if (ctx.fact.resourceKind !== "http") return unknown("field-not-applicable");
+			const extra = ctx.fact.extra;
+			if (extra?.kind !== "http") return unknown("field-not-applicable");
+			return known(extra.method);
+		},
+		jsonSchemaFragment: {
+			oneOf: [{ type: "string" }, { type: "array", items: { type: "string" } }],
+		},
+	},
+	{
+		name: "capability.resource.ui.kind",
+		scope: "fact",
+		valueShape: "enum-list",
+		enumValues: ["confirm", "message", "error", "dialog", "modalPage", "requestPage"],
+		description: "UI kind (derived from op when ui-* ops are present).",
+		evaluate(ctx) {
+			if (ctx.fact.resourceKind !== "ui") return unknown("field-not-applicable");
+			switch (ctx.fact.op) {
+				case "ui-confirm":
+					return known("confirm");
+				case "ui-message":
+					return known("message");
+				case "ui-error":
+					return known("error");
+				default:
+					return unknown("field-not-applicable");
+			}
+		},
+		jsonSchemaFragment: {
+			oneOf: [{ type: "string" }, { type: "array", items: { type: "string" } }],
+		},
+	},
+	{
+		name: "capability.confidence",
+		scope: "fact",
+		valueShape: "enum-list",
+		enumValues: CONFIDENCE_VALUES,
+		description:
+			"Capability confidence (static, boundedDynamic, configDynamic, userDynamic, unresolved).",
+		evaluate(ctx) {
+			return known(ctx.fact.confidence);
+		},
+		jsonSchemaFragment: {
+			oneOf: [
+				{ type: "string", enum: CONFIDENCE_VALUES },
+				{ type: "array", items: { type: "string", enum: CONFIDENCE_VALUES } },
+			],
+		},
+	},
+	{
+		name: "capability.origin",
+		scope: "fact",
+		valueShape: "enum-list",
+		enumValues: PROVENANCE_VALUES,
+		description: "Capability origin: direct (this routine) or inherited (transitive).",
+		// Maps to CapabilityFact.provenance ("direct" | "inherited").
+		evaluate(ctx) {
+			return known(ctx.fact.provenance);
+		},
+		jsonSchemaFragment: {
+			oneOf: [
+				{ type: "string", enum: PROVENANCE_VALUES },
+				{ type: "array", items: { type: "string", enum: PROVENANCE_VALUES } },
+			],
+		},
+	},
+	{
+		name: "capability.via",
+		scope: "fact",
+		valueShape: "enum-list",
+		enumValues: VIA_VALUES,
+		description: "Edge kind that brought the fact in.",
+		evaluate(ctx) {
+			return known(ctx.fact.via);
+		},
+		jsonSchemaFragment: {
+			oneOf: [
+				{ type: "string", enum: VIA_VALUES },
+				{ type: "array", items: { type: "string", enum: VIA_VALUES } },
+			],
+		},
+	},
+] as const;
+
+const fieldByName = new Map(PREDICATE_FIELDS.map((f) => [f.name, f] as const));
+
+export function getFieldDef(name: string): PredicateFieldDef | undefined {
+	return fieldByName.get(name);
+}
+
+export function listFieldNames(): readonly string[] {
+	return PREDICATE_FIELDS.map((f) => f.name);
+}