@nmnmcc/ability 2.0.2 → 2.0.5

package/src/internal/decide.ts

@@ -37,6 +37,8 @@ interface DecideContext {
 	readonly input: Condition.Input
 	/** The resource of the kind, for the fields that a rule may grant. */
 	readonly descriptor: Resource.Descriptor
+	/** The test of `RuleData.fitsOf` for the catalog, for this decision. */
+	readonly fits: (pattern: string) => boolean
 	/** The rules that were tested, for {@link explain}. */
 	readonly trace: Ref.Ref<Chunk.Chunk<Step>> | undefined
 }
@@ -282,6 +284,7 @@ const makeContext = (
 			path: descriptor.path,
 		},
 		descriptor,
+		fits: RuleData.fitsOf(descriptor.catalog),
 		trace,
 	}
 }

package/src/internal/place.ts

@@ -0,0 +1,32 @@
+/**
+ * The place of a part of an input, as a path that shares the path of its
+ * parent. A deep tree with very many rules would need very much memory for a
+ * full copy of the path of each rule, so a place keeps only its own parts and
+ * its parent. The full path is made only for a problem, in one walk up.
+ */
+import * as Arr from "effect/Array"
+import * as Option from "effect/Option"
+
+/** A place: its own parts of the path, after the path of its parent. */
+export interface Place {
+	readonly parent: Place | undefined
+	readonly parts: ReadonlyArray<PropertyKey>
+}
+
+/** The place below `parent` with more parts. */
+export const at = (
+	parent: Place | undefined,
+	...parts: ReadonlyArray<PropertyKey>
+): Place => ({ parent, parts })
+
+/** The full path of a place. The root, with no place, has the empty path. */
+export const pathOf = (place: Place | undefined): ReadonlyArray<PropertyKey> =>
+	Arr.flatten(
+		Arr.reverse(
+			Arr.unfold(place, (current) =>
+				current === undefined
+					? Option.none()
+					: Option.some([current.parts, current.parent] as const),
+			),
+		),
+	)

package/src/internal/policy-json.ts

@@ -12,6 +12,7 @@ import type * as Domain from "../Domain.ts"
 import * as Rule from "./rule.ts"
 import * as Json from "./json.ts"
 import * as Limits from "./limits.ts"
+import * as Place from "./place.ts"
 import * as PolicyNodes from "./policy-nodes.ts"
 
 type Node = PolicyNodes.Node
@@ -213,10 +214,13 @@ const spendValue = (
 	)
 }
 
-/** A rule in the input, with its place, to decode after the tree. */
+/**
+ * A rule in the input, with its place, to decode after the tree. The place
+ * shares the path of its parent: see `Place`.
+ */
 interface RuleInput {
 	readonly input: unknown
-	readonly path: ReadonlyArray<PropertyKey>
+	readonly place: Place.Place
 }
 
 /**
@@ -227,20 +231,20 @@ interface RuleInput {
 type Plan =
 	| {
 			readonly _tag: "Rules"
-			readonly path: ReadonlyArray<PropertyKey>
+			readonly place: Place.Place | undefined
 			readonly size: number
 			readonly algorithm: PolicyNodes.Algorithm
 			readonly rules: ReadonlyArray<number>
 	  }
 	| {
 			readonly _tag: "All" | "Any" | "FirstOf"
-			readonly path: ReadonlyArray<PropertyKey>
+			readonly place: Place.Place | undefined
 			readonly size: number
 			readonly policies: ReadonlyArray<Plan>
 	  }
 	| {
 			readonly _tag: "Ceiling"
-			readonly path: ReadonlyArray<PropertyKey>
+			readonly place: Place.Place | undefined
 			readonly size: number
 			readonly cap: Plan
 			readonly policy: Plan
@@ -252,11 +256,13 @@ type Plan =
  * the value, so its size counts in the budget.
  */
 const decodeMeta = (
-	{ input, path }: RuleInput,
+	rule: RuleInput,
 	domain: Domain.Any,
 	budget: Json.Budget,
-): Effect.Effect<unknown, Json.Problem> =>
-	Effect.flatMap(
+): Effect.Effect<unknown, Json.Problem> => {
+	const { input } = rule
+	const path = Place.pathOf(rule.place)
+	return Effect.flatMap(
 		attempt(() =>
 			typeof input !== "object" || input === null
 				? undefined
@@ -285,13 +291,16 @@ const decodeMeta = (
 							}),
 					),
 	)
