@callcium/sdk 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Provencraft
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,17 @@
+# @callcium/sdk
+
+TypeScript implementation of the Callcium policy engine.
+
+## Install
+
+```bash
+bun add @callcium/sdk
+```
+
+## Documentation
+
+Full documentation at [callcium.dev/docs/sdk](https://callcium.dev/docs/sdk).
+
+## License
+
+MIT License. See [LICENSE](LICENSE).

package/dist/index.d.ts

@@ -29,17 +29,110 @@ type EnforceResult = {
   ok: false;
   violations: Violation[];
 };
-/** Machine-readable reason code for an enforcement violation. */
-type ViolationCode = "VALUE_MISMATCH" | "SELECTOR_MISMATCH" | "MISSING_SELECTOR" | "CALLDATA_OUT_OF_BOUNDS" | "ARRAY_INDEX_OUT_OF_BOUNDS" | "MISSING_CONTEXT" | "QUANTIFIER_LIMIT_EXCEEDED" | "QUANTIFIER_EMPTY_ARRAY";
-/** Details of a single rule failure during enforcement. */
-type Violation = {
-  /** Group index that failed. Absent for pre-group failures (e.g. selector mismatch). */group?: number; /** Rule index within the group. Absent for pre-rule failures. */
-  rule?: number;
-  code: ViolationCode;
-  message: string; /** Rule path that was being evaluated when the violation occurred. */
-  path?: Hex; /** The actual value found in calldata or context, for diagnostic display. */
+/** Subset of violation codes emitted by reader/navigation primitives. */
+type NavigationViolationCode = "CALLDATA_OUT_OF_BOUNDS" | "ARRAY_INDEX_OUT_OF_BOUNDS";
+/** Calldata is shorter than the policy's selector slot. */
+type MissingSelectorViolation = {
+  code: "MISSING_SELECTOR";
+};
+/** Calldata selector does not match the policy's expected selector. */
+type SelectorMismatchViolation = {
+  code: "SELECTOR_MISMATCH"; /** Selector declared by the policy. */
+  expectedValue: Hex; /** Selector observed in the calldata. */
+  resolvedValue: Hex;
+};
+/**
+ * A context-scoped rule referenced a property not supplied in the execution context.
+ *
+ * `opCode` and `operandData` may be added in future versions as diagnostic context
+ * without breaking the contract; consumers should tolerate their presence.
+ */
+type MissingContextViolation = {
+  code: "MISSING_CONTEXT";
+  group: number;
+  rule: number;
+  scope: number;
+  path: Hex; /** Declared type of the missing context property. */
+  typeCode: number;
+  opCode?: number;
+  operandData?: Hex;
+};
+/**
+ * A rule's operator returned false against the loaded value.
+ *
+ * Field combinations:
+ * - `resolvedValue` present, `elementIndex` absent — scalar leaf or context value that failed the operator.
+ * - `resolvedValue` present, `elementIndex` present — universal-quantifier per-element failure.
+ * - `resolvedValue` absent, `elementIndex` absent — existential-aggregate failure (no element satisfied).
+ * - `resolvedValue` absent, `elementIndex` present — per-element failure where the leaf could not be loaded.
+ *
+ * For length operations (`isLengthOp(opCode)`), `resolvedValue` is a hex-encoded count
+ * rather than a 32-byte ABI word.
+ */
+type ValueMismatchViolation = {
+  code: "VALUE_MISMATCH";
+  group: number;
+  rule: number;
+  scope: number;
+  path: Hex; /** Operator code with the `Op.NOT` bit intact. */
+  opCode: number; /** Full untruncated operand bytes declared by the rule. */
+  operandData: Hex; /** Type code of the failing value's leaf. */
+  typeCode: number;
   resolvedValue?: Hex;
+  elementIndex?: number;
+};
+/**
+ * Single-code shape for a calldata-navigation failure. Internal helper for de-duplication.
+ * @internal
+ */
+type CalldataNavigationVariant<C extends NavigationViolationCode> = {
+  code: C;
+  group: number;
+  rule: number;
+  scope: number;
+  path: Hex;
+  opCode?: number;
+  operandData?: Hex;
+  typeCode?: number;
+  elementIndex?: number;
+};
+/**
+ * Calldata structure prevented the rule from being evaluated.
+ *
+ * The operator was never applied; `opCode`, `operandData`, `typeCode`, and `elementIndex`
+ * are diagnostic context describing the failing site, not a constraint claim. Renderers
+ * must not summarise these as "constraint violated".
+ *
+ * Encoded as a union of per-code variants so consumers can narrow on a single code via
+ * `Extract<Violation, { code: "..." }>`.
+ */
+type CalldataNavigationViolation = CalldataNavigationVariant<"CALLDATA_OUT_OF_BOUNDS"> | CalldataNavigationVariant<"ARRAY_INDEX_OUT_OF_BOUNDS">;
+/** A quantified array exceeded `Limits.MAX_QUANTIFIED_ARRAY_LENGTH`. */
+type QuantifierLimitExceededViolation = {
+  code: "QUANTIFIER_LIMIT_EXCEEDED";
+  group: number;
+  rule: number;
+  scope: number;
+  path: Hex; /** Hex-encoded element count of the offending array. */
+  resolvedValue: Hex;
 };
+/** A quantifier (`ANY` or `ALL`) was applied to an empty array. */
+type QuantifierEmptyArrayViolation = {
+  code: "QUANTIFIER_EMPTY_ARRAY";
+  group: number;
+  rule: number;
+  scope: number;
+  path: Hex;
+};
+/**
+ * Structured details of a single rule failure during enforcement.
+ *
+ * Carries semantic data only — message strings are the consumer's responsibility.
+ * Discriminate on `code` to narrow to the matching variant.
+ */
+type Violation = MissingSelectorViolation | SelectorMismatchViolation | MissingContextViolation | ValueMismatchViolation | CalldataNavigationViolation | QuantifierLimitExceededViolation | QuantifierEmptyArrayViolation;
+/** Machine-readable reason code for an enforcement violation. Derived from `Violation` to prevent drift. */
+type ViolationCode = Violation["code"];
 /** Canonical structured representation of a policy. */
 type PolicyData = {
   isSelectorless: boolean;
@@ -673,6 +766,10 @@ type TypeCodeInfo = TypeClassInfo & {
  */
 declare function lookupTypeCode(code: number): TypeCodeInfo;
 //#endregion
+//#region src/operators.d.ts
+/** Return true when the operator code (with or without NOT flag) is a LENGTH_* variant. */
+declare function isLengthOp(opCode: number): boolean;
+//#endregion
 //#region src/errors.d.ts
 /** Machine-readable error code for structural decoding and validation failures. */
 type CallciumErrorCode = "UNSUPPORTED_VERSION" | "MALFORMED_HEADER" | "UNEXPECTED_END" | "NODE_OVERFLOW" | "UNKNOWN_TYPE_CODE" | "INVALID_OPERATOR" | "INVALID_ARRAY_LENGTH" | "INVALID_TUPLE_FIELD_COUNT" | "PARAM_COUNT_MISMATCH" | "EMPTY_POLICY" | "EMPTY_GROUP" | "EMPTY_PATH" | "INVALID_CONTEXT_PATH" | "INVALID_CONTEXT_PROPERTY" | "INVALID_QUANTIFIER" | "INVALID_SCOPE" | "RULE_SIZE_MISMATCH" | "GROUP_SIZE_MISMATCH" | "GROUP_OVERFLOW" | "RULE_OVERFLOW" | "TRAILING_BYTES" | "INTERNAL_ERROR" | "INVALID_SIGNATURE" | "INVALID_TYPE_STRING" | "UNKNOWN_TYPE" | "DESCRIPTOR_TOO_LARGE" | "INVALID_PATH" | "DUPLICATE_PATH" | "INVALID_CONSTRAINT" | "INVALID_OPERATOR_DATA" | "EMPTY_SET" | "SET_TOO_LARGE" | "INVALID_RANGE" | "GROUP_COUNT_OVERFLOW" | "RULE_COUNT_OVERFLOW" | "RULE_SIZE_OVERFLOW" | "DESC_LENGTH_OVERFLOW" | "INVALID_HEX" | "VALIDATION_ERROR";
@@ -690,12 +787,16 @@ declare class CallciumError extends Error {
  * Thrown by `PolicyEnforcer.enforce` when calldata fails policy enforcement.
  * Distinct from `CallciumError("VALIDATION_ERROR")`, which signals static
  * issues in the policy itself.
- * Carries the full list of violations (one per failed group).
+ *
+ * Carries the full list of structured violations (one per failed group). The
+ * `Error.message` is a minimal non-lossy diagnostic summary built from the
+ * first violation's structured fields — not a presentation contract. Consumers
+ * rendering violations to users should iterate `violations` directly.
  */
 declare class PolicyViolationError extends Error {
   readonly violations: Violation[];
   constructor(violations: Violation[]);
 }
 //#endregion
-export { type Address, CallciumError, type CallciumErrorCode, type Constraint, type ConstraintBuilder, type Context, ContextProperty, type ContextPropertyInfo, type DecodedGroup, type DecodedParam, type DecodedPolicy, type DecodedRule, Descriptor, DescriptorCoder, type EnforceResult, type Field, type Hex, type Issue, type IssueCategory, type IssueSeverity, Limits, Op, type OpInfo, type Operands, PolicyBuilder, PolicyCoder, type PolicyData, PolicyEnforcer, PolicyValidator, PolicyViolationError, Quantifier, type QuantifierInfo, type ScalarValue, Scope, type ScopeInfo, type Span, type TypeClass, type TypeClassInfo, TypeCode, type TypeCodeInfo, type TypeInfo, type Violation, type ViolationCode, arg, blockNumber, blockTimestamp, bytesToHex, chainId, hexToBytes, isOpAllowed, isQuantifier, lookupContextProperty, lookupOp, lookupQuantifier, lookupScope, lookupTypeCode, msgSender, msgValue, parsePathSteps, toAddress, txOrigin };
+export { type Address, CallciumError, type CallciumErrorCode, type CalldataNavigationViolation, type Constraint, type ConstraintBuilder, type Context, ContextProperty, type ContextPropertyInfo, type DecodedGroup, type DecodedParam, type DecodedPolicy, type DecodedRule, Descriptor, DescriptorCoder, type EnforceResult, type Field, type Hex, type Issue, type IssueCategory, type IssueSeverity, Limits, type MissingContextViolation, type MissingSelectorViolation, type NavigationViolationCode, Op, type OpInfo, type Operands, PolicyBuilder, PolicyCoder, type PolicyData, PolicyEnforcer, PolicyValidator, PolicyViolationError, Quantifier, type QuantifierEmptyArrayViolation, type QuantifierInfo, type QuantifierLimitExceededViolation, type ScalarValue, Scope, type ScopeInfo, type SelectorMismatchViolation, type Span, type TypeClass, type TypeClassInfo, TypeCode, type TypeCodeInfo, type TypeInfo, type ValueMismatchViolation, type Violation, type ViolationCode, arg, blockNumber, blockTimestamp, bytesToHex, chainId, hexToBytes, isLengthOp, isOpAllowed, isQuantifier, lookupContextProperty, lookupOp, lookupQuantifier, lookupScope, lookupTypeCode, msgSender, msgValue, parsePathSteps, toAddress, txOrigin };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/types.ts","../src/constraint.ts","../src/policy-builder.ts","../src/policy-coder.ts","../src/descriptor.ts","../src/policy-validator.ts","../src/policy-enforcer.ts","../src/bytes.ts","../src/descriptor-coder.ts","../src/constants.ts","../src/errors.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/types.ts","../src/constraint.ts","../src/policy-builder.ts","../src/policy-coder.ts","../src/descriptor.ts","../src/policy-validator.ts","../src/policy-enforcer.ts","../src/bytes.ts","../src/descriptor-coder.ts","../src/constants.ts","../src/operators.ts","../src/errors.ts"],"mappings":"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"}

package/dist/index.js

@@ -20,19 +20,27 @@ var CallciumError = class CallciumError extends Error {
 * Thrown by `PolicyEnforcer.enforce` when calldata fails policy enforcement.
 * Distinct from `CallciumError("VALIDATION_ERROR")`, which signals static
 * issues in the policy itself.
-* Carries the full list of violations (one per failed group).
+*
+* Carries the full list of structured violations (one per failed group). The
+* `Error.message` is a minimal non-lossy diagnostic summary built from the
+* first violation's structured fields — not a presentation contract. Consumers
+* rendering violations to users should iterate `violations` directly.
 */
 var PolicyViolationError = class PolicyViolationError extends Error {
 	violations;
 	constructor(violations) {
-		const first = violations[0];
-		const msg = first ? `Policy violation: ${first.message}` : "Policy violation";
-		super(msg);
+		super(formatDiagnostic(violations[0]));
 		this.name = "PolicyViolationError";
 		this.violations = violations;
 		Object.setPrototypeOf(this, PolicyViolationError.prototype);
 	}
 };
+/** Build a stack-trace-friendly diagnostic line from a violation's code and coordinates. */
+function formatDiagnostic(violation) {
+	if (!violation) return "Policy violation";
+	const location = "group" in violation ? ` at group ${violation.group} rule ${violation.rule}` : "";
+	return `Policy violation: ${violation.code}${location}`;
+}
 //#endregion
 //#region src/bytes.ts
 /** Regex that matches a valid hex body (even number of hex chars). */
@@ -2707,11 +2715,11 @@ function locate(tree, callData, pathBytes, baseOffset) {
 	for (let i = 0; i < paramIndex; i++) head += headContribution(tree[i]);
 	let base = baseOffset;
 	let node = tree[paramIndex];
-	for (let s = 1; s < stepCount; s++) {
-		const step = readStep(pathBytes, s);
+	for (let stepIndex = 1; stepIndex < stepCount; stepIndex++) {
+		const step = readStep(pathBytes, stepIndex);
 		if (isQuantifier(step)) {
-			const remaining = pathBytes.subarray((s + 1) * 2);
-			for (let r = 0; r < remaining.length / 2; r++) if (isQuantifier(readStep(remaining, r))) throw new CallciumError("INVALID_QUANTIFIER", "Nested quantifiers are not supported.");
+			const remaining = pathBytes.subarray((stepIndex + 1) * 2);
+			for (let remainingStepIndex = 0; remainingStepIndex < remaining.length / 2; remainingStepIndex++) if (isQuantifier(readStep(remaining, remainingStepIndex))) throw new CallciumError("INVALID_QUANTIFIER", "Nested quantifiers are not supported.");
 			return {
 				ok: true,
 				type: "quantifier",
@@ -2887,8 +2895,8 @@ function loadSlice(callData, location) {
 function descendPath(callData, location, pathBytes) {
 	const stepCount = pathBytes.length / 2;
 	let { head, base, node } = location;
-	for (let s = 0; s < stepCount; s++) {
-		const step = readStep(pathBytes, s);
+	for (let stepIndex = 0; stepIndex < stepCount; stepIndex++) {
+		const step = readStep(pathBytes, stepIndex);
 		const result = descend(node, callData, head, base, step);
 		if (result.type === "violation") return {
 			ok: false,
@@ -2916,38 +2924,27 @@ function addressToBigInt(hex) {
 	padded.set(bytes, 32 - bytes.length);
 	return toBigInt(padded, 0);
 }
-/** Format a bigint as a compact hex string without leading-zero padding. */
-function compactHex(value) {
-	if (value === 0n) return "0x0";
-	return `0x${value.toString(16)}`;
-}
-/** Truncate a hex string to at most maxChars characters, adding ellipsis if needed. */
-function truncateHexForMessage(hex, maxChars = 66) {
-	if (hex.length <= maxChars) return hex;
-	return `${hex.slice(0, maxChars - 1)}…`;
-}
-/** Format a decoded operand as decimal for length ops, otherwise compact hex. */
-function formatOperandValue(value, opCode) {
-	return isLengthOp(opCode) ? value.toString(10) : compactHex(value);
-}
-/** Format the constraint (operator + operands) from a single lookupOp call. */
-function formatConstraint(opCode, operandData) {
-	const negated = (opCode & Op.NOT) !== 0;
-	const { label, operands } = lookupOp(opCode);
-	const op = negated ? `not ${label}` : label;
-	let formattedOperands;
-	if (operands === "variadic") formattedOperands = `(${operandData.length / 32} values)`;
-	else if (operands === "range") {
-		const min = toBigInt(operandData, 0);
-		const max = toBigInt(operandData, 32);
-		formattedOperands = `[${formatOperandValue(min, opCode)}, ${formatOperandValue(max, opCode)}]`;
-	} else formattedOperands = formatOperandValue(toBigInt(operandData, 0), opCode);
-	return `${op} ${formattedOperands}`;
-}
-/** Build a self-contained VALUE_MISMATCH message for a scalar or length comparison. */
-function mismatchMessage(opCode, actual, operandData) {
-	const display = typeof actual === "number" ? String(actual) : truncateHexForMessage(compactHex(actual));
-	return `constraint ${formatConstraint(opCode, operandData)} violated by ${display}`;
+/**
+* Walk a descriptor subtree through path steps and return the terminal leaf type code.
+*
+* Used only for violation metadata. Valid policies have structurally valid
+* quantifier suffixes (enforced by `PolicyValidator`); if a hand-crafted blob
+* violates that invariant, return the last resolvable node's type code as
+* best-effort diagnostic context.
+*/
+function resolveLeafTypeCode(elementNode, remainingPath) {
+	let node = elementNode;
+	const stepCount = remainingPath.length / 2;
+	for (let step = 0; step < stepCount; step++) {
+		const childIndex = readU16(remainingPath, step * 2);
+		if (node.type === "tuple") {
+			const field = node.fields[childIndex];
+			if (!field) break;
+			node = field;
+		} else if (node.type === "staticArray" || node.type === "dynamicArray") node = node.element;
+		else break;
+	}
+	return node.typeCode;
 }
 /**
 * Check a policy against ABI-encoded call data without throwing on violations.
@@ -2963,10 +2960,7 @@ function check(policy, callData, context) {
 	if (!decoded.isSelectorless) {
 		if (callDataBytes.length < 4) return {
 			ok: false,
-			violations: [{
-				code: "MISSING_SELECTOR",
-				message: "Calldata too short to contain a selector"
-			}]
+			violations: [{ code: "MISSING_SELECTOR" }]
 		};
 		const expectedSelector = decoded.selector.value;
 		const actualSelector = bytesToHex(callDataBytes.subarray(0, 4));
@@ -2974,8 +2968,8 @@ function check(policy, callData, context) {
 			ok: false,
 			violations: [{
 				code: "SELECTOR_MISMATCH",
-				message: `Expected selector ${expectedSelector}, got ${actualSelector}`,
-				resolvedValue: actualSelector
+				resolvedValue: actualSelector,
+				expectedValue: expectedSelector
 			}]
 		};
 	}
@@ -3028,8 +3022,10 @@ function evaluateRule(rule, tree, callDataBytes, baseOffset, groupIndex, ruleInd
 		group: groupIndex,
 		rule: ruleIndex,
 		code: locResult.code,
-		message: `Navigation failed: ${locResult.code}`,
-		path: rule.path.value
+		scope: Scope.CALLDATA,
+		path: rule.path.value,
+		opCode,
+		operandData: rule.data.value
 	};
 	if (locResult.type === "quantifier") return evaluateQuantifier(locResult.quantifier, callDataBytes, opCode, operandData, groupIndex, ruleIndex, rule.path.value);
 	return evaluateLeaf(locResult.location, callDataBytes, opCode, operandData, groupIndex, ruleIndex, rule.path.value);
@@ -3044,23 +3040,33 @@ function evaluateContextRule(pathBytes, opCode, operandData, groupIndex, ruleInd
 		group: groupIndex,
 		rule: ruleIndex,
 		code: "MISSING_CONTEXT",
-		message: `Context property ${propInfo.label} not provided`,
-		path: pathHex
+		scope: Scope.CONTEXT,
+		path: pathHex,
+		typeCode: propInfo.typeCode
 	};
 	let value;
 	if (typeof contextValue === "string") value = addressToBigInt(contextValue);
 	else value = contextValue;
-	if (!applyOperator(opCode, value, 32, operandData, TypeCode.UINT_MAX)) return {
+	if (!applyOperator(opCode, value, 32, operandData, propInfo.typeCode)) return {
 		group: groupIndex,
 		rule: ruleIndex,
 		code: "VALUE_MISMATCH",
-		message: mismatchMessage(opCode, value, operandData),
+		scope: Scope.CONTEXT,
 		path: pathHex,
+		opCode,
+		operandData: bytesToHex(operandData),
+		typeCode: propInfo.typeCode,
 		resolvedValue: bigintToHex(value)
 	};
 	return null;
 }
-/** Load a value from calldata at the given location and apply the operator. */
+/**
+* Load a value from calldata at the given location and apply the operator.
+*
+* `resolvedValue` is normalised at the decision point: length operators encode
+* the byte/element count as a hex bigint; scalar operators preserve the full
+* 32-byte ABI word so downstream rendering can decode left-aligned `bytesN` faithfully.
+*/
 function applyLeafOperator(callDataBytes, location, opCode, operandData) {
 	const { node } = location;
 	if (isLengthOp(opCode)) {
@@ -3072,61 +3078,68 @@ function applyLeafOperator(callDataBytes, location, opCode, operandData) {
 		} else valueLength = node.staticSize;
 		return {
 			passed: applyOperator(opCode, 0n, valueLength, operandData, node.typeCode),
-			length: valueLength
+			resolvedValue: bigintToHex(BigInt(valueLength))
 		};
 	}
 	const result = loadScalar(callDataBytes, location);
 	if (!result.ok) return { error: result.code };
-	const value = toBigInt(result.value, 0);
 	return {
-		passed: applyOperator(opCode, value, 32, operandData, node.typeCode),
-		value
+		passed: applyOperator(opCode, toBigInt(result.value, 0), 32, operandData, node.typeCode),
+		resolvedValue: bytesToHex(result.value)
 	};
 }
 /** Evaluate a leaf rule, producing a violation on failure or null on pass. */
 function evaluateLeaf(location, callDataBytes, opCode, operandData, groupIndex, ruleIndex, pathHex) {
 	const result = applyLeafOperator(callDataBytes, location, opCode, operandData);
-	if ("error" in result) {
-		const message = isLengthOp(opCode) ? `Failed to read length: ${result.error}` : `Failed to load value: ${result.error}`;
-		return {
-			group: groupIndex,
-			rule: ruleIndex,
-			code: result.error,
-			message,
-			path: pathHex
-		};
-	}
-	if (!result.passed) {
-		const actual = result.value !== void 0 ? result.value : result.length ?? 0;
-		return {
-			group: groupIndex,
-			rule: ruleIndex,
-			code: "VALUE_MISMATCH",
-			message: mismatchMessage(opCode, actual, operandData),
-			path: pathHex,
-			resolvedValue: bigintToHex(typeof actual === "number" ? BigInt(actual) : actual)
-		};
-	}
+	const typeCode = location.node.typeCode;
+	if ("error" in result) return {
+		group: groupIndex,
+		rule: ruleIndex,
+		code: result.error,
+		scope: Scope.CALLDATA,
+		path: pathHex,
+		opCode,
+		operandData: bytesToHex(operandData),
+		typeCode
+	};
+	if (!result.passed) return {
+		group: groupIndex,
+		rule: ruleIndex,
+		code: "VALUE_MISMATCH",
+		scope: Scope.CALLDATA,
+		path: pathHex,
+		opCode,
+		operandData: bytesToHex(operandData),
+		typeCode,
+		resolvedValue: result.resolvedValue
+	};
 	return null;
 }
 /** Evaluate a quantified rule by iterating over array elements with ALL/ANY semantics. */
 function evaluateQuantifier(qResult, callDataBytes, opCode, operandData, groupIndex, ruleIndex, pathHex) {
 	const { quantifier, location: arrayLocation, remainingPath } = qResult;
+	const operandHex = bytesToHex(operandData);
+	const arrayNode = arrayLocation.node;
+	const leafTypeCode = resolveLeafTypeCode(arrayNode.type === "staticArray" || arrayNode.type === "dynamicArray" ? arrayNode.element : arrayNode, remainingPath);
 	const shapeResult = arrayShape(callDataBytes, arrayLocation);
 	if (!shapeResult.ok) return {
 		group: groupIndex,
 		rule: ruleIndex,
 		code: shapeResult.code,
-		message: `Failed to read array shape: ${shapeResult.code}`,
-		path: pathHex
+		scope: Scope.CALLDATA,
+		path: pathHex,
+		opCode,
+		operandData: operandHex,
+		typeCode: leafTypeCode
 	};
 	const shape = shapeResult.shape;
 	if (shape.length > Limits.MAX_QUANTIFIED_ARRAY_LENGTH) return {
 		group: groupIndex,
 		rule: ruleIndex,
 		code: "QUANTIFIER_LIMIT_EXCEEDED",
-		message: `Array length ${shape.length} exceeds maximum ${Limits.MAX_QUANTIFIED_ARRAY_LENGTH}`,
-		path: pathHex
+		scope: Scope.CALLDATA,
+		path: pathHex,
+		resolvedValue: bigintToHex(BigInt(shape.length))
 	};
 	if (shape.length === 0) {
 		if (quantifier === Quantifier.ALL_OR_EMPTY) return null;
@@ -3134,7 +3147,7 @@ function evaluateQuantifier(qResult, callDataBytes, opCode, operandData, groupIn
 			group: groupIndex,
 			rule: ruleIndex,
 			code: "QUANTIFIER_EMPTY_ARRAY",
-			message: "Quantifier applied to empty array",
+			scope: Scope.CALLDATA,
 			path: pathHex
 		};
 	}
@@ -3147,70 +3160,82 @@ function evaluateQuantifier(qResult, callDataBytes, opCode, operandData, groupIn
 				group: groupIndex,
 				rule: ruleIndex,
 				code: elemResult.code,
-				message: `Quantifier element ${elemIndex}: ${elemResult.code}`,
-				path: pathHex
+				scope: Scope.CALLDATA,
+				path: pathHex,
+				opCode,
+				operandData: operandHex,
+				typeCode: leafTypeCode,
+				elementIndex: elemIndex
 			};
 			continue;
 		}
 		const elemLocation = elemResult.location;
-		let elemPassed;
+		let leafLocation;
 		if (hasSuffix) {
-			const leafResult = descendPath(callDataBytes, elemLocation, remainingPath);
-			if (!leafResult.ok) {
-				if (isUniversal) return {
-					group: groupIndex,
-					rule: ruleIndex,
-					code: leafResult.code,
-					message: `Quantifier element ${elemIndex} navigation failed: ${leafResult.code}`,
-					path: pathHex
-				};
-				continue;
-			}
-			elemPassed = evaluateLeafValue(leafResult.location, callDataBytes, opCode, operandData);
-		} else {
-			const leafResult = applyLeafOperator(callDataBytes, elemLocation, opCode, operandData);
-			if ("error" in leafResult) {
+			const navResult = descendPath(callDataBytes, elemLocation, remainingPath);
+			if (!navResult.ok) {
 				if (isUniversal) return {
 					group: groupIndex,
 					rule: ruleIndex,
-					code: leafResult.error,
-					message: `Quantifier element ${elemIndex}: ${leafResult.error}`,
-					path: pathHex
+					code: navResult.code,
+					scope: Scope.CALLDATA,
+					path: pathHex,
+					opCode,
+					operandData: operandHex,
+					typeCode: leafTypeCode,
+					elementIndex: elemIndex
 				};
 				continue;
 			}
-			elemPassed = leafResult.passed;
+			leafLocation = navResult.location;
+		} else leafLocation = elemLocation;
+		const applied = applyLeafOperator(callDataBytes, leafLocation, opCode, operandData);
+		if ("error" in applied) {
+			if (isUniversal) return {
+				group: groupIndex,
+				rule: ruleIndex,
+				code: applied.error,
+				scope: Scope.CALLDATA,
+				path: pathHex,
+				opCode,
+				operandData: operandHex,
+				typeCode: leafTypeCode,
+				elementIndex: elemIndex
+			};
+			continue;
 		}
-		if (isUniversal && !elemPassed) return {
+		if (isUniversal && !applied.passed) return {
 			group: groupIndex,
 			rule: ruleIndex,
 			code: "VALUE_MISMATCH",
-			message: `constraint ${formatConstraint(opCode, operandData)} violated at element ${elemIndex}`,
-			path: pathHex
+			scope: Scope.CALLDATA,
+			path: pathHex,
+			opCode,
+			operandData: operandHex,
+			typeCode: leafTypeCode,
+			resolvedValue: applied.resolvedValue,
+			elementIndex: elemIndex
 		};
-		if (!isUniversal && elemPassed) return null;
+		if (!isUniversal && applied.passed) return null;
 	}
 	if (isUniversal) return null;
 	return {
 		group: groupIndex,
 		rule: ruleIndex,
 		code: "VALUE_MISMATCH",
-		message: `constraint ${formatConstraint(opCode, operandData)} violated by all elements`,
-		path: pathHex
+		scope: Scope.CALLDATA,
+		path: pathHex,
+		opCode,
+		operandData: operandHex,
+		typeCode: leafTypeCode
 	};
 }
-/** Apply a leaf operator and return a boolean. Returns false on calldata read failure. */
-function evaluateLeafValue(location, callDataBytes, opCode, operandData) {
-	const result = applyLeafOperator(callDataBytes, location, opCode, operandData);
-	if ("error" in result) return false;
-	return result.passed;
-}
 /** Check and enforce policies against ABI-encoded call data. */
 const PolicyEnforcer = {
 	check,
 	enforce
 };
 //#endregion
-export { CallciumError, ContextProperty, Descriptor, DescriptorCoder, Limits, Op, PolicyBuilder, PolicyCoder, PolicyEnforcer, PolicyValidator, PolicyViolationError, Quantifier, Scope, TypeCode, arg, blockNumber, blockTimestamp, bytesToHex, chainId, hexToBytes, isOpAllowed, isQuantifier, lookupContextProperty, lookupOp, lookupQuantifier, lookupScope, lookupTypeCode, msgSender, msgValue, parsePathSteps, toAddress, txOrigin };
+export { CallciumError, ContextProperty, Descriptor, DescriptorCoder, Limits, Op, PolicyBuilder, PolicyCoder, PolicyEnforcer, PolicyValidator, PolicyViolationError, Quantifier, Scope, TypeCode, arg, blockNumber, blockTimestamp, bytesToHex, chainId, hexToBytes, isLengthOp, isOpAllowed, isQuantifier, lookupContextProperty, lookupOp, lookupQuantifier, lookupScope, lookupTypeCode, msgSender, msgValue, parsePathSteps, toAddress, txOrigin };
 
 //# sourceMappingURL=index.js.map