@orkestrel/reason 0.0.5 → 0.0.6

package/dist/src/core/index.cjs

@@ -770,6 +770,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 (0, _orkestrel_contract.whereOf)(_orkestrel_contract.isObject, (result) => {
+		if ((0, _orkestrel_contract.isArray)(result)) return false;
+		const confidence = Reflect.get(result, "confidence");
+		return (0, _orkestrel_contract.isString)(Reflect.get(result, "id")) && (0, _orkestrel_contract.isString)(Reflect.get(result, "predicate")) && (0, _orkestrel_contract.isArray)(Reflect.get(result, "terms")) && (confidence === void 0 || (0, _orkestrel_contract.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 (0, _orkestrel_contract.whereOf)(_orkestrel_contract.isObject, (result) => {
+		if ((0, _orkestrel_contract.isArray)(result)) return false;
+		const error = Reflect.get(result, "error");
+		return isFieldPath(Reflect.get(result, "field")) && (0, _orkestrel_contract.isBoolean)(Reflect.get(result, "met")) && Reflect.has(result, "actual") && (error === void 0 || (0, _orkestrel_contract.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 (0, _orkestrel_contract.whereOf)(_orkestrel_contract.isObject, (result) => {
+		if ((0, _orkestrel_contract.isArray)(result)) return false;
+		const raw = Reflect.get(result, "raw");
+		const checks = Reflect.get(result, "checks");
+		return (0, _orkestrel_contract.isString)(Reflect.get(result, "id")) && (0, _orkestrel_contract.isBoolean)(Reflect.get(result, "applied")) && (0, _orkestrel_contract.isNumber)(Reflect.get(result, "value")) && (raw === void 0 || (0, _orkestrel_contract.isNumber)(raw)) && (checks === void 0 || (0, _orkestrel_contract.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 (0, _orkestrel_contract.whereOf)(_orkestrel_contract.isObject, (result) => {
+		return !(0, _orkestrel_contract.isArray)(result) && (0, _orkestrel_contract.isString)(Reflect.get(result, "id")) && (0, _orkestrel_contract.isBoolean)(Reflect.get(result, "applied")) && (0, _orkestrel_contract.isNumber)(Reflect.get(result, "value")) && (0, _orkestrel_contract.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 (0, _orkestrel_contract.whereOf)(_orkestrel_contract.isObject, (result) => {
+		return !(0, _orkestrel_contract.isArray)(result) && (0, _orkestrel_contract.isString)(Reflect.get(result, "id")) && (0, _orkestrel_contract.isBoolean)(Reflect.get(result, "applied")) && (0, _orkestrel_contract.arrayOf)(_orkestrel_contract.isBoolean)(Reflect.get(result, "premises")) && (0, _orkestrel_contract.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 (0, _orkestrel_contract.holds)(() => {
+		if (!(0, _orkestrel_contract.isObject)(value) || (0, _orkestrel_contract.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 > _orkestrel_contract.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 (!(0, _orkestrel_contract.isString)(Reflect.get(node, "fact")) || !(0, _orkestrel_contract.isNumber)(Reflect.get(node, "depth")) || inference !== void 0 && !(0, _orkestrel_contract.isString)(inference)) return false;
+			if (children === void 0) continue;
+			if (!(0, _orkestrel_contract.isArray)(children)) return false;
+			const entries = (0, _orkestrel_contract.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 (!(0, _orkestrel_contract.isObject)(child) || (0, _orkestrel_contract.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 (0, _orkestrel_contract.whereOf)(_orkestrel_contract.isObject, (result) => {
+		return !(0, _orkestrel_contract.isArray)(result) && Reflect.get(result, "reasoning") === "quantitative" && (0, _orkestrel_contract.isNumber)(Reflect.get(result, "value")) && (0, _orkestrel_contract.arrayOf)(isGroupResult)(Reflect.get(result, "groups")) && (0, _orkestrel_contract.isNumber)(Reflect.get(result, "count")) && (0, _orkestrel_contract.isBoolean)(Reflect.get(result, "success")) && (0, _orkestrel_contract.arrayOf)(_orkestrel_contract.isString)(Reflect.get(result, "trace")) && (0, _orkestrel_contract.arrayOf)(_orkestrel_contract.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 (0, _orkestrel_contract.whereOf)(_orkestrel_contract.isObject, (result) => {
+		return !(0, _orkestrel_contract.isArray)(result) && Reflect.get(result, "reasoning") === "logical" && (0, _orkestrel_contract.isBoolean)(Reflect.get(result, "conclusion")) && (0, _orkestrel_contract.arrayOf)(isRuleResult)(Reflect.get(result, "rules")) && (0, _orkestrel_contract.isNumber)(Reflect.get(result, "count")) && (0, _orkestrel_contract.isBoolean)(Reflect.get(result, "success")) && (0, _orkestrel_contract.arrayOf)(_orkestrel_contract.isString)(Reflect.get(result, "trace")) && (0, _orkestrel_contract.arrayOf)(_orkestrel_contract.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 (0, _orkestrel_contract.whereOf)(_orkestrel_contract.isObject, (result) => {
+		return !(0, _orkestrel_contract.isArray)(result) && Reflect.get(result, "reasoning") === "symbolic" && (0, _orkestrel_contract.whereOf)(_orkestrel_contract.isObject, (solutions) => !(0, _orkestrel_contract.isArray)(solutions) && Object.getOwnPropertyNames(solutions).every((key) => (0, _orkestrel_contract.isNumber)(Reflect.get(solutions, key))))(Reflect.get(result, "solutions")) && (0, _orkestrel_contract.isBoolean)(Reflect.get(result, "success")) && (0, _orkestrel_contract.arrayOf)(_orkestrel_contract.isString)(Reflect.get(result, "trace")) && (0, _orkestrel_contract.arrayOf)(_orkestrel_contract.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 (0, _orkestrel_contract.whereOf)(_orkestrel_contract.isObject, (result) => {
+		if ((0, _orkestrel_contract.isArray)(result)) return false;
+		const proof = Reflect.get(result, "proof");
+		return Reflect.get(result, "reasoning") === "inferential" && (0, _orkestrel_contract.arrayOf)(isResultFact)(Reflect.get(result, "derived")) && (proof === void 0 || isProofNode(proof)) && (0, _orkestrel_contract.isBoolean)(Reflect.get(result, "success")) && (0, _orkestrel_contract.arrayOf)(_orkestrel_contract.isString)(Reflect.get(result, "trace")) && (0, _orkestrel_contract.arrayOf)(_orkestrel_contract.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 (0, _orkestrel_contract.whereOf)(_orkestrel_contract.isObject, (result) => {
+		return !(0, _orkestrel_contract.isArray)(result) && (0, _orkestrel_contract.isBoolean)(Reflect.get(result, "valid")) && (0, _orkestrel_contract.arrayOf)(_orkestrel_contract.isString)(Reflect.get(result, "errors")) && (0, _orkestrel_contract.arrayOf)(_orkestrel_contract.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.
 *
@@ -1798,13 +2095,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;
 }
@@ -5315,7 +5614,6 @@ var DefinitionBuilder = class {
 			case "inferential":
 				this.facts.collection = definition.facts;
 				this.inferences.collection = definition.inferences;
-				break;
 		}
 		this.#envelope = this.#strip(definition);
 	}
@@ -5981,6 +6279,7 @@ exports.isAggregation = isAggregation;
 exports.isBounds = isBounds;
 exports.isChainingStrategy = isChainingStrategy;
 exports.isCheck = isCheck;
+exports.isCheckResult = isCheckResult;
 exports.isComparison = isComparison;
 exports.isDefinition = isDefinition;
 exports.isDefinitionBuilder = isDefinitionBuilder;
@@ -5990,22 +6289,33 @@ exports.isFact = isFact;
 exports.isFactor = isFactor;
 exports.isFactorGroup = isFactorGroup;
 exports.isFactorRange = isFactorRange;
+exports.isFactorResult = isFactorResult;
 exports.isFieldPath = isFieldPath;
+exports.isGroupResult = isGroupResult;
 exports.isInference = isInference;
 exports.isInferentialDefinition = isInferentialDefinition;
+exports.isInferentialResult = isInferentialResult;
 exports.isLogicalDefinition = isLogicalDefinition;
 exports.isLogicalOperator = isLogicalOperator;
+exports.isLogicalResult = isLogicalResult;
 exports.isMathOperation = isMathOperation;
 exports.isNumberRecord = isNumberRecord;
+exports.isProofNode = isProofNode;
 exports.isQuantitativeDefinition = isQuantitativeDefinition;
+exports.isQuantitativeResult = isQuantitativeResult;
 exports.isReasonError = isReasonError;
+exports.isReasonResult = isReasonResult;
+exports.isReasonValidationResult = isReasonValidationResult;
 exports.isReasoning = isReasoning;
+exports.isResultFact = isResultFact;
 exports.isRule = isRule;
+exports.isRuleResult = isRuleResult;
 exports.isSource = isSource;
 exports.isSubject = isSubject;
 exports.isSubjectBuilder = isSubjectBuilder;
 exports.isSymbolicDefinition = isSymbolicDefinition;
 exports.isSymbolicExpression = isSymbolicExpression;
+exports.isSymbolicResult = isSymbolicResult;
 exports.isTransform = isTransform;
 exports.logicalDefinition = logicalDefinition;
 exports.lookupFactor = lookupFactor;