+}
 
 const decodeRule = (
-	{ input, path }: RuleInput,
+	rule: RuleInput,
 	meta: unknown,
 	budget: Json.Budget,
 	domain: Domain.Any,
 ): Rule.Rule => {
+	const { input } = rule
+	const path = Place.pathOf(rule.place)
 	if (typeof input !== "object" || input === null) {
 		throw Json.problem(path, "A rule must be an object")
 	}
@@ -330,11 +339,13 @@ const decodeRule = (
 /**
  * Reads the shape of a tree, and puts each rule in `rules`. The rules are
  * decoded after the walk: a condition has levels of its own, and a decode
- * inside the walk would go down the levels of both.
+ * inside the walk would go down the levels of both. `path` is the path of the
+ * node for a problem here, and `place` keeps it for later.
  */
 const readTree = (
 	input: unknown,
 	path: ReadonlyArray<PropertyKey>,
+	place: Place.Place | undefined,
 	depth: number,
 	budget: Json.Budget,
 	// The rules of one decode. The list belongs to that decode.
@@ -350,8 +361,15 @@ const readTree = (
 		throw Json.problem(path, "A node of a policy must be an object")
 	}
 	Json.spend(budget, 1, path)
-	const child = (value: unknown, at: ReadonlyArray<PropertyKey>) =>
-		readTree(value, at, depth + 1, budget, rules)
+	const child = (value: unknown, ...parts: ReadonlyArray<PropertyKey>) =>
+		readTree(
+			value,
+			[...path, ...parts],
+			Place.at(place, ...parts),
+			depth + 1,
+			budget,
+			rules,
+		)
 	const tag = Json.read(input, "_tag", path)
 	switch (tag) {
 		case "Rules": {
@@ -365,11 +383,14 @@ const readTree = (
 			const found = Arr.map(
 				Json.readList(input, "rules", path, budget),
 				(rule, index) =>
-					rules.push({ input: rule, path: [...path, "rules", index] }) - 1,
+					rules.push({
+						input: rule,
+						place: Place.at(place, "rules", index),
+					}) - 1,
 			)
-			return sized({
+			return sized(path, {
 				_tag: "Rules",
-				path,
+				place,
 				size: 1 + found.length,
 				algorithm: algorithm as PolicyNodes.Algorithm,
 				rules: found,
@@ -380,24 +401,21 @@ const readTree = (
 		case "FirstOf": {
 			const policies = Arr.map(
 				Json.readList(input, "policies", path, budget),
-				(value, index) => child(value, [...path, "policies", index]),
+				(value, index) => child(value, "policies", index),
 			)
-			return sized({
+			return sized(path, {
 				_tag: tag,
-				path,
+				place,
 				size: Arr.reduce(policies, 1, (total, plan) => total + plan.size),
 				policies,
 			})
 		}
 		case "Ceiling": {
-			const cap = child(Json.read(input, "cap", path), [...path, "cap"])
-			const policy = child(Json.read(input, "policy", path), [
-				...path,
-				"policy",
-			])
-			return sized({
+			const cap = child(Json.read(input, "cap", path), "cap")
+			const policy = child(Json.read(input, "policy", path), "policy")
+			return sized(path, {
 				_tag: "Ceiling",
-				path,
+				place,
 				size: 1 + cap.size + policy.size,
 				cap,
 				policy,
@@ -409,10 +427,10 @@ const readTree = (
 }
 
 /** Stops a plan past `policyNodes`, with the message of the nodes. */
-const sized = (plan: Plan): Plan => {
+const sized = (path: ReadonlyArray<PropertyKey>, plan: Plan): Plan => {
 	if (plan.size > Limits.policyNodes) {
 		throw Json.problem(
-			plan.path,
+			path,
 			`A policy tree has ${String(plan.size)} nodes. The most is ${String(Limits.policyNodes)}.`,
 		)
 	}
@@ -443,7 +461,7 @@ const build = (plan: Plan, rules: ReadonlyArray<Rule.Rule>): Node => {
 	} catch (error) {
 		// A node past a limit is a problem at its place.
 		if (error instanceof Limits.LimitExceeded) {
-			throw Json.problem(plan.path, error.message)
+			throw Json.problem(Place.pathOf(plan.place), error.message)
 		}
 		throw error
 	}
@@ -474,7 +492,9 @@ export const decode = (
 		const budget: Json.Budget = { used: 0 }
 		// The rules of this decode. The list belongs to this decode.
 		const inputs: Array<RuleInput> = []
-		const plan = yield* attempt(() => readTree(input, [], 1, budget, inputs))
+		const plan = yield* attempt(() =>
+			readTree(input, [], undefined, 1, budget, inputs),
+		)
 		const metas = yield* Effect.forEach(inputs, (rule) =>
 			decodeMeta(rule, domain, budget),
 		)

package/src/internal/rule.ts

@@ -9,6 +9,7 @@ import * as Arr from "effect/Array"
 import * as Data from "effect/Data"
 import * as Condition from "../Condition.ts"
 import type * as Domain from "../Domain.ts"
+import type * as Policy from "../Policy.ts"
 import type * as Resource from "../Resource.ts"
 import * as Catalog from "./catalog.ts"
 import * as Nodes from "./nodes.ts"
@@ -33,17 +34,42 @@ export interface Shape {
 	readonly domain?: Domain.Any
 }
 
-/** The class of every rule value. */
-export class Rule extends Data.Class<Shape> {
-	*[Symbol.iterator](): Generator<this, this, unknown> {
+/**
+ * The class of every rule value. The types are those of `Policy.Rule`: `D` is
+ * the domain, `I` is what the tests of the condition read, and `X` is the
+ * mark of the condition. With no types, as in the nodes of a policy, a rule
+ * fits no domain, its condition fits no other rule, and it may have a
+ * predicate.
+ */
+export class Rule<D = never, I = never, X = unknown> extends Data.Class<
+	Policy.RuleShape<I, X>
+> {
+	/** Only in the types. */
+	declare readonly "~Opaque": () => X
+	/** Only in the types. */
+	declare readonly "~Domain": (domain: D) => D
+	// A private field makes the type of a rule its own, as for a policy: a
+	// spread of a rule, or an object made by hand, is not a rule. `Equal` does
+	// not read it. It comes last, so its `;` stays: the generator method below
+	// needs one after a field. Node.js takes the `declare` fields out of the
+	// code, and a `;` after one of them would go with it.
+	readonly #rule = true;
+
+	*[Symbol.iterator](): Generator<Rule<D, I, X>, Rule<D, I, X>, unknown> {
 		yield this
 		return this
 	}
+
+	/** Tests if a value is a rule, by its private field. */
+	static is(u: unknown): u is Rule {
+		return typeof u === "object" && u !== null && #rule in u
+	}
 }
 
 /** Makes a rule from its data. It does not check the data against a domain. */
 export const make = (data: Shape): Rule =>
 	// A missing option is left out, so two rules with the same data are equal.
+	// The data has no types here, as the code below works with no types.
 	new Rule({
 		_tag: data._tag,
 		actions: [...data.actions],
@@ -54,7 +80,7 @@ export const make = (data: Shape): Rule =>
 		...(data.id === undefined ? {} : { id: data.id }),
 		...(data.meta === undefined ? {} : { meta: data.meta }),
 		...(data.domain === undefined ? {} : { domain: data.domain }),
-	})
+	} as never)
 
 /**
  * Makes a rule from its data, as `Policy.rule` does. A condition with a
@@ -71,7 +97,7 @@ export const makePlain = (data: Shape): Rule => {
 }
 
 /** Tests if a value is a rule. */
-export const isRule = (u: unknown): u is Rule => u instanceof Rule
+export const isRule = (u: unknown): u is Rule => Rule.is(u)
 
 const toArray = <A>(value: A | ReadonlyArray<A>): ReadonlyArray<A> =>
 	Array.isArray(value) ? value : [value as A]
@@ -132,6 +158,31 @@ export const matchesField = (pattern: string, field: string): boolean =>
 export const matchesInside = (pattern: string, field: string): boolean =>
 	Patterns.matchesBelow(Patterns.parseBound(pattern), field.split("."))
 
+/**
+ * Makes the test "a field pattern matches some field of the catalog" for one
+ * walk, such as one decision. A policy may name one pattern very many times,
+ * so the test keeps each answer by the text of the pattern, and the memo goes
+ * away when the walk ends. The binding puts a limit on the work of the
+ * patterns of a policy on each kind, so one walk does at most that work.
+ */
+export const fitsOf = (
+	catalog: Catalog.Catalog,
+): ((pattern: string) => boolean) => {
+	// A native `Map`: the hash of a string in Effect has no random seed, and a
+	// policy could hold very many patterns with one hash. The engine hashes a
+	// string with a random seed.
+	const memo = new Map<string, boolean>()
+	return (pattern) => {
+		const known = memo.get(pattern)
+		if (known !== undefined) {
+			return known
+		}
+		const found = Patterns.fitsCatalog(Patterns.parseBound(pattern), catalog)
+		memo.set(pattern, found)
+		return found
+	}
+}
+
 /**
  * Tests the parts of a rule that do not need the resource value: the action,
  * the kind and the field.
@@ -152,6 +203,8 @@ export const matchesTarget = (
 		readonly kind: string
 		readonly field?: string | undefined
 		readonly descriptor?: Resource.Descriptor | undefined
+		/** The test of {@link fitsOf} for the catalog of the descriptor. */
+		readonly fits?: ((pattern: string) => boolean) | undefined
 	},
 ): boolean => {
 	if (!rule.actions.includes("*") && !rule.actions.includes(target.action)) {
@@ -173,12 +226,7 @@ export const matchesTarget = (
 		return (
 			rule._tag === "Allow" &&
 			(descriptor === undefined ||
-				Arr.some(rule.fields, (pattern) =>
-					Patterns.fitsCatalog(
-						Patterns.parseBound(pattern),
-						descriptor.catalog,
-					),
-				))
+				Arr.some(rule.fields, target.fits ?? fitsOf(descriptor.catalog)))
 		)
 	}
 	const field = target.field

package/src/internal/search.ts

@@ -11,9 +11,6 @@
  */
 import * as Arr from "effect/Array"
 import * as Data from "effect/Data"
-import * as HashMap from "effect/HashMap"
-import * as HashSet from "effect/HashSet"
-import * as MutableHashMap from "effect/MutableHashMap"
 import * as Option from "effect/Option"
 import { isObject } from "effect/Predicate"
 import * as Algebra from "./algebra.ts"
@@ -146,14 +143,24 @@ const cellText = (cell: unknown): string =>
 			? `number:${Object.is(cell, -0) ? "0" : String(cell)}`
 			: `${typeof cell}:${String(cell)}`
 
-/** Keeps the first cell of each text, in order. */
-const dedupeCells = (cells: ReadonlyArray<unknown>): ReadonlyArray<unknown> =>
-	Arr.flatten(
-		Arr.mapAccum(cells, HashSet.empty<string>(), (seen, cell) => {
-			const text = cellText(cell)
-			return [HashSet.add(seen, text), HashSet.has(seen, text) ? [] : [cell]]
-		})[1],
-	)
+/**
+ * Keeps the first cell of each text, in order. The texts come from the
+ * values of a policy, so they go into a native `Set`: the hash of a string in
+ * Effect has no random seed, and a policy could hold very many strings with
+ * one hash. The engine hashes a string with a random seed.
+ */
+const dedupeCells = (cells: ReadonlyArray<unknown>): ReadonlyArray<unknown> => {
+	// The set belongs to this call.
+	const seen = new Set<string>()
+	return Arr.filter(cells, (cell) => {
+		const text = cellText(cell)
+		if (seen.has(text)) {
+			return false
+		}
+		seen.add(text)
+		return true
+	})
+}
 
 /** Gives one value from each cell of a field. */
 const cellsOf = (
@@ -185,16 +192,22 @@ interface Search {
 	 * The texts of the values of each `In` test, so one test of a value does
 	 * not read every value of the test. It is a native `Map`, because it must
 	 * find a node by the node itself: a hash of a node reads all its values.
+	 * The texts are in a native `Set`, as in {@link dedupeCells}.
 	 */
-	readonly members: Map<Nodes.In, HashSet.HashSet<string>>
+	readonly members: Map<Nodes.In, Set<string>>
+	/**
+	 * The texts of the structure of the conditions that the search found to be
+	 * unsatisfiable. A condition with the same structure has the same free
+	 * fields, so its answer is the same. The set only grows, so the steps of a
+	 * search may share it. It is a native `Set`, as in {@link dedupeCells}.
+	 */
+	readonly failed: Set<string>
 	readonly budget: number
 }
 
 /** What a search has done up to now. Each step gives a new one. */
 interface SearchState {
 	readonly steps: number
-	/** The conditions that the search found to be unsatisfiable. */
-	readonly failed: HashSet.HashSet<Node>
 }
 
 interface Found {
@@ -228,13 +241,13 @@ const fixedValue = (
 				: null
 			: free
 
-const membersOf = (node: Nodes.In, search: Search): HashSet.HashSet<string> => {
+const membersOf = (node: Nodes.In, search: Search): Set<string> => {
 	const known = search.members.get(node)
 	if (known !== undefined) {
 		return known
 	}
 	// `===` finds no `NaN`, so the set has none, and `NaN` is in no test.
-	const members = HashSet.fromIterable(
+	const members = new Set(
 		Arr.map(
 			Arr.filter(
 				Arr.map(node.values, literalOf),
@@ -257,8 +270,7 @@ const testFixed = (
 			return Algebra.testCompare(node.op, value, literalOf(node.value))
 		case "In":
 			return (
-				!Number.isNaN(value) &&
-				HashSet.has(membersOf(node, search), cellText(value))
+				!Number.isNaN(value) && membersOf(node, search).has(cellText(value))
 			)
 		case "Exists":
 			return value !== null
@@ -318,13 +330,11 @@ const testedFields = (node: Node): ReadonlyArray<string> => {
  * and then the first name in order, so the choice is the same each time.
  */
 const nextField = (node: Node): string => {
-	const counts = MutableHashMap.empty<string, number>()
+	// A native `Map`, as in `dedupeCells`: a condition that is not bound to a
+	// domain may have any field names. The map belongs to this call.
+	const counts = new Map<string, number>()
 	Arr.forEach(testedFields(node), (field) =>
-		MutableHashMap.set(
-			counts,
-			field,
-			Option.getOrElse(MutableHashMap.get(counts, field), () => 0) + 1,
-		),
+		counts.set(field, (counts.get(field) ?? 0) + 1),
 	)
 	const depth = (field: string) => field.split(".").length
 	const [first, ...rest] = Array.from(counts)
@@ -351,7 +361,13 @@ const searchNode = (
 	if (node._tag === "True") {
 		return { assignment: Option.some(assignment), state }
 	}
-	if (node._tag === "False" || HashSet.has(state.failed, node)) {
+	if (node._tag === "False") {
+		return { assignment: Option.none(), state }
+	}
+	// The text reads all of the node. The step before counted the size of a
+	// larger node, so the budget counts this work too.
+	const text = Algebra.structureText(node)
+	if (search.failed.has(text)) {
 		return { assignment: Option.none(), state }
 	}
 	if (state.steps + node.size > search.budget) {
@@ -383,17 +399,10 @@ const searchNode = (
 			)
 		},
 	)
-	return Option.isSome(result.assignment)
-		? result
-		: {
-				assignment: Option.none(),
-				state: {
-					...result.state,
-					// A condition with the same structure has the same free fields,
-					// so its answer is the same.
-					failed: HashSet.add(result.state.failed, node),
-				},
-			}
+	if (Option.isNone(result.assignment)) {
+		search.failed.add(text)
+	}
+	return result
 }
 
 /**
@@ -434,10 +443,12 @@ const exampleOf = (
 		(root, [field, value]) => setPath(root, field.split("."), value),
 	)
 
-/** The constants that the tests of each field use. */
-const constantsOf = (
-	node: Node,
-): HashMap.HashMap<string, HashSet.HashSet<Nodes.Scalar>> => {
+/**
+ * The constants that the tests of each field use. They come from a policy, so
+ * they go into a native `Map` and `Set`, as in {@link dedupeCells}. The map
+ * belongs to one search.
+ */
+const constantsOf = (node: Node): Map<string, Set<Nodes.Scalar>> => {
 	const pairs = (
 		current: Node,
 	): ReadonlyArray<readonly [string, ReadonlyArray<Nodes.Scalar>]> => {
@@ -461,16 +472,13 @@ const constantsOf = (
 				return []
 		}
 	}
-	return Arr.reduce(pairs(node), HashMap.empty(), (all, [field, values]) =>
-		HashMap.set(
-			all,
-			field,
-			HashSet.union(
-				Option.getOrElse(HashMap.get(all, field), HashSet.empty),
-				HashSet.fromIterable(values),
-			),
-		),
-	)
+	const all = new Map<string, Set<Nodes.Scalar>>()
+	Arr.forEach(pairs(node), ([field, values]) => {
+		const known = all.get(field) ?? new Set<Nodes.Scalar>()
+		Arr.forEach(values, (value) => known.add(value))
+		all.set(field, known)
+	})
+	return all
 }
 
 /** Gives the kinds of each field of a catalog. A field that it does not have may hold any value. */
@@ -495,38 +503,33 @@ export const satisfiable = (
 	}
 	const constants = constantsOf(node)
 	// The search calls itself one time for each field that it fixes.
-	if (HashMap.size(constants) > Limits.searchFields) {
+	if (constants.size > Limits.searchFields) {
 		return satisfiability.Unknown({ reason: "budget" })
 	}
-	// The cells of each field. A field name is a string, so an Effect map
-	// finds it.
-	const cells = MutableHashMap.empty<string, ReadonlyArray<unknown>>()
+	// The cells of each field, in a native `Map` as the constants are.
+	const cells = new Map<string, ReadonlyArray<unknown>>()
 	const search: Search = {
 		members: new Map(),
-		cells: (field) =>
-			Option.getOrElse(MutableHashMap.get(cells, field), () => {
-				// The cells come from the constants, so many constants are work
-				// that the budget must count before the cells are made.
-				const known = Option.getOrElse(
-					HashMap.get(constants, field),
-					HashSet.empty,
-				)
-				if (HashSet.size(known) > budget) {
-					throw new OutOfBudget()
-				}
-				const found = cellsOf(kindsOf(field), Array.from(known))
-				MutableHashMap.set(cells, field, found)
-				return found
-			}),
+		failed: new Set(),
+		cells: (field) => {
+			const made = cells.get(field)
+			if (made !== undefined) {
+				return made
+			}
+			// The cells come from the constants, so many constants are work
+			// that the budget must count before the cells are made.
+			const known = constants.get(field) ?? new Set<Nodes.Scalar>()
+			if (known.size > budget) {
+				throw new OutOfBudget()
+			}
+			const found = cellsOf(kindsOf(field), Array.from(known))
+			cells.set(field, found)
+			return found
+		},
 		budget,
 	}
 	try {
-		const found = searchNode(
-			Algebra.simplify(node),
-			search,
-			{ steps: 0, failed: HashSet.empty() },
-			[],
-		)
+		const found = searchNode(Algebra.simplify(node), search, { steps: 0 }, [])
 		return Option.match(found.assignment, {
 			onNone: () => satisfiability.Unsatisfiable(),
 			onSome: (assignment) =>