@callcium/sdk 0.9.0 → 0.11.0

package/src/policy-builder.ts

@@ -1,10 +1,12 @@
 import { bytesToHex } from "./bytes";
-import { Scope, TypeCode, isQuantifier, MAX_CONTEXT_PROPERTY_ID } from "./constants";
-import { ConstraintBuilder } from "./constraint";
+import { Scope, TypeCode, lookupContextProperty } from "./constants";
+import { readOperandExtremes } from "./constraint";
 import { Descriptor } from "./descriptor";
 import { DescriptorCoder } from "./descriptor-coder";
 import { CallciumError, ValidationError } from "./errors";
-import { PolicyCoder, parsePathSteps } from "./policy-coder";
+import { isSigned } from "./operators";
+import { isQuantifier, parsePathSteps } from "./path";
+import { PolicyCoder } from "./policy-coder";
 import { PolicyValidator } from "./policy-validator";
 import { SignatureParser } from "./signature";
 
@@ -19,35 +21,30 @@ type PolicyDraft = {
   selector: Hex;
   descriptor: Uint8Array;
   groups: Constraint[][];
-  pathHashes: Set<string>[];
+  /** Scope-qualified paths already taken in the group being built. */
+  groupPathKeys: Set<string>;
 };
 
 ///////////////////////////////////////////////////////////////////////////
 // Path validation
 ///////////////////////////////////////////////////////////////////////////
 
