@callcium/sdk 0.10.0 → 0.11.0

package/src/policy-enforcer.ts

@@ -1,12 +1,13 @@
 import { hexToBytes, bytesToHex, readU16, readU32, bigintToHex, toAddress } from "./bytes";
-import { loadWord, readPointer } from "./calldata-reader";
-import { PolicyFormat as PF, Scope, MAX_CONTEXT_PROPERTY_ID, Op, TypeCode, lookupContextProperty } from "./constants";
+import { loadWord, readLength, readPointer } from "./calldata-reader";
+import { PolicyFormat as PF, Scope, Op, TypeCode, lookupContextProperty } from "./constants";
 import { CallciumError, PolicyViolationError } from "./errors";
-import { applyOperator, toBigInt, isLengthOp, isLengthValidType, canonicalize, classifyTypeCode } from "./operators";
+import { applyOperator, toBigInt, isLengthValidType, canonicalize } from "./operators";
 import { decodePolicy } from "./policy-coder";
 
 import type { ReadResult } from "./calldata-reader";
 import type {
+  Address,
   Context,
   DecodedRule,
   EnforceResult,
@@ -29,9 +30,19 @@ const abortViolationCodes: ReadonlySet<ViolationCode> = new Set<ViolationCode>([
   "QUANTIFIER_LIMIT_EXCEEDED",
 ]);
 
-/** Validate a hex address and read it as a 256-bit bigint. */
-function addressToBigInt(hex: string): bigint {
-  return BigInt(toAddress(hex));
+/**
+ * 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.
+ */
+function contextValueToWord(value: bigint | Address): bigint {
+  if (typeof value === "string") return BigInt(toAddress(value));
+  if (BigInt.asUintN(256, value) !== value) {
+    throw new CallciumError(
+      "CONTEXT_VALUE_OVERFLOW",
+      `Context value ${value} is outside the range a 32-byte word represents`,
+    );
+  }
+  return value;
 }
 
 ///////////////////////////////////////////////////////////////////////////
@@ -44,7 +55,8 @@ function addressToBigInt(hex: string): 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.
+ * @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.
  */
 function check(policy: Hex, callData: Hex, context?: Context): EnforceResult {
   const { policy: decoded, data: policyBytes } = decodePolicy(policy);
@@ -111,7 +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.
+ * @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.
  */
 function enforce(policy: Hex, callData: Hex, context?: Context): void {
   const result = check(policy, callData, context);
@@ -165,15 +178,24 @@ function evaluateRule(
   );
 }
 
+/** An `EQ_CTX` 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.
  */
-function resolveContextOperand(operandData: Uint8Array, context?: Context): bigint | { ctxTypeCode: number } {
+function resolveContextOperand(operandData: Uint8Array, context?: Context): ReferenceOperand {
   const propertyInfo = lookupContextProperty(Number(toBigInt(operandData, 0)));
   const value = context?.[propertyInfo.contextKey];
   if (value === undefined) return { ctxTypeCode: propertyInfo.typeCode };
-  return typeof value === "string" ? addressToBigInt(value) : value;
+  return contextValueToWord(value);
+}
+
+/** Resolve the reference operand of an `EQ_CTX` 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;
+  return resolveContextOperand(operandData, context);
 }
 
 ///////////////////////////////////////////////////////////////////////////
@@ -225,8 +247,8 @@ function chainResolve(
     const meta = readU16(hint, hop + PF.HINT_HOP_META_OFFSET);
     let elems = base;
     if ((meta & PF.HINT_META_DYNAMIC_ARRAY) !== 0) {
-      const length = readPointer(callData, elems);
-      if (typeof length !== "number") return length;
+      const length = readLength(callData, elems);
+      if (typeof length !== "bigint") return length;
       if (index >= length) return { code: "ARRAY_INDEX_OUT_OF_BOUNDS" };
       elems += 32;
     }
@@ -266,30 +288,24 @@ function evalTarget(
   block: TargetBlock,
   opCode: number,
   operandData: Uint8Array,
-  context?: Context,
+  ctxOperand?: ReferenceOperand,
 ): TargetResult {
   const typeCode = block.typeCode;
 
   // A dynamic target's chain ends at its payload, so the word there is the declared length.
   if (isLengthValidType(typeCode)) {
-    if (!isLengthOp(opCode)) {
-      throw new CallciumError("OPERATOR_TARGET_MISMATCH", "Value operator on a target without a scalar word");
-    }
-    const length = readPointer(callData, target);
-    if (typeof length !== "number") return { error: length.code };
+    const length = readLength(callData, target);
+    if (typeof length !== "bigint") return { error: length.code };
 
     // The declared payload of `length` items must lie within calldata past the length word.
     const stride = typeCode === TypeCode.DYNAMIC_ARRAY ? (block.targetMeta & PF.HINT_META_STRIDE_MASK) * 32 : 1;
     const room = callData.length - (target + 32);
-    if (stride !== 0 && length > Math.floor(room / stride)) return { error: "CALLDATA_OUT_OF_BOUNDS" };
+    if (stride !== 0 && length > BigInt(Math.floor(room / stride))) return { error: "CALLDATA_OUT_OF_BOUNDS" };
 
     const passed = applyOperator(opCode, 0n, length, operandData, typeCode);
-    return { passed, value: BigInt(length) };
+    return { passed, value: length };
   }
 
-  if (classifyTypeCode(typeCode).typeClass !== "elementary") {
-    throw new CallciumError("OPERATOR_TARGET_MISMATCH", "Operator target does not carry a scalar word");
-  }
   const word = loadWord(callData, target);
   if (!(word instanceof Uint8Array)) return { error: word.code };
 
@@ -298,14 +314,13 @@ function evalTarget(
     return { error: "NON_CANONICAL_VALUE", value };
   }
 
-  if ((opCode & ~Op.NOT) === Op.EQ_CTX) {
-    const operand = resolveContextOperand(operandData, context);
-    if (typeof operand !== "bigint") return { error: "MISSING_CONTEXT", ctxTypeCode: operand.ctxTypeCode };
-    const passed = (value === operand) !== ((opCode & Op.NOT) !== 0);
-    return { passed, value, ctxOperand: operand };
+  if (ctxOperand !== undefined) {
+    if (typeof ctxOperand !== "bigint") return { error: "MISSING_CONTEXT", ctxTypeCode: ctxOperand.ctxTypeCode };
+    const passed = (value === ctxOperand) !== ((opCode & Op.NOT) !== 0);
+    return { passed, value, ctxOperand };
   }
 
-  const passed = applyOperator(opCode, value, 32, operandData, typeCode);
+  const passed = applyOperator(opCode, value, 32n, operandData, typeCode);
   return { passed, value };
 }
 
@@ -323,17 +338,24 @@ type RuleFrame = {
   typeCode: number;
 };
 
-/** Build a navigation violation for a read the enforcer cannot perform. */
-function navigationViolation(frame: RuleFrame, code: NavigationViolationCode, elementIndex?: number): Violation {
+/** The coordinates, target and operator fields every violation of a calldata rule carries. */
+function ruleFields(frame: RuleFrame) {
   return {
     group: frame.group,
     rule: frame.rule,
-    code,
     scope: Scope.CALLDATA,
     path: frame.path,
     opCode: frame.opCode,
     operandData: bytesToHex(frame.operandData),
     typeCode: frame.typeCode,
+  };
+}
+
+/** Build a navigation violation for a read the enforcer cannot perform. */
+function navigationViolation(frame: RuleFrame, code: NavigationViolationCode, elementIndex?: number): Violation {
+  return {
+    code,
+    ...ruleFields(frame),
     ...(elementIndex !== undefined && { elementIndex }),
   };
 }
@@ -342,27 +364,17 @@ function navigationViolation(frame: RuleFrame, code: NavigationViolationCode, el
 function targetViolation(frame: RuleFrame, result: TargetResult, elementIndex?: number): Violation | null {
   if ("error" in result) {
     if (result.error === "MISSING_CONTEXT") {
+      // The type reported is the absent property's, not the target the operator reads.
       return {
-        group: frame.group,
-        rule: frame.rule,
         code: result.error,
-        scope: Scope.CALLDATA,
-        path: frame.path,
-        opCode: frame.opCode,
-        operandData: bytesToHex(frame.operandData),
+        ...ruleFields(frame),
         typeCode: result.ctxTypeCode,
       };
     }
     if (result.error === "NON_CANONICAL_VALUE") {
       return {
-        group: frame.group,
-        rule: frame.rule,
         code: result.error,
-        scope: Scope.CALLDATA,
-        path: frame.path,
-        opCode: frame.opCode,
-        operandData: bytesToHex(frame.operandData),
-        typeCode: frame.typeCode,
+        ...ruleFields(frame),
         resolvedValue: bigintToHex(result.value),
         ...(elementIndex !== undefined && { elementIndex }),
       };
@@ -372,14 +384,8 @@ function targetViolation(frame: RuleFrame, result: TargetResult, elementIndex?:
 
   if (result.passed) return null;
   return {
-    group: frame.group,
-    rule: frame.rule,
     code: "VALUE_MISMATCH",
-    scope: Scope.CALLDATA,
-    path: frame.path,
-    opCode: frame.opCode,
-    operandData: bytesToHex(frame.operandData),
-    typeCode: frame.typeCode,
+    ...ruleFields(frame),
     resolvedValue: bigintToHex(result.value),
     ...(result.ctxOperand !== undefined && { resolvedOperand: bigintToHex(result.ctxOperand) }),
     ...(elementIndex !== undefined && { elementIndex }),
@@ -435,7 +441,14 @@ function evaluateCalldataRule(
 
   return targetViolation(
     frame,
-    evalTarget(callDataBytes, base + block.targetDelta, block, opCode, operandData, context),
+    evalTarget(
+      callDataBytes,
+      base + block.targetDelta,
+      block,
+      opCode,
+      operandData,
+      referenceOperand(opCode, operandData, context),
+    ),
   );
 }
 
@@ -480,27 +493,27 @@ function evaluateQuantified(
   let elems = chained + arrayDelta;
 
   // A frame declaring no count spans a dynamic array, whose length word precedes its elements.
-  let count = readU16(hint, frameOffset + PF.HINT_FRAME_COUNT_OFFSET);
-  if (count === 0) {
-    const length = readPointer(callDataBytes, elems);
-    if (typeof length !== "number") return navigationViolation(frame, length.code);
+  let count = BigInt(readU16(hint, frameOffset + PF.HINT_FRAME_COUNT_OFFSET));
+  if (count === 0n) {
+    const length = readLength(callDataBytes, elems);
+    if (typeof length !== "bigint") return navigationViolation(frame, length.code);
     count = length;
     elems += 32;
   }
 
-  if (count > PF.MAX_QUANTIFIED_ARRAY_LENGTH) {
+  if (count > BigInt(PF.MAX_QUANTIFIED_ARRAY_LENGTH)) {
     return {
       group: groupIndex,
       rule: ruleIndex,
       code: "QUANTIFIER_LIMIT_EXCEEDED",
       scope: Scope.CALLDATA,
       path: pathHex,
-      resolvedValue: bigintToHex(BigInt(count)),
+      resolvedValue: bigintToHex(count),
     };
   }
 
   const isUniversal = kind === PF.HINT_KIND_ALL;
-  if (count === 0) {
+  if (count === 0n) {
     if (isUniversal) return null;
     return {
       group: groupIndex,
@@ -515,8 +528,9 @@ function evaluateQuantified(
   const elemStride = (meta & PF.HINT_META_STRIDE_MASK) * 32;
   const elemIsDynamic = (meta & PF.HINT_META_ELEM_DYNAMIC) !== 0;
 
-  // A reference operand resolves identically for every element; any element's result carries it.
-  let ctxOperand: bigint | undefined;
+  // A reference operand resolves identically for every element, so it resolves before iterating.
+  const reference = referenceOperand(opCode, operandData, context);
+
   for (let elemIndex = 0; elemIndex < count; elemIndex++) {
     const slot = elems + elemIndex * elemStride;
     let elem: number = slot;
@@ -535,7 +549,7 @@ function evaluateQuantified(
       base = chainedElem;
     }
 
-    const applied = evalTarget(callDataBytes, base + block.targetDelta, block, opCode, operandData, context);
+    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
@@ -549,21 +563,14 @@ function evaluateQuantified(
     } else if (isUniversal) {
       return targetViolation(frame, applied, elemIndex);
     }
-    ctxOperand = applied.ctxOperand;
   }
 
   if (isUniversal) return null;
   // Existential (ANY) failure: every element rejected the constraint.
   return {
-    group: groupIndex,
-    rule: ruleIndex,
     code: "VALUE_MISMATCH",
-    scope: Scope.CALLDATA,
-    path: pathHex,
-    opCode,
-    operandData: bytesToHex(operandData),
-    typeCode: block.typeCode,
-    ...(ctxOperand !== undefined && { resolvedOperand: bigintToHex(ctxOperand) }),
+    ...ruleFields(frame),
+    ...(typeof reference === "bigint" && { resolvedOperand: bigintToHex(reference) }),
   };
 }
 
@@ -582,34 +589,15 @@ function evaluateContextRule(
   context?: Context,
 ): Violation | null {
   const propertyId = readU16(pathBytes, 0);
-
-  if (propertyId > MAX_CONTEXT_PROPERTY_ID) {
-    throw new CallciumError(
-      "UNKNOWN_CONTEXT_PROPERTY",
-      `Unknown context property ID 0x${propertyId.toString(16).padStart(4, "0")}`,
-    );
-  }
-
   const propertyInfo = lookupContextProperty(propertyId);
   const contextValue = context?.[propertyInfo.contextKey];
+  const site = { group: groupIndex, rule: ruleIndex, scope: Scope.CONTEXT, path: pathHex };
 
   if (contextValue === undefined) {
-    return {
-      group: groupIndex,
-      rule: ruleIndex,
-      code: "MISSING_CONTEXT",
-      scope: Scope.CONTEXT,
-      path: pathHex,
-      typeCode: propertyInfo.typeCode,
-    };
+    return { code: "MISSING_CONTEXT", ...site, typeCode: propertyInfo.typeCode };
   }
 
-  let value: bigint;
-  if (typeof contextValue === "string") {
-    value = addressToBigInt(contextValue);
-  } else {
-    value = contextValue;
-  }
+  const value = contextValueToWord(contextValue);
 
   let result: boolean;
   let ctxOperand: bigint | undefined;
@@ -617,11 +605,8 @@ function evaluateContextRule(
     const operand = resolveContextOperand(operandData, context);
     if (typeof operand !== "bigint") {
       return {
-        group: groupIndex,
-        rule: ruleIndex,
         code: "MISSING_CONTEXT",
-        scope: Scope.CONTEXT,
-        path: pathHex,
+        ...site,
         opCode,
         operandData: bytesToHex(operandData),
         typeCode: operand.ctxTypeCode,
@@ -630,16 +615,13 @@ function evaluateContextRule(
     result = (value === operand) !== ((opCode & Op.NOT) !== 0);
     ctxOperand = operand;
   } else {
-    result = applyOperator(opCode, value, 32, operandData, propertyInfo.typeCode);
+    result = applyOperator(opCode, value, 32n, operandData, propertyInfo.typeCode);
   }
 
   if (!result) {
     return {
-      group: groupIndex,
-      rule: ruleIndex,
       code: "VALUE_MISMATCH",
-      scope: Scope.CONTEXT,
-      path: pathHex,
+      ...site,
       opCode,
       operandData: bytesToHex(operandData),
       typeCode: propertyInfo.typeCode,

package/src/policy-validator.ts

@@ -1,5 +1,5 @@
 import { bigintToHex, bytesToHex, hexToBytes } from "./bytes";
-import { PolicyFormat, lookupContextProperty, MAX_CONTEXT_PROPERTY_ID, Op, Scope, TypeCode } from "./constants";
+import { fieldMax, findContextProperty, MAX_CONTEXT_PROPERTY_ID, Op, PolicyFormat, Scope, TypeCode } from "./constants";
 import { Descriptor, type TypeInfo } from "./descriptor";
 import { decodeDescriptor } from "./descriptor-coder";
 import { CallciumError, type CallciumErrorCode } from "./errors";
@@ -9,8 +9,9 @@ import {
   isSigned,
   isLengthOp,
   isLengthValidType,
-  classifyTypeCode,
+  isElementary,
   isValidOperatorData,
+  toOperatorBytes,
 } from "./operators";
 import { Quantifier, isQuantifier, parsePathSteps } from "./path";
 import * as ValidationIssue from "./validation-issue";
@@ -23,7 +24,6 @@ import type { Constraint, Hex, Issue, IssueCode, PolicyData } from "./types";
 
 /** Codes a path walk raises when the path does not navigate the descriptor (PV-1). */
 const navigabilityCodes: ReadonlySet<CallciumErrorCode> = new Set<CallciumErrorCode>([
-  "EMPTY_PATH",
   "PARAM_INDEX_OUT_OF_BOUNDS",
   "TUPLE_FIELD_OUT_OF_BOUNDS",
   "STATIC_ARRAY_INDEX_OUT_OF_BOUNDS",
@@ -88,8 +88,15 @@ const INT256_SIGN_BIT = 1n << 255n;
 /** Signed-aware difference of two raw uint256 values: negative if a<b, zero if equal, positive if a>b. */
 function signedCompare(a: bigint, b: bigint, signed: boolean): bigint {
   if (!signed) return a - b;
-  const toS = (v: bigint) => (v >= INT256_SIGN_BIT ? v - (1n << 256n) : v);
-  return toS(a) - toS(b);
+  const toSigned = (word: bigint) => (word >= INT256_SIGN_BIT ? word - (1n << 256n) : word);
+  return toSigned(a) - toSigned(b);
+}
+
+/** True when a value lies outside the domain's physical bounds. */
+function isOutsideDomain(domain: BoundDomain, value: bigint): boolean {
+  return (
+    signedCompare(value, domain.min, domain.isSigned) < 0n || signedCompare(value, domain.max, domain.isSigned) > 0n
+  );
 }
 
 ///////////////////////////////////////////////////////////////////////////
@@ -162,7 +169,7 @@ function getIncompat(opBase: number, typeInfo: TypeInfo): { code: IssueCode; mes
     if (isDynamic || staticSize !== 32) {
       return { code: "VALUE_OP_ON_DYNAMIC", message: "Value operator used on dynamic type" };
     }
-    if (classifyTypeCode(typeCode).typeClass !== "elementary") {
+    if (!isElementary(typeCode)) {
       return { code: "VALUE_OP_ON_COMPOSITE", message: "Value operator used on composite type" };
     }
     if (isComparisonOp(opBase) && !isNumericType(typeCode)) {
@@ -304,7 +311,8 @@ function initContext(scope: number, path: Hex, steps: number[], typeInfo: TypeIn
     steps,
     typeInfo,
     numeric: emptyBoundDomain(isSigned(typeInfo.typeCode), min, max),
-    bitmask: { mustBeOne: 0n, mustBeZero: 0n },
+    // Bits above the target's width are zero in every canonical value.
+    bitmask: { mustBeOne: 0n, mustBeZero: isBitmaskCompatible(typeInfo.typeCode) ? UINT256_MAX ^ max : 0n },
     length: emptyBoundDomain(false, 0n, LENGTH_MAX),
     set: {
       hasIn: false,
@@ -331,6 +339,10 @@ function updateBound(
 ): void {
   if (isNegated) {
     if (base === Op.EQ) {
+      // A hole outside the type's domain excludes nothing.
+      if (isOutsideDomain(domain, value)) {
+        issues.push(ValidationIssue.outOfPhysicalBounds(isLength, groupIndex, constraintIndex, bigintToHex(value)));
+      }
       if (domain.hasEq && domain.eq === value) {
         issues.push(ValidationIssue.eqNeqContradiction(isLength, groupIndex, constraintIndex, bigintToHex(value)));
       }
@@ -358,10 +370,7 @@ function updateBound(
   }
 
   // Physical bounds and impossibility.
-  if (
-    signedCompare(value, domain.min, domain.isSigned) < 0n ||
-    signedCompare(value, domain.max, domain.isSigned) > 0n
-  ) {
+  if (isOutsideDomain(domain, value)) {
     issues.push(ValidationIssue.outOfPhysicalBounds(isLength, groupIndex, constraintIndex, bigintToHex(value)));
   } else if (base === Op.GT && value === domain.max) {
     issues.push(ValidationIssue.impossibleGt(isLength, groupIndex, constraintIndex, bigintToHex(value)));
@@ -681,6 +690,13 @@ 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.
+  for (const value of values) {
+    if (isOutsideDomain(ctx.numeric, value)) {
+      issues.push(ValidationIssue.outOfPhysicalBounds(false, groupIndex, constraintIndex, bigintToHex(value)));
+    }
+  }
+
   if (isNegated) {
     for (const value of values) {
       if (ctx.numeric.hasEq && ctx.numeric.eq === value) {
@@ -702,16 +718,6 @@ function updateSet(
     }
     checkSetEmpty(ctx, groupIndex, constraintIndex, issues);
   } else {
-    // Physical bounds: a member outside the type's domain can never be matched.
-    for (const value of values) {
-      if (
-        signedCompare(value, ctx.numeric.min, ctx.numeric.isSigned) < 0n ||
-        signedCompare(value, ctx.numeric.max, ctx.numeric.isSigned) > 0n
-      ) {
-        issues.push(ValidationIssue.outOfPhysicalBounds(false, groupIndex, constraintIndex, bigintToHex(value)));
-      }
-    }
-
     if (ctx.numeric.hasEq) {
       let found = false;
       for (const candidate of values) {
@@ -817,6 +823,11 @@ function checkFusibleRange(
   }
 }
 
+/** Check whether a payload length fits the `dataLength` field and matches the operator's arity. */
+function hasValidPayload(opBase: number, dataLength: number): boolean {
+  return dataLength <= fieldMax(PolicyFormat.RULE_DATALENGTH_SIZE) && isValidOperatorData(opBase, dataLength);
+}
+
 /** Return the operand pair when the operators contain exactly one of each unnegated bound opcode. */
 function findLonePair(operators: Hex[], lowerOp: number, upperOp: number): { low: bigint; high: bigint } | null {
   let lowerCount = 0;
@@ -827,7 +838,7 @@ function findLonePair(operators: Hex[], lowerOp: number, upperOp: number): { low
   for (const opHex of operators) {
     const opCode = parseInt(opHex.slice(2, 4), 16);
     const dataLength = (opHex.length - 4) / 2;
-    if (dataLength > 0xffff || !isValidOperatorData(opCode & ~Op.NOT, dataLength)) continue;
+    if (!hasValidPayload(opCode & ~Op.NOT, dataLength)) continue;
     if (opCode === lowerOp) {
       lowerCount++;
       low = readValue(opHex);
@@ -856,12 +867,14 @@ function validateConstraint(
   const underAny = constraint.scope === Scope.CALLDATA && ctx.steps.includes(Quantifier.ANY);
 
   for (const opHex of operators) {
-    const opCode = parseInt(opHex.slice(2, 4), 16);
+    // Every later read slices the hex, so the operator is established as bytes first.
+    const opBytes = toOperatorBytes(opHex);
+    const opCode = opBytes[0]!;
     const base = opCode & ~Op.NOT;
 
     // An unassigned opcode or mismatched payload size has no defined semantics to analyze.
-    const dataLength = (opHex.length - 4) / 2;
-    if (dataLength > 0xffff || !isValidOperatorData(base, dataLength)) {
+    const dataLength = opBytes.length - 1;
+    if (!hasValidPayload(base, dataLength)) {
       issues.push(
         ValidationIssue.fromOpRule(
           "UNKNOWN_OPERATOR",
@@ -898,7 +911,8 @@ function validateConstraint(
     if (base === Op.EQ_CTX) {
       // The operand names a context property, not a value: nothing to fold into a domain.
       const ctxOperand = readValue(opHex);
-      if (ctxOperand > BigInt(MAX_CONTEXT_PROPERTY_ID)) {
+      const property = findContextProperty(Number(ctxOperand));
+      if (!property) {
         issues.push(
           ValidationIssue.unknownContextProperty(
             groupIndex,
@@ -910,7 +924,7 @@ 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.
-        const propertyIsAddress = lookupContextProperty(Number(ctxOperand)).typeCode === TypeCode.ADDRESS;
+        const propertyIsAddress = property.typeCode === TypeCode.ADDRESS;
         const targetIsAddress = ctx.typeInfo.typeCode === TypeCode.ADDRESS;
         if (propertyIsAddress !== targetIsAddress) {
           issues.push(
@@ -1030,6 +1044,7 @@ function validateGroup(data: PolicyData, descBytes: Uint8Array, groupIndex: numb
 
     if (!ctx) {
       const steps = parsePathSteps(constraint.path);
+      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).
@@ -1072,7 +1087,8 @@ function validateGroup(data: PolicyData, descBytes: Uint8Array, groupIndex: numb
         typeInfo = walk.typeInfo;
       } else {
         const ctxId = steps[0]!;
-        if (ctxId > MAX_CONTEXT_PROPERTY_ID) {
+        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.
           issues.push(
@@ -1083,23 +1099,21 @@ function validateGroup(data: PolicyData, descBytes: Uint8Array, groupIndex: numb
               bigintToHex(BigInt(MAX_CONTEXT_PROPERTY_ID)),
             ),
           );
-          typeInfo = { typeCode: TypeCode.UINT_MAX, isDynamic: false, staticSize: 32 };
-        } else {
-          const typeCode = lookupContextProperty(ctxId).typeCode;
-          typeInfo = { typeCode, isDynamic: false, staticSize: 32 };
         }
+        typeInfo = { typeCode: property?.typeCode ?? TypeCode.UINT_MAX, isDynamic: false, staticSize: 32 };
       }
       ctx = initContext(constraint.scope, normalizedPath, steps, typeInfo);
       contexts.push(ctx);
     }
 
     // A carried hint must equal the compilation of its own path; constraints without an encoding
-    // carry none, 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.
+    // 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.
     if (
       constraint.scope === Scope.CALLDATA &&
       constraint.hint !== undefined &&
+      constraint.hint !== "0x" &&
       ctx.steps.length <= PolicyFormat.MAX_PATH_DEPTH
     ) {
       const compiled = bytesToHex(Descriptor.compileHint(descBytes, ctx.steps));
@@ -1124,6 +1138,9 @@ function validateGroup(data: PolicyData, descBytes: Uint8Array, groupIndex: numb
  * @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.
  */
 function validate(data: PolicyData): Issue[] {
   const descBytes = hexToBytes(data.descriptor);