@orkestrel/qualifier 0.0.1

package/dist/src/core/index.cjs

@@ -0,0 +1,747 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _orkestrel_contract = require("@orkestrel/contract");
+let _orkestrel_reason = require("@orkestrel/reason");
+let _orkestrel_emitter = require("@orkestrel/emitter");
+//#region src/core/constants.ts
+/** Default definition validation policy for `createQualifier` / `Qualifier.qualify`. */
+var DEFAULT_QUALIFIER_VALIDATE = true;
+/** The reserved internal projection namespace a pass's working projection is written under. */
+var QUALIFICATION_KEY = "qualification";
+/** Eligibility severity order — most to least severe. */
+var ELIGIBILITY_PRECEDENCE = Object.freeze([
+	"ineligible",
+	"referral",
+	"eligible"
+]);
+/** The eligibility impact of each {@link QualificationEffect}; `condition` remains eligible. */
+var EFFECT_ELIGIBILITIES = Object.freeze({
+	restriction: "ineligible",
+	referral: "referral",
+	condition: "eligible"
+});
+//#endregion
+//#region src/core/errors.ts
+/**
+* A coded programmer error thrown by the qualifier layer.
+*
+* @remarks
+* `DEFINITION` — a qualification definition failed semantic validation.
+* `MISMATCH` — a subject is not a record or already carries the reserved
+* `qualification` key. `DESTROYED` — use of a destroyed qualifier.
+*/
+var QualifierError = class extends Error {
+	code;
+	context;
+	constructor(code, message, context) {
+		super(message);
+		this.name = "QualifierError";
+		this.code = code;
+		this.context = context;
+	}
+};
+/** Narrow a caught value to a {@link QualifierError}. */
+function isQualifierError(value) {
+	return value instanceof QualifierError;
+}
+//#endregion
+//#region src/core/validators.ts
+/** Determine whether a value is an {@link Eligibility} literal. */
+var isEligibility = (0, _orkestrel_contract.literalOf)("eligible", "ineligible", "referral");
+/** Determine whether a value is a {@link QualificationEffect} literal. */
+var isQualificationEffect = (0, _orkestrel_contract.literalOf)("restriction", "referral", "condition");
+/** Determine whether a value is a {@link QualificationPass} (a quantitative or logical definition). */
+function isQualificationPass(value) {
+	return (0, _orkestrel_reason.isQuantitativeDefinition)(value) || (0, _orkestrel_reason.isLogicalDefinition)(value);
+}
+/** Determine whether a value is an exact {@link Ruling} record. */
+function isRuling(value) {
+	return (0, _orkestrel_contract.recordOf)({
+		id: _orkestrel_contract.isString,
+		pass: _orkestrel_contract.isString,
+		rule: _orkestrel_contract.isString,
+		effect: isQualificationEffect,
+		scope: _orkestrel_contract.isString,
+		message: _orkestrel_contract.isString
+	}, ["scope", "message"])(value);
+}
+/** Determine whether a value is an exact {@link QualificationDefinition} record. */
+function isQualificationDefinition(value) {
+	if (!(0, _orkestrel_contract.isRecord)(value)) return false;
+	return (0, _orkestrel_contract.recordOf)({
+		id: _orkestrel_contract.isString,
+		name: _orkestrel_contract.isString,
+		description: _orkestrel_contract.isString,
+		passes: (0, _orkestrel_contract.arrayOf)(isQualificationPass),
+		rulings: (0, _orkestrel_contract.arrayOf)(isRuling),
+		metadata: _orkestrel_contract.isRecord
+	}, [
+		"description",
+		"rulings",
+		"metadata"
+	])(value);
+}
+//#endregion
+//#region src/core/helpers.ts
+/**
+* Interpolate `{{dotted.path}}` tokens in a message template against a subject.
+*
+* @remarks
+* Each token is split on `.` into a `FieldPath` array and resolved with
+* `resolveField` (a plain string field is ONE key, never dot-split — the split
+* here is the token-to-path bridge). A finite number renders with `en-US`
+* thousand grouping (`5010` → `5,010`); any other resolved value String-coerces.
+* An UNRESOLVED path renders as the empty string.
+*
+* @param template - The message template carrying `{{dotted.path}}` tokens
+* @param subject - The record tokens resolve against
+* @returns The template with every token replaced
+*
+* @example
+* ```ts
+* import { interpolateMessage } from '@orkestrel/qualifier'
+*
+* interpolateMessage('Limit is {{limit}}', { limit: 5010 }) // 'Limit is 5,010'
+* interpolateMessage('Missing {{gone}}', {})                // 'Missing '
+* ```
+*/
+function interpolateMessage(template, subject) {
+	return template.replace(/\{\{\s*([^}]+?)\s*\}\}/g, (_match, path) => {
+		const value = (0, _orkestrel_contract.resolveField)(subject, path.split("."));
+		if (value === void 0) return "";
+		if ((0, _orkestrel_contract.isFiniteNumber)(value)) return value.toLocaleString("en-US");
+		return String(value);
+	});
+}
+/**
+* Describe a {@link Premise} comparison as a display-neutral verb phrase.
+*
+* @param comparison - The comparison to describe
+* @returns A display-neutral phrase
+*
+* @example
+* ```ts
+* import { describeComparison } from '@orkestrel/qualifier'
+*
+* describeComparison('above') // 'is more than'
+* ```
+*/
+function describeComparison(comparison) {
+	switch (comparison) {
+		case "equals": return "is";
+		case "not": return "is not";
+		case "above": return "is more than";
+		case "below": return "is less than";
+		case "from": return "is at least";
+		case "to": return "is at most";
+		case "any": return "is any of";
+		case "none": return "is none of";
+		case "between": return "is between";
+		case "outside": return "is outside";
+	}
+}
+/**
+* Render a structured or scalar expected value display-neutrally.
+*
+* @remarks
+* An array renders as its elements, each `String`-coerced, joined with `', '`.
+* A reason `Bounds`-shaped record (the `between` / `outside` expected value)
+* renders its present sides joined with the word `and`; an absent side is
+* omitted. A finite number and everything else fall back to plain `String()` —
+* a finite number is NOT grouped here (grouping is {@link interpolateMessage}'s
+* message-token-only behavior).
+*
+* @param value - The value to render
+* @returns A display-neutral rendering
+*
+* @example
+* ```ts
+* import { describeValue } from '@orkestrel/qualifier'
+*
+* describeValue([18, 25, 40]) // '18, 25, 40'
+* describeValue({ minimum: 18, maximum: 65 }) // '18 and 65'
+* describeValue(42) // '42'
+* ```
+*/
+function describeValue(value) {
+	if (Array.isArray(value)) return value.map((entry) => String(entry)).join(", ");
+	if ((0, _orkestrel_reason.isBounds)(value)) {
+		const sides = [];
+		if (value.minimum !== void 0) sides.push(String(value.minimum));
+		if (value.maximum !== void 0) sides.push(String(value.maximum));
+		return sides.join(" and ");
+	}
+	return String(value);
+}
+/**
+* Render one {@link Premise} into a display-neutral sentence.
+*
+* @param entry - The premise to render
+* @param labels - Optional field-to-label overrides, keyed by dot-joined field
+* @returns A display-neutral sentence
+*
+* @example
+* ```ts
+* import { describePremise } from '@orkestrel/qualifier'
+*
+* describePremise({ field: 'age', comparison: 'above', expected: 18, actual: 25, met: true })
+* // 'age is more than 18 → met'
+* ```
+*/
+function describePremise(entry, labels) {
+	const status = entry.met === void 0 ? "unknown" : entry.met ? "met" : "not met";
+	if (entry.field === void 0 || entry.comparison === void 0) return `${entry.description ?? "Premise"} → ${status}`;
+	const field = (0, _orkestrel_reason.formatField)(entry.field);
+	const label = labels?.[field] ?? entry.label ?? field;
+	const expected = entry.expected === void 0 ? "" : ` ${describeValue(entry.expected)}`;
+	return `${label} ${describeComparison(entry.comparison)}${expected} → ${status}`;
+}
+/**
+* Build a {@link Premise} from an authored {@link Check} and its evaluated
+* `CheckResult`.
+*
+* @param check - The authored check
+* @param result - The evaluated check result carrying the resolved `actual` and `met`
+* @param labels - Optional field-to-label overrides, keyed by dot-joined field
+* @returns A fresh premise
+*
+* @example
+* ```ts
+* import { premiseCheck } from '@orkestrel/qualifier'
+* import { check } from '@orkestrel/reason'
+*
+* const authored = check('age', 'above', 18)
+* premiseCheck(authored, { field: 'age', actual: 25, met: true })
+* // { field: 'age', comparison: 'above', expected: 18, actual: 25, met: true }
+* ```
+*/
+function premiseCheck(check, result, labels) {
+	const field = (0, _orkestrel_reason.formatField)(check.field);
+	return {
+		field: check.field,
+		...labels?.[field] === void 0 ? {} : { label: labels[field] },
+		comparison: check.operator,
+		expected: check.value,
+		actual: result.actual,
+		...result.met === void 0 ? {} : { met: result.met }
+	};
+}
+/**
+* Build rich premises for one fired {@link Rule} by walking its premise atoms
+* and re-evaluating each against the working subject.
+*
+* @remarks
+* A reason rule result carries only booleans, so this is the qualifier's own
+* premise-audit projection: each authored premise expression is flattened to its
+* atom leaves via `extractAtoms`, and each leaf's `Check` is re-evaluated through
+* the injected `evaluator`. A membership check (`any` / `none`) over an EMPTY
+* array value is content-free and is skipped.
+*
+* @param rule - The authored rule
+* @param working - The working subject to evaluate against
+* @param evaluator - The shared reason check evaluator
+* @param labels - Optional field-to-label overrides, keyed by dot-joined field
+* @returns A fresh, ordered list of rich premises
+*
+* @example
+* ```ts
+* import { logicalPremises } from '@orkestrel/qualifier'
+* import { atom, createEvaluator, logicalDefinition, rule } from '@orkestrel/reason'
+*
+* const gates = logicalDefinition('gates', 'Gates', [
+*   rule('licensed', [atom('licensed', 'equals', false)], atom('blocked', 'equals', true)),
+* ])
+* const evaluator = createEvaluator()
+* const premises = logicalPremises(gates.rules[0], { licensed: false }, evaluator)
+*
+* premises[0]?.met // true
+* ```
+*/
+function logicalPremises(rule, working, evaluator, labels) {
+	const output = [];
+	for (const premise of rule.premises) for (const atom of (0, _orkestrel_reason.extractAtoms)(premise)) {
+		const { check } = atom;
+		if ((check.operator === "any" || check.operator === "none") && Array.isArray(check.value) && check.value.length === 0) continue;
+		output.push(premiseCheck(check, evaluator.evaluate(check, working), labels));
+	}
+	return output;
+}
+/**
+* Locate an authored {@link Rule} by id.
+*
+* @param definition - The logical definition to search
+* @param id - The rule id
+* @returns The matching rule, or `undefined`
+*
+* @example
+* ```ts
+* import { findRule } from '@orkestrel/qualifier'
+* import { atom, logicalDefinition, rule } from '@orkestrel/reason'
+*
+* const gates = logicalDefinition('gates', 'Gates', [
+*   rule('licensed', [atom('licensed', 'equals', false)], atom('blocked', 'equals', true)),
+* ])
+*
+* findRule(gates, 'licensed')?.id // 'licensed'
+* ```
+*/
+function findRule(definition, id) {
+	return definition.rules.find((rule) => rule.id === id);
+}
+/**
+* Project one reason result into the internal qualification namespace.
+*
+* @remarks
+* A quantitative result contributes its numeric `value`. A logical result
+* contributes a record of its `conclusion` plus every applied rule's asserted
+* conclusion fields (`extractConclusions`). A mismatched pairing contributes
+* `false`. The projection is pure — it never mutates the subject or the result.
+*
+* @param definition - The pass definition that produced the result
+* @param result - The evaluated reason result
+* @returns The pass's working projection
+*/
+function reasonResultToProjection(definition, result) {
+	if (definition.reasoning === "quantitative" && result.reasoning === "quantitative") return result.value;
+	if (definition.reasoning !== "logical" || result.reasoning !== "logical") return false;
+	const projection = { conclusion: result.conclusion };
+	for (const resolved of result.rules) {
+		if (!resolved.applied) continue;
+		const authored = definition.rules.find((rule) => rule.id === resolved.id);
+		if (authored === void 0) continue;
+		const conclusions = (0, _orkestrel_reason.extractConclusions)(authored.conclusion);
+		for (const [key, value] of Object.entries(conclusions)) projection[key] = value;
+	}
+	return projection;
+}
+/**
+* Project a quantitative result into a {@link Derivation} audit record.
+*
+* @param id - The pass id
+* @param result - The evaluated quantitative result
+* @returns A fresh derivation
+*/
+function quantitativeResultToDerivation(id, result) {
+	return {
+		id,
+		value: result.value,
+		success: result.success,
+		trace: [...result.trace],
+		errors: [...result.errors]
+	};
+}
+/**
+* Wrap a {@link QualificationContext} under {@link QUALIFICATION_KEY}.
+*
+* @param context - The accumulated projection context
+* @returns A record carrying the context under the reserved key
+*/
+function qualificationToRecord(context) {
+	return { [QUALIFICATION_KEY]: context };
+}
+/**
+* Copy-on-write merge one pass projection into the context.
+*
+* @param context - The current projection context
+* @param id - The pass id to project under
+* @param projection - The pass's working projection
+* @returns A fresh context with the projection added
+*/
+function mergeQualificationContext(context, id, projection) {
+	return {
+		...context,
+		[id]: projection
+	};
+}
+/**
+* Join a ruling, its logical rule result, the pass, the pre-projection subject,
+* and an evaluator into a {@link Finding}.
+*
+* @remarks
+* `applied` reflects whether the ruling's rule fired. Premises are re-evaluated
+* against the SAME subject snapshot the pass evaluated, so a conclusion the pass
+* derived can never satisfy its own reported premise. The message interpolates
+* against that snapshot.
+*
+* @param ruling - The authored ruling
+* @param pass - The pass the ruling's rule lives in
+* @param result - The pass's evaluated logical result
+* @param subject - The pre-projection subject snapshot the pass evaluated
+* @param evaluator - The shared reason check evaluator
+* @param labels - Optional field-to-label overrides, keyed by dot-joined field
+* @returns A fresh finding
+*/
+function rulingToFinding(ruling, pass, result, subject, evaluator, labels) {
+	const applied = result.rules.find((item) => item.id === ruling.rule)?.applied ?? false;
+	const rule = pass.reasoning === "logical" ? findRule(pass, ruling.rule) : void 0;
+	const premises = rule === void 0 ? [] : logicalPremises(rule, subject, evaluator, labels);
+	return {
+		id: ruling.id,
+		pass: ruling.pass,
+		rule: ruling.rule,
+		effect: ruling.effect,
+		...ruling.scope === void 0 ? {} : { scope: ruling.scope },
+		applied,
+		...ruling.message === void 0 ? {} : { message: interpolateMessage(ruling.message, subject) },
+		premises
+	};
+}
+/**
+* Derive global eligibility from applied, unscoped findings.
+*
+* @remarks
+* Only findings that both applied and carry no `scope` shape global eligibility.
+* A failed pass contributes a synthetic `referral` (fail-closed), passed through
+* `failed`.
+*
+* @param findings - The resolved findings
+* @param failed - Whether an operational pass failure occurred
+* @returns The most severe global eligibility
+*/
+function deriveFindingEligibility(findings, failed = false) {
+	const eligibilities = findings.filter((finding) => finding.applied && finding.scope === void 0).map((finding) => EFFECT_ELIGIBILITIES[finding.effect]);
+	if (failed) eligibilities.push("referral");
+	return combineEligibilities(eligibilities);
+}
+/**
+* Return the most severe {@link Eligibility} in a list.
+*
+* @param eligibilities - The eligibilities to combine
+* @returns The most severe eligibility, or `'eligible'` for an empty list
+*
+* @example
+* ```ts
+* import { combineEligibilities } from '@orkestrel/qualifier'
+*
+* combineEligibilities(['eligible', 'referral']) // 'referral'
+* ```
+*/
+function combineEligibilities(eligibilities) {
+	for (const eligibility of ELIGIBILITY_PRECEDENCE) if (eligibilities.includes(eligibility)) return eligibility;
+	return "eligible";
+}
+/**
+* Derive one eligibility per finding scope.
+*
+* @remarks
+* Only applied, scoped findings contribute. Each named scope combines its own
+* findings' impacts by severity. An unmentioned scope is absent (eligible by
+* default at the program layer).
+*
+* @param findings - The resolved findings
+* @returns A fresh record of scope to its combined eligibility
+*/
+function deriveScopeEligibilities(findings) {
+	const grouped = {};
+	for (const finding of findings) {
+		if (!finding.applied || finding.scope === void 0) continue;
+		const current = grouped[finding.scope] ?? [];
+		grouped[finding.scope] = [...current, EFFECT_ELIGIBILITIES[finding.effect]];
+	}
+	const scopes = {};
+	for (const [scope, eligibilities] of Object.entries(grouped)) scopes[scope] = combineEligibilities(eligibilities);
+	return scopes;
+}
+/**
+* Find rulings whose pass or rule does not exist, whose pass is not logical, or
+* a pass id shadowing the reserved {@link QUALIFICATION_KEY}.
+*
+* @param definition - The qualification definition to check
+* @returns A fresh list of reference-error messages
+*/
+function findMissingReferences(definition) {
+	const errors = [];
+	const passes = new Map(definition.passes.map((pass) => [pass.id, pass]));
+	for (const pass of definition.passes) if (pass.id === "qualification") errors.push(`Pass id must not equal reserved key '${QUALIFICATION_KEY}'`);
+	for (const ruling of definition.rulings ?? []) {
+		const pass = passes.get(ruling.pass);
+		if (pass === void 0) {
+			errors.push(`Ruling '${ruling.id}' references missing pass '${ruling.pass}'`);
+			continue;
+		}
+		if (pass.reasoning !== "logical") {
+			errors.push(`Ruling '${ruling.id}' references non-logical pass '${ruling.pass}'`);
+			continue;
+		}
+		if (findRule(pass, ruling.rule) === void 0) errors.push(`Ruling '${ruling.id}' references missing rule '${ruling.rule}' in pass '${ruling.pass}'`);
+	}
+	return errors;
+}
+/**
+* Find duplicate ids in a list, once each.
+*
+* @param ids - The ids to scan
+* @returns A fresh list of ids that appear more than once
+*/
+function findDuplicateIds(ids) {
+	const seen = /* @__PURE__ */ new Set();
+	const duplicates = /* @__PURE__ */ new Set();
+	for (const id of ids) if (seen.has(id)) duplicates.add(id);
+	else seen.add(id);
+	return [...duplicates];
+}
+/**
+* Determine whether a subject already owns the reserved {@link QUALIFICATION_KEY}.
+*
+* @param subject - The subject to check
+* @returns `true` when the subject owns the reserved key
+*/
+function hasReservedKey(subject) {
+	return Object.hasOwn(subject, QUALIFICATION_KEY);
+}
+/**
+* Assert a value is a valid qualification {@link Subject}, narrowing it in place.
+*
+* @param value - The candidate subject to validate
+* @throws {@link QualifierError} `'MISMATCH'` when the value is not a record, or
+* when it already carries the reserved `qualification` key
+*/
+function assertSubject(value) {
+	if (!(0, _orkestrel_contract.isRecord)(value)) throw new QualifierError("MISMATCH", "Qualification subject must be a record");
+	if (hasReservedKey(value)) throw new QualifierError("MISMATCH", `Qualification subject must not contain reserved key '${QUALIFICATION_KEY}'`);
+}
+//#endregion
+//#region src/core/Qualifier.ts
+/**
+* A qualifier — runs ordered passes over one reason engine and returns
+* pre-rating eligibility.
+*
+* @remarks
+* The engine is OWNED when self-created (destroyed on `destroy()`) and borrowed
+* when injected (never destroyed). `qualify` builds its working subject through
+* copy-on-write overlays only — the caller's `subject` is never mutated, and the
+* qualifier's internal projection is discarded after each call.
+*/
+var Qualifier = class {
+	#emitter;
+	#engine;
+	#evaluator;
+	#owned;
+	#validate;
+	#labels;
+	#destroyed = false;
+	constructor(options) {
+		this.#emitter = new _orkestrel_emitter.Emitter({
+			on: options?.on,
+			error: options?.error
+		});
+		this.#evaluator = (0, _orkestrel_reason.createEvaluator)();
+		this.#owned = options?.engine === void 0;
+		this.#engine = options?.engine ?? (0, _orkestrel_reason.createReason)({
+			reasoners: [(0, _orkestrel_reason.createQuantitativeReasoner)({ evaluator: this.#evaluator }), (0, _orkestrel_reason.createLogicalReasoner)({ evaluator: this.#evaluator })],
+			bail: false
+		});
+		this.#validate = options?.validate ?? true;
+		this.#labels = options?.labels;
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	qualify(subject, definition) {
+		this.#alive();
+		if (this.#validate) {
+			const validation = this.validate(definition);
+			if (!validation.valid) throw new QualifierError("DEFINITION", `Qualification definition is invalid: ${validation.errors.join(", ")}`, definition.id);
+		}
+		return this.#qualify(subject, definition);
+	}
+	validate(definition) {
+		this.#alive();
+		const errors = [];
+		const warnings = [];
+		if (definition.id.length === 0) errors.push("Definition id must not be empty");
+		if (definition.name.length === 0) errors.push("Definition name must not be empty");
+		if (definition.passes.length === 0) warnings.push("Definition has no passes");
+		for (const id of findDuplicateIds(definition.passes.map((pass) => pass.id))) errors.push(`Duplicate pass id '${id}'`);
+		for (const id of findDuplicateIds((definition.rulings ?? []).map((ruling) => ruling.id))) errors.push(`Duplicate ruling id '${id}'`);
+		for (const reference of findMissingReferences(definition)) errors.push(reference);
+		return {
+			valid: errors.length === 0,
+			errors,
+			warnings
+		};
+	}
+	destroy() {
+		if (this.#destroyed) return;
+		if (this.#owned) this.#engine.destroy();
+		this.#destroyed = true;
+		this.#emitter.emit("destroy");
+		this.#emitter.destroy();
+	}
+	#qualify(subject, definition) {
+		assertSubject(subject);
+		let context = {};
+		let working = { ...subject };
+		const findings = [];
+		const derivations = [];
+		const trace = [];
+		const errors = [];
+		let failed = false;
+		for (const pass of definition.passes) {
+			const evaluated = working;
+			const result = this.#engine.reason(evaluated, pass);
+			trace.push(...result.trace.map((entry) => `${pass.id}: ${entry}`));
+			errors.push(...result.errors.map((entry) => `${pass.id}: ${entry}`));
+			if (result.reasoning === "quantitative") {
+				const derivation = quantitativeResultToDerivation(pass.id, result);
+				derivations.push(derivation);
+				this.#emitter.emit("derive", derivation);
+			}
+			if (result.reasoning === "logical") {
+				const rulings = (definition.rulings ?? []).filter((ruling) => ruling.pass === pass.id);
+				for (const ruling of rulings) {
+					const finding = rulingToFinding(ruling, pass, result, evaluated, this.#evaluator, this.#labels);
+					findings.push(finding);
+					this.#emitter.emit("finding", finding);
+				}
+			}
+			const projection = reasonResultToProjection(pass, result);
+			context = mergeQualificationContext(context, pass.id, projection);
+			working = {
+				...subject,
+				...qualificationToRecord(context)
+			};
+			if (!result.success) {
+				failed = true;
+				break;
+			}
+			if (deriveFindingEligibility(findings) === "ineligible") break;
+		}
+		const success = !failed && errors.length === 0;
+		const qualification = {
+			id: definition.id,
+			name: definition.name,
+			eligibility: deriveFindingEligibility(findings, !success),
+			scopes: deriveScopeEligibilities(findings),
+			findings,
+			derivations,
+			success,
+			trace,
+			errors
+		};
+		this.#emitter.emit("qualify", qualification);
+		return qualification;
+	}
+	#alive() {
+		if (this.#destroyed) throw new QualifierError("DESTROYED", "Qualifier has been destroyed");
+	}
+};
+//#endregion
+//#region src/core/factories.ts
+/**
+* Create one qualifier over a reason engine.
+*
+* @remarks
+* A standalone qualifier creates and OWNS one shared quantitative-plus-logical
+* reason engine, destroying it on `destroy()`. An injected `options.engine`
+* remains caller-owned and is never destroyed. Validation is on by default.
+*
+* @param options - Optional injected engine, validation, labels, and emitter hooks
+* @returns A {@link QualifierInterface}
+*
+* @example
+* ```ts
+* import { createQualifier } from '@orkestrel/qualifier'
+*
+* const qualifier = createQualifier()
+* qualifier.qualify({ id: 'risk-1' }, definition)
+* qualifier.destroy()
+* ```
+*/
+function createQualifier(options) {
+	return new Qualifier(options);
+}
+/**
+* Build a {@link QualificationDefinition}.
+*
+* @remarks
+* Returns a fresh top-level definition, omitting absent optional keys;
+* `passes` and `rulings` arrays are copied, and record `metadata` is
+* shallow-copied so nested values are not deep-cloned.
+*
+* @param id - The definition id
+* @param name - The display name
+* @param passes - The ordered qualification passes
+* @param input - Optional description, rulings, and metadata
+* @returns A fresh qualification definition
+*
+* @example
+* ```ts
+* import { qualificationDefinition } from '@orkestrel/qualifier'
+*
+* qualificationDefinition('standard', 'Standard', [gates], { rulings: [ruling] })
+* ```
+*/
+function qualificationDefinition(id, name, passes, input) {
+	return {
+		id,
+		name,
+		passes: [...passes],
+		...input?.description === void 0 ? {} : { description: input.description },
+		...input?.rulings === void 0 ? {} : { rulings: [...input.rulings] },
+		...input?.metadata === void 0 ? {} : { metadata: { ...input.metadata } }
+	};
+}
+/**
+* Build a {@link Ruling} — one authored consequence for one rule in one pass.
+*
+* @param id - The ruling id
+* @param pass - The logical pass id the rule lives in
+* @param rule - The rule id whose firing this ruling reacts to
+* @param effect - The eligibility impact when the rule fires
+* @param input - Optional rating scope and message template
+* @returns A fresh ruling
+*
+* @example
+* ```ts
+* import { rulingDefinition } from '@orkestrel/qualifier'
+*
+* rulingDefinition('license', 'gates', 'licensed', 'restriction', { message: 'A license is required' })
+* ```
+*/
+function rulingDefinition(id, pass, rule, effect, input) {
+	return {
+		id,
+		pass,
+		rule,
+		effect,
+		...input?.scope === void 0 ? {} : { scope: input.scope },
+		...input?.message === void 0 ? {} : { message: input.message }
+	};
+}
+//#endregion
+exports.DEFAULT_QUALIFIER_VALIDATE = DEFAULT_QUALIFIER_VALIDATE;
+exports.EFFECT_ELIGIBILITIES = EFFECT_ELIGIBILITIES;
+exports.ELIGIBILITY_PRECEDENCE = ELIGIBILITY_PRECEDENCE;
+exports.QUALIFICATION_KEY = QUALIFICATION_KEY;
+exports.Qualifier = Qualifier;
+exports.QualifierError = QualifierError;
+exports.assertSubject = assertSubject;
+exports.combineEligibilities = combineEligibilities;
+exports.createQualifier = createQualifier;
+exports.deriveFindingEligibility = deriveFindingEligibility;
+exports.deriveScopeEligibilities = deriveScopeEligibilities;
+exports.describeComparison = describeComparison;
+exports.describePremise = describePremise;
+exports.describeValue = describeValue;
+exports.findDuplicateIds = findDuplicateIds;
+exports.findMissingReferences = findMissingReferences;
+exports.findRule = findRule;
+exports.hasReservedKey = hasReservedKey;
+exports.interpolateMessage = interpolateMessage;
+exports.isEligibility = isEligibility;
+exports.isQualificationDefinition = isQualificationDefinition;
+exports.isQualificationEffect = isQualificationEffect;
+exports.isQualificationPass = isQualificationPass;
+exports.isQualifierError = isQualifierError;
+exports.isRuling = isRuling;
+exports.logicalPremises = logicalPremises;
+exports.mergeQualificationContext = mergeQualificationContext;
+exports.premiseCheck = premiseCheck;
+exports.qualificationDefinition = qualificationDefinition;
+exports.qualificationToRecord = qualificationToRecord;
+exports.quantitativeResultToDerivation = quantitativeResultToDerivation;
+exports.reasonResultToProjection = reasonResultToProjection;
+exports.rulingDefinition = rulingDefinition;
+exports.rulingToFinding = rulingToFinding;
+
+//# sourceMappingURL=index.cjs.map