@callcium/sdk 0.11.1 → 0.12.0

package/src/policy-coder.ts

@@ -1,4 +1,5 @@
 import { keccak_256 } from "@noble/hashes/sha3.js";
+import { concatBytes } from "@noble/hashes/utils.js";
 
 import { bytesToHex, hexToBytes, toHex, readU16, readU32, writeBE16, writeBE32 } from "./bytes";
 import {
@@ -15,6 +16,7 @@ import { Descriptor } from "./descriptor";
 import { decodeDescriptor } from "./descriptor-coder";
 import { CallciumError, type CallciumErrorCode } from "./errors";
 import {
+  isContextOp,
   isLengthOp,
   isLengthValidType,
   toBigInt,
@@ -45,9 +47,8 @@ function field<T>(value: T, start: number, end: number): Field<T> {
 }
 
 /**
- * Wrap the hex rendering of `data[start, end)` with its span, rendering on first read.
- * Enforcement reads the span as bytes, so the string is built only for a caller that asks.
- * The field reads and assigns like the plain one it replaces.
+ * Wrap the hex rendering of `data[start, end)` with its span, rendering on first read. Enforcement reads the span as
+ * bytes, so the string is built only for a caller that asks. The field reads and assigns like a plain one.
  */
 function hexField(data: Uint8Array, start: number, end: number): Field<Hex> {
   let hex: Hex | undefined;
@@ -140,8 +141,8 @@ function validateHint(data: Uint8Array, hintStart: number, hintSize: number, rul
     targetTypeCode === TypeCode.DYNAMIC_ARRAY ? (targetMeta & PF.HINT_META_RESERVED_MASK) === 0 : targetMeta === 0;
   if (!targetMetaOk) malformedHint("Target meta carries reserved or unused state", ruleOffset);
 
-  // An operator reads either a scalar word or a declared length, so a target carrying neither —
-  // a tuple, a static array, or an undefined code — addresses nothing.
+  // An operator reads either a scalar word or a declared length, so a target carrying neither — a tuple, a static
+  // array, or an undefined code — addresses nothing.
   if (!isAddressableTarget(targetTypeCode)) malformedHint("Target type code addresses no value", ruleOffset);
 }
 
@@ -300,8 +301,8 @@ export function decodePolicy(blob: Hex): { policy: DecodedPolicy; data: Uint8Arr
         throw new CallciumError("UNKNOWN_OPERATOR", "Unrecognized or malformed operator", ruleOffset);
       }
 
-      // A length operator reads the declared length a dynamic target resolves to, and a value
-      // operator reads a scalar word, so the target type fixes which family the rule may carry.
+      // A length operator reads the declared length a dynamic target resolves to, and a value operator reads a scalar
+      // word, so the target type fixes which family the rule may carry.
       if (hintSize !== 0) {
         const targetTypeCode = hintTargetTypeCode(data, hintStart, hintSize);
         if (isLengthValidType(targetTypeCode) !== isLengthOp(opBase)) {
@@ -328,12 +329,12 @@ export function decodePolicy(blob: Hex): { policy: DecodedPolicy; data: Uint8Arr
         }
       }
 
-      // An EQ_CTX operand word must be a defined context property ID.
-      if (opBase === Op.EQ_CTX) {
+      // A context reference operand word must be a defined context property ID.
+      if (isContextOp(opBase)) {
         if (toBigInt(data, dataStart) > BigInt(MAX_CONTEXT_PROPERTY_ID)) {
           throw new CallciumError(
             "UNKNOWN_CONTEXT_PROPERTY",
-            "EQ_CTX operand references an undefined context property",
+            "Context reference operand references an undefined context property",
             ruleOffset,
           );
         }
@@ -468,9 +469,8 @@ function readConstraintTarget(constraint: Constraint, desc: Uint8Array): Constra
 
 /** Flatten a Constraint into one Rule per operator, compiling its hint against the descriptor. */
 function flattenConstraint(constraint: Constraint, desc: Uint8Array): Rule[] {
-  // The rule is the unit these checks run over: each rule's operator is established before the
-  // path and hint it shares with its siblings. A constraint carrying no operator produces no rule,
-  // so its path is never read.
+  // The rule is the unit these checks run over: each rule's operator is established before the path and hint it shares
+  // with its siblings. A constraint carrying no operator produces no rule, so its path is never read.
   let target: ConstraintTarget | undefined;
 
   return constraint.operators.map((operatorHex) => {
@@ -509,8 +509,7 @@ function requireFieldFits(value: number, byteWidth: number, code: CallciumErrorC
 }
 
 /**
- * Serialize a single rule to its wire format bytes.
- * Path shape and operator framing are established by `flattenConstraint`.
+ * Serialize a single rule to its wire format bytes. `flattenConstraint` establishes path shape and operator framing.
  */
 function encodeRule(rule: Rule): Uint8Array {
   const depth = rule.path.length / 2;
@@ -537,15 +536,7 @@ function encodeRule(rule: Rule): Uint8Array {
 
 /** Serialize all rules in a group to a single byte array. */
 function encodeGroupRules(rules: Rule[]): Uint8Array {
-  const parts = rules.map(encodeRule);
-  const totalSize = parts.reduce((sum, p) => sum + p.length, 0);
-  const buf = new Uint8Array(totalSize);
-  let offset = 0;
-  for (const part of parts) {
-    buf.set(part, offset);
-    offset += part.length;
-  }
-  return buf;
+  return concatBytes(...rules.map(encodeRule));
 }
 
 ///////////////////////////////////////////////////////////////////////////
@@ -572,8 +563,8 @@ function encode(data: PolicyData): Hex {
   }
   requireFieldFits(data.groups.length, PF.GROUP_COUNT_SIZE, "GROUP_COUNT_OVERFLOW", "Group count");
 
-  // Flatten constraints into rules and sort within each group. Hints are compiled first because
-  // they are part of the rule bytes the group hash covers.
+  // Flatten constraints into rules and sort within each group. Hints are compiled first because they are part of the
+  // rule bytes the group hash covers.
   const sortedGroups: Rule[][] = data.groups.map((group) => {
     const rules = group.flatMap((constraint) => flattenConstraint(constraint, descBytes));
     sortRules(rules);
@@ -590,8 +581,8 @@ function encode(data: PolicyData): Hex {
     return { wireBytes: encodeGroupRules(rules), ruleCount: rules.length };
   });
 
-  // Several groups are ordered by ascending keccak256 over their rule bytes; a lone group is
-  // already in canonical position, so it needs no hash.
+  // Several groups are ordered by ascending keccak256 over their rule bytes; a lone group is already in canonical
+  // position, so it needs no hash.
   if (encodedGroups.length > 1) {
     const hashes = new Map(encodedGroups.map((group) => [group, keccak_256(group.wireBytes)]));
     encodedGroups.sort((a, b) => compareBytes(hashes.get(a)!, hashes.get(b)!));
@@ -648,7 +639,7 @@ function encode(data: PolicyData): Hex {
 /**
  * Decode a binary policy blob into a PolicyData structure.
  * @param blob - Binary policy as 0x-prefixed hex string.
- * @returns The decoded policy data with constraints grouped by scope and path.
+ * @returns The decoded policy data with constraints grouped by scope, path, and hint.
  * @throws {CallciumError} If the blob is structurally malformed.
  */
 function decode(blob: Hex): PolicyData {

package/src/policy-enforcer.ts

@@ -1,8 +1,8 @@
 import { hexToBytes, bytesToHex, readU16, readU32, bigintToHex, toAddress } from "./bytes";
 import { loadWord, readLength, readPointer } from "./calldata-reader";
-import { PolicyFormat as PF, Scope, Op, TypeCode, lookupContextProperty } from "./constants";
+import { PolicyFormat as PF, Scope, TypeCode, lookupContextProperty } from "./constants";
 import { CallciumError, PolicyViolationError } from "./errors";
-import { applyOperator, toBigInt, isLengthValidType, canonicalize } from "./operators";
+import { applyOperator, isContextOp, toBigInt, isLengthValidType, canonicalize } from "./operators";
 import { decodePolicy } from "./policy-coder";
 
 import type { ReadResult } from "./calldata-reader";
@@ -32,7 +32,7 @@ const abortViolationCodes: ReadonlySet<ViolationCode> = new Set<ViolationCode>([
 
 /**
  * Read a supplied context value as the 32-byte word that carries it.
- * @throws {CallciumError} When an integer lies outside the range a 32-byte word represents.
+ * @throws {CallciumError} When an address is not 20 bytes of hex or an integer does not fit a 32-byte word.
  */
 function contextValueToWord(value: bigint | Address): bigint {
   if (typeof value === "string") return BigInt(toAddress(value));
@@ -55,8 +55,8 @@ function contextValueToWord(value: bigint | Address): bigint {
  * @param callData - ABI-encoded call data as 0x-prefixed hex string.
  * @param context - Optional execution context for context-scoped rules.
  * @returns Pass with matched group index, or fail with one violation per evaluated failing group.
- * @throws {CallciumError} If the policy blob is structurally malformed, or a context value a rule
- * reads is not an address or an integer a 32-byte word represents.
+ * @throws {CallciumError} If the policy blob is structurally malformed, the call data is not valid hex, or a context
+ * value a rule reads is not an address or an integer a 32-byte word represents.
  */
 function check(policy: Hex, callData: Hex, context?: Context): EnforceResult {
   const { policy: decoded, data: policyBytes } = decodePolicy(policy);
@@ -123,8 +123,8 @@ function check(policy: Hex, callData: Hex, context?: Context): EnforceResult {
  * @param callData - ABI-encoded call data as 0x-prefixed hex string.
  * @param context - Optional execution context for context-scoped rules.
  * @throws {PolicyViolationError} If the policy rejects the call data.
- * @throws {CallciumError} If the policy blob is structurally malformed, or a context value a rule
- * reads is not an address or an integer a 32-byte word represents.
+ * @throws {CallciumError} If the policy blob is structurally malformed, the call data is not valid hex, or a context
+ * value a rule reads is not an address or an integer a 32-byte word represents.
  */
 function enforce(policy: Hex, callData: Hex, context?: Context): void {
   const result = check(policy, callData, context);
@@ -178,12 +178,12 @@ function evaluateRule(
   );
 }
 
-/** An `EQ_CTX` operand resolved to its word, or the missing property's type code. */
+/** A context reference operand resolved to its word, or the missing property's type code. */
 type ReferenceOperand = bigint | { ctxTypeCode: number };
 
 /**
- * Resolve an EQ_CTX operand word to the referenced context property's value as a raw word.
- * Returns the missing property's type code when the context does not supply it.
+ * Resolve a context reference operand word to the referenced context property's value as a raw word. Returns the
+ * missing property's type code when the context does not supply it.
  */
 function resolveContextOperand(operandData: Uint8Array, context?: Context): ReferenceOperand {
   const propertyInfo = lookupContextProperty(Number(toBigInt(operandData, 0)));
@@ -192,9 +192,9 @@ function resolveContextOperand(operandData: Uint8Array, context?: Context): Refe
   return contextValueToWord(value);
 }
 
-/** Resolve the reference operand of an `EQ_CTX` rule; every other operator reads a literal. */
+/** Resolve the reference operand of a context reference rule; every other operator reads a literal. */
 function referenceOperand(opCode: number, operandData: Uint8Array, context?: Context): ReferenceOperand | undefined {
-  if ((opCode & ~Op.NOT) !== Op.EQ_CTX) return undefined;
+  if (!isContextOp(opCode)) return undefined;
   return resolveContextOperand(operandData, context);
 }
 
@@ -281,9 +281,8 @@ type TargetResult =
 /**
  * Load the value at a resolved target offset and apply the operator.
  *
- * `value` is normalised at the decision point: length operators yield the byte/element
- * count; scalar operators preserve the full 32-byte ABI word, keeping left-aligned `bytesN`
- * decodable. A passing target allocates no string.
+ * `value` is normalised at the decision point: length operators yield the byte/element count; scalar operators preserve
+ * the full 32-byte ABI word, keeping left-aligned `bytesN` decodable. A passing target allocates no string.
  */
 function evalTarget(
   callData: Uint8Array,
@@ -319,7 +318,7 @@ function evalTarget(
 
   if (ctxOperand !== undefined) {
     if (typeof ctxOperand !== "bigint") return { error: "MISSING_CONTEXT", ctxTypeCode: ctxOperand.ctxTypeCode };
-    const passed = (value === ctxOperand) !== ((opCode & Op.NOT) !== 0);
+    const passed = applyOperator(opCode, value, 32n, hexToBytes(bigintToHex(ctxOperand)), typeCode);
     return { passed, value, ctxOperand };
   }
 
@@ -539,8 +538,8 @@ function evaluateQuantified(
     let elem: number = slot;
     if (elemIsDynamic) {
       const followed = follow(callDataBytes, elems, slot);
-      // Navigation failures abort under every quantifier: calldata the enforcer cannot read is
-      // not an element that merely fails the operator.
+      // Navigation failures abort under every quantifier: calldata the enforcer cannot read is not an element that
+      // merely fails the operator.
       if (typeof followed !== "number") return navigationViolation(frame, followed.code, elemIndex);
       elem = followed;
     }
@@ -554,9 +553,8 @@ function evaluateQuantified(
 
     const applied = evalTarget(callDataBytes, base + block.targetDelta, block, opCode, operandData, reference);
     if ("error" in applied) {
-      // Error results end the rule whatever the quantifier: a later element cannot rescue
-      // calldata the enforcer cannot read (an abort effect), and a missing context
-      // property is missing for every element alike (group-local).
+      // Error results end the rule whatever the quantifier: a later element cannot rescue calldata the enforcer cannot
+      // read (an abort effect), and a missing context property is missing for every element alike (group-local).
       return targetViolation(frame, applied, elemIndex);
     }
 
@@ -604,7 +602,7 @@ function evaluateContextRule(
 
   let result: boolean;
   let ctxOperand: bigint | undefined;
-  if ((opCode & ~Op.NOT) === Op.EQ_CTX) {
+  if (isContextOp(opCode)) {
     const operand = resolveContextOperand(operandData, context);
     if (typeof operand !== "bigint") {
       return {
@@ -615,7 +613,7 @@ function evaluateContextRule(
         typeCode: operand.ctxTypeCode,
       };
     }
-    result = (value === operand) !== ((opCode & Op.NOT) !== 0);
+    result = applyOperator(opCode, value, 32n, hexToBytes(bigintToHex(operand)), propertyInfo.typeCode);
     ctxOperand = operand;
   } else {
     result = applyOperator(opCode, value, 32n, operandData, propertyInfo.typeCode);

package/src/policy-validator.ts

@@ -1,5 +1,14 @@
 import { bigintToHex, bytesToHex, hexToBytes } from "./bytes";
-import { fieldMax, findContextProperty, MAX_CONTEXT_PROPERTY_ID, Op, PolicyFormat, Scope, TypeCode } from "./constants";
+import {
+  fieldMax,
+  findContextProperty,
+  MAX_CONTEXT_PROPERTY_ID,
+  Op,
+  operandsOf,
+  PolicyFormat,
+  Scope,
+  TypeCode,
+} from "./constants";
 import { Descriptor, type TypeInfo } from "./descriptor";
 import { decodeDescriptor } from "./descriptor-coder";
 import { CallciumError, type CallciumErrorCode } from "./errors";
@@ -7,6 +16,7 @@ import {
   canonicalize,
   isLeftAligned,
   isSigned,
+  isContextOp,
   isLengthOp,
   isLengthValidType,
   isElementary,
@@ -143,7 +153,7 @@ function getDomainLimits(typeCode: number): { min: bigint; max: bigint } {
 // Operator classification
 ///////////////////////////////////////////////////////////////////////////
 
-/** True for EQ, GT, LT, GTE, LTE, BETWEEN, IN, EQ_CTX, BITMASK_*. */
+/** True if an operator code is in the value-operator range (unassigned codes included). */
 function isValueOp(opBase: number): boolean {
   return opBase <= Op.BITMASK_NONE;
 }
@@ -163,7 +173,7 @@ function isBitmaskOp(opBase: number): boolean {
 ///////////////////////////////////////////////////////////////////////////
 
 /** Return the incompatibility reason, or null if the operator is allowed. */
-function getIncompat(opBase: number, typeInfo: TypeInfo): { code: IssueCode; message: string } | null {
+function checkCompatibility(opBase: number, typeInfo: TypeInfo): { code: IssueCode; message: string } | null {
   const { typeCode, isDynamic, staticSize } = typeInfo;
   if (isValueOp(opBase)) {
     if (isDynamic || staticSize !== 32) {
@@ -178,15 +188,16 @@ function getIncompat(opBase: number, typeInfo: TypeInfo): { code: IssueCode; mes
     if (isBitmaskOp(opBase) && !isBitmaskCompatible(typeCode)) {
       return { code: "BITMASK_ON_INVALID", message: "Bitmask operator used on incompatible type" };
     }
-    // IN on bool is degenerate: the two-value domain reduces every set to an equality, a tautology, or dead members.
+    // IN on bool is degenerate: two values reduce every set to an equality, a tautology, or dead members.
     if (opBase === Op.IN && typeCode === TypeCode.BOOL) {
       return { code: "IN_ON_BOOL", message: "IN operator used on boolean type" };
     }
-    // Context properties are addresses or uint256, so only those target classes can match.
+    // Context properties are addresses or uint256, so only those target classes can match, and an address is an
+    // identity rather than a magnitude, so it pairs under equality only.
     if (
-      opBase === Op.EQ_CTX &&
-      typeCode !== TypeCode.ADDRESS &&
-      !(typeCode >= TypeCode.UINT_MIN && typeCode <= TypeCode.UINT_MAX)
+      isContextOp(opBase) &&
+      !(typeCode >= TypeCode.UINT_MIN && typeCode <= TypeCode.UINT_MAX) &&
+      !(opBase === Op.EQ_CTX && typeCode === TypeCode.ADDRESS)
     ) {
       return { code: "CONTEXT_TYPE_MISMATCH", message: "Context reference operator used on incompatible type" };
     }
@@ -202,11 +213,12 @@ function getIncompat(opBase: number, typeInfo: TypeInfo): { code: IssueCode; mes
 }
 
 /**
- * True if operator `opCode` is allowed on a target with the given type info.
- * Tolerates the NOT flag on `opCode`.
+ * True if operator `opCode` is a defined operator allowed on a target with the given type info. Tolerates the NOT flag
+ * on `opCode`.
  */
 export function isOpAllowed(opCode: number, typeInfo: TypeInfo): boolean {
-  return getIncompat(opCode & ~Op.NOT, typeInfo) === null;
+  const opBase = opCode & ~Op.NOT;
+  return operandsOf(opBase) !== undefined && checkCompatibility(opBase, typeInfo) === null;
 }
 
 ///////////////////////////////////////////////////////////////////////////
@@ -690,7 +702,7 @@ function updateSet(
   constraintIndex: number,
   issues: Issue[],
 ): void {
-  // Physical bounds: a member outside the type's domain never occurs, so it neither matches nor excludes anything.
+  // Physical bounds: a member outside the type's domain never occurs, so it matches and excludes nothing.
   for (const value of values) {
     if (isOutsideDomain(ctx.numeric, value)) {
       issues.push(ValidationIssue.outOfPhysicalBounds(false, groupIndex, constraintIndex, bigintToHex(value)));
@@ -781,9 +793,9 @@ function checkDuplicates(issues: Issue[], operators: Hex[], groupIndex: number,
 ///////////////////////////////////////////////////////////////////////////
 
 /**
- * Report a lone unnegated gte/lte pair (value or length domain) as fusible into the
- * corresponding single range operator. Fires only for a satisfiable pair on a compatible
- * type; contradictions and dominated bounds are already reported by the domain checks.
+ * Report a lone unnegated gte/lte pair (value or length domain) as fusible into the corresponding single range
+ * operator. Fires only for a satisfiable pair on a compatible type; contradictions and dominated bounds are already
+ * reported by the domain checks.
  */
 function checkFusibleRange(
   ctx: ConstraintContext,
@@ -795,7 +807,7 @@ function checkFusibleRange(
   const numericPair = findLonePair(operators, Op.GTE, Op.LTE);
   if (
     numericPair &&
-    getIncompat(Op.GTE, ctx.typeInfo) === null &&
+    checkCompatibility(Op.GTE, ctx.typeInfo) === null &&
     signedCompare(numericPair.low, numericPair.high, ctx.numeric.isSigned) <= 0n
   ) {
     issues.push(
@@ -810,7 +822,7 @@ function checkFusibleRange(
   }
 
   const lengthPair = findLonePair(operators, Op.LENGTH_GTE, Op.LENGTH_LTE);
-  if (lengthPair && getIncompat(Op.LENGTH_GTE, ctx.typeInfo) === null && lengthPair.low <= lengthPair.high) {
+  if (lengthPair && checkCompatibility(Op.LENGTH_GTE, ctx.typeInfo) === null && lengthPair.low <= lengthPair.high) {
     issues.push(
       ValidationIssue.fusibleRange(
         true,
@@ -894,12 +906,12 @@ function validateConstraint(
       issues.push(ValidationIssue.negationUnderAny(groupIndex, constraintIndex, bigintToHex(BigInt(opCode))));
     }
 
-    const incompat = getIncompat(base, ctx.typeInfo);
-    if (incompat) {
+    const incompatibility = checkCompatibility(base, ctx.typeInfo);
+    if (incompatibility) {
       issues.push(
         ValidationIssue.fromOpRule(
-          incompat.code,
-          incompat.message,
+          incompatibility.code,
+          incompatibility.message,
           groupIndex,
           constraintIndex,
           bigintToHex(BigInt(opCode)),
@@ -908,7 +920,7 @@ function validateConstraint(
       continue;
     }
 
-    if (base === Op.EQ_CTX) {
+    if (isContextOp(base)) {
       // The operand names a context property, not a value: nothing to fold into a domain.
       const ctxOperand = readValue(opHex);
       const property = findContextProperty(Number(ctxOperand));
@@ -922,8 +934,8 @@ function validateConstraint(
           ),
         );
       } else {
-        // Compatibility has already narrowed the target to an address or unsigned type,
-        // so the pairing reduces to whether both sides are addresses.
+        // Compatibility has already narrowed the target to an address or unsigned type, so the pairing reduces to
+        // whether both sides are addresses.
         const propertyIsAddress = property.typeCode === TypeCode.ADDRESS;
         const targetIsAddress = ctx.typeInfo.typeCode === TypeCode.ADDRESS;
         if (propertyIsAddress !== targetIsAddress) {
@@ -938,10 +950,8 @@ function validateConstraint(
         }
       }
     } else if (isValueOp(base)) {
-      // A non-canonical operand can never equal a canonicalized runtime value (PC-1, spec
-      // section 4.5), so the rule is unsatisfiable or vacuous; skip analyzing the garbage
-      // word. Scoped to the left-aligned types: numeric, address, and bool operands are
-      // already covered by the physical domain limits.
+      // An operand that breaks PC-1 never matches, since enforcement only admits canonical values, so the rule is
+      // unsatisfiable or vacuous; skip it. Numeric, address and bool operands are already covered by the domain limits.
       const typeCode = ctx.typeInfo.typeCode;
       if (isLeftAligned(typeCode)) {
         const nonCanonical = findNonCanonicalWord(opHex, typeCode);
@@ -960,10 +970,9 @@ function validateConstraint(
 
       if (base >= Op.EQ && base <= Op.BETWEEN) {
         if (base === Op.BETWEEN) {
-          // A negated range is a disjunction (value < low OR value > high); distributing the
-          // negation over the decomposed bounds would conjoin the complement halves into a
-          // spurious contradiction. Leave it un-analyzed, like a neq hole. Inverted bounds
-          // still surface: negating an empty range excludes nothing.
+          // A negated range is a disjunction (value < low OR value > high); distributing the negation over the
+          // decomposed bounds would conjoin the complement halves into a spurious contradiction. Leave it un-analyzed,
+          // like a neq hole. Inverted bounds still surface: negating an empty range excludes nothing.
           const { low, high } = readPair(opHex);
           if (!isNegated) {
             updateBound(ctx.numeric, Op.GTE, false, low, false, groupIndex, constraintIndex, issues);
@@ -1047,7 +1056,7 @@ function validateGroup(data: PolicyData, descBytes: Uint8Array, groupIndex: numb
       if (steps.length === 0) throw new CallciumError("EMPTY_PATH", "Path must have at least one step");
       let typeInfo: TypeInfo;
       if (constraint.scope === Scope.CALLDATA) {
-        // Compatibility warnings against the limits the spec fixes (PWF-17, PV-7).
+        // Compatibility issues against the limits the spec fixes (PWF-17, PV-7).
         if (steps.length > PolicyFormat.MAX_PATH_DEPTH) {
           issues.push(
             ValidationIssue.pathDepthExceeded(
@@ -1089,8 +1098,8 @@ function validateGroup(data: PolicyData, descBytes: Uint8Array, groupIndex: numb
         const ctxId = steps[0]!;
         const property = findContextProperty(ctxId);
         if (!property) {
-          // An unassigned ID declares no type, so the analysis proceeds over the widest
-          // unsigned domain and the warning carries the ID.
+          // An unassigned ID declares no type, so the analysis proceeds over the widest unsigned domain and the warning
+          // carries the ID.
           issues.push(
             ValidationIssue.unknownContextProperty(
               groupIndex,
@@ -1106,10 +1115,9 @@ function validateGroup(data: PolicyData, descBytes: Uint8Array, groupIndex: numb
       contexts.push(ctx);
     }
 
-    // A carried hint must equal the compilation of its own path; constraints without an encoding
-    // carry none, an empty one carries nothing to compare, and the encoder compiles theirs from
-    // the same descriptor. Reaching here means the path navigates the descriptor and quantifies at
-    // most once, so only the depth PWF-17 admits remains to be established.
+    // A carried hint must equal the compilation of its own path; constraints without an encoding carry none, an empty
+    // one carries nothing to compare, and the encoder compiles theirs from the same descriptor. Reaching here means the
+    // path navigates the descriptor and quantifies at most once, so only the PWF-17 depth check remains.
     if (
       constraint.scope === Scope.CALLDATA &&
       constraint.hint !== undefined &&
@@ -1136,11 +1144,10 @@ function validateGroup(data: PolicyData, descBytes: Uint8Array, groupIndex: numb
  * Validate a policy for type mismatches, contradictions, redundancies, and vacuities.
  * @param data - The canonical policy data to validate.
  * @returns All validation issues found, ordered by group and constraint index.
- * @throws {CallciumError} If the descriptor is not well-formed; semantic validation is
- * defined only over a well-formed descriptor.
- * @throws {CallciumError} With code `EMPTY_PATH` when a constraint carries no path step, and
- * `INVALID_HEX` or `INVALID_OPERATOR_BYTES` when an operator is not a readable encoding. Analysis
- * is defined over canonical data, so these reject the input rather than report an issue on it.
+ * @throws {CallciumError} If the descriptor is malformed; semantic validation is defined only over a well-formed one.
+ * @throws {CallciumError} With `EMPTY_PATH` or `MALFORMED_PATH` for a path that is empty or not whole steps, and
+ * `INVALID_HEX` or `INVALID_OPERATOR_BYTES` for an unreadable path or operator. Analysis is defined over canonical
+ * data, so these reject the input rather than report an issue.
  */
 function validate(data: PolicyData): Issue[] {
   const descBytes = hexToBytes(data.descriptor);

package/src/signature.ts

@@ -31,14 +31,14 @@ function isAlphanum(char: number): boolean {
 /**
  * Parse an ABI function signature into its selector and types.
  *
- * Strict mode: no whitespace, name must match `[A-Za-z_][A-Za-z0-9_]*`,
- * structure must be `name(types)` with the final `)` as the last character.
+ * Strict mode: no space, tab, LF or CR; name must match `[A-Za-z_][A-Za-z0-9_]*`; structure must be `name(types)` with
+ * the final `)` as the last character.
  *
  * @param signature - A function signature string, e.g. `"transfer(address,uint256)"`.
  * @returns The 4-byte selector and the comma-separated types string.
  * @throws {CallciumError} with code `"MALFORMED_SIGNATURE"`, `"SIGNATURE_CONTAINS_WHITESPACE"`, or
- * `"INVALID_FUNCTION_NAME"` if the signature is malformed. The types between the parentheses are
- * returned unread; whether they name types is for the type parser to say.
+ * `"INVALID_FUNCTION_NAME"` if the signature is malformed. The types between the parentheses are returned unread;
+ * whether they name types is for the type parser to say.
  */
 function parse(signature: string): ParsedSignature {
   if (signature.length < 3) {
@@ -72,8 +72,8 @@ function parse(signature: string): ParsedSignature {
     throw new CallciumError("INVALID_FUNCTION_NAME", "Function name must not be empty");
   }
 
-  // Validate function name: [A-Za-z_][A-Za-z0-9_]*. Every character outside ASCII carries a code
-  // unit above the alphanumeric ranges, so the same test rejects it.
+  // Validate function name: [A-Za-z_][A-Za-z0-9_]*. Every character outside ASCII carries a code unit above the
+  // alphanumeric ranges, so the same test rejects it.
   const firstChar = signature.charCodeAt(0);
   if (!isAlpha(firstChar) && firstChar !== 0x5f) {
     throw new CallciumError("INVALID_FUNCTION_NAME", "Function name must start with a letter or underscore");

package/src/type-desc.ts

@@ -9,10 +9,8 @@ import { CallciumError } from "./errors";
 /**
  * Extract the staticWords count from a descriptor node.
  *
- * For elementary types (typeCode < STATIC_ARRAY), returns 1 unless the type is
- * BYTES or STRING, which are ABI-dynamic and return 0. For composite types,
- * reads the 24-bit meta field at offset 1 and shifts right by
- * META_STATIC_WORDS_SHIFT.
+ * For elementary types (typeCode < STATIC_ARRAY), returns 1 unless the type is BYTES or STRING, which are ABI-dynamic
+ * and return 0. For composite types, returns the 24-bit meta at offset 1 right-shifted by META_STATIC_WORDS_SHIFT.
  */
 function extractStaticWords(desc: Uint8Array): number {
   const typeCode = desc[0]!;
@@ -99,7 +97,8 @@ export function bytesN(length: number): Uint8Array {
  *
  * @param elemDesc - Descriptor bytes for the element type.
  * @param length - Fixed array length. When omitted, produces a dynamic array.
- * @throws {CallciumError} If length is 0 or exceeds MAX_STATIC_ARRAY_LENGTH.
+ * @throws {CallciumError} If length is 0 or above MAX_STATIC_ARRAY_LENGTH.
+ * @throws {CallciumError} If the node exceeds MAX_NODE_LENGTH or MAX_STATIC_WORDS.
  */
 export function array(elemDesc: Uint8Array, length?: number): Uint8Array {
   if (length === undefined) {
@@ -156,7 +155,8 @@ export function array(elemDesc: Uint8Array, length?: number): Uint8Array {
  * Format: `[0x90][meta:3][fieldCount:be16][field0][field1]...`
  *
  * @param fieldDescs - Descriptor bytes for each field, in order.
- * @throws {CallciumError} If fieldDescs is empty, exceeds MAX_TUPLE_FIELDS, or nodeLength overflows MAX_NODE_LENGTH.
+ * @throws {CallciumError} If fieldDescs is empty or above MAX_TUPLE_FIELDS.
+ * @throws {CallciumError} If the node exceeds MAX_NODE_LENGTH or MAX_STATIC_WORDS.
  */
 export function tuple(fieldDescs: Uint8Array[]): Uint8Array {
   if (fieldDescs.length === 0 || fieldDescs.length > DF.MAX_TUPLE_FIELDS) {

package/src/types.ts

@@ -16,9 +16,8 @@ export type Span = { start: number; end: number };
 ///////////////////////////////////////////////////////////////////////////
 
 /**
- * Execution context for context-scoped rules.
- * Each property maps to a well-known EVM execution environment value.
- * Only the properties referenced by the policy need to be supplied.
+ * Execution context for context-scoped rules. Each property maps to a well-known EVM execution environment value. Only
+ * the properties referenced by the policy need to be supplied.
  */
 export type Context = {
   msgSender?: Address;
@@ -52,8 +51,8 @@ export type SelectorMismatchViolation = {
 };
 
 /**
- * A rule referenced a context property not supplied in the execution context — a context-scoped
- * subject, or an `EQ_CTX` operand on either scope.
+ * A rule referenced a context property not supplied in the execution context — a context-scoped subject, or a context
+ * reference operand on either scope.
  */
 export type MissingContextViolation = {
   code: "MISSING_CONTEXT";
@@ -76,10 +75,8 @@ export type MissingContextViolation = {
  * - `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.
+ * For length operators, `resolvedValue` is the length as a 32-byte word.
  */
 export type ValueMismatchViolation = {
   code: "VALUE_MISMATCH";
@@ -95,8 +92,8 @@ export type ValueMismatchViolation = {
   typeCode: number;
   resolvedValue?: Hex;
   /**
-   * Resolved runtime value of a reference operand as a 32-byte word; present when the
-   * operator's operand names a reference resolved at enforcement, not a literal.
+   * Resolved runtime value of a reference operand as a 32-byte word; present when the operator's operand names a
+   * reference resolved at enforcement, not a literal.
    */
   resolvedOperand?: Hex;
   elementIndex?: number;
@@ -121,8 +118,8 @@ type CalldataNavigationVariant<C extends NavigationViolationCode> = {
 /**
  * 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.
+ * The operator was never applied; `opCode`, `operandData`, `typeCode`, and `elementIndex` are diagnostic context
+ * describing the failing site, not a constraint claim.
  *
  * A union of per-code variants, narrowable with `Extract<Violation, { code: "..." }>`.
  */
@@ -173,8 +170,7 @@ export type QuantifierEmptyArrayViolation = {
 /**
  * Structured details of a single rule failure during enforcement.
  *
- * Carries semantic data only; no message strings.
- * Discriminate on `code` to narrow to the matching variant.
+ * Carries semantic data only; no message strings. Discriminate on `code` to narrow to the matching variant.
  */
 export type Violation =
   | MissingSelectorViolation
@@ -277,8 +273,7 @@ export type IssueCategory = "typeMismatch" | "contradiction" | "redundancy" | "v
 /**
  * Machine-readable code for a policy validation issue.
  *
- * Each code names one finding of the semantic validator and matches the constant of the same
- * name in the Solidity `IssueCode` library.
+ * Each code names one finding of the semantic validator, matching the same-named Solidity `IssueCode` constant.
  */
 export type IssueCode =
   // Type mismatch.