-/** Validate a context-scope path. */
-function validateContextPath(steps: number[]): void {
+/** Validate a context-scope path and return the referenced property's type code. */
+function validateContextPath(steps: number[]): number {
   if (steps.length !== 1) {
-    throw new CallciumError("INVALID_CONTEXT_PATH", "Context-scope path must be exactly one step.");
-  }
-  const step = steps[0]!;
-  if (step > MAX_CONTEXT_PROPERTY_ID) {
-    throw new CallciumError(
-      "UNKNOWN_CONTEXT_PROPERTY",
-      `Unknown context property ID 0x${step.toString(16).padStart(4, "0")}.`,
-    );
+    throw new CallciumError("INVALID_CONTEXT_PATH", "Context-scope path must be exactly one step");
   }
+  return lookupContextProperty(steps[0]!).typeCode;
 }
 
-/** Validate a calldata-scope path against the descriptor. */
-function validateCalldataPath(steps: number[], desc: Uint8Array): void {
+/** Validate a calldata-scope path against the descriptor and return the target's type code. */
+function validateCalldataPath(steps: number[], desc: Uint8Array): number {
   const argIndex = steps[0]!;
   const paramCount = Descriptor.paramCount(desc);
   if (argIndex >= paramCount) {
     throw new CallciumError(
       "PARAM_INDEX_OUT_OF_BOUNDS",
-      `Param index ${argIndex} out of range (descriptor has ${paramCount} params).`,
+      `Param index ${argIndex} out of range (descriptor has ${paramCount} params)`,
     );
   }
 
@@ -61,10 +58,10 @@ function validateCalldataPath(steps: number[], desc: Uint8Array): void {
 
     if (isQuantifier(step)) {
       if (!isArray) {
-        throw new CallciumError("QUANTIFIER_ON_NON_ARRAY", "Quantifier step is only valid on an array node.");
+        throw new CallciumError("QUANTIFIER_ON_NON_ARRAY", "Quantifier step is only valid on an array node");
       }
       if (hasQuantifier) {
-        throw new CallciumError("NESTED_QUANTIFIER", "Nested quantifiers are not allowed.");
+        throw new CallciumError("NESTED_QUANTIFIER", "Nested quantifiers are not allowed");
       }
       hasQuantifier = true;
     }
@@ -74,7 +71,7 @@ function validateCalldataPath(steps: number[], desc: Uint8Array): void {
       if (step >= fieldCount) {
         throw new CallciumError(
           "TUPLE_FIELD_OUT_OF_BOUNDS",
-          `Tuple field index ${step} out of range (tuple has ${fieldCount} fields).`,
+          `Tuple field index ${step} out of range (tuple has ${fieldCount} fields)`,
         );
       }
       offset = Descriptor.tupleFieldOffset(desc, offset, step);
@@ -84,15 +81,72 @@ function validateCalldataPath(steps: number[], desc: Uint8Array): void {
         if (step >= arrayLength) {
           throw new CallciumError(
             "STATIC_ARRAY_INDEX_OUT_OF_BOUNDS",
-            `Array index ${step} out of range (static array has ${arrayLength} elements).`,
+            `Array index ${step} out of range (static array has ${arrayLength} elements)`,
           );
         }
       }
       offset = Descriptor.arrayElementOffset(offset);
     } else {
-      throw new CallciumError("NOT_COMPOSITE", "Cannot descend into an elementary type.");
+      throw new CallciumError("NOT_COMPOSITE", "Cannot descend into an elementary type");
     }
   }
+
+  return Descriptor.inspect(desc, offset).typeCode;
+}
+
+///////////////////////////////////////////////////////////////////////////
+// Operand domain
+///////////////////////////////////////////////////////////////////////////
+
+// Values a 32-byte word represents, which is the distance between an operand and its alias.
+const WORD_VALUES = 1n << 256n;
+
+/** Integers an integer target admits, or null for any other type. */
+function targetBounds(typeCode: number): { min: bigint; max: bigint } | null {
+  if (typeCode >= TypeCode.UINT_MIN && typeCode <= TypeCode.UINT_MAX) {
+    const bits = BigInt(typeCode - TypeCode.UINT_MIN + 1) * 8n;
+    return { min: 0n, max: (1n << bits) - 1n };
+  }
+  if (typeCode >= TypeCode.INT_MIN && typeCode <= TypeCode.INT_MAX) {
+    const bits = BigInt(typeCode - TypeCode.INT_MIN + 1) * 8n;
+    const half = 1n << (bits - 1n);
+    return { min: -half, max: half - 1n };
+  }
+  return null;
+}
+
+/** Reject an operand outside the target's range whose word carries a value inside it. */
+function reject(written: bigint, folded: bigint): never {
+  throw new CallciumError(
+    "OUT_OF_PHYSICAL_BOUNDS",
+    `Operand ${written} is outside the physical range of the type and encodes as ${folded}`,
+  );
+}
+
+/**
+ * Reject an operand that two's complement folds onto a value the target admits.
+ * Such an operand and the value it folds onto encode to one word, so the operands as written are
+ * the only place the two stay distinct. An operand spans no more than one word, which leaves two
+ * ways across: a negative's alias clears every target narrower than the whole word, and a positive
+ * reaches a signed range only at that type's own minimum word.
+ */
+function checkOperandDomain(constraint: Constraint, typeCode: number): void {
+  const bounds = targetBounds(typeCode);
+  const extremes = readOperandExtremes(constraint);
+  if (bounds === null || extremes === undefined) return;
+
+  // A negative operand occupies the word its unsigned alias does, which only the target holding
+  // the whole word can hold too.
+  if (extremes.leastNegative < 0n && typeCode === TypeCode.UINT_MAX) {
+    reject(extremes.leastNegative, extremes.leastNegative + WORD_VALUES);
+  }
+
+  if (!isSigned(typeCode)) return;
+  // An operand at or above the signed minimum's own word denotes that negative, and every such
+  // operand already exceeds the signed maximum.
+  if (extremes.greatest >= WORD_VALUES + bounds.min) {
+    reject(extremes.greatest, extremes.greatest - WORD_VALUES);
+  }
 }
 
 ///////////////////////////////////////////////////////////////////////////
@@ -119,7 +173,7 @@ export class PolicyBuilder {
       selector: parsed.selector,
       descriptor,
       groups: [[]],
-      pathHashes: [new Set()],
+      groupPathKeys: new Set(),
     });
   }
 
