@callcium/sdk 0.6.0 → 0.8.0

package/src/policy-validator.ts

@@ -0,0 +1,1112 @@
+import { bigintToHex, bytesToHex, hexToBytes } from "./bytes";
+import {
+  classifyTypeCode,
+  isQuantifier,
+  isValidOperatorData,
+  Limits,
+  lookupContextProperty,
+  MAX_CONTEXT_PROPERTY_ID,
+  Op,
+  Quantifier,
+  Scope,
+  TypeCode,
+} from "./constants";
+import { Descriptor, type TypeInfo } from "./descriptor";
+import { decodeDescriptor } from "./descriptor-coder";
+import { CallciumError, type CallciumErrorCode } from "./errors";
+import { canonicalize, isLeftAligned, isSigned, isLengthOp, isLengthValidType } from "./operators";
+import { parsePathSteps } from "./policy-coder";
+import * as ValidationIssue from "./validation-issue";
+
+import type { Constraint, Hex, Issue, PolicyData } from "./types";
+
+///////////////////////////////////////////////////////////////////////////
+// Internal types
+///////////////////////////////////////////////////////////////////////////
+
+/** Codes a path walk raises when the path does not navigate the descriptor (PV-1). */
+const NAVIGABILITY_CODES: ReadonlySet<CallciumErrorCode> = new Set<CallciumErrorCode>([
+  "EMPTY_PATH",
+  "PARAM_INDEX_OUT_OF_BOUNDS",
+  "TUPLE_FIELD_OUT_OF_BOUNDS",
+  "STATIC_ARRAY_INDEX_OUT_OF_BOUNDS",
+  "NOT_COMPOSITE",
+]);
+
+type BoundDomain = {
+  isSigned: boolean;
+  min: bigint;
+  max: bigint;
+  hasEq: boolean;
+  eq: bigint;
+  hasLower: boolean;
+  lower: bigint;
+  lowerInclusive: boolean;
+  hasUpper: boolean;
+  upper: bigint;
+  upperInclusive: boolean;
+  holes: bigint[];
+};
+
+type BitmaskDomain = {
+  mustBeOne: bigint;
+  mustBeZero: bigint;
+};
+
+type SetDomain = {
+  hasIn: boolean;
+  inValues: bigint[];
+  notInValues: bigint[];
+};
+
+type ConstraintContext = {
+  scope: number;
+  path: Hex;
+  /** Path steps of every constraint sharing this context. */
+  steps: number[];
+  typeInfo: TypeInfo;
+  numeric: BoundDomain;
+  bitmask: BitmaskDomain;
+  length: BoundDomain;
+  set: SetDomain;
+};
+
+///////////////////////////////////////////////////////////////////////////
+// Constants
+///////////////////////////////////////////////////////////////////////////
+
+/**
+ * Maximum length value for dynamic types.
+ */
+const LENGTH_MAX = 0xffffffffn;
+
+// Mask for reinterpreting uint256 as int256 (two's complement).
+const UINT256_MAX = (1n << 256n) - 1n;
+const INT256_SIGN_BIT = 1n << 255n;
+
+///////////////////////////////////////////////////////////////////////////
+// Signed-aware comparisons
+///////////////////////////////////////////////////////////////////////////
+
+/** 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);
+}
+
+///////////////////////////////////////////////////////////////////////////
+// Type classification
+///////////////////////////////////////////////////////////////////////////
+
+/** True for uint and int type codes. */
+function isNumericType(typeCode: number): boolean {
+  return (
+    (typeCode >= TypeCode.UINT_MIN && typeCode <= TypeCode.UINT_MAX) ||
+    (typeCode >= TypeCode.INT_MIN && typeCode <= TypeCode.INT_MAX)
+  );
+}
+
+/** True for uint and bytes32 type codes. */
+function isBitmaskCompatible(typeCode: number): boolean {
+  return (typeCode >= TypeCode.UINT_MIN && typeCode <= TypeCode.UINT_MAX) || typeCode === TypeCode.FIXED_BYTES_MIN + 31;
+}
+
+/** Physical domain limits for a type code (returned as raw uint256 bigints). */
+function getDomainLimits(typeCode: number): { min: bigint; max: bigint } {
+  if (typeCode >= TypeCode.UINT_MIN && typeCode <= TypeCode.UINT_MAX) {
+    const bits = BigInt(typeCode - TypeCode.UINT_MIN + 1) * 8n;
+    return { min: 0n, max: bits === 256n ? UINT256_MAX : (1n << bits) - 1n };
+  }
+  if (typeCode >= TypeCode.INT_MIN && typeCode <= TypeCode.INT_MAX) {
+    const bits = BigInt(typeCode - TypeCode.INT_MIN + 1) * 8n;
+    if (bits === 256n) {
+      // int256: min = uint256(type(int256).min), max = uint256(type(int256).max).
+      return { min: INT256_SIGN_BIT, max: INT256_SIGN_BIT - 1n };
+    }
+    const half = 1n << (bits - 1n);
+    // Stored as raw uint256: min is two's complement of -(2^(bits-1)).
+    const max = half - 1n;
+    const min = (UINT256_MAX - half + 1n) & UINT256_MAX;
+    return { min, max };
+  }
+  if (typeCode === TypeCode.BOOL) return { min: 0n, max: 1n };
+  if (typeCode === TypeCode.ADDRESS) return { min: 0n, max: (1n << 160n) - 1n };
+  return { min: 0n, max: UINT256_MAX };
+}
+
+///////////////////////////////////////////////////////////////////////////
+// Operator classification
+///////////////////////////////////////////////////////////////////////////
+
+/** True for EQ, GT, LT, GTE, LTE, BETWEEN, IN, BITMASK_*. */
+function isValueOp(opBase: number): boolean {
+  return opBase <= Op.BITMASK_NONE;
+}
+
+/** True for GT, LT, GTE, LTE, BETWEEN. */
+function isComparisonOp(opBase: number): boolean {
+  return opBase >= Op.GT && opBase <= Op.BETWEEN;
+}
+
+/** True for BITMASK_ALL, BITMASK_ANY, BITMASK_NONE. */
+function isBitmaskOp(opBase: number): boolean {
+  return opBase >= Op.BITMASK_ALL && opBase <= Op.BITMASK_NONE;
+}
+
+///////////////////////////////////////////////////////////////////////////
+// Type compatibility check
+///////////////////////////////////////////////////////////////////////////
+
+/** Return the incompatibility reason, or null if the operator is allowed. */
+function getIncompat(opBase: number, typeInfo: TypeInfo): { code: string; message: string } | null {
+  const { typeCode, isDynamic, staticSize } = typeInfo;
+  if (isValueOp(opBase)) {
+    if (isDynamic || staticSize !== 32) {
+      return { code: "VALUE_OP_ON_DYNAMIC", message: "Value operator used on dynamic type" };
+    }
+    if (classifyTypeCode(typeCode).typeClass !== "elementary") {
+      return { code: "VALUE_OP_ON_COMPOSITE", message: "Value operator used on composite type" };
+    }
+    if (isComparisonOp(opBase) && !isNumericType(typeCode)) {
+      return { code: "NUMERIC_OP_ON_NON_NUMERIC", message: "Comparison operator used on non-numeric type" };
+    }
+    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.
+    if (opBase === Op.IN && typeCode === TypeCode.BOOL) {
+      return { code: "IN_ON_BOOL", message: "IN operator used on boolean type" };
+    }
+    return null;
+  }
+  if (isLengthOp(opBase)) {
+    if (!isLengthValidType(typeCode)) {
+      return { code: "LENGTH_ON_STATIC", message: "Length operator used on non-dynamic type" };
+    }
+    return null;
+  }
+  return { code: "UNKNOWN_OPERATOR", message: "Unknown operator code" };
+}
+
+/**
+ * True if operator `opCode` is 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;
+}
+
+///////////////////////////////////////////////////////////////////////////
+// Payload reading
+///////////////////////////////////////////////////////////////////////////
+
+/** Read a single uint256 from operator hex (bytes after the opcode byte). */
+function readValue(opHex: Hex): bigint {
+  return BigInt(`0x${opHex.slice(4)}`);
+}
+
+/** First payload word deviating from the canonical encoding for the type, with its canonical form, or null. */
+function findNonCanonicalWord(opHex: Hex, typeCode: number): { word: bigint; canonical: bigint } | null {
+  const body = opHex.slice(4);
+  for (let i = 0; i + 64 <= body.length; i += 64) {
+    const word = BigInt(`0x${body.slice(i, i + 64)}`);
+    const canonical = canonicalize(word, typeCode);
+    if (canonical !== word) return { word, canonical };
+  }
+  return null;
+}
+
+/** Read a pair of uint256 values from a BETWEEN operator. */
+function readPair(opHex: Hex): { low: bigint; high: bigint } {
+  const body = opHex.slice(4);
+  return {
+    low: BigInt(`0x${body.slice(0, 64)}`),
+    high: BigInt(`0x${body.slice(64, 128)}`),
+  };
+}
+
+/** Unpack an IN operator's payload into an array of bigint values. */
+function unpackSet(opHex: Hex): bigint[] {
+  const body = opHex.slice(4);
+  const count = body.length / 64;
+  const values: bigint[] = [];
+  for (let i = 0; i < count; i++) {
+    values.push(BigInt(`0x${body.slice(i * 64, (i + 1) * 64)}`));
+  }
+  return values;
+}
+
+/** True if every element is strictly greater than the previous. */
+function isStrictlyAscending(values: bigint[]): boolean {
+  for (let i = 1; i < values.length; i++) {
+    if (values[i]! <= values[i - 1]!) return false;
+  }
+  return true;
+}
+
+///////////////////////////////////////////////////////////////////////////
+// Opcode normalization
+///////////////////////////////////////////////////////////////////////////
+
+/** Convert LENGTH_* opcode to its core comparison equivalent. */
+function normalizeLengthOp(base: number): number {
+  if (base === Op.LENGTH_EQ) return Op.EQ;
+  if (base === Op.LENGTH_GT) return Op.GT;
+  if (base === Op.LENGTH_LT) return Op.LT;
+  if (base === Op.LENGTH_GTE) return Op.GTE;
+  if (base === Op.LENGTH_LTE) return Op.LTE;
+  return base;
+}
+
+/** Convert a negated bound opcode to its positive equivalent. */
+function negateBoundOp(base: number): number {
+  if (base === Op.GT) return Op.LTE;
+  if (base === Op.GTE) return Op.LT;
+  if (base === Op.LT) return Op.GTE;
+  if (base === Op.LTE) return Op.GT;
+  return base;
+}
+
+///////////////////////////////////////////////////////////////////////////
+// Context initialization
+///////////////////////////////////////////////////////////////////////////
+
+/** Fresh bound domain with no constraints recorded yet. */
+function emptyBoundDomain(boundIsSigned: boolean, min: bigint, max: bigint): BoundDomain {
+  return {
+    isSigned: boundIsSigned,
+    min,
+    max,
+    hasEq: false,
+    eq: 0n,
+    hasLower: false,
+    lower: 0n,
+    lowerInclusive: false,
+    hasUpper: false,
+    upper: 0n,
+    upperInclusive: false,
+    holes: [],
+  };
+}
+
+/** Create a fresh constraint context with domain limits from the type. */
+function initContext(scope: number, path: Hex, steps: number[], typeInfo: TypeInfo): ConstraintContext {
+  const { min, max } = getDomainLimits(typeInfo.typeCode);
+  return {
+    scope,
+    path,
+    steps,
+    typeInfo,
+    numeric: emptyBoundDomain(isSigned(typeInfo.typeCode), min, max),
+    bitmask: { mustBeOne: 0n, mustBeZero: 0n },
+    length: emptyBoundDomain(false, 0n, LENGTH_MAX),
+    set: {
+      hasIn: false,
+      inValues: [],
+      notInValues: [],
+    },
+  };
+}
+
+///////////////////////////////////////////////////////////////////////////
+// Bound domain update
+///////////////////////////////////////////////////////////////////////////
+
+/** Narrow the numeric bound domain with an operator and emit issues on contradiction or redundancy. */
+function updateBound(
+  domain: BoundDomain,
+  base: number,
+  isNegated: boolean,
+  value: bigint,
+  isLength: boolean,
+  groupIndex: number,
+  constraintIndex: number,
+  issues: Issue[],
+): void {
+  if (isNegated) {
+    if (base === Op.EQ) {
+      if (domain.hasEq && domain.eq === value) {
+        issues.push(ValidationIssue.eqNeqContradiction(isLength, groupIndex, constraintIndex, bigintToHex(value)));
+      }
+      let alreadyHole = false;
+      for (let j = 0; j < domain.holes.length; j++) {
+        if (domain.holes[j] === value) {
+          alreadyHole = true;
+          break;
+        }
+      }
+      if (!alreadyHole) {
+        domain.holes.push(value);
+      }
+    } else {
+      updateBound(domain, negateBoundOp(base), false, value, isLength, groupIndex, constraintIndex, issues);
+    }
+    return;
+  }
+
+  // Vacuity checks.
+  if (base === Op.GTE && value === domain.min) {
+    issues.push(ValidationIssue.vacuousGte(isLength, groupIndex, constraintIndex, bigintToHex(value)));
+  } else if (base === Op.LTE && value === domain.max) {
+    issues.push(ValidationIssue.vacuousLte(isLength, groupIndex, constraintIndex, bigintToHex(value)));
+  }
+
+  // Physical bounds and impossibility.
+  if (
+    signedCompare(value, domain.min, domain.isSigned) < 0n ||
+    signedCompare(value, domain.max, domain.isSigned) > 0n
+  ) {
+    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)));
+  } else if (base === Op.LT && value === domain.min) {
+    issues.push(ValidationIssue.impossibleLt(isLength, groupIndex, constraintIndex, bigintToHex(value)));
+  }
+
+  let changedEq = false;
+  let changedLower = false;
+  let changedUpper = false;
+
+  // Equality handling.
+  if (base === Op.EQ) {
+    if (!domain.hasEq || domain.eq !== value) changedEq = true;
+    if (domain.hasEq) {
+      if (domain.eq !== value) {
+        issues.push(
+          ValidationIssue.conflictingEquality(
+            isLength,
+            groupIndex,
+            constraintIndex,
+            bigintToHex(domain.eq),
+            bigintToHex(value),
+          ),
+        );
+      }
+    }
+    for (let j = 0; j < domain.holes.length; j++) {
+      if (domain.holes[j] === value) {
+        issues.push(ValidationIssue.eqNeqContradiction(isLength, groupIndex, constraintIndex, bigintToHex(value)));
+      }
+    }
+    domain.hasEq = true;
+    domain.eq = value;
+  } else if (base === Op.GT || base === Op.GTE) {
+    const inclusive = base === Op.GTE;
+    if (domain.hasLower) {
+      let redundant = false;
+      let strictlyBetter = false;
+
+      if (signedCompare(value, domain.lower, domain.isSigned) < 0n) {
+        redundant = true;
+      } else if (value === domain.lower) {
+        if (domain.lowerInclusive) {
+          if (!inclusive) strictlyBetter = true;
+          else redundant = true;
+        } else {
+          if (!inclusive) redundant = true;
+        }
+      } else {
+        strictlyBetter = true;
+      }
+
+      if (redundant) {
+        issues.push(ValidationIssue.dominatedBound(isLength, groupIndex, constraintIndex, bigintToHex(value)));
+      }
+
+      if (strictlyBetter) {
+        issues.push(ValidationIssue.dominatedBound(isLength, groupIndex, constraintIndex, bigintToHex(domain.lower)));
+        domain.lower = value;
+        domain.lowerInclusive = inclusive;
+        changedLower = true;
+      }
+    } else {
+      domain.hasLower = true;
+      domain.lower = value;
+      domain.lowerInclusive = inclusive;
+      changedLower = true;
+    }
+  } else if (base === Op.LT || base === Op.LTE) {
+    const inclusive = base === Op.LTE;
+    if (domain.hasUpper) {
+      let redundant = false;
+      let strictlyBetter = false;
+
+      if (signedCompare(value, domain.upper, domain.isSigned) > 0n) {
+        redundant = true;
+      } else if (value === domain.upper) {
+        if (domain.upperInclusive) {
+          if (!inclusive) strictlyBetter = true;
+          else redundant = true;
+        } else {
+          if (!inclusive) redundant = true;
+        }
+      } else {
+        strictlyBetter = true;
+      }
+
+      if (redundant) {
+        issues.push(ValidationIssue.dominatedBound(isLength, groupIndex, constraintIndex, bigintToHex(value)));
+      }
+
+      if (strictlyBetter) {
+        issues.push(ValidationIssue.dominatedBound(isLength, groupIndex, constraintIndex, bigintToHex(domain.upper)));
+        domain.upper = value;
+        domain.upperInclusive = inclusive;
+        changedUpper = true;
+      }
+    } else {
+      domain.hasUpper = true;
+      domain.upper = value;
+      domain.upperInclusive = inclusive;
+      changedUpper = true;
+    }
+  }
+
+  // Cross-checks: equality vs lower bound.
+  if (changedEq || changedLower) {
+    if (domain.hasEq && domain.hasLower) {
+      const contradiction = domain.lowerInclusive
+        ? signedCompare(domain.eq, domain.lower, domain.isSigned) < 0n
+        : signedCompare(domain.eq, domain.lower, domain.isSigned) <= 0n;
+      if (contradiction) {
+        issues.push(
+          ValidationIssue.boundsExcludeEquality(
+            isLength,
+            groupIndex,
+            constraintIndex,
+            bigintToHex(domain.eq),
+            bigintToHex(domain.lower),
+          ),
+        );
+      } else {
+        issues.push(
+          ValidationIssue.redundantBound(
+            isLength,
+            groupIndex,
+            constraintIndex,
+            bigintToHex(domain.lower),
+            bigintToHex(domain.eq),
+          ),
+        );
+      }
+    }
+  }
+
+  // Cross-checks: equality vs upper bound.
+  if (changedEq || changedUpper) {
+    if (domain.hasEq && domain.hasUpper) {
+      const contradiction = domain.upperInclusive
+        ? signedCompare(domain.eq, domain.upper, domain.isSigned) > 0n
+        : signedCompare(domain.eq, domain.upper, domain.isSigned) >= 0n;
+      if (contradiction) {
+        issues.push(
+          ValidationIssue.boundsExcludeEquality(
+            isLength,
+            groupIndex,
+            constraintIndex,
+            bigintToHex(domain.eq),
+            bigintToHex(domain.upper),
+          ),
+        );
+      } else {
+        issues.push(
+          ValidationIssue.redundantBound(
+            isLength,
+            groupIndex,
+            constraintIndex,
+            bigintToHex(domain.upper),
+            bigintToHex(domain.eq),
+          ),
+        );
+      }
+    }
+  }
+
+  // Cross-check: lower vs upper bound.
+  if (changedLower || changedUpper) {
+    if (domain.hasLower && domain.hasUpper) {
+      const impossible =
+        signedCompare(domain.lower, domain.upper, domain.isSigned) > 0n ||
+        (domain.lower === domain.upper && (!domain.lowerInclusive || !domain.upperInclusive));
+      if (impossible) {
+        issues.push(
+          ValidationIssue.impossibleRange(
+            isLength,
+            groupIndex,
+            constraintIndex,
+            bigintToHex(domain.lower),
+            bigintToHex(domain.upper),
+          ),
+        );
+      }
+    }
+  }
+}
+
+///////////////////////////////////////////////////////////////////////////
+// Bitmask domain update
+///////////////////////////////////////////////////////////////////////////
+
+/** Update the bitmask domain and emit issues on contradiction or redundancy. */
+function updateBitmask(
+  ctx: ConstraintContext,
+  base: number,
+  isNegated: boolean,
+  mask: bigint,
+  groupIndex: number,
+  constraintIndex: number,
+  issues: Issue[],
+): void {
+  if (isNegated) return;
+
+  if (base === Op.BITMASK_ALL) {
+    if ((ctx.bitmask.mustBeZero & mask) !== 0n) {
+      issues.push(
+        ValidationIssue.bitmaskContradiction(
+          groupIndex,
+          constraintIndex,
+          bigintToHex(mask),
+          bigintToHex(ctx.bitmask.mustBeZero),
+        ),
+      );
+    }
+    if ((ctx.bitmask.mustBeOne & mask) === mask) {
+      issues.push(
+        ValidationIssue.redundantBitmask(
+          groupIndex,
+          constraintIndex,
+          bigintToHex(mask),
+          bigintToHex(ctx.bitmask.mustBeOne),
+        ),
+      );
+    }
+    ctx.bitmask.mustBeOne |= mask;
+  } else if (base === Op.BITMASK_NONE) {
+    if ((ctx.bitmask.mustBeOne & mask) !== 0n) {
+      issues.push(
+        ValidationIssue.bitmaskContradiction(
+          groupIndex,
+          constraintIndex,
+          bigintToHex(mask),
+          bigintToHex(ctx.bitmask.mustBeOne),
+        ),
+      );
+    }
+    if ((ctx.bitmask.mustBeZero & mask) === mask) {
+      issues.push(
+        ValidationIssue.redundantBitmask(
+          groupIndex,
+          constraintIndex,
+          bigintToHex(mask),
+          bigintToHex(ctx.bitmask.mustBeZero),
+        ),
+      );
+    }
+    ctx.bitmask.mustBeZero |= mask;
+  } else if (base === Op.BITMASK_ANY) {
+    if (mask !== 0n && (ctx.bitmask.mustBeZero & mask) === mask) {
+      issues.push(
+        ValidationIssue.bitmaskAnyImpossible(
+          groupIndex,
+          constraintIndex,
+          bigintToHex(mask),
+          bigintToHex(ctx.bitmask.mustBeZero),
+        ),
+      );
+    }
+    if ((ctx.bitmask.mustBeOne & mask) !== 0n) {
+      issues.push(
+        ValidationIssue.redundantBitmask(
+          groupIndex,
+          constraintIndex,
+          bigintToHex(mask),
+          bigintToHex(ctx.bitmask.mustBeOne),
+        ),
+      );
+    }
+  }
+}
+
+///////////////////////////////////////////////////////////////////////////
+// Set domain update
+///////////////////////////////////////////////////////////////////////////
+
+/** Emit an issue if the IN set has been fully excluded by NOT_IN or NEQ holes. */
+function checkSetEmpty(ctx: ConstraintContext, groupIndex: number, constraintIndex: number, issues: Issue[]): void {
+  if (!ctx.set.hasIn) return;
+
+  let possibleCount = 0;
+  const inCount = ctx.set.inValues.length;
+  for (let i = 0; i < inCount; i++) {
+    const value = ctx.set.inValues[i]!;
+    let forbidden = false;
+    for (let k = 0; k < ctx.numeric.holes.length; k++) {
+      if (ctx.numeric.holes[k] === value) {
+        forbidden = true;
+        break;
+      }
+    }
+    if (!forbidden) {
+      for (let k = 0; k < ctx.set.notInValues.length; k++) {
+        if (ctx.set.notInValues[k] === value) {
+          forbidden = true;
+          break;
+        }
+      }
+    }
+    if (!forbidden) possibleCount++;
+  }
+
+  if (possibleCount === 0) {
+    issues.push(ValidationIssue.setFullyExcluded(groupIndex, constraintIndex));
+  } else if (possibleCount < inCount) {
+    issues.push(
+      ValidationIssue.setPartiallyExcluded(groupIndex, constraintIndex, bigintToHex(BigInt(inCount - possibleCount))),
+    );
+  }
+}
+
+/** Update the set domain with IN or NOT_IN values and emit issues on contradiction or redundancy. */
+function updateSet(
+  ctx: ConstraintContext,
+  isNegated: boolean,
+  values: bigint[],
+  groupIndex: number,
+  constraintIndex: number,
+  issues: Issue[],
+): void {
+  if (isNegated) {
+    for (const value of values) {
+      if (ctx.numeric.hasEq && ctx.numeric.eq === value) {
+        issues.push(ValidationIssue.setExcludesEquality(groupIndex, constraintIndex, bigintToHex(value)));
+      }
+      if (ctx.set.hasIn) {
+        let inSet = false;
+        for (const existing of ctx.set.inValues) {
+          if (existing === value) {
+            inSet = true;
+            break;
+          }
+        }
+        if (inSet) {
+          issues.push(ValidationIssue.setReduction(groupIndex, constraintIndex, bigintToHex(value)));
+        }
+      }
+      ctx.set.notInValues.push(value);
+    }
+    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) {
+        if (candidate === ctx.numeric.eq) {
+          found = true;
+          break;
+        }
+      }
+      if (!found) {
+        issues.push(ValidationIssue.setExcludesEquality(groupIndex, constraintIndex, bigintToHex(ctx.numeric.eq)));
+      }
+    }
+
+    if (ctx.set.hasIn) {
+      const intersection: bigint[] = [];
+      for (const existing of ctx.set.inValues) {
+        for (const candidate of values) {
+          if (existing === candidate) {
+            intersection.push(existing);
+            break;
+          }
+        }
+      }
+
+      if (intersection.length === 0) {
+        issues.push(ValidationIssue.emptySetIntersection(groupIndex, constraintIndex));
+      } else if (intersection.length < values.length || intersection.length < ctx.set.inValues.length) {
+        issues.push(
+          ValidationIssue.setRedundancy(groupIndex, constraintIndex, bigintToHex(BigInt(intersection.length))),
+        );
+      }
+      ctx.set.inValues = intersection;
+    } else {
+      ctx.set.hasIn = true;
+      ctx.set.inValues = values;
+    }
+
+    checkSetEmpty(ctx, groupIndex, constraintIndex, issues);
+  }
+}
+
+///////////////////////////////////////////////////////////////////////////
+// Duplicate detection
+///////////////////////////////////////////////////////////////////////////
+
+/** Emit a warning if the constraint contains any identical operators. */
+function checkDuplicates(issues: Issue[], operators: Hex[], groupIndex: number, constraintIndex: number): void {
+  const seen = new Set<string>();
+  for (const op of operators) {
+    const key = op.toLowerCase();
+    if (seen.has(key)) {
+      issues.push(ValidationIssue.duplicateConstraint(groupIndex, constraintIndex));
+      return;
+    }
+    seen.add(key);
+  }
+}
+
+///////////////////////////////////////////////////////////////////////////
+// Fusible range detection
+///////////////////////////////////////////////////////////////////////////
+
+/**
+ * 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,
+  operators: Hex[],
+  groupIndex: number,
+  constraintIndex: number,
+  issues: Issue[],
+): void {
+  const numericPair = findLonePair(operators, Op.GTE, Op.LTE);
+  if (
+    numericPair &&
+    getIncompat(Op.GTE, ctx.typeInfo) === null &&
+    signedCompare(numericPair.low, numericPair.high, ctx.numeric.isSigned) <= 0n
+  ) {
+    issues.push(
+      ValidationIssue.fusibleRange(
+        false,
+        groupIndex,
+        constraintIndex,
+        bigintToHex(numericPair.low),
+        bigintToHex(numericPair.high),
+      ),
+    );
+  }
+
+  const lengthPair = findLonePair(operators, Op.LENGTH_GTE, Op.LENGTH_LTE);
+  if (lengthPair && getIncompat(Op.LENGTH_GTE, ctx.typeInfo) === null && lengthPair.low <= lengthPair.high) {
+    issues.push(
+      ValidationIssue.fusibleRange(
+        true,
+        groupIndex,
+        constraintIndex,
+        bigintToHex(lengthPair.low),
+        bigintToHex(lengthPair.high),
+      ),
+    );
+  }
+}
+
+/** 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;
+  let upperCount = 0;
+  let low = 0n;
+  let high = 0n;
+
+  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 (opCode === lowerOp) {
+      lowerCount++;
+      low = readValue(opHex);
+    } else if (opCode === upperOp) {
+      upperCount++;
+      high = readValue(opHex);
+    }
+  }
+
+  return lowerCount === 1 && upperCount === 1 ? { low, high } : null;
+}
+
+///////////////////////////////////////////////////////////////////////////
+// Constraint validation
+///////////////////////////////////////////////////////////////////////////
+
+/** Validate all operators on a single constraint against its domain context. */
+function validateConstraint(
+  ctx: ConstraintContext,
+  constraint: Constraint,
+  groupIndex: number,
+  constraintIndex: number,
+  issues: Issue[],
+): void {
+  const operators = constraint.operators;
+  const underAny = constraint.scope === Scope.CALLDATA && ctx.steps.includes(Quantifier.ANY);
+
+  for (const opHex of operators) {
+    const opCode = parseInt(opHex.slice(2, 4), 16);
+    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)) {
+      issues.push(
+        ValidationIssue.fromOpRule(
+          "UNKNOWN_OPERATOR",
+          "Unknown operator code",
+          groupIndex,
+          constraintIndex,
+          bigintToHex(BigInt(opCode)),
+        ),
+      );
+      continue;
+    }
+
+    const isNegated = (opCode & Op.NOT) !== 0;
+
+    // A negated operator under any() is satisfied by a single decoy element.
+    if (underAny && isNegated) {
+      issues.push(ValidationIssue.negationUnderAny(groupIndex, constraintIndex, bigintToHex(BigInt(opCode))));
+    }
+
+    const incompat = getIncompat(base, ctx.typeInfo);
+    if (incompat) {
+      issues.push(
+        ValidationIssue.fromOpRule(
+          incompat.code,
+          incompat.message,
+          groupIndex,
+          constraintIndex,
+          bigintToHex(BigInt(opCode)),
+        ),
+      );
+      continue;
+    }
+
+    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.
+      const typeCode = ctx.typeInfo.typeCode;
+      if (isLeftAligned(typeCode)) {
+        const nonCanonical = findNonCanonicalWord(opHex, typeCode);
+        if (nonCanonical !== null) {
+          issues.push(
+            ValidationIssue.nonCanonicalOperand(
+              groupIndex,
+              constraintIndex,
+              bigintToHex(nonCanonical.word),
+              bigintToHex(nonCanonical.canonical),
+            ),
+          );
+          continue;
+        }
+      }
+
+      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.
+          const { low, high } = readPair(opHex);
+          if (!isNegated) {
+            updateBound(ctx.numeric, Op.GTE, false, low, false, groupIndex, constraintIndex, issues);
+            updateBound(ctx.numeric, Op.LTE, false, high, false, groupIndex, constraintIndex, issues);
+          } else if (signedCompare(low, high, ctx.numeric.isSigned) > 0n) {
+            issues.push(
+              ValidationIssue.vacuousNegatedRange(
+                false,
+                groupIndex,
+                constraintIndex,
+                bigintToHex(low),
+                bigintToHex(high),
+              ),
+            );
+          }
+        } else {
+          const value = readValue(opHex);
+          const holesBefore = ctx.numeric.holes.length;
+          updateBound(ctx.numeric, base, isNegated, value, false, groupIndex, constraintIndex, issues);
+          if (ctx.numeric.holes.length > holesBefore) {
+            checkSetEmpty(ctx, groupIndex, constraintIndex, issues);
+          }
+        }
+      } else if (isBitmaskOp(base)) {
+        const mask = readValue(opHex);
+        updateBitmask(ctx, base, isNegated, mask, groupIndex, constraintIndex, issues);
+      } else if (base === Op.IN) {
+        const values = unpackSet(opHex);
+        if (!isStrictlyAscending(values)) {
+          issues.push(ValidationIssue.unsortedInSet(groupIndex, constraintIndex));
+        } else {
+          updateSet(ctx, isNegated, values, groupIndex, constraintIndex, issues);
+        }
+      }
+    } else if (isLengthOp(base)) {
+      if (base === Op.LENGTH_BETWEEN) {
+        // Same disjunction reasoning as the negated value-range above.
+        const { low, high } = readPair(opHex);
+        if (!isNegated) {
+          updateBound(ctx.length, Op.GTE, false, low, true, groupIndex, constraintIndex, issues);
+          updateBound(ctx.length, Op.LTE, false, high, true, groupIndex, constraintIndex, issues);
+        } else if (low > high) {
+          issues.push(
+            ValidationIssue.vacuousNegatedRange(true, groupIndex, constraintIndex, bigintToHex(low), bigintToHex(high)),
+          );
+        }
+      } else {
+        const value = readValue(opHex);
+        updateBound(ctx.length, normalizeLengthOp(base), isNegated, value, true, groupIndex, constraintIndex, issues);
+      }
+    }
+  }
+
+  checkDuplicates(issues, operators, groupIndex, constraintIndex);
+}
+
+///////////////////////////////////////////////////////////////////////////
+// Group validation
+///////////////////////////////////////////////////////////////////////////
+
+/** Validate all constraints in a group, building per-path contexts for cross-constraint analysis. */
+function validateGroup(data: PolicyData, descBytes: Uint8Array, groupIndex: number, issues: Issue[]): void {
+  const constraints = data.groups[groupIndex]!;
+  const contexts: ConstraintContext[] = [];
+
+  for (let constraintIndex = 0; constraintIndex < constraints.length; constraintIndex++) {
+    const constraint = constraints[constraintIndex]!;
+    const normalizedPath: Hex = `0x${constraint.path.slice(2).toLowerCase()}`;
+
+    // Find existing context for this (scope, path) pair.
+    let ctx: ConstraintContext | undefined;
+    for (const existing of contexts) {
+      if (existing.scope === constraint.scope && existing.path === normalizedPath) {
+        ctx = existing;
+        break;
+      }
+    }
+
+    if (!ctx) {
+      const steps = parsePathSteps(constraint.path);
+      let typeInfo: TypeInfo;
+      if (constraint.scope === Scope.CALLDATA) {
+        // Compatibility warnings against the limits the spec fixes (PWF-17, PV-7).
+        if (steps.length > Limits.MAX_PATH_DEPTH) {
+          issues.push(
+            ValidationIssue.pathDepthExceeded(
+              groupIndex,
+              constraintIndex,
+              bigintToHex(BigInt(steps.length)),
+              bigintToHex(BigInt(Limits.MAX_PATH_DEPTH)),
+            ),
+          );
+        }
+        let walk: ReturnType<typeof Descriptor.walkPath>;
+        try {
+          walk = Descriptor.walkPath(descBytes, steps);
+        } catch (error) {
+          // Navigability faults become issues; anything else propagates.
+          if (error instanceof CallciumError && NAVIGABILITY_CODES.has(error.code)) {
+            issues.push(ValidationIssue.unnavigablePath(groupIndex, constraintIndex));
+            continue;
+          }
+          throw error;
+        }
+        // One array at a time carries a quantifier, so the element chain stays singular.
+        if (steps.filter(isQuantifier).length > 1) {
+          issues.push(ValidationIssue.nestedQuantifier(groupIndex, constraintIndex));
+          continue;
+        }
+        if (walk.quantifiedStaticLength > Limits.MAX_QUANTIFIED_ARRAY_LENGTH) {
+          issues.push(
+            ValidationIssue.quantifierOverStaticLimit(
+              groupIndex,
+              constraintIndex,
+              bigintToHex(BigInt(walk.quantifiedStaticLength)),
+              bigintToHex(BigInt(Limits.MAX_QUANTIFIED_ARRAY_LENGTH)),
+            ),
+          );
+        }
+        typeInfo = walk.typeInfo;
+      } else {
+        const ctxId = steps[0]!;
+        if (ctxId > MAX_CONTEXT_PROPERTY_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,
+              constraintIndex,
+              bigintToHex(BigInt(ctxId)),
+              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 };
+        }
+      }
+      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.
+    if (
+      constraint.scope === Scope.CALLDATA &&
+      constraint.hint !== undefined &&
+      ctx.steps.length <= Limits.MAX_PATH_DEPTH
+    ) {
+      const compiled = bytesToHex(Descriptor.compileHint(descBytes, ctx.steps));
+      if (compiled !== constraint.hint.toLowerCase()) {
+        issues.push(ValidationIssue.hintMismatch(groupIndex, constraintIndex));
+      }
+    }
+
+    validateConstraint(ctx, constraint, groupIndex, constraintIndex, issues);
+
+    checkFusibleRange(ctx, constraint.operators, groupIndex, constraintIndex, issues);
+  }
+}
+
+///////////////////////////////////////////////////////////////////////////
+// Public API
+///////////////////////////////////////////////////////////////////////////
+
+/**
+ * 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.
+ */
+function validate(data: PolicyData): Issue[] {
+  const descBytes = hexToBytes(data.descriptor);
+  decodeDescriptor(descBytes);
+
+  const issues: Issue[] = [];
+  for (let groupIndex = 0; groupIndex < data.groups.length; groupIndex++) {
+    if (data.groups[groupIndex]!.length === 0) {
+      issues.push(ValidationIssue.emptyGroup(groupIndex));
+      continue;
+    }
+    validateGroup(data, descBytes, groupIndex, issues);
+  }
+
+  return issues;
+}
+
+/** Semantic validation for policies. */
+export const PolicyValidator = { validate };