@callcium/sdk 0.9.0 → 0.11.0

package/src/policy-validator.ts

@@ -1,32 +1,29 @@
 import { bigintToHex, bytesToHex, hexToBytes } from "./bytes";
-import {
-  classifyTypeCode,
-  isQuantifier,
-  isValidOperatorData,
-  Limits,
-  lookupContextProperty,
-  MAX_CONTEXT_PROPERTY_ID,
-  Op,
-  Quantifier,
-  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";
-import { canonicalize, isLeftAligned, isSigned, isLengthOp, isLengthValidType } from "./operators";
-import { parsePathSteps } from "./policy-coder";
+import {
+  canonicalize,
+  isLeftAligned,
+  isSigned,
+  isLengthOp,
+  isLengthValidType,
+  isElementary,
+  isValidOperatorData,
+  toOperatorBytes,
+} from "./operators";
+import { Quantifier, isQuantifier, parsePathSteps } from "./path";
 import * as ValidationIssue from "./validation-issue";
 
-import type { Constraint, Hex, Issue, PolicyData } from "./types";
+import type { Constraint, Hex, Issue, IssueCode, 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",
+const navigabilityCodes: ReadonlySet<CallciumErrorCode> = new Set<CallciumErrorCode>([
   "PARAM_INDEX_OUT_OF_BOUNDS",
   "TUPLE_FIELD_OUT_OF_BOUNDS",
   "STATIC_ARRAY_INDEX_OUT_OF_BOUNDS",
@@ -91,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
+  );
 }
 
 ///////////////////////////////////////////////////////////////////////////
@@ -159,13 +163,13 @@ function isBitmaskOp(opBase: number): boolean {
 ///////////////////////////////////////////////////////////////////////////
 
 /** Return the incompatibility reason, or null if the operator is allowed. */
-function getIncompat(opBase: number, typeInfo: TypeInfo): { code: string; message: string } | null {
+function getIncompat(opBase: number, typeInfo: TypeInfo): { code: IssueCode; 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") {
+    if (!isElementary(typeCode)) {
       return { code: "VALUE_OP_ON_COMPOSITE", message: "Value operator used on composite type" };
     }
     if (isComparisonOp(opBase) && !isNumericType(typeCode)) {
@@ -307,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,
@@ -334,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)));
       }
@@ -361,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)));
@@ -684,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) {
@@ -705,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) {
@@ -820,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;
@@ -830,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);
@@ -859,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",
@@ -901,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,
@@ -913,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(
@@ -1033,16 +1044,17 @@ 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).
-        if (steps.length > Limits.MAX_PATH_DEPTH) {
+        if (steps.length > PolicyFormat.MAX_PATH_DEPTH) {
           issues.push(
             ValidationIssue.pathDepthExceeded(
               groupIndex,
               constraintIndex,
               bigintToHex(BigInt(steps.length)),
-              bigintToHex(BigInt(Limits.MAX_PATH_DEPTH)),
+              bigintToHex(BigInt(PolicyFormat.MAX_PATH_DEPTH)),
             ),
           );
         }
@@ -1051,7 +1063,7 @@ function validateGroup(data: PolicyData, descBytes: Uint8Array, groupIndex: numb
           walk = Descriptor.walkPath(descBytes, steps);
         } catch (error) {
           // Navigability faults become issues; anything else propagates.
-          if (error instanceof CallciumError && NAVIGABILITY_CODES.has(error.code)) {
+          if (error instanceof CallciumError && navigabilityCodes.has(error.code)) {
             issues.push(ValidationIssue.unnavigablePath(groupIndex, constraintIndex));
             continue;
           }
@@ -1062,20 +1074,21 @@ function validateGroup(data: PolicyData, descBytes: Uint8Array, groupIndex: numb
           issues.push(ValidationIssue.nestedQuantifier(groupIndex, constraintIndex));
           continue;
         }
-        if (walk.quantifiedStaticLength > Limits.MAX_QUANTIFIED_ARRAY_LENGTH) {
+        if (walk.quantifiedStaticLength > PolicyFormat.MAX_QUANTIFIED_ARRAY_LENGTH) {
           issues.push(
             ValidationIssue.quantifierOverStaticLimit(
               groupIndex,
               constraintIndex,
               bigintToHex(BigInt(walk.quantifiedStaticLength)),
-              bigintToHex(BigInt(Limits.MAX_QUANTIFIED_ARRAY_LENGTH)),
+              bigintToHex(BigInt(PolicyFormat.MAX_QUANTIFIED_ARRAY_LENGTH)),
             ),
           );
         }
         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(
@@ -1086,24 +1099,22 @@ 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 &&
-      ctx.steps.length <= Limits.MAX_PATH_DEPTH
+      constraint.hint !== "0x" &&
+      ctx.steps.length <= PolicyFormat.MAX_PATH_DEPTH
     ) {
       const compiled = bytesToHex(Descriptor.compileHint(descBytes, ctx.steps));
       if (compiled !== constraint.hint.toLowerCase()) {
@@ -1127,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);

package/src/signature.ts

@@ -1,4 +1,5 @@
 import { keccak_256 } from "@noble/hashes/sha3.js";
+import { utf8ToBytes } from "@noble/hashes/utils.js";
 
 import { bytesToHex } from "./bytes";
 import { CallciumError } from "./errors";
@@ -18,13 +19,13 @@ export type ParsedSignature = {
 };
 
 /** Return true if the char code is an ASCII letter. */
-function isAlpha(c: number): boolean {
-  return (c >= 0x41 && c <= 0x5a) || (c >= 0x61 && c <= 0x7a);
+function isAlpha(char: number): boolean {
+  return (char >= 0x41 && char <= 0x5a) || (char >= 0x61 && char <= 0x7a);
 }
 
 /** Return true if the char code is an ASCII alphanumeric character. */
-function isAlphanum(c: number): boolean {
-  return isAlpha(c) || (c >= 0x30 && c <= 0x39);
+function isAlphanum(char: number): boolean {
+  return isAlpha(char) || (char >= 0x30 && char <= 0x39);
 }
 
 /**
@@ -36,29 +37,27 @@ function isAlphanum(c: number): boolean {
  * @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.
+ * `"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) {
     throw new CallciumError("MALFORMED_SIGNATURE", `Invalid signature: too short, got "${signature}"`);
   }
 
-  // Scan for whitespace, non-ASCII, and the opening parenthesis in one pass.
+  // Scan for whitespace and the opening parenthesis in one pass.
   let openParen = -1;
   for (let i = 0; i < signature.length; i++) {
-    const c = signature.charCodeAt(i);
-    if (c === 0x20 || c === 0x09 || c === 0x0a || c === 0x0d) {
+    const char = signature.charCodeAt(i);
+    if (char === 0x20 || char === 0x09 || char === 0x0a || char === 0x0d) {
       throw new CallciumError("SIGNATURE_CONTAINS_WHITESPACE", "Signature must not contain whitespace");
     }
-    if (c > 0x7e) {
-      throw new CallciumError("MALFORMED_SIGNATURE", "Signature must contain only ASCII characters");
-    }
-    if (openParen === -1 && c === 0x28) {
+    if (openParen === -1 && char === 0x28) {
       openParen = i;
     }
   }
 
-  if (openParen < 1) {
+  if (openParen === -1) {
     throw new CallciumError(
       "MALFORMED_SIGNATURE",
       `Invalid signature: must have a function name followed by parentheses, got "${signature}"`,
@@ -69,14 +68,19 @@ function parse(signature: string): ParsedSignature {
     throw new CallciumError("MALFORMED_SIGNATURE", `Invalid signature: must end with ")", got "${signature}"`);
   }
 
-  // Validate function name: [A-Za-z_][A-Za-z0-9_]*.
+  if (openParen === 0) {
+    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.
   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");
   }
   for (let i = 1; i < openParen; i++) {
-    const c = signature.charCodeAt(i);
-    if (!isAlphanum(c) && c !== 0x5f) {
+    const char = signature.charCodeAt(i);
+    if (!isAlphanum(char) && char !== 0x5f) {
       throw new CallciumError(
         "INVALID_FUNCTION_NAME",
         "Function name must contain only alphanumeric characters or underscores",
@@ -84,9 +88,7 @@ function parse(signature: string): ParsedSignature {
     }
   }
 
-  const encoded = new Uint8Array(signature.length);
-  for (let i = 0; i < signature.length; i++) encoded[i] = signature.charCodeAt(i);
-  const hash = keccak_256(encoded);
+  const hash = keccak_256(utf8ToBytes(signature));
 
   const selector = bytesToHex(hash.subarray(0, 4));
   const types = signature.slice(openParen + 1, signature.length - 1);

package/src/type-desc.ts

@@ -48,7 +48,7 @@ export function function_(): Uint8Array {
  */
 export function uintN(bits: number): Uint8Array {
   if (bits < 8 || bits > 256 || bits % 8 !== 0) {
-    throw new CallciumError("UNKNOWN_TYPE", `Invalid uintN bits: ${bits}. Must be 8–256 in steps of 8.`);
+    throw new CallciumError("UNKNOWN_TYPE", `Invalid uintN bits: ${bits}. Must be 8–256 in steps of 8`);
   }
   return new Uint8Array([TypeCode.UINT_MIN + (bits / 8 - 1)]);
 }
@@ -60,7 +60,7 @@ export function uintN(bits: number): Uint8Array {
  */
 export function intN(bits: number): Uint8Array {
   if (bits < 8 || bits > 256 || bits % 8 !== 0) {
-    throw new CallciumError("UNKNOWN_TYPE", `Invalid intN bits: ${bits}. Must be 8–256 in steps of 8.`);
+    throw new CallciumError("UNKNOWN_TYPE", `Invalid intN bits: ${bits}. Must be 8–256 in steps of 8`);
   }
   return new Uint8Array([TypeCode.INT_MIN + (bits / 8 - 1)]);
 }
@@ -77,14 +77,14 @@ export function string_(): Uint8Array {
 
 /**
  * Build a descriptor node for `bytesN`.
- * @param n - Byte width, 1–32.
- * @throws {CallciumError} With code `UNKNOWN_TYPE` if n is out of range.
+ * @param length - Byte width, 1–32.
+ * @throws {CallciumError} With code `UNKNOWN_TYPE` if length is out of range.
  */
-export function bytesN(n: number): Uint8Array {
-  if (n < 1 || n > 32) {
-    throw new CallciumError("UNKNOWN_TYPE", `Invalid bytesN size: ${n}. Must be 1–32.`);
+export function bytesN(length: number): Uint8Array {
+  if (length < 1 || length > 32) {
+    throw new CallciumError("UNKNOWN_TYPE", `Invalid bytesN size: ${length}. Must be 1–32`);
   }
-  return new Uint8Array([TypeCode.FIXED_BYTES_MIN + (n - 1)]);
+  return new Uint8Array([TypeCode.FIXED_BYTES_MIN + (length - 1)]);
 }
 
 ///////////////////////////////////////////////////////////////////////////
@@ -108,7 +108,7 @@ export function array(elemDesc: Uint8Array, length?: number): Uint8Array {
     if (nodeLength > DF.MAX_NODE_LENGTH) {
       throw new CallciumError(
         "NODE_LENGTH_TOO_LARGE",
-        `Dynamic array node length ${nodeLength} exceeds maximum ${DF.MAX_NODE_LENGTH}.`,
+        `Dynamic array node length ${nodeLength} exceeds maximum ${DF.MAX_NODE_LENGTH}`,
       );
     }
     const meta24 = (0 << DF.META_STATIC_WORDS_SHIFT) | nodeLength;
@@ -123,14 +123,14 @@ export function array(elemDesc: Uint8Array, length?: number): Uint8Array {
   if (length <= 0 || length > DF.MAX_STATIC_ARRAY_LENGTH) {
     throw new CallciumError(
       "INVALID_ARRAY_LENGTH",
-      `Static array length ${length} out of range. Must be 1–${DF.MAX_STATIC_ARRAY_LENGTH}.`,
+      `Static array length ${length} out of range. Must be 1–${DF.MAX_STATIC_ARRAY_LENGTH}`,
     );
   }
   const nodeLength = DF.ARRAY_HEADER_SIZE + elemDesc.length + DF.ARRAY_LENGTH_SIZE;
   if (nodeLength > DF.MAX_NODE_LENGTH) {
     throw new CallciumError(
       "NODE_LENGTH_TOO_LARGE",
-      `Static array node length ${nodeLength} exceeds maximum ${DF.MAX_NODE_LENGTH}.`,
+      `Static array node length ${nodeLength} exceeds maximum ${DF.MAX_NODE_LENGTH}`,
     );
   }
   const elemStaticWords = extractStaticWords(elemDesc);
@@ -138,7 +138,7 @@ export function array(elemDesc: Uint8Array, length?: number): Uint8Array {
   if (staticWords > DF.MAX_STATIC_WORDS) {
     throw new CallciumError(
       "STATIC_WORDS_TOO_LARGE",
-      `Static array static words ${staticWords} exceeds maximum ${DF.MAX_STATIC_WORDS}.`,
+      `Static array static words ${staticWords} exceeds maximum ${DF.MAX_STATIC_WORDS}`,
     );
   }
   const meta24 = (staticWords << DF.META_STATIC_WORDS_SHIFT) | nodeLength;
@@ -162,7 +162,7 @@ export function tuple(fieldDescs: Uint8Array[]): Uint8Array {
   if (fieldDescs.length === 0 || fieldDescs.length > DF.MAX_TUPLE_FIELDS) {
     throw new CallciumError(
       "INVALID_TUPLE_FIELD_COUNT",
-      `Tuple field count ${fieldDescs.length} out of range. Must be 1–${DF.MAX_TUPLE_FIELDS}.`,
+      `Tuple field count ${fieldDescs.length} out of range. Must be 1–${DF.MAX_TUPLE_FIELDS}`,
     );
   }
   const totalFieldBytes = fieldDescs.reduce((sum, f) => sum + f.length, 0);
@@ -170,7 +170,7 @@ export function tuple(fieldDescs: Uint8Array[]): Uint8Array {
   if (nodeLength > DF.MAX_NODE_LENGTH) {
     throw new CallciumError(
       "NODE_LENGTH_TOO_LARGE",
-      `Tuple node length ${nodeLength} exceeds maximum ${DF.MAX_NODE_LENGTH}.`,
+      `Tuple node length ${nodeLength} exceeds maximum ${DF.MAX_NODE_LENGTH}`,
     );
   }
 
@@ -187,7 +187,7 @@ export function tuple(fieldDescs: Uint8Array[]): Uint8Array {
   if (staticWords > DF.MAX_STATIC_WORDS) {
     throw new CallciumError(
       "STATIC_WORDS_TOO_LARGE",
-      `Tuple static words ${staticWords} exceeds maximum ${DF.MAX_STATIC_WORDS}.`,
+      `Tuple static words ${staticWords} exceeds maximum ${DF.MAX_STATIC_WORDS}`,
     );
   }
   const meta24 = (staticWords << DF.META_STATIC_WORDS_SHIFT) | nodeLength;

package/src/types.ts

@@ -130,7 +130,7 @@ export type CalldataNavigationViolation =
   | CalldataNavigationVariant<"CALLDATA_OUT_OF_BOUNDS">
   | CalldataNavigationVariant<"ARRAY_INDEX_OUT_OF_BOUNDS">;
 
-/** A quantified array exceeded `Limits.MAX_QUANTIFIED_ARRAY_LENGTH`. */
+/** A quantified array exceeded `PolicyFormat.MAX_QUANTIFIED_ARRAY_LENGTH`. */
 export type QuantifierLimitExceededViolation = {
   code: "QUANTIFIER_LIMIT_EXCEEDED";
   group: number;
@@ -142,7 +142,7 @@ export type QuantifierLimitExceededViolation = {
 };
 
 /**
- * A resolved word is not the canonical encoding of its declared type (spec §7.4).
+ * A resolved word is not the canonical encoding of its declared type.
  *
  * `resolvedValue` is the raw 32-byte word as it appeared in calldata, before any masking.
  */
@@ -274,13 +274,80 @@ export type IssueSeverity = "info" | "warning" | "error";
 /** Category of a validation issue. */
 export type IssueCategory = "typeMismatch" | "contradiction" | "redundancy" | "vacuity" | "compatibility";
 
+/**
+ * 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.
+ */
+export type IssueCode =
+  // Type mismatch.
+  | "VALUE_OP_ON_DYNAMIC"
+  | "VALUE_OP_ON_COMPOSITE"
+  | "NUMERIC_OP_ON_NON_NUMERIC"
+  | "BITMASK_ON_INVALID"
+  | "IN_ON_BOOL"
+  | "LENGTH_ON_STATIC"
+  | "CONTEXT_TYPE_MISMATCH"
+  | "UNKNOWN_OPERATOR"
+  | "NON_CANONICAL_OPERAND"
+  | "UNNAVIGABLE_PATH"
+  | "NESTED_QUANTIFIER"
+  | "HINT_MISMATCH"
+  // Contradiction.
+  | "EQ_NEQ_CONTRADICTION"
+  | "CONFLICTING_EQUALITY"
+  | "OUT_OF_PHYSICAL_BOUNDS"
+  | "IMPOSSIBLE_GT"
+  | "IMPOSSIBLE_LT"
+  | "BOUNDS_EXCLUDE_EQUALITY"
+  | "IMPOSSIBLE_RANGE"
+  | "SET_EXCLUDES_EQUALITY"
+  | "EMPTY_SET_INTERSECTION"
+  | "SET_FULLY_EXCLUDED"
+  | "LENGTH_EQ_NEQ_CONTRADICTION"
+  | "CONFLICTING_LENGTH"
+  | "BOUNDS_EXCLUDE_LENGTH"
+  | "IMPOSSIBLE_LENGTH_RANGE"
+  | "OUT_OF_PHYSICAL_LENGTH_BOUNDS"
+  | "IMPOSSIBLE_LENGTH_GT"
+  | "IMPOSSIBLE_LENGTH_LT"
+  | "BITMASK_CONTRADICTION"
+  | "BITMASK_ANY_IMPOSSIBLE"
+  | "UNSORTED_IN_SET"
+  | "EMPTY_GROUP"
+  // Redundancy.
+  | "DOMINATED_BOUND"
+  | "REDUNDANT_BOUND"
+  | "SET_REDUCTION"
+  | "SET_REDUNDANCY"
+  | "SET_PARTIALLY_EXCLUDED"
+  | "DOMINATED_LENGTH_BOUND"
+  | "REDUNDANT_LENGTH_BOUND"
+  | "REDUNDANT_BITMASK"
+  | "DUPLICATE_CONSTRAINT"
+  | "FUSIBLE_RANGE"
+  | "FUSIBLE_LENGTH_RANGE"
+  // Vacuity.
+  | "VACUOUS_GTE"
+  | "VACUOUS_LTE"
+  | "VACUOUS_LENGTH_GTE"
+  | "VACUOUS_LENGTH_LTE"
+  | "VACUOUS_NEGATED_RANGE"
+  | "VACUOUS_NEGATED_LENGTH_RANGE"
+  // Compatibility.
+  | "PATH_DEPTH_EXCEEDED"
+  | "QUANTIFIER_OVER_STATIC_LIMIT"
+  | "UNKNOWN_CONTEXT_PROPERTY"
+  | "NEGATION_UNDER_ANY";
+
 /** A single validation issue found during policy analysis. */
 export type Issue = {
   severity: IssueSeverity;
   category: IssueCategory;
   groupIndex: number;
   constraintIndex: number;
-  code: string;
+  code: IssueCode;
   value1: Hex;
   value2: Hex;
   message: string;

package/src/validation-issue.ts

@@ -1,4 +1,4 @@
-import type { Hex, Issue } from "./types";
+import type { Hex, Issue, IssueCode } from "./types";
 
 ///////////////////////////////////////////////////////////////////////////
 // Constants
@@ -12,7 +12,7 @@ const ZERO: Hex = `0x${"0".repeat(64)}`;
 
 /** Create an issue from operator compatibility results. */
 export function fromOpRule(
-  code: string,
+  code: IssueCode,
   message: string,
   groupIndex: number,
   constraintIndex: number,
@@ -304,7 +304,7 @@ export function unsortedInSet(groupIndex: number, constraintIndex: number): Issu
     code: "UNSORTED_IN_SET",
     value1: ZERO,
     value2: ZERO,
-    message: "isIn/notIn set is not strictly sorted and deduplicated.",
+    message: "isIn/notIn set is not strictly sorted and deduplicated",
   };
 }
 
@@ -318,7 +318,7 @@ export function emptyGroup(groupIndex: number): Issue {
     code: "EMPTY_GROUP",
     value1: ZERO,
     value2: ZERO,
-    message: "Group contains zero constraints.",
+    message: "Group contains zero constraints",
   };
 }