@orkestrel/qualifier 0.0.13 → 0.0.14

package/README.md

@@ -1,13 +1,18 @@
 # @orkestrel/qualifier
 
-A typed **eligibility engine** over [`@orkestrel/reason`](https://github.com/orkestrel/reason):
-authored **passes** — quantitative derivations and logical rule gates — run in order
-against a **subject** (a plain data record) to produce **findings** (evidence-rich
-ruling outcomes), **derivations** (quantitative audit trails), and **eligibility**
-(global plus per-scope). The caller supplies the definition; `Qualifier` only
-evaluates what it is given. Qualification never mutates its inputs — every result is
-a fresh object. Environment-agnostic — no I/O, no browser or server assumptions.
-Part of the `@orkestrel` line.
+> A synchronous, deterministic eligibility engine that runs a pure,
+> JSON-serializable `QualificationDefinition`'s ordered `passes` against one
+> subject through one `@orkestrel/reason` engine and returns a fresh
+> `QualificationResult` carrying global and scoped eligibility, evidence-rich
+> `findings`, and quantitative `derivations`.
+
+Author the passes — quantitative derivations and logical rule gates — hand a subject
+(a plain data record) to `qualify`, and read what comes back. The caller supplies the
+definition; `Qualifier` only evaluates what it is given. Inject a
+[`@orkestrel/reason`](https://github.com/orkestrel/reason) `ReasonInterface` where
+qualification shares an engine with the rest of your reasoning, and call `destroy()`
+when the qualifier's work is done. Environment-agnostic — no I/O, no browser or
+server assumptions. Part of the `@orkestrel` line.
 
 ## Install
 

package/dist/src/core/index.cjs

@@ -3,17 +3,26 @@ let _orkestrel_contract = require("@orkestrel/contract");
 let _orkestrel_reason = require("@orkestrel/reason");
 let _orkestrel_emitter = require("@orkestrel/emitter");
 //#region src/core/constants.ts
-/** Holds the default definition validation policy for `createQualifier` / `Qualifier.qualify`. */
+/**
+* Holds the default definition validation policy for `createQualifier` and
+* `Qualifier.qualify`, `true`.
+*/
 var DEFAULT_QUALIFIER_VALIDATE = true;
-/** Names the reserved internal projection namespace a pass's working projection is written under. */
+/**
+* Names `'qualification'`, the reserved internal projection namespace a pass's working
+* projection is written under.
+*/
 var QUALIFICATION_KEY = "qualification";
-/** Lists the eligibility severities in order — most to least severe. */
+/** Lists the eligibility severities most to least severe: `ineligible`, `referral`, `eligible`. */
 var ELIGIBILITY_PRECEDENCE = Object.freeze([
 	"ineligible",
 	"referral",
 	"eligible"
 ]);
-/** Maps each {@link QualificationEffect} to its eligibility impact; `condition` remains eligible. */
+/**
+* Maps each {@link QualificationEffect} to its eligibility impact — `restriction` to
+* `ineligible`, `referral` to `referral`, and `condition` to `eligible`.
+*/
 var EFFECT_ELIGIBILITIES = Object.freeze({
 	restriction: "ineligible",
 	referral: "referral",
@@ -22,7 +31,8 @@ var EFFECT_ELIGIBILITIES = Object.freeze({
 //#endregion
 //#region src/core/errors.ts
 /**
-* Represents a coded programmer error thrown by the qualifier layer.
+* Represents a coded programmer error thrown by the qualifier layer, carrying a
+* `QualifierErrorCode` and an optional context record.
 *
 * @remarks
 * `DEFINITION` — a qualification definition failed semantic validation; when
@@ -60,6 +70,10 @@ function isQualifierError(value) {
 /**
 * Determines whether a value is an {@link Eligibility} literal.
 *
+* @remarks
+* The guard is total and leaves nothing unchecked: a scalar union has no open or exact
+* axis.
+*
 * @param value - The value to test
 * @returns True if `value` is one of the eligibility literals; false otherwise
 */
@@ -67,6 +81,10 @@ var isEligibility = (0, _orkestrel_contract.literalOf)("eligible", "ineligible",
 /**
 * Determines whether a value is a {@link QualificationEffect} literal.
 *
+* @remarks
+* The guard is total and leaves nothing unchecked: a scalar union has no open or exact
+* axis.
+*
 * @param value - The value to test
 * @returns True if `value` is one of the effect literals; false otherwise
 */
@@ -75,8 +93,9 @@ var isQualificationEffect = (0, _orkestrel_contract.literalOf)("restriction", "r
 * Determines whether a value is an open string-keyed record of {@link Eligibility} values.
 *
 * @remarks
-* Every own string-named property is checked, including non-enumerable properties. Inherited and
-* symbol-named members are left unchecked because they are outside the record this guard certifies.
+* Every own string-named value is checked through {@link isEligibility}, including
+* non-enumerable values. Inherited and symbol-named members are left unchecked because they
+* are outside the own string-keyed record this guard certifies.
 *
 * @param value - The value to test
 * @returns True if `value` is a non-array object whose own string-named values are
@@ -89,9 +108,11 @@ function isEligibilityRecord(value) {
 * Determines whether a value is an open result-side {@link Premise}.
 *
 * @remarks
-* `expected` is unchecked and may be absent or contain any value because its published type is
-* `unknown`. `actual` is unchecked and may be absent or contain any value for the same reason.
-* Unknown members are admitted.
+* The optional `field`, `label`, `description`, `comparison`, and `met` members are checked
+* when they are defined. `expected` is unchecked and may be absent or contain any value
+* because its published type is `unknown`. `actual` is unchecked and may be absent or contain
+* any value for the same reason. Unknown members are admitted, because an open result admits
+* what the published contract does not name.
 *
 * @param value - The value to test
 * @returns True if every checked premise member follows its published type; false otherwise
@@ -115,8 +136,10 @@ function isPremise(value) {
 * Determines whether a value is an open result-side {@link Finding}.
 *
 * @remarks
-* Unknown members are admitted. Optional `scope` and `message` members may be absent or
-* `undefined`; a present defined value must be a string.
+* Every published member is checked, including each nested {@link Premise}. Optional `scope`
+* and `message` members may be absent or `undefined`; a present defined value must be a
+* string. Unknown members are admitted, because a foreign result implementation may add them
+* without changing the published contract.
 *
 * @param value - The value to test
 * @returns True if every published finding member is valid; false otherwise
@@ -137,8 +160,10 @@ function isFinding(value) {
 * Determines whether a value is an open result-side {@link Derivation}.
 *
 * @remarks
-* Unknown members are admitted. `value` follows the published `number` type, including `NaN` and
-* infinities.
+* Every published member is checked: `value` follows the published `number` type, including
+* `NaN` and the infinities, and `trace` and `errors` hold strings. Unknown members are
+* admitted, because a foreign result implementation may add them without changing the
+* published contract.
 *
 * @param value - The value to test
 * @returns True if every published derivation member is valid; false otherwise
@@ -157,7 +182,10 @@ function isDerivation(value) {
 *
 * @remarks
 * This guard is result-postured for values returned through a borrowed qualifier interface. It
-* admits unknown members and class instances while checking the complete published result closure.
+* checks the complete published result closure — eligibility, scope values, findings,
+* derivations, success, and the audit trail — and admits unknown members and class instances,
+* because a borrowed `QualifierInterface` implementation may add them beyond the
+* published contract.
 *
 * @param value - The value to test
 * @returns True if every published qualification-result member is valid; false otherwise
@@ -178,6 +206,11 @@ function isQualificationResult(value) {
 /**
 * Determines whether a value is a {@link QualificationPass} (a quantitative or logical definition).
 *
+* @remarks
+* The guard is exact and requires either complete reason shape, the quantitative definition or
+* the logical one. Nothing is left unchecked, because the reason package owns both authored
+* input shapes.
+*
 * @param value - The value to test
 * @returns True if `value` is a complete reason quantitative or logical definition; false otherwise
 */
@@ -187,6 +220,10 @@ function isQualificationPass(value) {
 /**
 * Determines whether a value is an exact {@link Ruling} record.
 *
+* @remarks
+* Every authored ruling member and the complete key set are checked. Nothing is left
+* unchecked, because this package owns the authored input record.
+*
 * @param value - The value to test
 * @returns True if `value` carries every ruling member and no unknown key; false otherwise
 */
@@ -203,6 +240,11 @@ function isRuling(value) {
 /**
 * Determines whether a value is an exact {@link QualificationDefinition} record.
 *
+* @remarks
+* Every authored definition member, the nested pass and ruling shapes, and the complete key
+* set are checked. Nothing is left unchecked, because this package owns the authored input
+* record.
+*
 * @param value - The value to test
 * @returns True if `value` carries every definition member and no unknown key; false otherwise
 */
@@ -227,10 +269,10 @@ function isQualificationDefinition(value) {
 *
 * @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
+* `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.
+* An unresolved path renders as the empty string.
 *
 * @param template - The message template carrying `{{dotted.path}}` tokens
 * @param subject - The record tokens resolve against
@@ -287,7 +329,7 @@ function renderComparison(comparison) {
 * 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
+* a finite number is not grouped here (grouping is {@link interpolateMessage}'s
 * message-token-only behavior).
 *
 * @param value - The value to render
@@ -316,7 +358,7 @@ function renderValue(value) {
 * Renders one {@link Premise} into a display-neutral sentence.
 *
 * @remarks
-* The checked form renders only when `field` and `comparison` are BOTH
+* The checked form renders only when `field` and `comparison` are both
 * present, and `description` then goes unused; a premise missing either half
 * of the checked pair renders as described instead.
 *
@@ -381,7 +423,7 @@ function checkToPremise(check, result, labels) {
 * 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 through `extractAtoms`, and each leaf's `Check` is re-evaluated through
-* the injected `evaluator`. A membership check (`any` / `none`) over an EMPTY
+* the injected `evaluator`. A membership check (`any` / `none`) over an empty
 * array value is content-free and is skipped.
 *
 * @param rule - The authored rule
@@ -550,7 +592,7 @@ function mergeQualificationContext(context, id, projection) {
 *
 * @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
+* 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.
 *
@@ -863,8 +905,9 @@ function describeUnreadDerivations(definition) {
 * Runs ordered passes over one reason engine and returns eligibility.
 *
 * @remarks
-* The engine is OWNED when self-created (destroyed on `destroy()`) and borrowed
-* when injected (never destroyed). `qualify` builds its working subject through
+* The engine is owned when self-created (destroyed on `destroy()`) and borrowed
+* when injected (never destroyed). Semantic validation runs before the first pass
+* whenever the `validate` option is on. `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.
 */
@@ -1092,10 +1135,10 @@ var Qualifier = class {
 //#endregion
 //#region src/core/factories.ts
 /**
-* Creates one qualifier over a reason engine.
+* Creates one {@link QualifierInterface} over a reason engine.
 *
 * @remarks
-* A standalone qualifier creates and OWNS one shared quantitative-plus-logical
+* 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. `validate` runs semantic
 * validation before every qualification. Default: `true`. `labels` overrides the
@@ -1105,12 +1148,37 @@ var Qualifier = class {
 * @param options - Optional injected engine, validation, labels, and emitter hooks
 * @returns A {@link QualifierInterface}
 *
-* @example
+* @example Create a qualifier
 * ```ts
-* import { createQualifier } from '@orkestrel/qualifier'
+* import { createQualificationDefinition, createQualifier, createRuling } from '@orkestrel/qualifier'
+* import { createAtom, createLogicalDefinition, createRule } from '@orkestrel/reason'
+*
+* const gates = createLogicalDefinition('gates', 'Eligibility gates', [
+* 	createRule(
+* 		'licensed',
+* 		[createAtom('licensed', 'equals', false)],
+* 		createAtom('blocked', 'equals', true),
+* 	),
+* ])
+*
+* const bare = createRuling('license', 'gates', 'licensed', 'restriction')
+* const messaged = createRuling('license', 'gates', 'licensed', 'restriction', {
+* 	message: 'A license is required',
+* })
+*
+* 'message' in bare // false — an absent optional key is omitted, never written as undefined
+* messaged.message // 'A license is required'
+*
+* const passes = [gates]
+* const definition = createQualificationDefinition('standard', 'Standard eligibility', passes, {
+* 	rulings: [messaged],
+* })
+*
+* 'description' in definition // false
+* definition.passes === passes // false — the factory copies what it is handed
 *
 * const qualifier = createQualifier()
-* qualifier.qualify({ id: 'risk-1' }, definition)
+* qualifier.qualify({ id: 'risk-1', licensed: false }, definition)
 * qualifier.destroy()
 * ```
 */
@@ -1118,10 +1186,9 @@ function createQualifier(options) {
 	return new Qualifier(options);
 }
 /**
-* Creates a {@link QualificationDefinition}.
+* Creates a fresh {@link QualificationDefinition}, omitting every absent optional key.
 *
 * @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.
 *
@@ -1149,7 +1216,7 @@ function createQualificationDefinition(id, name, passes, input) {
 	};
 }
 /**
-* Creates a {@link Ruling} — one authored consequence for one rule in one pass.
+* Creates a fresh {@link Ruling} from the rule it reacts to and the effect it applies.
 *
 * @param id - The ruling id
 * @param pass - The logical pass id the rule lives in