@@ -134,47 +188,54 @@ export class PolicyBuilder {
       selector: "0x00000000",
       descriptor,
       groups: [[]],
-      pathHashes: [new Set()],
+      groupPathKeys: new Set(),
     });
   }
 
   /**
    * Add a constraint to the current group.
    * @param constraint - A `Constraint` object or a `ConstraintBuilder` instance.
+   * @throws {CallciumError} With code `OUT_OF_PHYSICAL_BOUNDS` when a numeric operand lies outside
+   * the target type's range and encodes as a value inside it. Operands are read as written, so a
+   * `Constraint` carrying encoded operator bytes is left to {@link validate}.
    */
-  add(constraint: Constraint | ConstraintBuilder): this {
-    const c: Constraint = {
+  add(constraint: Constraint): this {
+    // A builder compiles no hint; one arrives only on a constraint that came already encoded.
+    const added: Constraint = {
       scope: constraint.scope,
       path: constraint.path,
       operators: [...constraint.operators],
+      ...("hint" in constraint && constraint.hint !== undefined && { hint: constraint.hint }),
     };
 
-    if (c.operators.length === 0) {
-      throw new CallciumError("NO_CONSTRAINT_OPERATORS", "Constraint must have at least one operator.");
+    if (added.operators.length === 0) {
+      throw new CallciumError("NO_CONSTRAINT_OPERATORS", "Constraint must have at least one operator");
     }
 
     // Path shape is established before the scope decides how to navigate it.
-    const steps = parsePathSteps(c.path);
+    const steps = parsePathSteps(added.path);
     if (steps.length === 0) {
-      throw new CallciumError("EMPTY_PATH", "Path must have at least one step.");
+      throw new CallciumError("EMPTY_PATH", "Path must have at least one step");
     }
 
-    if (c.scope === Scope.CONTEXT) {
-      validateContextPath(steps);
-    } else if (c.scope === Scope.CALLDATA) {
-      validateCalldataPath(steps, this.draft.descriptor);
+    let targetTypeCode: number;
+    if (added.scope === Scope.CONTEXT) {
+      targetTypeCode = validateContextPath(steps);
+    } else if (added.scope === Scope.CALLDATA) {
+      targetTypeCode = validateCalldataPath(steps, this.draft.descriptor);
     } else {
-      throw new CallciumError("INVALID_SCOPE", `Unknown scope value ${c.scope}.`);
+      throw new CallciumError("INVALID_SCOPE", `Unknown scope value ${added.scope}`);
     }
 
-    const key = `${c.scope}:${c.path.toLowerCase()}`;
-    const currentHashes = this.draft.pathHashes[this.draft.pathHashes.length - 1]!;
-    if (currentHashes.has(key)) {
-      throw new CallciumError("DUPLICATE_PATH_IN_GROUP", `Duplicate path ${c.path} in the same group.`);
+    checkOperandDomain(constraint, targetTypeCode);
+
+    const key = `${added.scope}:${added.path.toLowerCase()}`;
+    if (this.draft.groupPathKeys.has(key)) {
+      throw new CallciumError("DUPLICATE_PATH_IN_GROUP", `Duplicate path ${added.path} in the same group`);
     }
 
-    currentHashes.add(key);
-    this.draft.groups[this.draft.groups.length - 1]!.push(c);
+    this.draft.groupPathKeys.add(key);
+    this.draft.groups[this.draft.groups.length - 1]!.push(added);
     return this;
   }
 
@@ -182,10 +243,10 @@ export class PolicyBuilder {
   or(): this {
     const lastGroup = this.draft.groups[this.draft.groups.length - 1]!;
     if (lastGroup.length === 0) {
-      throw new CallciumError("EMPTY_GROUP", "Cannot start a new group when the current group is empty.");
+      throw new CallciumError("EMPTY_GROUP", "Cannot start a new group when the current group is empty");
     }
     this.draft.groups.push([]);
-    this.draft.pathHashes.push(new Set());
+    this.draft.groupPathKeys.clear();
     return this;
   }
 
@@ -196,6 +257,8 @@ export class PolicyBuilder {
    * @returns The policy as a 0x-prefixed hex string.
    * @throws {CallciumError} If any group is empty.
    * @throws {ValidationError} If validation finds any issue.
+   * @throws {CallciumError} With code `RULE_SIZE_OVERFLOW` when a rule's encoded bytes exceed the
+   * width of the rule size field.
    */
   build(): Hex {
     this.checkGroups();
@@ -233,7 +296,7 @@ export class PolicyBuilder {
   private checkGroups(): void {
     for (let i = 0; i < this.draft.groups.length; i++) {
       if (this.draft.groups[i]!.length === 0) {
-        throw new CallciumError("EMPTY_GROUP", `Group ${i} is empty.`);
+        throw new CallciumError("EMPTY_GROUP", `Group ${i} is empty`);
       }
     }
   }

package/src/policy-coder.ts

@@ -3,19 +3,26 @@ import { keccak_256 } from "@noble/hashes/sha3.js";
 import { bytesToHex, hexToBytes, toHex, readU16, readU32, writeBE16, writeBE32 } from "./bytes";
 import {
   DescriptorFormat as DF,
+  fieldMax,
+  formatCode,
+  MAX_CONTEXT_PROPERTY_ID,
+  Op,
   PolicyFormat as PF,
   Scope,
-  Limits,
-  Op,
   TypeCode,
-  isValidOperatorData,
-  isAddressableTarget,
-  MAX_CONTEXT_PROPERTY_ID,
 } from "./constants";
 import { Descriptor } from "./descriptor";
 import { decodeDescriptor } from "./descriptor-coder";
-import { CallciumError } from "./errors";
-import { isLengthOp, isLengthValidType, toBigInt } from "./operators";
+import { CallciumError, type CallciumErrorCode } from "./errors";
+import {
+  isLengthOp,
+  isLengthValidType,
+  toBigInt,
+  isAddressableTarget,
+  isValidOperatorData,
+  toOperatorBytes,
+} from "./operators";
+import { parsePathSteps } from "./path";
 
 import type {
   Constraint,
@@ -28,27 +35,6 @@ import type {
   PolicyData,
 } from "./types";
 
-///////////////////////////////////////////////////////////////////////////
-// Path helper
-///////////////////////////////////////////////////////////////////////////
-
-/**
- * Parse a BE16-encoded hex path into an array of step values.
- * @param path - 0x-prefixed hex string containing BE16-encoded path steps.
- * @returns Array of numeric step values.
- */
-export function parsePathSteps(path: Hex): number[] {
-  const bytes = hexToBytes(path);
-  if (bytes.length % PF.PATH_STEP_SIZE !== 0) {
-    throw new CallciumError("MALFORMED_PATH", `Path byte length ${bytes.length} is not a whole number of steps`);
-  }
-  const steps: number[] = [];
-  for (let offset = 0; offset < bytes.length; offset += PF.PATH_STEP_SIZE) {
-    steps.push(readU16(bytes, offset));
-  }
-  return steps;
-}
-
 ///////////////////////////////////////////////////////////////////////////
 // Policy field helper
 ///////////////////////////////////////////////////////////////////////////
@@ -58,6 +44,24 @@ function field<T>(value: T, start: number, end: number): Field<T> {
   return { value, span: { start, end } };
 }
 
+/**
+ * Wrap the hex rendering of `data[start, end)` with its span, rendering on first read.
+ * Enforcement reads the span as bytes, so the string is built only for a caller that asks.
+ * The field reads and assigns like the plain one it replaces.
+ */
+function hexField(data: Uint8Array, start: number, end: number): Field<Hex> {
+  let hex: Hex | undefined;
+  return {
+    get value(): Hex {
+      return (hex ??= toHex(data, start, end));
+    },
+    set value(replacement: Hex) {
+      hex = replacement;
+    },
+    span: { start, end },
+  };
+}
+
 ///////////////////////////////////////////////////////////////////////////
 // Hint block
 ///////////////////////////////////////////////////////////////////////////
@@ -153,7 +157,7 @@ function hintTargetTypeCode(data: Uint8Array, hintStart: number, hintSize: numbe
 /** Decode a policy blob, returning the structural representation and the blob bytes it spans. */
 export function decodePolicy(blob: Hex): { policy: DecodedPolicy; data: Uint8Array } {
   const data = hexToBytes(blob);
-  if (data.length < PF.DESC_OFFSET + 1) {
+  if (data.length < PF.DESC_OFFSET) {
     throw new CallciumError("MALFORMED_HEADER", "Policy blob is too short");
   }
 
@@ -199,7 +203,8 @@ export function decodePolicy(blob: Hex): { policy: DecodedPolicy; data: Uint8Arr
       end: descStart + param.span.end,
     },
   }));
-  const descriptorRaw = toHex(data, descStart, descEnd);
+
+  const descriptorRaw = hexField(data, descStart, descEnd);
 
   const groupCountStart = groupCountOffset;
   const groupCountEnd = groupCountStart + PF.GROUP_COUNT_SIZE;
@@ -221,6 +226,10 @@ export function decodePolicy(blob: Hex): { policy: DecodedPolicy; data: Uint8Arr
     const groupBodyStart = offset + PF.GROUP_HEADER_SIZE;
     const groupEnd = groupBodyStart + groupSizeValue;
 
+    if (groupEnd > data.length) {
+      throw new CallciumError("GROUP_OVERFLOW", "Group extends beyond policy blob", offset);
+    }
+
     const ruleCountStart = offset;
     const ruleCountValue = readU16(data, ruleCountStart);
     if (ruleCountValue === 0) {
@@ -229,9 +238,6 @@ export function decodePolicy(blob: Hex): { policy: DecodedPolicy; data: Uint8Arr
     if (groupSizeValue < ruleCountValue * PF.RULE_MIN_SIZE) {
       throw new CallciumError("GROUP_TOO_SMALL", "Declared group size is too small for its rule count", offset);
     }
-    if (groupEnd > data.length) {
-      throw new CallciumError("GROUP_OVERFLOW", "Group extends beyond policy blob", offset);
-    }
 
     const rules: DecodedRule[] = [];
     let ruleOffset = groupBodyStart;
@@ -249,8 +255,8 @@ export function decodePolicy(blob: Hex): { policy: DecodedPolicy; data: Uint8Arr
           ruleOffset,
         );
       }
-      if (ruleOffset + ruleSizeValue > groupEnd) {
-        throw new CallciumError("RULE_OVERFLOW", "Rule extends beyond group boundary", ruleOffset);
+      if (ruleOffset + ruleSizeValue > data.length) {
+        throw new CallciumError("RULE_OVERFLOW", "Rule extends beyond policy blob", ruleOffset);
       }
 
       const scopeOffset = ruleOffset + PF.RULE_SCOPE_OFFSET;
@@ -312,12 +318,13 @@ export function decodePolicy(blob: Hex): { policy: DecodedPolicy; data: Uint8Arr
       // IN operands must be strictly ascending (unsigned); strictness also rejects duplicates.
       if (opBase === Op.IN) {
         const wordCount = dataLengthValue / 32;
+        let prev = toBigInt(data, dataStart);
         for (let word = 1; word < wordCount; word++) {
-          const prev = data.subarray(dataStart + (word - 1) * 32, dataStart + word * 32);
-          const cur = data.subarray(dataStart + word * 32, dataStart + (word + 1) * 32);
-          if (compareBytes(prev, cur) >= 0) {
+          const cur = toBigInt(data, dataStart + word * 32);
+          if (cur <= prev) {
             throw new CallciumError("UNSORTED_IN_SET", "IN operands must be strictly ascending", ruleOffset);
           }
+          prev = cur;
         }
       }
 
@@ -336,10 +343,10 @@ export function decodePolicy(blob: Hex): { policy: DecodedPolicy; data: Uint8Arr
       if (depthValue === 0) {
         throw new CallciumError("EMPTY_PATH", "Rule path must have at least one step", ruleOffset);
       }
-      if (depthValue > Limits.MAX_PATH_DEPTH) {
+      if (depthValue > PF.MAX_PATH_DEPTH) {
         throw new CallciumError(
           "PATH_TOO_DEEP",
-          `Path depth ${depthValue} exceeds maximum ${Limits.MAX_PATH_DEPTH}`,
+          `Path depth ${depthValue} exceeds maximum ${PF.MAX_PATH_DEPTH}`,
           ruleOffset,
         );
       }
@@ -357,7 +364,7 @@ export function decodePolicy(blob: Hex): { policy: DecodedPolicy; data: Uint8Arr
         if (contextPropertyId > MAX_CONTEXT_PROPERTY_ID) {
           throw new CallciumError(
             "UNKNOWN_CONTEXT_PROPERTY",
-            `Context rule references undefined context property 0x${contextPropertyId.toString(16).padStart(4, "0")}`,
+            `Context rule references undefined context property ${formatCode(contextPropertyId, PF.PATH_STEP_SIZE)}`,
             ruleOffset,
           );
         }
@@ -370,14 +377,17 @@ export function decodePolicy(blob: Hex): { policy: DecodedPolicy; data: Uint8Arr
         pathDepth: field(depthValue, depthOffset, depthOffset + 1),
         path: field(pathHex, pathStart, pathStart + pathLength),
         ...(hintSize > 0 && {
-          hint: field(toHex(data, hintStart, hintStart + hintSize), hintStart, hintStart + hintSize),
+          hint: hexField(data, hintStart, hintStart + hintSize),
         }),
         opCode: field(opCodeValue, opCodeOffset, opCodeOffset + PF.RULE_OPCODE_SIZE),
         dataLength: field(dataLengthValue, dataLengthOffset, dataLengthOffset + PF.RULE_DATALENGTH_SIZE),
-        data: field(toHex(data, dataStart, dataStart + dataLengthValue), dataStart, dataStart + dataLengthValue),
+        data: hexField(data, dataStart, dataStart + dataLengthValue),
         span: { start: ruleOffset, end: ruleOffset + ruleSizeValue },
       });
 
+      if (ruleOffset + ruleSizeValue > groupEnd) {
+        throw new CallciumError("RULE_OVERFLOW", "Rule extends beyond group boundary", ruleOffset);
+      }
       ruleOffset += ruleSizeValue;
     }
 
@@ -404,7 +414,12 @@ export function decodePolicy(blob: Hex): { policy: DecodedPolicy; data: Uint8Arr
     selector: field(selectorHex, selectorStart, selectorEnd),
     descLength: field(descLengthValue, descLengthStart, descLengthStart + PF.DESC_LENGTH_SIZE),
     descriptor: {
-      raw: descriptorRaw,
+      get raw(): Hex {
+        return descriptorRaw.value;
+      },
+      set raw(replacement: Hex) {
+        descriptorRaw.value = replacement;
+      },
       header: field({ version: desc.version, paramCount: desc.params.length }, descStart, descStart + DF.HEADER_SIZE),
       params,
       span: { start: descStart, end: descEnd },
@@ -425,34 +440,44 @@ export function decodePolicy(blob: Hex): { policy: DecodedPolicy; data: Uint8Arr
 
 type Rule = { scope: number; path: Uint8Array; operator: Uint8Array; hint: Uint8Array };
 
-/** Flatten a Constraint into one Rule per operator, compiling its hint against the descriptor. */
-function flattenConstraint(constraint: Constraint, desc: Uint8Array): Rule[] {
-  const operators = constraint.operators.map(hexToBytes);
-  for (const operator of operators) {
-    if (operator.length < 1) {
-      throw new CallciumError("INVALID_OPERATOR_BYTES", "Operator must have at least one byte (opcode).");
-    }
-  }
+/** The path bytes and compiled hint every rule a constraint produces carries. */
+type ConstraintTarget = { path: Uint8Array; hint: Uint8Array };
 
+/** Read a constraint's path and compile the hint its rules carry. */
+function readConstraintTarget(constraint: Constraint, desc: Uint8Array): ConstraintTarget {
   const path = hexToBytes(constraint.path);
 
   // Path shape checks precede compilation: the compiler assumes a framed, depth-bounded path.
   if (path.length === 0) {
-    throw new CallciumError("EMPTY_PATH", "Rule path must have at least one step.");
+    throw new CallciumError("EMPTY_PATH", "Rule path must have at least one step");
   }
   if ((path.length & 1) !== 0) {
-    throw new CallciumError("MALFORMED_PATH", "Path byte length must be even.");
+    throw new CallciumError("MALFORMED_PATH", "Path byte length must be even");
   }
   const depth = path.length / 2;
-  if (depth > Limits.MAX_PATH_DEPTH) {
-    throw new CallciumError("PATH_TOO_DEEP", `Path depth ${depth} exceeds maximum ${Limits.MAX_PATH_DEPTH}.`);
+  if (depth > PF.MAX_PATH_DEPTH) {
+    throw new CallciumError("PATH_TOO_DEEP", `Path depth ${depth} exceeds maximum ${PF.MAX_PATH_DEPTH}`);
   }
 
   const hint =
     constraint.scope === Scope.CALLDATA
       ? Descriptor.compileHint(desc, parsePathSteps(constraint.path))
       : new Uint8Array(0);
-  return operators.map((operator) => ({ scope: constraint.scope, path, operator, hint }));
+  return { path, hint };
+}
+
+/** Flatten a Constraint into one Rule per operator, compiling its hint against the descriptor. */
+function flattenConstraint(constraint: Constraint, desc: Uint8Array): Rule[] {
+  // The rule is the unit these checks run over: each rule's operator is established before the
+  // path and hint it shares with its siblings. A constraint carrying no operator produces no rule,
+  // so its path is never read.
+  let target: ConstraintTarget | undefined;
+
+  return constraint.operators.map((operatorHex) => {
+    const operator = toOperatorBytes(operatorHex);
+    target ??= readConstraintTarget(constraint, desc);
+    return { scope: constraint.scope, operator, ...target };
+  });
 }
 
 /** Compare two byte arrays lexicographically. */
@@ -477,6 +502,12 @@ function sortRules(rules: Rule[]): void {
   });
 }
 
+/** Require a value to fit the big-endian field of `byteWidth` bytes. */
+function requireFieldFits(value: number, byteWidth: number, code: CallciumErrorCode, subject: string): void {
+  const max = fieldMax(byteWidth);
+  if (value > max) throw new CallciumError(code, `${subject} ${value} exceeds maximum ${max}`);
+}
+
 /**
  * Serialize a single rule to its wire format bytes.
  * Path shape and operator framing are established by `flattenConstraint`.
@@ -484,13 +515,11 @@ function sortRules(rules: Rule[]): void {
 function encodeRule(rule: Rule): Uint8Array {
   const depth = rule.path.length / 2;
   if (rule.scope === Scope.CONTEXT && depth !== 1) {
-    throw new CallciumError("INVALID_CONTEXT_PATH", "Context-scope rules must have exactly one path step.");
+    throw new CallciumError("INVALID_CONTEXT_PATH", "Context-scope rules must have exactly one path step");
   }
   const data = rule.operator.subarray(1);
   const ruleSize = PF.RULE_FIXED_OVERHEAD + rule.path.length + rule.hint.length + data.length;
-  if (ruleSize > 0xffff) {
-    throw new CallciumError("RULE_SIZE_OVERFLOW", `Rule size ${ruleSize} exceeds maximum 65535`);
-  }
+  requireFieldFits(ruleSize, PF.RULE_SIZE_SIZE, "RULE_SIZE_OVERFLOW", "Rule size");
 
   const buf = new Uint8Array(ruleSize);
   writeBE16(buf, 0, ruleSize);
@@ -541,9 +570,7 @@ function encode(data: PolicyData): Hex {
   if (data.groups.length === 0) {
     throw new CallciumError("EMPTY_POLICY", "Policy must contain at least one group");
   }
-  if (data.groups.length > 0xff) {
-    throw new CallciumError("GROUP_COUNT_OVERFLOW", `Group count ${data.groups.length} exceeds maximum 255`);
-  }
+  requireFieldFits(data.groups.length, PF.GROUP_COUNT_SIZE, "GROUP_COUNT_OVERFLOW", "Group count");
 
   // Flatten constraints into rules and sort within each group. Hints are compiled first because
   // they are part of the rule bytes the group hash covers.
@@ -553,20 +580,13 @@ function encode(data: PolicyData): Hex {
     return rules;
   });
 
-  if (descBytes.length > 0xffff) {
-    throw new CallciumError("DESC_LENGTH_OVERFLOW", `Descriptor length ${descBytes.length} exceeds maximum 65535`);
-  }
+  requireFieldFits(descBytes.length, PF.DESC_LENGTH_SIZE, "DESC_LENGTH_OVERFLOW", "Descriptor length");
 
   const encodedGroups = sortedGroups.map((rules, groupIndex) => {
     if (rules.length === 0) {
       throw new CallciumError("EMPTY_GROUP", `Group ${groupIndex} is empty`);
     }
-    if (rules.length > 0xffff) {
-      throw new CallciumError(
-        "RULE_COUNT_OVERFLOW",
-        `Group ${groupIndex} rule count ${rules.length} exceeds maximum 65535`,
-      );
-    }
+    requireFieldFits(rules.length, PF.GROUP_RULECOUNT_SIZE, "RULE_COUNT_OVERFLOW", `Group ${groupIndex} rule count`);
     return { wireBytes: encodeGroupRules(rules), ruleCount: rules.length };
   });
 
@@ -577,7 +597,13 @@ function encode(data: PolicyData): Hex {
     encodedGroups.sort((a, b) => compareBytes(hashes.get(a)!, hashes.get(b)!));
   }
 
-  const selectorBytes = data.isSelectorless ? new Uint8Array(4) : hexToBytes(data.selector);
+  const selectorBytes = data.isSelectorless ? new Uint8Array(PF.SELECTOR_SIZE) : hexToBytes(data.selector);
+  if (selectorBytes.length !== PF.SELECTOR_SIZE) {
+    throw new CallciumError(
+      "MALFORMED_SELECTOR",
+      `Selector must be ${PF.SELECTOR_SIZE} bytes, got ${selectorBytes.length}`,
+    );
+  }
 
   const headerByte = PF.VERSION | (data.isSelectorless ? PF.FLAG_NO_SELECTOR : 0);
 
@@ -629,8 +655,8 @@ function decode(blob: Hex): PolicyData {
   const { policy } = decodePolicy(blob);
 
   const groups: Constraint[][] = policy.groups.map((group) => {
+    // A Map keeps its insertion order, which is the order the rules named their constraints in.
     const constraintMap = new Map<string, Constraint>();
-    const constraintOrder: string[] = [];
 
     for (const rule of group.rules) {
       const hintHex = rule.hint?.value;
@@ -649,11 +675,10 @@ function decode(blob: Hex): PolicyData {
           span: rule.span,
         };
         constraintMap.set(key, constraint);
-        constraintOrder.push(key);
       }
     }
 
-    return constraintOrder.map((k) => constraintMap.get(k)!);
+    return [...constraintMap.values()];
   });
 
   return {