@orkestrel/reason 0.0.4 → 0.0.6

package/dist/src/core/index.js

@@ -1,4 +1,4 @@
-import { arrayOf, isArray, isBoolean, isFiniteNumber, isNumber, isObject, isRecord, isString, lazyOf, literalOf, notOf, orOf, parseJSONAs, parseNumber, parseNumberField, recordOf, resolveField, unionOf, whereOf } from "@orkestrel/contract";
+import { GUARD_DEPTH_LIMIT, arrayOf, holds, isArray, isBoolean, isFiniteNumber, isNumber, isObject, isRecord, isString, lazyOf, literalOf, notOf, orOf, parseJSONAs, parseNumber, parseNumberField, readArrayEntries, recordOf, resolveField, unionOf, whereOf } from "@orkestrel/contract";
 import { Emitter } from "@orkestrel/emitter";
 //#region src/core/constants.ts
 /**
@@ -769,6 +769,303 @@ function isDefinition(value) {
 	return isQuantitativeDefinition(value) || isLogicalDefinition(value) || isSymbolicDefinition(value) || isInferentialDefinition(value);
 }
 /**
+* Determine whether a value is a result-side {@link Fact}.
+*
+* @remarks
+* Unlike the exact input guard {@link isFact}, this guard accepts unknown
+* members, class instances, and every JavaScript `number` confidence.
+*
+* @param value - The value to test
+* @returns `true` when every published fact member is valid for a result
+*
+* @example
+* ```ts
+* import { isResultFact } from '@src/core'
+*
+* isResultFact({ id: 'f1', predicate: 'bird', terms: ['tweety'], note: 'derived' }) // true
+* isResultFact({ id: 'f1', predicate: 'bird' }) // false
+* ```
+*/
+function isResultFact(value) {
+	return whereOf(isObject, (result) => {
+		if (isArray(result)) return false;
+		const confidence = Reflect.get(result, "confidence");
+		return isString(Reflect.get(result, "id")) && isString(Reflect.get(result, "predicate")) && isArray(Reflect.get(result, "terms")) && (confidence === void 0 || isNumber(confidence));
+	})(value);
+}
+/**
+* Determine whether a value is a {@link CheckResult}.
+*
+* @param value - The value to test
+* @returns `true` when every published check-result member is valid
+*
+* @example
+* ```ts
+* import { isCheckResult } from '@src/core'
+*
+* isCheckResult({ field: 'age', met: true, actual: 30 }) // true
+* isCheckResult({ field: 'age', met: 'yes', actual: 30 }) // false
+* ```
+*/
+function isCheckResult(value) {
+	return whereOf(isObject, (result) => {
+		if (isArray(result)) return false;
+		const error = Reflect.get(result, "error");
+		return isFieldPath(Reflect.get(result, "field")) && isBoolean(Reflect.get(result, "met")) && Reflect.has(result, "actual") && (error === void 0 || isString(error));
+	})(value);
+}
+/**
+* Determine whether a value is a {@link FactorResult}.
+*
+* @param value - The value to test
+* @returns `true` when every published factor-result member is valid
+*
+* @example
+* ```ts
+* import { isFactorResult } from '@src/core'
+*
+* isFactorResult({ id: 'age', applied: true, value: 5 }) // true
+* isFactorResult({ id: 'age', applied: true, value: '5' }) // false
+* ```
+*/
+function isFactorResult(value) {
+	return whereOf(isObject, (result) => {
+		if (isArray(result)) return false;
+		const raw = Reflect.get(result, "raw");
+		const checks = Reflect.get(result, "checks");
+		return isString(Reflect.get(result, "id")) && isBoolean(Reflect.get(result, "applied")) && isNumber(Reflect.get(result, "value")) && (raw === void 0 || isNumber(raw)) && (checks === void 0 || arrayOf(isCheckResult)(checks));
+	})(value);
+}
+/**
+* Determine whether a value is a {@link GroupResult}.
+*
+* @param value - The value to test
+* @returns `true` when every published group-result member is valid
+*
+* @example
+* ```ts
+* import { isGroupResult } from '@src/core'
+*
+* isGroupResult({ id: 'risk', applied: true, value: 5, factors: [] }) // true
+* isGroupResult({ id: 'risk', applied: true, value: 5 }) // false
+* ```
+*/
+function isGroupResult(value) {
+	return whereOf(isObject, (result) => {
+		return !isArray(result) && isString(Reflect.get(result, "id")) && isBoolean(Reflect.get(result, "applied")) && isNumber(Reflect.get(result, "value")) && arrayOf(isFactorResult)(Reflect.get(result, "factors"));
+	})(value);
+}
+/**
+* Determine whether a value is a {@link RuleResult}.
+*
+* @param value - The value to test
+* @returns `true` when every published rule-result member is valid
+*
+* @example
+* ```ts
+* import { isRuleResult } from '@src/core'
+*
+* isRuleResult({ id: 'adult', applied: true, premises: [true], conclusion: true }) // true
+* isRuleResult({ id: 'adult', applied: true, premises: [1], conclusion: true }) // false
+* ```
+*/
+function isRuleResult(value) {
+	return whereOf(isObject, (result) => {
+		return !isArray(result) && isString(Reflect.get(result, "id")) && isBoolean(Reflect.get(result, "applied")) && arrayOf(isBoolean)(Reflect.get(result, "premises")) && isBoolean(Reflect.get(result, "conclusion"));
+	})(value);
+}
+/**
+* Determine whether a value is a depth-bounded, acyclic {@link ProofNode} tree.
+*
+* @remarks
+* Traversal is iterative and reuses `GUARD_DEPTH_LIMIT`. Active ancestors refuse cycles, and a
+* settled-depth record prevents repeated validation of shared subtrees while keeping the bound
+* exact: a node revisited no deeper than its validated depth is skipped, and one reached deeper
+* is walked again. The traversal accepts an acyclic graph only when every reachable node is
+* valid and every root-to-node path contains at most `GUARD_DEPTH_LIMIT` nodes; shared aliases
+* and sibling order do not affect the verdict.
+*
+* @param value - The value to test
+* @returns `true` when every proof node is valid within the runtime guard bound
+*
+* @example
+* ```ts
+* import { isProofNode } from '@src/core'
+*
+* isProofNode({ fact: 'bird', depth: 0, children: [{ fact: 'feathers', depth: 1 }] }) // true
+* isProofNode({ fact: 'bird', children: [] }) // false
+* ```
+*/
+function isProofNode(value) {
+	return holds(() => {
+		if (!isObject(value) || isArray(value)) return false;
+		const active = /* @__PURE__ */ new WeakSet();
+		const settled = /* @__PURE__ */ new WeakMap();
+		const worklist = [[
+			value,
+			1,
+			false
+		]];
+		while (worklist.length > 0) {
+			const frame = worklist.pop();
+			if (frame === void 0) continue;
+			const node = frame[0];
+			const depth = frame[1];
+			if (frame[2]) {
+				active.delete(node);
+				const known = settled.get(node);
+				settled.set(node, known === void 0 || depth > known ? depth : known);
+				continue;
+			}
+			if (depth > GUARD_DEPTH_LIMIT || active.has(node)) return false;
+			const known = settled.get(node);
+			if (known !== void 0 && depth <= known) continue;
+			active.add(node);
+			worklist.push([
+				node,
+				depth,
+				true
+			]);
+			const inference = Reflect.get(node, "inference");
+			const children = Reflect.get(node, "children");
+			if (!isString(Reflect.get(node, "fact")) || !isNumber(Reflect.get(node, "depth")) || inference !== void 0 && !isString(inference)) return false;
+			if (children === void 0) continue;
+			if (!isArray(children)) return false;
+			const entries = readArrayEntries(children);
+			if (!entries.success || !entries.value.dense) return false;
+			for (let index = entries.value.entries.length - 1; index >= 0; index -= 1) {
+				const child = entries.value.entries[index];
+				if (!isObject(child) || isArray(child)) return false;
+				worklist.push([
+					child,
+					depth + 1,
+					false
+				]);
+			}
+		}
+		return true;
+	});
+}
+/**
+* Determine whether a value is a {@link QuantitativeResult}.
+*
+* @param value - The value to test
+* @returns `true` when every published quantitative-result member is valid
+*
+* @example
+* ```ts
+* import { isQuantitativeResult } from '@src/core'
+*
+* isQuantitativeResult({ reasoning: 'quantitative', value: 0, groups: [], count: 0, success: true, trace: [], errors: [] }) // true
+* isQuantitativeResult({ reasoning: 'quantitative' }) // false
+* ```
+*/
+function isQuantitativeResult(value) {
+	return whereOf(isObject, (result) => {
+		return !isArray(result) && Reflect.get(result, "reasoning") === "quantitative" && isNumber(Reflect.get(result, "value")) && arrayOf(isGroupResult)(Reflect.get(result, "groups")) && isNumber(Reflect.get(result, "count")) && isBoolean(Reflect.get(result, "success")) && arrayOf(isString)(Reflect.get(result, "trace")) && arrayOf(isString)(Reflect.get(result, "errors"));
+	})(value);
+}
+/**
+* Determine whether a value is a {@link LogicalResult}.
+*
+* @param value - The value to test
+* @returns `true` when every published logical-result member is valid
+*
+* @example
+* ```ts
+* import { isLogicalResult } from '@src/core'
+*
+* isLogicalResult({ reasoning: 'logical', conclusion: false, rules: [], count: 0, success: true, trace: [], errors: [] }) // true
+* isLogicalResult({ reasoning: 'logical', rules: [] }) // false
+* ```
+*/
+function isLogicalResult(value) {
+	return whereOf(isObject, (result) => {
+		return !isArray(result) && Reflect.get(result, "reasoning") === "logical" && isBoolean(Reflect.get(result, "conclusion")) && arrayOf(isRuleResult)(Reflect.get(result, "rules")) && isNumber(Reflect.get(result, "count")) && isBoolean(Reflect.get(result, "success")) && arrayOf(isString)(Reflect.get(result, "trace")) && arrayOf(isString)(Reflect.get(result, "errors"));
+	})(value);
+}
+/**
+* Determine whether a value is a {@link SymbolicResult}.
+*
+* @remarks
+* `solutions` is checked across its OWN string-named members, enumerable or
+* not. Inherited members are deliberately unread: they belong to the
+* accepted-prototype property, not to the record this guard certifies.
+*
+* @param value - The value to test
+* @returns `true` when every published symbolic-result member is valid
+*
+* @example
+* ```ts
+* import { isSymbolicResult } from '@src/core'
+*
+* isSymbolicResult({ reasoning: 'symbolic', solutions: { x: 4 }, success: true, trace: [], errors: [] }) // true
+* isSymbolicResult({ reasoning: 'symbolic', solutions: { x: '4' }, success: true, trace: [], errors: [] }) // false
+* ```
+*/
+function isSymbolicResult(value) {
+	return whereOf(isObject, (result) => {
+		return !isArray(result) && Reflect.get(result, "reasoning") === "symbolic" && whereOf(isObject, (solutions) => !isArray(solutions) && Object.getOwnPropertyNames(solutions).every((key) => isNumber(Reflect.get(solutions, key))))(Reflect.get(result, "solutions")) && isBoolean(Reflect.get(result, "success")) && arrayOf(isString)(Reflect.get(result, "trace")) && arrayOf(isString)(Reflect.get(result, "errors"));
+	})(value);
+}
+/**
+* Determine whether a value is an {@link InferentialResult}.
+*
+* @param value - The value to test
+* @returns `true` when every published inferential-result member is valid
+*
+* @example
+* ```ts
+* import { isInferentialResult } from '@src/core'
+*
+* isInferentialResult({ reasoning: 'inferential', derived: [], success: true, trace: [], errors: [] }) // true
+* isInferentialResult({ reasoning: 'inferential', derived: [null], success: true, trace: [], errors: [] }) // false
+* ```
+*/
+function isInferentialResult(value) {
+	return whereOf(isObject, (result) => {
+		if (isArray(result)) return false;
+		const proof = Reflect.get(result, "proof");
+		return Reflect.get(result, "reasoning") === "inferential" && arrayOf(isResultFact)(Reflect.get(result, "derived")) && (proof === void 0 || isProofNode(proof)) && isBoolean(Reflect.get(result, "success")) && arrayOf(isString)(Reflect.get(result, "trace")) && arrayOf(isString)(Reflect.get(result, "errors"));
+	})(value);
+}
+/**
+* Determine whether a value is any {@link ReasonResult} arm.
+*
+* @param value - The value to test
+* @returns `true` when one complete reasoning-result guard accepts the value
+*
+* @example
+* ```ts
+* import { isReasonResult } from '@src/core'
+*
+* isReasonResult({ reasoning: 'symbolic', solutions: {}, success: true, trace: [], errors: [] }) // true
+* isReasonResult({ reasoning: 'unknown' }) // false
+* ```
+*/
+function isReasonResult(value) {
+	return isQuantitativeResult(value) || isLogicalResult(value) || isSymbolicResult(value) || isInferentialResult(value);
+}
+/**
+* Determine whether a value is a {@link ReasonValidationResult}.
+*
+* @param value - The value to test
+* @returns `true` when every published validation-result member is valid
+*
+* @example
+* ```ts
+* import { isReasonValidationResult } from '@src/core'
+*
+* isReasonValidationResult({ valid: true, errors: [], warnings: [] }) // true
+* isReasonValidationResult({ valid: true, errors: [] }) // false
+* ```
+*/
+function isReasonValidationResult(value) {
+	return whereOf(isObject, (result) => {
+		return !isArray(result) && isBoolean(Reflect.get(result, "valid")) && arrayOf(isString)(Reflect.get(result, "errors")) && arrayOf(isString)(Reflect.get(result, "warnings"));
+	})(value);
+}
+/**
 * Determine whether a value is a `DefinitionBuilder` ENTITY — the brand-guarded
 * stateful workspace, not the plain {@link Definition} data union.
 *
@@ -1797,13 +2094,15 @@ function matchFacts(pattern, candidate) {
 	for (let index = 0; index < pattern.terms.length; index++) {
 		const patternTerm = pattern.terms[index];
 		const factTerm = candidate.terms[index];
-		if (typeof patternTerm === "string" && patternTerm.startsWith("?")) if (patternTerm in bindings) {
-			if (bindings[patternTerm] !== factTerm) return void 0;
-		} else bindings[patternTerm] = factTerm;
-		else if (typeof factTerm === "string" && factTerm.startsWith("?")) if (factTerm in bindings) {
-			if (bindings[factTerm] !== patternTerm) return void 0;
-		} else bindings[factTerm] = patternTerm;
-		else if (patternTerm !== factTerm) return;
+		if (typeof patternTerm === "string" && patternTerm.startsWith("?")) {
+			if (patternTerm in bindings) {
+				if (bindings[patternTerm] !== factTerm) return void 0;
+			} else bindings[patternTerm] = factTerm;
+		} else if (typeof factTerm === "string" && factTerm.startsWith("?")) {
+			if (factTerm in bindings) {
+				if (bindings[factTerm] !== patternTerm) return void 0;
+			} else bindings[factTerm] = patternTerm;
+		} else if (patternTerm !== factTerm) return;
 	}
 	return bindings;
 }
@@ -5314,7 +5613,6 @@ var DefinitionBuilder = class {
 			case "inferential":
 				this.facts.collection = definition.facts;
 				this.inferences.collection = definition.inferences;
-				break;
 		}
 		this.#envelope = this.#strip(definition);
 	}
@@ -5880,6 +6178,6 @@ function createInferenceManager(options) {
 	return new InferenceManager(options);
 }
 //#endregion
-export { AGGREGATOR_ID, Aggregator, CONFIDENCE_PRECISION, DEFAULT_BASE, DEFAULT_CONFIDENCE, DEFAULT_DEPTH, DEFAULT_PRECISION, DEFAULT_PRIORITY, DEFAULT_REASON_BAIL, DEFAULT_VALIDATE, DEFAULT_WEIGHT, DEFINITION_BUILDER_BRAND, DefinitionBuilder, EVALUATOR_ID, EquationManager, Evaluator, FactManager, FactorManager, GroupManager, INFERENTIAL_ID, INVERTIBLE_OPERATIONS, InferenceManager, InferentialReasoner, LOGICAL_ID, LogicalReasoner, QUANTITATIVE_ID, QuantitativeReasoner, Reason, ReasonError, RuleManager, SUBJECT_BUILDER_BRAND, SYMBOLIC_ID, SubjectBuilder, SymbolicReasoner, TRANSFORMER_ID, Transformer, VariableManager, addVariable, appendById, appendEquation, appendFact, appendFactor, appendGroup, appendInference, appendRule, applyOperation, assignField, atom, bounds, buildErrorResult, check, clamp, clearInferentialDefinition, clearLogicalDefinition, clearQuantitativeDefinition, clearSymbolicDefinition, compound, constant, containsVariable, createAggregator, createDefinitionBuilder, createEquationManager, createEvaluator, createFactManager, createFactorManager, createGroupManager, createInferenceManager, createInferentialReasoner, createLogicalReasoner, createQuantitativeReasoner, createReason, createRuleManager, createSubjectBuilder, createSymbolicReasoner, createTransformer, createVariableManager, equalValues, equation, extractAtoms, extractConclusions, fact, factToArityKey, factToKey, factorGroup, fieldFactor, fieldSource, findDuplicates, findOverlayMismatches, findUnboundVariables, formatField, indexByArity, inference, inferentialDefinition, instantiateFact, invertLeft, invertRight, isAggregation, isBounds, isChainingStrategy, isCheck, isComparison, isDefinition, isDefinitionBuilder, isEquation, isExpression, isFact, isFactor, isFactorGroup, isFactorRange, isFieldPath, isInference, isInferentialDefinition, isLogicalDefinition, isLogicalOperator, isMathOperation, isNumberRecord, isQuantitativeDefinition, isReasonError, isReasoning, isRule, isSource, isSubject, isSubjectBuilder, isSymbolicDefinition, isSymbolicExpression, isTransform, logicalDefinition, lookupFactor, lookupSource, matchFacts, mergeById, mergeInferentialDefinition, mergeLogicalDefinition, mergeQuantitativeDefinition, mergeSubjects, mergeSymbolicDefinition, operation, parseDefinition, prependById, prependEquation, prependFact, prependFactor, prependGroup, prependInference, prependRule, quantitativeDefinition, rangeFactor, rangeSource, removeById, removeEquation, removeFact, removeFactor, removeField, removeGroup, removeInference, removeRule, removeVariable, repeatSubject, replaceById, replaceEquation, replaceFact, replaceFactor, replaceGroup, replaceInference, replaceRule, roundTo, rule, sortByPriority, staticFactor, staticSource, subjectToFacts, symbolicDefinition, termToKey, transform, variable };
+export { AGGREGATOR_ID, Aggregator, CONFIDENCE_PRECISION, DEFAULT_BASE, DEFAULT_CONFIDENCE, DEFAULT_DEPTH, DEFAULT_PRECISION, DEFAULT_PRIORITY, DEFAULT_REASON_BAIL, DEFAULT_VALIDATE, DEFAULT_WEIGHT, DEFINITION_BUILDER_BRAND, DefinitionBuilder, EVALUATOR_ID, EquationManager, Evaluator, FactManager, FactorManager, GroupManager, INFERENTIAL_ID, INVERTIBLE_OPERATIONS, InferenceManager, InferentialReasoner, LOGICAL_ID, LogicalReasoner, QUANTITATIVE_ID, QuantitativeReasoner, Reason, ReasonError, RuleManager, SUBJECT_BUILDER_BRAND, SYMBOLIC_ID, SubjectBuilder, SymbolicReasoner, TRANSFORMER_ID, Transformer, VariableManager, addVariable, appendById, appendEquation, appendFact, appendFactor, appendGroup, appendInference, appendRule, applyOperation, assignField, atom, bounds, buildErrorResult, check, clamp, clearInferentialDefinition, clearLogicalDefinition, clearQuantitativeDefinition, clearSymbolicDefinition, compound, constant, containsVariable, createAggregator, createDefinitionBuilder, createEquationManager, createEvaluator, createFactManager, createFactorManager, createGroupManager, createInferenceManager, createInferentialReasoner, createLogicalReasoner, createQuantitativeReasoner, createReason, createRuleManager, createSubjectBuilder, createSymbolicReasoner, createTransformer, createVariableManager, equalValues, equation, extractAtoms, extractConclusions, fact, factToArityKey, factToKey, factorGroup, fieldFactor, fieldSource, findDuplicates, findOverlayMismatches, findUnboundVariables, formatField, indexByArity, inference, inferentialDefinition, instantiateFact, invertLeft, invertRight, isAggregation, isBounds, isChainingStrategy, isCheck, isCheckResult, isComparison, isDefinition, isDefinitionBuilder, isEquation, isExpression, isFact, isFactor, isFactorGroup, isFactorRange, isFactorResult, isFieldPath, isGroupResult, isInference, isInferentialDefinition, isInferentialResult, isLogicalDefinition, isLogicalOperator, isLogicalResult, isMathOperation, isNumberRecord, isProofNode, isQuantitativeDefinition, isQuantitativeResult, isReasonError, isReasonResult, isReasonValidationResult, isReasoning, isResultFact, isRule, isRuleResult, isSource, isSubject, isSubjectBuilder, isSymbolicDefinition, isSymbolicExpression, isSymbolicResult, isTransform, logicalDefinition, lookupFactor, lookupSource, matchFacts, mergeById, mergeInferentialDefinition, mergeLogicalDefinition, mergeQuantitativeDefinition, mergeSubjects, mergeSymbolicDefinition, operation, parseDefinition, prependById, prependEquation, prependFact, prependFactor, prependGroup, prependInference, prependRule, quantitativeDefinition, rangeFactor, rangeSource, removeById, removeEquation, removeFact, removeFactor, removeField, removeGroup, removeInference, removeRule, removeVariable, repeatSubject, replaceById, replaceEquation, replaceFact, replaceFactor, replaceGroup, replaceInference, replaceRule, roundTo, rule, sortByPriority, staticFactor, staticSource, subjectToFacts, symbolicDefinition, termToKey, transform, variable };
 
 //# sourceMappingURL=index.js.map